Skip to content

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(): mutates accesses in place and returns void. Exact duplicate paths are collapsed; for duplicate paths the outcome follows precedence: WriteWins keeps write access, LastAddedWins keeps 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.