Skip to main content
Pi Durable is Pi’s durable agent harness: conversations, turns and tool calls are stored before anything is shown, so a restarted process picks a run up where it stopped. Its built-in tools (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 a MirageExecutionEnv 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

Give MirageExecutionEnv 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. sessionId names a session on the server, created on first use.
  • id defaults 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 a cd or export does not carry over to the next one, as with a new process.
  • Sessions: pass sessionId to 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 /tmp as 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