In-app

Call these when your agent runs in the same process as the workspace. Every other way in ends in the same calls.

Workspace

import { Workspace } from '@struktoai/mirage-node'

class Workspace {
  constructor(
    mounts: Record<string, VFS>,
    options?: WorkspaceOptions,
  )
}

One terminal over the backends mounted at each prefix.

Record<string, VFS>

required

The backend at each prefix, such as { '/': new RAMVFS(), '/s3': new S3VFS(config) }.

MountMode

default:"MountMode.READ"

The mode a mount gets when it sets none: READ, WRITE or EXEC.

Record<string, SessionProfile>

Named profiles a session can be created under.

string

The profile a session gets when it names none.

Policy[]

Policies every line passes through.

AskHandler

Answers an ask while the line waits. Without one, asks wait in ws.decisions.

The other options (cache, index, store, runtimes, clis, env, secrets, commandLimits, …) are the top-level YAML keys, in camelCase.

import { MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'

const ws = new Workspace(
  { '/': new RAMVFS() },
  { mode: MountMode.WRITE },
)

ws.session

ws.session(sessionId, { profile?, mounts? }): Promise<Session>

The Session every call below runs as. It creates the session when the id is new and adopts it when it exists. profile and mounts apply only on create, and throw for an existing session. ws.createSession is the same call without the handle.

const session = await ws.session('agent')

ws.listSessions, ws.closeSession

ws.listSessions(): SessionState[]
ws.closeSession(sessionId): Promise<void>

List the sessions, or close one: its lines are cancelled and its jobs end. The default session cannot be closed.

Show SessionState

string

The working directory.

Readonly<Record<string, string>>

The exported variables.

string | null

The profile it was created under.

ReadonlyMap<string, MountMode> | null

Its mount modes, when narrower than the workspace’s.

number

$?.

number

Unix time, in seconds.

console.log(ws.listSessions().map((s) => s.sessionId))
await ws.closeSession('agent')

ws.cancel, ws.kill

ws.cancel(sessionId?): Promise<number>
ws.kill(sessionId?): Promise<number>

Stop a session’s work, or every session’s with no id, and leave the sessions open. 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 processes runtimes started. Each answers how many it stopped.

await ws.cancel('agent')
await ws.kill()

ws.snapshot, Workspace.load

ws.snapshot(): Promise<Uint8Array>
ws.snapshot(target, { s3? }): Promise<number>
Workspace.load(source, { s3?, ... }): Promise<Workspace>

Save the workspace to a tar and rebuild it from one. With no target, snapshot answers the tar’s bytes; with one, its size. target and source are a path, or an object key with s3; source can also be the bytes. While it captures, new lines and file writes wait, and running ones get 30 seconds to end, else it rejects with an EBUSY error; a path target streams disk mount files rather than holding them whole. See Snapshots for what a tar holds.

const tar = await ws.snapshot()
const restored = await Workspace.load(tar)

ws.copy

ws.copy(): Promise<Workspace>

A deep copy, without a tar in between. RAM and disk mounts are copied, so a write in the copy never reaches the original; a disk mount’s copy lives in a new temporary directory. Sessions, history and profiles come along. Remote backends such as S3 or Redis are shared, so a write through the copy reaches the same bucket. Policies are not copied.

const fork = await ws.copy()

ws.decisions

ws.decisions.pending(sessionId?): Decision[]
ws.decisions.answer(
  decisionId, outcome, scope?, note?
): Promise<void>

The asks waiting for a host. Each one belongs to the session that ran the line: 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, answers the one line, so its retry runs or is refused; Scope.SESSION allows every line the rule covers for the rest of that session.

Show Decision

string

The id to answer it by.

string

The session that ran the line.

string

The command name.

readonly string[]

The words after the name, expanded.

string

readonly string[]

The paths the line names.

string

The rule’s reason.

Outcome | null

The answer; null while it waits.

Scope

string

What the host said when answering.

import { Outcome } from '@struktoai/mirage-node'

for (const ask of ws.decisions.pending()) {
  await ws.decisions.answer(ask.id, Outcome.ALLOW)
}

ws.close

ws.close(): Promise<void>

Stops its jobs and closes its mounts. Sessions and history stay in the workspace’s store.

Session

import { Session } from '@struktoai/mirage-node'

class Session {
  constructor(workspace: Workspace, sessionId: string)
}

One session’s handle, from ws.session. Every call on it answers 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.

string

SessionState

The session’s record, as ws.listSessions answers it.

Ops

The file API, below.

MirageToolOperations

The agent tools, below.

Decisions

The workspace’s asks ledger, which this session’s questions land in.

session.shell

session.shell(
  command, { stdin?, cwd?, env?, signal?, record? },
): Promise<ExecuteResult>

Runs a shell line as the session. A non-zero exit is a result, not an exception.

Uint8Array | AsyncIterable<Uint8Array>

The line’s stdin. An async iterable streams it.

string

A working directory for this line only. A cd in the line does not leak.

Record<string, string>

Variables for this line only.

AbortSignal

Aborting it stops the line, which throws an AbortError.

boolean

default:"true"

false keeps the line out of history.

Show ExecuteResult

number

string

The output as text. stdout is the bytes.

string

The error output as text. stderr is the bytes.

Refusal | null

Why the line did not run, or null.

Show Refusal

string

deny for a refusal, pending for an ask nobody answered, failed for a policy that raised.

string

The rule’s or the policy’s words.

string

The policy class that refused; empty for an ask.

string

command or operand.

string | null

The ask’s id, for pending.

const stdin = new TextEncoder().encode('a\nb\n')
const result = await session.shell('wc -l', { stdin })
console.log(result.exitCode, result.stdoutText)

session.glob

session.glob(pattern): Promise<string[]>

The paths a pattern matches, as the session sees them.

const paths = await session.glob('/src/**/*.ts')

session.explain

session.explain.shell(line): Promise<ShellExplanation>
session.explain.vfs.<call>(...): Promise<VfsExplanation>

What 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. In a browser (no async task isolation) explain.vfs throws and explain.shell’s policies act for real. See Explain.

const shellRes = await session.explain.shell('rm /data/x')
console.log(shellRes.exitCode, shellRes.reason)
for (const node of shellRes.node.children) {
  if ('command' in node) console.log(node.command, node.answers.map((a) => a.policy))
}
const vfsRes = await session.explain.vfs.write('/data/x', 'hi')
console.log(vfsRes.error, vfsRes.answers.map((a) => a.policy))

session.vfs

The file API, run as the session. Paths are absolute, bytes are Uint8Array. A failure throws an Error whose code is the POSIX name, as Node’s fs does: ENOENT, EACCES, EROFS.

Call	Answers
`read(path, { offset, size })`	The bytes, whole or a range.
`write(path, data)`, `append(path, data)`	Nothing.
`stat(path, undefined, { nofollow })`	A `FileStat`.
`readdir(path)`	The full path of each entry.
`exists(path)`	`true` or `false`.
`mkdir(path)`, `rmdir(path)`, `unlink(path)`	Nothing.
`rename(src, dst)`	Nothing.
`truncate(path, length)`	Nothing.

Show FileStat

string

FileType

FILE, DIRECTORY, SYMLINK or CHAR_DEVICE.

number | null

The bytes a read answers; null when unknown.

string | null

ISO 8601.

ContentType | null

A file’s content shape, such as text.

number | null

The permission bits.

number | string | null

string | null

The backend’s ETag and version, when it has them.

Record<string, unknown>

Backend-specific fields.

const data = new TextEncoder().encode('hello\n')
await session.vfs.write('/notes.txt', data)
const bytes = await session.vfs.read('/notes.txt')
console.log(new TextDecoder().decode(bytes))

session.tools

session.tools.shell(command, signal?): Promise<ToolResult>
session.tools.read(path, offset?, limit?): Promise<ToolResult>
session.tools.write(path, content): Promise<ToolResult>
session.tools.edit(
  path, oldString, newString, replaceAll?,
): Promise<ToolResult>
session.tools.ls(path, signal?): Promise<ToolResult>
session.tools.grep(pattern, path, { ignoreCase?, ... }, signal?)
session.tools.glob(pattern, path?): Promise<ToolResult>
session.tools.call(name, args, signal?): Promise<ToolResult>
session.tools.names(): readonly string[]

The seven agent tools, for a model rather than a program: every answer is text, and a failure is isError, never a throw. call takes a tool’s name and its JSON input, the form an agent loop gets from the model. The session has one table, shared by every caller, so write and edit refuse a file the agent has not read in full, or one that changed since it read it. names() is the tools the session’s profile leaves it, which MCP, RPC and the agent adapters offer: shell needs a command the allow list installs, ls and grep those commands, write and edit a mount the session may write.

Tool	Answers
`shell`	The line’s stdout, stderr and exit status as one text.
`read`	Numbered lines, `limit` of them from `offset`.
`write`	Writes a new file; an existing one only after a full `read`.
`edit`	Replaces `old_string` once, or everywhere with `replace_all`.
`ls`, `grep`	`ls` and `grep -rn`, as text.
`glob`	The files a pattern matches, one per line.

Show ToolResult

{ type: 'text', text: string }[]

The text handed back to the agent.

boolean | undefined

true when the call failed.

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 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.

await session.tools.call('read', { path: '/notes.txt' })
const result = await session.tools.call('edit', {
  path: '/notes.txt',
  old_string: 'hello',
  new_string: 'hi',
})
console.log(result.content[0]?.text, result.isError === true)

Getting Started

Access

AI Agents

VFS

CLIs

Watch

Runtimes

Workspace

ws.session

ws.listSessions, ws.closeSession

ws.cancel, ws.kill

ws.snapshot, Workspace.load

ws.copy

ws.decisions

ws.close

Session

session.shell

session.glob

session.explain

session.vfs

session.tools

​Workspace

​ws.session

​ws.listSessions, ws.closeSession

​ws.cancel, ws.kill

​ws.snapshot, Workspace.load

​ws.copy

​ws.decisions

​ws.close

​Session

​session.shell

​session.glob

​session.explain

​session.vfs

​session.tools

Workspace

ws.session

ws.listSessions, ws.closeSession

ws.cancel, ws.kill

ws.snapshot, Workspace.load

ws.copy

ws.decisions

ws.close

Session

session.shell

session.glob

session.explain

session.vfs

session.tools