Introduction

omp-spt is the native Oh My Pi adapter for Spacetime (spt-core). It gives named Spacetime endpoints a real OMP terminal session rather than translating OMP through another interface.

The adapter supports the two hostable agent roles that belong in an interactive OMP session:

ReadyAgent stays reachable for direct messages in its native OMP TUI.
LiveAgent uses the same native endpoint and also activates the live-agent Psyche lifecycle.

There is no plugin installation step. Install OMP and spt-core, then install the BigscreenVR/omp-spt adapter release.

Mental model

Three components share the work:

spt-core endpoint lifecycle
        |
        | launch, resume, attach
        v
native OMP process
        |-- owns the broker PTY and attachable TUI
        `-- loads adapter/strings/omp-spt.mjs
                    |
                    `-- bind, delivery, activity state, replies, shutdown

spt-core owns endpoint records, messaging, lifecycle coordination, subnet reachability, adapter installation, and updates.
Native OMP owns the hosted process, interactive terminal, model turn, tools, and transcript.
omp-spt supplies the launch and transcript helpers plus the packaged OMP extension that connects native OMP events to spt-core.

The release artifact is one fat adapter.spt archive. It contains the supported adapter binaries, the manifest, and the shared adapter/strings/omp-spt.mjs extension, so installation and updates move as one unit.

What the extension does

When OMP starts a hosted session, the extension binds the OMP session id to the named Spacetime endpoint and starts message delivery. Incoming messages are queued into OMP turns. OMP’s assistant response is sent back to the original sender, and the endpoint moves between busy and idle as the turn runs. When the TUI shuts down, the extension ends the bound session and releases its listener.

The result is still normal OMP. You attach to OMP’s own TUI, and OMP remains in direct control of the broker PTY.

Start with the Quickstart. For event-by-event behavior, read the Native integration contract.

Quickstart

Goal: install omp-spt, create a named endpoint, and attach to its native OMP TUI.

1. Install the prerequisites

You need Oh My Pi 16.3.15 or newer and spt-core. There is no plugin installation step.

The v0.2.0 omp-spt release supports x86_64 Windows and x86_64 Linux only. Its archive has no macOS or Arm64 adapter payload.

PowerShell (x86_64 Windows)

if (-not (Get-Command omp -ErrorAction SilentlyContinue)) { irm https://omp.sh/install.ps1 | iex }
if (-not (Get-Command spt -ErrorAction SilentlyContinue)) { irm https://sabermage.github.io/spt-releases/install.ps1 | iex }

bash (x86_64 Linux / Git Bash on x86_64 Windows)

command -v omp >/dev/null 2>&1 || curl -fsSL https://omp.sh/install | sh
command -v spt >/dev/null 2>&1 || curl -fsSL https://sabermage.github.io/spt-releases/install.sh | sh

Open a fresh shell if either installer updated your PATH, then verify both commands:

omp --version
spt --version

omp-spt requires Oh My Pi 16.3.15 or newer and spt-core 0.31.0 or newer. If either version check reports an older release, run omp update or spt update as appropriate, open a fresh shell if needed, and repeat both checks before installing the adapter.

2. Install the adapter

spt adapter add --release BigscreenVR/omp-spt

This installs one fat adapter.spt release for the supported x86_64 Windows and Linux targets. The archive includes their adapter binaries, the manifest, and the packaged OMP extension.

3. Create and attach to an endpoint

Choose a stable endpoint id. This example uses librarian:

spt endpoint run --adapter omp-spt --id librarian --create

For another name, use the canonical form spt endpoint run --adapter omp-spt --id <id> --create and replace <id>.

The command launches OMP with adapter/strings/omp-spt.mjs and attaches your terminal directly to OMP’s native TUI. Native attach is the default. ReadyAgent and LiveAgent are the supported hostable roles.

During bring-up, the extension:

binds the OMP session id to the Spacetime endpoint;
marks the endpoint idle and starts delivery;
submits each incoming message as an OMP turn;
sends OMP’s response to the original sender; and
ends the binding when the native TUI shuts down.

You now have a named endpoint in the standard Spacetime messaging and lifecycle model. Use the spt-core documentation for endpoint rosters, messaging, subnets, and other public commands.

4. Update later

spt adapter update omp-spt

OMP loads the packaged extension fresh on endpoint bring-up. Restart an already running endpoint to move it to the updated adapter:

spt endpoint stop librarian
spt endpoint run --adapter omp-spt --id librarian

Next, read the Native integration contract for launch, delivery, reply, failure, and shutdown behavior.

Native integration contract

omp-spt hosts Spacetime endpoints as native Oh My Pi sessions. The authoritative generic adapter and CLI contract remains the spt-core public documentation. This page describes the OMP-specific ownership boundary and lifecycle.

Ownership boundary

Component	Owns
`spt-core`	Endpoint records, adapter resolution, messaging, subnet reachability, lifecycle coordination, and release updates.
Native OMP	The broker PTY, attachable TUI, interactive agent turns, tools, and transcript.
`omp-spt` launch helper	Locating and validating the real OMP executable, then starting or resuming OMP with the packaged extension.
`adapter/strings/omp-spt.mjs`	Binding, delivery, activity state, reply correlation, listener recovery, and session shutdown inside OMP.
`omp-spt` transcript helpers	Per-session history, digest extraction, end-of-session commune summaries, and LiveAgent Psyche turns.

This separation is deliberate. The launch helper gets out of the hosted process path after starting OMP, while OMP remains in direct control of the terminal.

Install and launch

Install the release:

spt adapter add --release BigscreenVR/omp-spt

Create a named endpoint and attach:

spt endpoint run --adapter omp-spt --id librarian --create

The canonical form is spt endpoint run --adapter omp-spt --id <id> --create. Native attach is the default. The command needs no separate start flag.

For a fresh endpoint, the resolved manifest starts the launch helper with the packaged extension. For an existing endpoint, the resume path selects the recorded OMP session and loads the same extension. Both paths leave the user in OMP’s native TUI.

Extension lifecycle

The extension receives the endpoint id from spt-core and responds to native OMP events:

OMP lifecycle point	Adapter action
Session start	Bind the endpoint to OMP’s session id, retain the returned authentication token, mark the endpoint idle, and start its delivery listener.
Incoming Spacetime message	Parse the self-delimiting message envelope, retain its sender, queue it, and submit it to OMP when no other agent turn is active.
Context assembly	Preserve the complete message envelope in the OMP turn so sender and body remain available to the model.
Agent start	Mark the endpoint busy.
Agent end	Extract the assistant response after the delivered message, send it to the original sender from this endpoint id, mark the endpoint idle, and dispatch the next queued message.
Session shutdown	Stop delivery and retry timers, return a failure outcome for pending messages, end the bound session, and clear the OMP status indicator.

Messages are processed one at a time in arrival order. A message received during an active turn waits in the extension queue rather than interrupting that turn. Every outcome is correlated with the sender carried by its original Spacetime envelope.

Identity and continuity

One hosted TUI has one immutable endpoint and OMP session identity. The extension blocks in-TUI session switches while the Spacetime endpoint is active. End the hosted endpoint first when you want to select a different OMP session.

ReadyAgent and LiveAgent use the same native OMP endpoint and extension. LiveAgent also activates the per-event Psyche role; ReadyAgent does not. History and digests are fetched from the JSONL transcript for the bound OMP session.

Failure behavior

Delivery listener exits are retried with bounded backoff. If binding fails or the listener exhausts its restart budget, the adapter fails closed: it reports the problem in the OMP TUI, returns failure outcomes for pending messages, ends the Spacetime session, and shuts down the hosted TUI. A half-bound endpoint is never presented as healthy.

Updates and packaging

Each release is one fat adapter.spt archive containing the supported adapter binaries and the shared adapter/strings/omp-spt.mjs extension. Update it with:

spt adapter update omp-spt

New endpoint bring-ups load the updated extension. A running endpoint keeps its current hosting path until it is restarted with spt endpoint stop <id> followed by spt endpoint run --adapter omp-spt --id <id>.

Keyboard shortcuts

omp-spt — Native Oh My Pi adapter for Spacetime