pi-agent-substrate

Use a persistent remote workspace from Pi or Oh My Pi through Agent Substrate. Keep the local conversation and terminal; run explicit remote file and process tools through the Substrate Environment API.

Capability	Implementation / verification
Pi and Oh My Pi	Separate adapters, one shared client and workspace state machine
Remote files and shell	Verified against the real upstream guest in both harness loaders
Background processes	Start, status, paginated logs, termination, durable tracking
Environment lifecycle	Create, attach, status, suspend, confirmed deletion
Idle suspension	Opt-in; blocked during active calls, tracked jobs, or uncertain process state
Checkpoint/restore proof	Verified end-to-end on a self-hosted kind cluster (suspend to FULL-scope snapshot, resume with filesystem and same-process memory restored); see Verification1

Prerequisites

• Pi 0.86.1 with Node 22.19+ or Oh My Pi 18.2.6 with Bun 1.3.14+.²
• A private Substrate cluster and deployed Environment API. Follow those upstream projects' deployment instructions.
• A working actor template containing ate-env-guest and sh.
• An operator-provided HTTPS endpoint or a loopback tunnel to ate-env-api. Use the root URL, without credentials, path, query, or fragment.

This package does not provision infrastructure. A standalone ate-env-guest supports the guest smoke test, but does not provide environment creation or suspension.

Try the checkout

Run these commands from this package directory in bash or zsh:

bun install --frozen-lockfile

# Choose the installed harness:
pi -e ./src/pi.ts --substrate-endpoint http://127.0.0.1:17777
omp -e ./src/omp.ts --substrate-endpoint http://127.0.0.1:17777

Replace the endpoint with your private service or established tunnel. For an existing environment, add --substrate-env my-workspace on a new session. Otherwise, enter these commands inside Pi or OMP:

/substrate create my-workspace
/substrate status

Ask the agent to use substrate_* tools for remote work. For example: “Use substrate_shell to inspect the remote workspace and substrate_write to create hello.txt there.”

To load the package on subsequent launches, install the local checkout using your chosen harness, then restart it:

# bash/zsh; from this package directory
pi install .
# Or:
omp install .

The package contains both pi.extensions and omp.extensions manifest entries. Do not load both adapters in the same harness. To distribute the local package without publishing it:

npm pack

Commands

In-session command	Use
/substrate create <id> [template]	Create and attach a new environment
/substrate attach <id>	Attach an existing environment
/substrate status	Inspect the environment and saved binding
/substrate suspend	Explicitly pause the environment, including background jobs
/substrate detach	Remove the session binding; retain remote files and processes
/substrate delete <id>	Permanently delete the attached environment after interactive confirmation

Use lowercase DNS-label environment/template IDs, up to 63 characters. Deletion requires the exact attached ID and interactive confirmation; it is unavailable in headless mode.

For normal wake-up, perform the next remote file or process operation. The upstream service handles activation on guest traffic. Environment status inspection alone does not request wake-up.

Tools

Tool	Parameters
substrate_read	Remote path; optional encoding: utf8 or base64
substrate_write	Remote path, complete content; optional encoding
substrate_shell	Shell command; optional remote cwd, background, timeoutSeconds
substrate_process	processId, action: status, logs, or kill; optional stdoutOffset and stderrOffset

Use substrate_shell for remote editing, search, and Git. The remote shell is sh; no local shell execution or file synchronization takes place through these tools.

Files and collected output are bounded to 1 MiB. Read binary content as base64. Foreground shell calls have a maximum duration of 120 seconds. On foreground cancellation, timeout, output overflow, or output failure, the extension attempts to terminate the known remote process. On cleanup failure, inspect its reported process ID before continuing.

For longer jobs, use background: true, then inspect with substrate_process. For output larger than one page, use action: "logs" and the returned byte offsets to retrieve subsequent pages. Logs are UTF-8 text; page boundaries can split a multibyte character. A status or kill operation reconciles completed tracked jobs.

Configuration

Flags override the corresponding environment variables. Set secrets through your normal environment/secret manager before starting the harness, never in a URL or command argument.

Flag	Environment variable	Default
--substrate-endpoint	SUBSTRATE_ENDPOINT	Required when using remote tools
--substrate-atespace	SUBSTRATE_ATESPACE	ate-env
--substrate-env	SUBSTRATE_ENV	No automatic attachment
--substrate-idle-seconds	SUBSTRATE_IDLE_SECONDS	0, disabled
None	SUBSTRATE_TOKEN	No bearer token

Use HTTPS for non-loopback endpoints. Standard TLS certificate verification remains enabled. No token is stored in the session binding. The guest/API must be protected by your network and authentication boundary.³

Idle suspension is an explicit opt-in for an environment dedicated to this session. Set a value between 0 and 86400 seconds. Active operations, tracked processes, or uncertain process starts prevent automatic suspension. Inspect completed processes to reconcile tracking. After a suspension attempt, no new attempt is scheduled until further workspace activity.

Session and isolation boundaries

• Resume the same conversation with the same endpoint and atespace to restore its saved attachment and process tracking. This also works with a custom harness session directory.
• Forked/new sessions do not silently inherit their parent's remote attachment. Attach explicitly when sharing is intentional.
• Detach explicitly before switching away from tracked or uncertain processes. Detachment neither kills nor suspends the environment.
• A lost process-start response is ambiguous: the process may already be running. The extension retains uncertainty and does not replay the command. Inspect the remote environment before explicitly detaching and reattaching.
• Closing the harness does not delete or suspend the remote environment.
• Local built-in tools, local shell shortcuts, other extensions, and subagents remain outside this routing boundary. Use the explicit remote tools consistently. For full-harness isolation, run the harness itself inside the sandbox as a separate deployment.
• Idle tracking covers processes started through these tools. Shell-daemonized descendants and work started by other clients are not discoverable through the current guest API; keep automatic suspension disabled for shared or externally managed environments.

Verification

Run from this checkout in bash/zsh:

bun run check
bun test

For an isolated real upstream guest, with the endpoint already available:

SUBSTRATE_GUEST_ENDPOINT=http://127.0.0.1:17779 bun run smoke:guest

The guest scenario writes disposable files, starts processes, checks output/exit codes and offsets, exercises cancellation and bounds, then removes its successful file fixture. It does not call a model.

For loader/tool verification, set SUBSTRATE_HARNESS_LOADER to the actual installed harness's extensions/loader module and SUBSTRATE_GUEST_ENDPOINT to the same guest. Run node scripts/smoke-harness.ts pi or bun scripts/smoke-harness.ts omp. This uses the real loader and live guest, with a synthetic session context to isolate the test from your normal sessions.

For the remaining full-cluster proof, configure SUBSTRATE_ENDPOINT, optional SUBSTRATE_ATESPACE, and optional SUBSTRATE_TOKEN, then run:

bun run smoke:cluster

The cluster scenario creates a unique environment, writes a file, and starts an in-memory shell counter. It suspends the environment, resumes through guest traffic, and checks the file plus a second increment in the same process. On success it deletes only that disposable environment. On failure it reports the environment ID and retains the environment for inspection.

Machine-readable results: verification.json. Reproduction scenarios: scripts. Protocol source: agent-substrate/env at the pinned revision.

License

Apache-2.0. Vendored upstream protocol notices are preserved; see LICENSE and NOTICE.

Footnotes

1. Real guest file/process operations, harness loading, and the full-cluster suspend/resume proof were verified; the cluster proof ran against a self-hosted kind deployment of Substrate at commit bb0effed with the Environment API at the pinned revision. No suspension-latency or density claims are made. ↩

2. Verification covers the listed Pi release and the recorded OMP source build, not every older or future release. Both extension APIs and the upstream Environment API can change. ↩

3. Upstream Substrate documents authentication without control-plane RBAC. Keep this deployment private and operator-controlled; a client-side namespace is not a tenant-authorization boundary. ↩