Workspace
The VFS at each path, such as
{ '/': new RAMVFS(), '/s3': new S3VFS(config) }.Named profiles a session can be created under.
Policies every line passes through.
Resolves an approval request (ask) while the line waits. Without a handler, asks are recorded in
ws.decisions.Where the workspace keeps its state: symlinks and file attributes, command logs, sessions and background jobs. In memory when unset. A store passed in is borrowed: close it after
ws.close(), or pass ownsStore: true.snake_case YAML settings.
Direct SDK construction defaults mode to READ; YAML defaults it to write.
Workspace methods
Expand one for its signature and an example.
ws.session
ws.session
Session for sessionId, creating it if the id is new.profile,mountsandpermissionsapply only when the session is created. Passing them for an existing session throws.permissionsadds a command tree, hides and narrower mount modes for this session. The stricter of it and the profile wins, so it cannot allow what the profile refuses. It cannot add a policy.ws.createSession(...)is the sync form. It returns aSessionState, not aSession.
ws.setProfile, ws.setSessionProfile
ws.setProfile, ws.setSessionProfile
setProfile(name, profile)adds or replaces a named profile. An invalid profile throwsPolicyErrorand changes nothing.- Running sessions keep their old rules until you call
setSessionProfile. setSessionProfile(sessionId, profile)takes a profile name,null(the workspace default) or an inline profile object. The session keeps its working directory, variables and history.- The profile name is the session’s user:
whoamiprints it (uid 1000). A session with no profile isroot. An inline profile has uid 1000 and no name.
ws.listSessions, ws.closeSession
ws.listSessions, ws.closeSession
ws.cancel, ws.kill
ws.cancel, ws.kill
cancel cancels the running and queued lines, whichever way they came in, and resolves once they have ended; each rejects with an AbortError. kill kills the background jobs (cmd &) and the programs machines started. Each answers how many it stopped.ws.snapshot, Workspace.load
ws.snapshot, Workspace.load
target and source are a path, or an object key with s3; source can also be the bytes. With no target, snapshot returns the tar’s bytes; with one, its size.- While it captures, new lines and file writes wait. Running ones get 30 seconds to end, else it rejects with an
EBUSYerror. A path target streams disk mount files rather than holding them whole. - The tar keeps the profiles, the command limits and each store’s
capacity. Each session loads back under the restrictions it ran with. - An override brings its own
capacity, or none. - The scratch root, the RAM root added when nothing is mounted at
/, comes back as the scratch root, an override for it included.
ws.copy
ws.copy
ws.decisions
ws.decisions
pending() lists every session’s, pending('agent') one session’s, and an answer never reaches another session. outcome is Outcome.ALLOW or Outcome.DENY. Scope.ONCE, the default, resolves the pending ask for this line, allowing its retry to run or be refused; Scope.SESSION allows every line the rule covers for the rest of that session.ws.close
ws.close
Session
ws.session. Every call on it runs under the session’s profile, working directory and environment. ws.shell, ws.glob, ws.vfs and ws.tools are the same calls as the workspace’s default session.
The session’s record, as returned by
ws.listSessions.The workspace’s asks ledger, which records pending approval requests for this session.
session.shell
stream: false (the default), it collects the execution’s output and returns an ExecuteResult. A non-zero exit is a result, not an exception. ws.shell has the same streaming option and accepts sessionId to select the session.
A working directory for this line only. The line runs in a subshell of its own, beside the session’s other lines rather than after them: a
cd in it does not leak, and its jobs are its own.Variables for this line only. Like
cwd, they run the line in a subshell of its own.Run the commands this workspace machine captures on it, by name, instead of where routing puts them. Throws for a name the workspace does not have.
Write the line’s output to this console as each statement finishes. Cannot be combined with
stream: true. The result then carries the exit code with empty stdout and stderr. The caller calls finish() on the console.Stream the output
Stream the output
stream: true returns a ShellExecution. Read execution.events (stdout and stderr chunks, in order), then await execution.wait() for the exit code.- Read the events before awaiting
wait(). A full queue (64 KiB, set by the workspace I/O settings) blocks the line. - Call
await execution.close()infinally, so stopping early cancels the line.cancel()requests cancellation;wait()then rejects withAbortError. await execution.collect(callback)gives the full result and callscallbackfor each chunk.- A policy with
postExecuteholds output until the line finishes.
sendBytes is the application’s async output sink:More session calls
session.glob
session.glob
session.explain
session.explain
session.shell or a session.vfs call would do, without running it: a line’s verdict and parse tree, a VFS call’s verdict and error, each with every policy’s answer. See Explain.session.vfs
The file API, run as the session. Paths are absolute, bytes areUint8Array. A failure throws an Error whose code is the POSIX name, as Node’s fs does: ENOENT, EACCES, EROFS.
stat may answer from the mount’s listing index. Pass fresh: true to ask the
service directly, for example after another client changed the file. Later
calls then see the new answer. nofollow: true reports a trailing symlink
itself.
session.tools
isError, never a throw. call takes a tool’s name and its JSON input, the form an agent loop gets from the model. write and edit refuse a file the session has not read in full, or one that changed since it was read. Every caller of the session shares that record. names() is the tools the session’s profile leaves it, which MCP, RPC and the agent adapters offer: shell needs a command its commands lets run, ls and grep those commands, write and edit a mount the session may write.
readMedia(path) answers an image or a PDF as media instead of numbered text, for adapters that hand media to the model. @struktoai/mirage-core/workspace/tools/tool_descriptions (needs pnpm add @struktoai/mirage-core) has each tool’s description and JSON schema to hand the model, and the agent adapters wire the tools into each framework. new MirageToolOperations(session, false), from @struktoai/mirage-core/workspace/tools/tool_operations, is a table without the read guard.