read, write, edit, bash, code mode) reach files and commands only through an ExecutionEnv. @struktoai/mirage-pi-durable provides one over a Mirage Workspace, so the tools work on whatever the workspace mounts.
Install
Usage
Install Pi’s coding tools and the Mirage extension, and build aMirageExecutionEnv for each call:
mirageExtension adds a mirage prompt section that describes the mounts. The conversation’s cwd (root.configure({ cwd })) reaches the environment, so each conversation can work in its own directory.
Durable runs
Open the harness on stored state to keep conversations across restarts. The workspace’s files persist as their mounts do:Use a workspace on a Mirage server
GiveMirageExecutionEnv and mirageExtension where a Mirage server’s workspace lives instead of a Workspace, and Pi’s tools call it over HTTP: each file call goes to its VFS API, each command to its shell. The harness can then run where nothing is mounted, such as a Cloudflare Worker or Durable Object. Import from @struktoai/mirage-pi-durable/remote there, which leaves out the workspace code of this process. It replaces the first example’s @struktoai/mirage-pi-durable import, ws, its registry.install(mirageExtension(ws)) line and harness:
- The server owns the mounts, machines and profiles.
sessionIdnames a session on the server, created on first use. iddefaults to the server and workspace, so every process reaching one workspace shares Pi’s file namespace.- The prompt section lists the mounts as the server describes them.
Behavior
- Commands run in Mirage’s shell as one session. Each call starts from its
cwd, so acdorexportdoes not carry over to the next one, as with a new process. - Sessions: pass
sessionIdto act as a Mirage session, under its profile’s mounts, hides and policies. A refused command’s output ends with the policy’s reason. - Long output past Pi’s bounds is written to a file under
/tmpas it arrives, which needs a writable mount there. A command cancelled after that keeps its file. - Mount roots cannot be removed or renamed, nor can a folder holding one, as in the shell.
- Watching polls: every
watch.pollIntervalMs, Pi compares snapshots of each watched path, asked of the backend each time. A file new to a remote folder shows once the mount’s listing of that folder refreshes. - Binary reads copy the file when Pi opens it, so a later rename or rewrite of the path does not reach an open reader.
Exports
MirageExecutionEnv accepts:
Examples
examples/typescript/agents/pi_durable/ram_pi_durable.ts, a Pi Durable run on a RAM workspace.