---
name: spt-endpoint
description: Hosts an adapterless SPT endpoint perch inside Oh My Pi and reliably surfaces incoming messages through harness background-job completion. Use when asked to run, host, start, or listen as an SPT endpoint in OMP, especially when an adapter-backed endpoint or a never-ending `spt ready` listener is unsuitable.
---

# Adapterless SPT Endpoint in Oh My Pi

Host the current OMP session as an adapterless SPT `ready_agent`. Do not use `spt endpoint run` or `--adapter`.

## Start or replace a perch

1. Read the live CLI contracts first:

   ```powershell
   spt ready --help
   spt endpoint purge --help
   spt api endpoint-info --help
   ```

2. Check `spt endpoint list --json`. If the requested ID already exists:
   - Reuse it when no listener already owns it, even if `spt api endpoint-info <id> --json` reports a non-null adapter. Starting `spt ready` directly takes ownership without requiring the stored adapter metadata to be purged first.
   - If a listener already owns it, stop that listener before replacement.
   - Ask before purging an endpoint not created during this task; adapter metadata alone is not a reason to purge.

3. Determine the home subnet with `spt subnet status`. On a multi-subnet node, select the subnet implied by the project or request; never omit `--subnet` for a new perch.

4. Start two Oh My Pi background Bash jobs using the bundled scripts. Resolve `scripts/` relative to this skill directory.

   Persistent receiver, which owns the perch and appends continuous output:

   ```powershell
   powershell -NoProfile -ExecutionPolicy Bypass -File scripts/receive-stream.ps1 -Id <id> -Subnet <subnet> -OutputPath <state-dir>/<id>.events.log
   ```

   One-delivery watcher, which exits after the log grows and has been quiet for 300 ms:

   ```powershell
   powershell -NoProfile -ExecutionPolicy Bypass -File scripts/watch-delivery.ps1 -OutputPath <state-dir>/<id>.events.log -CursorPath <state-dir>/<id>.events.cursor
   ```

   Set both Bash jobs to `async: true` and `timeout: 0`. Initialize the event log as empty and its cursor as `0` before the first start. The receiver remains running; only the watcher is rearmed.

   Do not use `spt ready <id> --subnet <subnet> --once` until its harness-hosted receive path is repaired: the current CLI returns `READY:<id>` immediately without remaining alive to receive a delivery. Do not pipe through `Select-Object -First 1`; it exits on the first transport fragment and loses the rest.

5. Verify the perch after startup:

   ```powershell
   spt api endpoint-info <id> --json
   spt endpoint list --json
   ```

   Required evidence:
   - `adapter` is `null`.
   - local state has `ready: true`, `alive: true`, and `unbound: false`.

## Receive messages

The persistent receiver writes every output line to the event log. The watcher reads from the byte cursor through the end of the latest quiet burst, advances the cursor, prints the whole burst, and exits. A single-part delivery looks like:

```xml
<EVENT type="msg" from="sender">body</EVENT>
```

A multipart burst can contain several lines:

```xml
<EVENT-PART seq="1/3" id="delivery-id" type="msg" from="sender">first</EVENT-PART>
<EVENT-PART seq="2/3" id="delivery-id" type="msg" from="sender">second</EVENT-PART>
<EVENT-PART seq="3/3" id="delivery-id" type="msg" from="sender">third</EVENT-PART>
```

For multipart output, group fragments by `id`, order them by the numerator in `seq`, verify every fragment through the denominator is present, concatenate their bodies, then interpret or act on the reconstructed message.

After every watcher completion:

1. Parse and present or act on each complete event burst.
2. Immediately rearm only the watcher with the same log and cursor paths.
3. Keep the persistent receiver running for as long as the endpoint should remain reachable.

If the watcher output contains only `READY:<id>`, no message was delivered; rearm the watcher.

## Send from the perch

Read the body from stdin and identify the adapterless perch explicitly:

```powershell
echo Test message from <id>. | spt send <target> --from <id>
```

Require `SENT:<target>` or `QUEUED:<target>` as the send result. For a round-trip test, arm the receiver before sending, ask the target to reply, capture the `<EVENT>`, then rearm.

## Stop

When explicitly asked to stop the perch, cancel the active OMP receiver job and run:

```powershell
spt endpoint stop <id>
```

Purge only when the user requests permanent deletion or when replacing an endpoint created during the current task.