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