API Reference
DirectoryConfiguration
Configures which directories are accessible and at what permission level. Construct with no arguments to read every value from environment variables. Passing any constructor argument uses only the supplied values and ignores the environment.
import { AccessType, DirectoryConfiguration } from '@johannes.latzel/llm-chat-workspace';
const config = new DirectoryConfiguration([
{ type: AccessType.Read, path: '/var/log' },
{ type: AccessType.Write, path: '/home/project' }
]);
| Property | Type | Description |
|---|---|---|
accesses |
{ type: AccessType; path: string }[] |
List of access entries |
skipDirs |
string[] |
Directory names to skip when walking |
resolveSymlinks |
boolean |
Resolve symlinks before access checks |
workspacePath |
string \| undefined |
The default workspace path, or undefined when unset |
precedence |
AccessPrecedence |
How duplicate accesses for the same path are resolved (default WriteWins) |
deduplicate(): mutatesaccessesin place and returnsvoid. Exact duplicate paths are collapsed; for duplicate paths the outcome followsprecedence:WriteWinskeeps write access,LastAddedWinskeeps the last supplied access
AccessPrecedence
Enum controlling how duplicate accesses for the same directory are resolved.
| Member | Value | Meaning |
|---|---|---|
WriteWins |
'write-wins' |
Write access wins over read access for the same path, regardless of order (default) |
LastAddedWins |
'last-added-wins' |
The last-supplied access for a path wins, overriding any earlier one |
Workspace
Manages the active workspace path and enforces access control for all file operations.
import { AccessType, DirectoryConfiguration, Workspace } from '@johannes.latzel/llm-chat-workspace';
const workspace = new Workspace(
new DirectoryConfiguration([{ type: AccessType.Write, path: '/home/project' }])
);
| Member | Description |
|---|---|
currentPath |
The active workspace directory (absolute) |
switchWorkspace(target) |
Changes the active path (mutex-guarded); throws if outside configured directories |
normalize(input) |
Resolves a relative or absolute path against the active workspace |
canRead(absPath) |
true if the path is within a read or write directory |
canWrite(absPath) |
true if the path is within a write directory |
getAccesses() |
The configured access entries |
addAccess(type, dir) |
Adds a directory access entry (duplicates collapsed; the outcome for an existing path follows precedence: write-wins keeps write access, last-added-wins overrides with the new access) |
removeAccess(dir) |
Removes all access entries for the directory; throws if none would remain |
setSkipDirs(dirs) |
Replaces the list of directory names skipped when walking |
setResolveSymlinks(value) |
Enables or disables symlink resolution before access checks |
setWorkspacePath(target?) |
Sets the default workspace path; undefined clears it |
get workspacePath |
The configured default workspace path, or undefined when unset |
getConfiguration() |
Returns a snapshot of the configuration as a new DirectoryConfiguration |
skipDirs |
Directory names skipped when walking |
resolveSymlinks |
Whether symlink resolution is enabled |
pathHint(raw, resolved) |
Diagnostic hint for failed access checks |
walk(dir, onError?) |
Async generator yielding WalkEntry for files and directories; throws when the root path does not exist or is not a directory (onError only fires for nested subdirectories) |
SwitchWorkspaceTool (tool name: switch_workspace)
Changes the current workspace path to a new directory within configured accessible directories. Must be called before any other filesystem tool when changing workspace. Do NOT call this tool in parallel with any other filesystem tool. Call it first, then call the other tools sequentially.
import {
AccessType,
DirectoryConfiguration,
Workspace,
SwitchWorkspaceTool
} from '@johannes.latzel/llm-chat-workspace';
const workspace = new Workspace(
new DirectoryConfiguration([{ type: AccessType.Write, path: '/home/project' }])
);
const tool = new SwitchWorkspaceTool(workspace);
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path |
string | yes | Target directory path. |
Returns: "Switched workspace to: <path>" on success, or an error message on failure.
EphemeralWorkspaceProvisioner
Creates and removes private temp-directory workspaces.
import { EphemeralWorkspaceProvisioner } from '@johannes.latzel/llm-chat-workspace';
const provisioner = new EphemeralWorkspaceProvisioner({ baseDir: '/tmp/diagram-mcp' });
const ephemeral = await provisioner.create();
await ephemeral.dispose();
| Member | Description |
|---|---|
directory |
Resolved base directory for new roots. |
create() |
Creates a new root and a Workspace restricted to it. |
dispose() on the result |
Removes the root directory. |
WorkspaceStore
Owns ephemeral workspace sessions, global byte and count limits, pinning, and LRU eviction.
import { WorkspaceStore } from '@johannes.latzel/llm-chat-workspace';
const store = new WorkspaceStore(
{
maxTotalBytes: 64 * 1024 * 1024,
maxBytesPerWorkspace: 8 * 1024 * 1024,
maxWorkspaces: 32,
maxFiles: 1024,
maxFilesPerWorkspace: 256
},
factory
);
const session = await store.create();
const lease = await store.acquire(session.id);
try {
// use lease.workspace and lease.resource
} finally {
lease.release();
}
| Member | Description |
|---|---|
create() |
Creates a session and evicts the LRU unpinned workspace if the count cap is full. |
acquire(id) |
Pins a workspace, touches its LRU order, and returns a lease. |
delete(id) |
Deletes an unpinned workspace. Unknown ids are ignored. |
info(id) |
Returns bytes, file count, created and last-used timestamps. |
ensureCapacity(id, additionalBytes, additionalFiles?) |
Reserves room for a byte and file delta and evicts other LRU unpinned workspaces if needed. |
refreshUsage(id) |
Rescans the workspace and updates the cached usage. |
dispose() |
Disposes every workspace and clears the store. |
WorkspaceSession exposes id, workspace, resource, and dispose().
WorkspaceLease exposes the same fields plus release(). The backing temp
root is owned by the provisioner and is not part of the public session shape.
Factory-created resources are opaque to the store.