warning: in the working copy of 'tools/omp-spt/Cargo.lock', LF will be replaced by CRLF the next time Git touches it diff --git a/CHANGELOG.md b/CHANGELOG.md index c7bf989..051a863 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,46 +1,53 @@ # Changelog All notable user-facing changes to **omp-spt** (the Spacetime adapter for oh-my-pi). The format follows [Keep a Changelog](https://keepachangelog.com/); each release section is the public release body verbatim. > Each release below is keyed to the **adapter version of truth** (the version `spt adapter list` reports and the GitHub release tag). omp-spt starts its own version line at 0.1.0; the sections from [0.17.3] down are the inherited **claude-spt** lineage this project forked from, retained for history. +## [0.3.5] - 2026-07-19 + +> Requires spt-core **v0.31.0 or newer** and Oh My Pi **v16.3.15 or newer**. Update with `spt adapter update omp-spt`, then restart existing endpoints so they load the corrected extension. + +### Fixed +- **Assistant output now stays inside the local OMP conversation.** Receiving a peer message no longer forwards subsequent assistant prose, errors, or shutdown text back to that peer. Outbound messages occur only when the agent or operator explicitly uses `spt send` or the `@<…@>` peer-message shortform, restoring `claude-spt` behavioral parity. + ## [0.3.4] - 2026-07-16 > Requires spt-core **v0.31.0 or newer** and Oh My Pi **v16.3.15 or newer**. Update with `spt adapter update omp-spt`, then restart existing endpoints so they load the new extension and skills. ### Added - **An ordinary OMP session can now become a ready or live SPT endpoint in place.** Native `/ready` and `/live` commands select or create endpoint identity, while `/live --auto` offers the most-recent compatible live identity for explicit confirmation; the extension owns the listener, so the agent never has to run a background poll. - **Live endpoints stay reachable during long turns and after interrupted work.** Accepted peer messages enter at the next safe tool or model boundary, retain ordered custody when no boundary appears, and restore honest receivability after cancellation, interruption, or failure. - **OMP now ships native commune, signoff, role, and setup skills.** Commune includes an OMP-native checkpoint mode that saves continuity, compacts context, and wakes the same endpoint; setup diagnoses versions, activation, GitHub transport, and subnet onboarding. - **Activated sessions now teach the SPT surface directly.** Startup guidance, targeted hints, and compatible-update notices cover identity, roster, messaging, lifecycle, continuity, versions, and subnet operations without duplicating public `spt` commands as skills. - **Assistant output can send peer messages with `@`.** The extension dispatches only the explicit shortform, excludes code blocks and ordinary mentions, and reports each target's delivery result. - **The release now includes a static Linux x86-64 musl helper compatibility tier.** Windows MSVC, GNU Linux, and static-musl Linux helpers ship together in one deterministic `adapter.spt`. ### Fixed - **Hosted messaging no longer tears down the listener when a peer reply mentions `` literally.** The frame parser tolerates non-frame `` text inside a message while still rejecting a genuinely nested valid frame, and decodes both published `
` and legacy `
` newline forms. ### Changed - **Release truth is now mechanically enforced.** The manifest version drives helper, plugin, changelog, and public-doc versions; deterministic documentation drift checks gate GitHub Pages publication; each supported target has schema-validated, digest-bound native acceptance evidence. ## [0.2.1] - 2026-07-15 > Requires spt-core **v0.31.0 or newer** for identity-preserving listener authentication. Run `spt update`, then `spt adapter update omp-spt`, and restart each endpoint. ### Fixed - **Starting or resuming an endpoint now records exactly one OMP session in endpoint history.** The listener continues from the already-bound native OMP session instead of registering a second synthetic `boot` session, so resume selection and session metadata remain tied to the real OMP transcript. ## [0.2.0] - 2026-07-14 > Native OMP cutover. Requires spt-core **v0.29.0 or newer** and Oh My Pi **v16.3.15 or newer**. If OMP is older, run `omp update` before launching an endpoint. Update the adapter with `spt adapter update omp-spt`, then restart each endpoint so it loads the packaged extension and helper from this release. ### Added - **Every endpoint now remains a real, attachable OMP session.** Ready and live endpoints use the same native OMP launch path, so an unattended endpoint can still be attached later without losing OMP's normal terminal interface. - **Inbound peer messages now arrive as ordinary OMP turns with full SPT context.** The visible prompt is a safe sender stub, while the complete event envelope is supplied to that turn as context; peer text cannot accidentally invoke a slash command. - **OMP profile-aware session tools.** History, digest, echo-commune, and Psyche session lookup now follow OMP's profile and configuration precedence, including deterministic exact-id and prefix handling. ### Changed - **The adapter is now OMP-native only.** The inherited Claude Code plugin, hooks, CCS profiles, worker topology, headless RPC bridge, and message-idle translation path are removed. `omp-spt` advertises ReadyAgent and LiveAgent only; Worker remains an intentional capability opt-out. - **Fresh, resumed, and daemon-driven turns validate the real Oh My Pi executable before launch.** Explicit overrides, known install paths, and PATH candidates all receive the same identity probe, so an unrelated `omp` command cannot become the hosted terminal. - **One endpoint stays bound to one OMP session for its lifetime.** In-TUI new, resume, fork, handoff, and branch actions are blocked; stop and relaunch the endpoint to select another native session. - **Commune and signoff drops now live under the project-local `.spt/` directory.** The old harness-specific continuity path is no longer used. diff --git a/SCOPE.md b/SCOPE.md index 28b6f0e..e662a4e 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -1,70 +1,70 @@ # omp-spt scope Status: **locked** (2026-07-14) ## Product `omp-spt` is the OMP-native SPT harness adapter. It starts or resumes a native Oh My Pi TUI inside an spt-core broker PTY and loads a packaged OMP extension that owns messaging and lifecycle integration. The public surface is deliberately narrow: - adapter id and binary: `omp-spt`; - release repository: `BigscreenVR/omp-spt`; - host application: Oh My Pi (`omp`); - endpoint types: `ReadyAgent` and `LiveAgent`; - distribution: one multi-platform `adapter.spt`; - updates: the manifest's `gh_release` avenue. ## In scope 1. **Native hosted sessions** - Fresh and native-resume launch through a validating shim. - OMP remains the terminal owner and renders the attachable TUI. - The extension binds the real OMP session id to the requested endpoint. 2. **Extension-owned delivery** - One serialized custody queue. - Message stub plus the full SPT event context in the same OMP turn. - - Correlated reply or explicit failure for every accepted delivery. + - Assistant output remains local; outbound peer messaging requires explicit CLI or shortform use. - Honest busy/idle state. - Bounded listener restart followed by loud session teardown and OMP shutdown if delivery cannot recover. 3. **Immutable identity** - One OMP session per endpoint lifetime. - In-TUI session switching, branching, creation, and resume are blocked. - A different session requires endpoint stop plus explicit relaunch. 4. **Live continuity** - ReadyAgent and LiveAgent only. - Bounded, per-event OMP Psyche turns; no resident adapter-side Psyche loop. - OMP history, digest, and echo-commune implementations. - Commune and signoff drops under project-local `.spt/`. 5. **Public-contract verification** - Published manifest schema and public `spt api`/CLI surface only. - Minimum spt-core version `0.31.0`, required for identity-preserving listener authentication; v0.29.0 remains the relative continuity-path floor. - Deterministic unit/integration checks plus a same-node native endpoint release gate. 6. **Capability parity** - Extension-native ready/live activation for already-open OMP sessions, including explicit live auto-resume and extension-owned listener custody. - Safe-boundary delivery during active turns and automatic receivability restoration after abnormal turn termination. - Startup briefs, targeted hints, compatible-update notices, packaged commune/signoff/role/setup skills, native checkpoint continuity, and the cross-harness peer-message shortform. - OMP-native provider/profile routing satisfies alternate-routing parity. - Windows x86-64, GNU Linux x86-64, and static Linux x86-64 musl helper targets, each with durable machine-readable release evidence. ## Out of scope - A headless RPC bridge or any second endpoint topology. - Any foreign-harness plugin, hook, context-injection, command launcher, update reconciliation, or model-wrapper compatibility layer. diff --git a/adapter/omp-spt.toml b/adapter/omp-spt.toml index e783cf5..6dee68f 100644 --- a/adapter/omp-spt.toml +++ b/adapter/omp-spt.toml @@ -1,52 +1,52 @@ # omp-spt — Oh My Pi harness adapter for spt-core. # # Native OMP owns every hosted terminal. The adapter binary is a launch, # digest/history, Psyche, and echo-commune helper; OMP's packaged extension owns # bind, delivery, activity state, reply, and shutdown inside the native TUI. # This manifest is authored only against the published spt-core manifest and # CLI contracts. See OMP-ADAPTER-PLAN.md and ADRs 0008-0013. [adapter] name = "omp-spt" kind = "harness" -version = "0.3.4" +version = "0.3.5" # v0.31.0 added identity-preserving `api listen --session-id`, which keeps the # listener on the native OMP session already recorded by the extension's bind. min_spt_core_version = "0.31.0" # [impl->REQ-OMP-READY-LIVE] hostable_types = ["LiveAgent", "ReadyAgent"] # Only the genuine OMP host process may resolve to this adapter. host_binaries = ["omp"] shortcut_basename = "omp" # Update through this repository's GitHub release. The packaged fat archive # contains all three supported target binaries plus the shared native plugin. # [impl->REQ-DIST-ADAPTER-RELEASE] [update] avenue = "gh_release" repo = "BigscreenVR/omp-spt" transport = "gh" message = """ **omp-spt updated.** The native OMP extension + extractors refreshed in place — no reload step: OMP loads the packaged extension fresh on each endpoint bringup. - Running endpoints keep the OLD hosting path until restarted: `spt endpoint stop ` then `spt endpoint run --adapter omp-spt --id ` picks up the new one. - Bring up a fresh Librarian endpoint: `spt endpoint run --adapter omp-spt --id --create`. """ [identity] # OMP reports the bound session id after spawn; the process-tree fallback is # the native host executable, never the adapter helper. session_id_source = "post_spawn" parent_ancestor_name = "omp" [session] # [impl->REQ-OMP-CONTINUITY-DROPS] commune_dir = ".spt" signoff_dir = ".spt" # The base manifest is live-capable. ReadyAgent and LiveAgent use the same OMP # endpoint; only LiveAgent activates the per-event Psyche role. diff --git a/docs-site/llms-full.txt b/docs-site/llms-full.txt index 180c149..396fcef 100644 --- a/docs-site/llms-full.txt +++ b/docs-site/llms-full.txt @@ -38,81 +38,81 @@ native OMP process ``` - **`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, manifest, shared native extension, OMP plugin metadata, and packaged commune, signoff, role, and setup skills, 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](./quickstart.md). For event-by-event behavior, read the [Native integration contract](./reference/harness-contract.md). --- # 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](https://github.com/can1357/oh-my-pi/commit/e8d0a93d) and [`spt-core`](https://sabermage.github.io/spt-releases). There is no separate plugin installation step because the adapter release carries its OMP plugin skills. -The v0.3.4 `omp-spt` release supports **x86_64 Windows and x86_64 Linux only**. +The v0.3.5 `omp-spt` release supports **x86_64 Windows and x86_64 Linux only**. Its archive contains Windows MSVC, Linux GNU, and static Linux musl x86_64 helpers, but no macOS or Arm64 payload. The musl helper is a compatibility tier for OMP-capable hosts; it is not a generic Alpine support claim. **PowerShell (x86_64 Windows)** ```powershell 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)** ```bash 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: ```bash 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 ```bash 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, native extension, OMP plugin metadata, and packaged commune, signoff, role, and setup skills. No separate plugin installation is needed. ## 3. Create and attach to an endpoint diff --git a/docs-site/src/quickstart.md b/docs-site/src/quickstart.md index b29e860..d6bf4ad 100644 --- a/docs-site/src/quickstart.md +++ b/docs-site/src/quickstart.md @@ -1,52 +1,52 @@ # 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](https://github.com/can1357/oh-my-pi/commit/e8d0a93d) and [`spt-core`](https://sabermage.github.io/spt-releases). There is no separate plugin installation step because the adapter release carries its OMP plugin skills. -The v0.3.4 `omp-spt` release supports **x86_64 Windows and x86_64 Linux only**. +The v0.3.5 `omp-spt` release supports **x86_64 Windows and x86_64 Linux only**. Its archive contains Windows MSVC, Linux GNU, and static Linux musl x86_64 helpers, but no macOS or Arm64 payload. The musl helper is a compatibility tier for OMP-capable hosts; it is not a generic Alpine support claim. **PowerShell (x86_64 Windows)** ```powershell 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)** ```bash 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: ```bash 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 ```bash 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, native extension, OMP plugin metadata, and packaged commune, signoff, role, and setup skills. No separate plugin installation is needed. ## 3. Create and attach to an endpoint diff --git a/docs/CI.md b/docs/CI.md index eeadaac..64a9457 100644 --- a/docs/CI.md +++ b/docs/CI.md @@ -25,93 +25,94 @@ node tests/omp-extension.mjs These are binary pass/fail checks. A release run must treat any `SKIP` caused by a missing interpreter, Rust toolchain, platform binary, or `traceable-reqs` installation as an incomplete gate, provision the dependency, and rerun. The archive test may intentionally prove that the packer refuses missing target binaries, but a release still needs all three target builds before packaging. The live acquisition integration intentionally skips unless `OMP_SPT_ACCEPTANCE=1`; after opt-in, missing release version, target, tools, or GitHub authentication are failures. Its hermetic central-gate test opts in and exercises those fail-closed paths without network access. ## Native OMP release acceptance ADR-0013 sets the release boundary. The supported helper targets are **x86_64 Windows** (`x86_64-pc-windows-msvc`), **x86_64 GNU Linux** (`x86_64-unknown-linux-gnu`), and a static **x86_64 musl Linux** compatibility tier (`x86_64-unknown-linux-musl`). The asset has no macOS or Arm64 payload. Acceptance must use the exact tagged candidate `adapter.spt`, a real `omp` installation, the native packaged extension, and disposable endpoint identities. Complete the full acceptance sequence independently on all three targets before promotion. Do not reuse an operator's long-lived endpoint id. Install the tagged candidate on each acceptance host and verify its manifest version: ```sh spt adapter add --release BigscreenVR/omp-spt --tag vX.Y.Z spt adapter version omp-spt ``` The version command must print exactly `X.Y.Z`. Then record target-specific evidence for every item below; a pass on one target cannot stand in for either of the others. ### musl selected-helper boundary Under [ADR-0019](adr/0019-musl-acceptance-follows-selected-helper.md), the musl record must come from a disposable OMP-capable host where spt-core selects `x86_64-unknown-linux-musl/omp-spt` from the tagged archive and the installed helper digest exactly matches that member. The base distribution may use glibc; helper selection and native execution, not distribution branding, define this adapter seam. Record `target: x86_64-unknown-linux-musl`, native `spt --version` and `omp --version` output, tagged acquisition, and the same endpoint evidence required below. This is a helper compatibility tier, not a claim of generic Alpine support. Manually executing the static helper does not qualify, and neither does a container where real OMP is absent. ### 1. Fresh bringup and attached TUI ```sh spt endpoint run --adapter omp-spt --id omp-spt-accept-fresh --create ``` The default action attaches the terminal. Pass only if the broker-held terminal displays the real interactive OMP TUI, the packaged `adapter/strings/omp-spt.mjs` extension binds `omp-spt-accept-fresh`, and the endpoint becomes reachable. Do not add a background-start flag: the attached native TUI is part of this proof. -### 2. Same-node message, turn, correlated reply, and state +### 2. Same-node message, turn, explicit reply, and state From a second terminal on the same node: ```sh -printf 'Reply with exactly OMP-SPT-ACCEPTED after reading this message.' | +printf 'After reading this message, explicitly send exactly OMP-SPT-ACCEPTED to the sender using spt send or the peer-message shortform.' | spt ring omp-spt-accept-fresh --timeout 120 ``` Pass only if: - the delivery becomes one ordinary OMP user turn containing the sender stub and complete SPT event context; - the TUI visibly runs that turn; -- `spt ring` prints the assistant's reply for that request, proving sender correlation; and -- `spt endpoint list --json` shows the endpoint move from idle to busy for the turn and back to idle after the reply. +- `spt ring` prints `OMP-SPT-ACCEPTED`, proving the agent used an explicit outbound messaging action; +- ordinary assistant prose visible in the TUI is not forwarded to the sender; and +- `spt endpoint list --json` shows the endpoint move from idle to busy for the turn and back to idle after completion. -This is an end-to-end custody check, not a check for model wording alone. A rejection or turn failure must return an explicit failure outcome to the sender rather than silently dropping the request. +This is an end-to-end delivery and explicit-messaging check. Turn failure, submission failure, and shutdown must remain local rather than synthesizing an outbound peer message. ### 3. Immutable in-TUI binding and native resume Record the bound OMP session id. While the endpoint is running, attempt OMP's in-TUI new-session and resume/switch actions. Both must be blocked with an `omp-spt` warning, and the bound session id must remain unchanged. End the endpoint gracefully, then bind a new disposable endpoint explicitly to the recorded OMP session: ```sh spt endpoint shutdown omp-spt-accept-fresh spt endpoint run --adapter omp-spt --id omp-spt-accept-resume --resume ``` Pass only if this launches OMP's native resume path into an attached TUI, preserves the prior transcript, and binds the new endpoint to the requested session. In-TUI switching stays blocked after resume. Native resume happens at endpoint launch, never by moving a running endpoint to another session. ### 4. ReadyAgent and LiveAgent Exercise both hostable roles through spt-core's current ReadyAgent and LiveAgent flows: - **ReadyAgent:** the native OMP endpoint binds, listens, receives a same-node request, replies, and shuts down without requiring a daemon-driven Psyche turn. - **LiveAgent:** the same native OMP hosting path remains attached and reachable while the daemon drives the manifest's bounded `psyche-omp` role; a Psyche event completes successfully, and normal message/turn/reply behavior still works afterward. Pass only if `omp-spt` advertises exactly ReadyAgent and LiveAgent and both use the native OMP endpoint. A Worker or an alternate hosting process is not an accepted adapter role. ### 5. Graceful shutdown ```sh spt endpoint shutdown omp-spt-accept-resume ``` Pass only if the extension ends the SPT session, reaps its listener, clears its TUI status, and the endpoint is no longer advertised as online. There must be no false-online endpoint and no orphaned acceptance process. ## Adapter release boundary Cross-node transport is outside the `omp-spt` release gate. Once the exact message contract succeeds through the adapter on one node, subnet routing adds no OMP-specific seam and belongs to spt-core. A cross-node check may be useful for spt-core qualification, but it must not replace or block the same-node adapter acceptance above. -Release evidence must identify the candidate `vX.Y.Z` tag and asset, OMP and spt-core versions, disposable endpoint ids, fresh and resumed OMP session ids, gate outputs, state transitions, correlated reply, both role outcomes, and final shutdown result separately for `x86_64-pc-windows-msvc`, `x86_64-unknown-linux-gnu`, and a host where spt-core selected the `x86_64-unknown-linux-musl` helper. Each target needs its own machine-readable release record; the musl record remains invalid if it omitted selected-member digest equality or any native endpoint check. +Release evidence must identify the candidate `vX.Y.Z` tag and asset, OMP and spt-core versions, disposable endpoint ids, fresh and resumed OMP session ids, gate outputs, state transitions, explicit messaging reply, both role outcomes, and final shutdown result separately for `x86_64-pc-windows-msvc`, `x86_64-unknown-linux-gnu`, and a host where spt-core selected the `x86_64-unknown-linux-musl` helper. Each target needs its own machine-readable release record; the musl record remains invalid if it omitted selected-member digest equality or any native endpoint check. diff --git a/docs/DOCS-STRATEGY.md b/docs/DOCS-STRATEGY.md index c75f34f..a584732 100644 --- a/docs/DOCS-STRATEGY.md +++ b/docs/DOCS-STRATEGY.md @@ -44,84 +44,84 @@ the `omp-spt` identity. the mdBook build must be reproducible and checked against committed output. ## Information architecture Order the public site by the user's journey. Put a runnable success first, then concepts in dependency order, then complete reference. ### 1. Start here - **Introduction:** what `omp-spt` does and the OMP / spt-core ownership boundary. - **Requirements:** supported spt-core floor, supported hosts, and an installed native OMP. - **Quickstart:** install the release adapter, create endpoint `atlas`, and attach to its native TUI. ### 2. Install and update - Install from the `BigscreenVR/omp-spt` GitHub release. - Explain that the default release asset is one multi-platform `adapter.spt`. - Update the registered adapter and restart an endpoint when it must pick up the new hosting payload. - Troubleshoot registration, version-floor, archive-selection, and executable-resolution errors. ### 3. Run native OMP endpoints - Create and launch a fresh endpoint. - Attach to, detach from, stop, and relaunch the broker-held native TUI. - Resume an existing OMP session through endpoint launch. - Explain the immutable binding: one SPT endpoint owns one OMP session for its lifetime, so a different session requires a stop and explicit relaunch. ### 4. Use hostable roles - Describe `ReadyAgent` and `LiveAgent` as the only hostable roles. - Show how both roles use the same native OMP endpoint. - Explain the daemon-driven Psyche behavior that distinguishes `LiveAgent`. - State why OMP subagents are not advertised as separately hostable endpoints. ### 5. Message an endpoint - Use the public spt-core send and roster surfaces. -- Trace one inbound message through serialized extension delivery, one OMP turn, and the - correlated reply to its sender. -- Document busy and idle activity, queued delivery, explicit failure replies, listener recovery, - fail-closed shutdown, and graceful session end. +- Trace one inbound message through serialized extension delivery and one OMP turn. +- Show that assistant output remains local and that replies require an explicit CLI or shortform action. +- Document busy and idle activity, queued delivery, listener recovery, fail-closed shutdown, and + graceful session end. ### 6. Preserve continuity and inspect records - Explain commune and signoff drops in project-local `.spt/`. - Document endpoint-qualified continuity filenames without treating them as OMP configuration. - Show the difference between opaque single-session history and the bounded digest view. - Keep resume, continuity, history, and digest examples tied to the same immutable session ID. ### 7. Adapter and release reference - Manifest reference for `[adapter]`, `[update]`, `[identity]`, `[session]`, `[history]`, `[digest]`, environment injection, and shared strings. - Extension reference for bind, message custody, context injection, correlated replies, activity, session-switch refusal, recovery, and shutdown. - `adapter.spt` reference for the root manifest, `strings/omp-spt.mjs`, and supported host binaries. - Release verification checklist and the explicit adapter / spt-core boundary. Each major capability can use the same internal sequence when it needs more than one page: `Overview -> Tutorial -> How-to -> Reference -> Explanation`. Do not force all five page types when one concise page is clearer. ## Canonical quickstart examples Install the adapter from its release repository: ```bash spt adapter add --release BigscreenVR/omp-spt ``` Create and launch a native endpoint: ```bash spt endpoint run --adapter omp-spt --id atlas --create ``` Attach to the same native OMP TUI from another terminal: ```bash spt rc atlas diff --git a/docs/KNOWN-HAZARDS.md b/docs/KNOWN-HAZARDS.md index 0e468b0..a3df1f8 100644 --- a/docs/KNOWN-HAZARDS.md +++ b/docs/KNOWN-HAZARDS.md @@ -1,63 +1,61 @@ # Known hazards This is the OMP adapter's conformance checklist. Each entry states a failure mode, the invariant that prevents it, the evidence boundary, and its source. An invariant is not covered merely because it is described here: the active requirement must point at production behavior and a focused test. -## 1. Delivery custody can be lost or mis-correlated +## 1. Delivery custody can be lost or assistant output can leak to a peer - **Failure:** Two SPT deliveries overlap, the active sender is overwritten, or - OMP rejects a submitted message after the listener has already accepted it. - The wrong peer can receive the next answer, or one accepted message can - disappear with no terminal outcome. -- **Invariant:** The extension serializes deliveries. From receipt until - completion it owns the sender, full event, submitted OMP turn, and terminal - outcome as one custody record. It advances only after sending either the - correlated answer or an explicit failure to that sender. Submission failure - is never treated as a successful empty answer. + ordinary assistant output is implicitly forwarded to a peer. +- **Invariant:** The extension serializes deliveries from receipt through their + OMP turn and releases each custody record on completion. It never converts + assistant output, turn failure, submission failure, or shutdown text into an + outbound peer message. Outbound messaging occurs only through explicit + `spt send` use or the `@<…@>` shortform. - **Mapping / notes:** The native OMP extension owns receipt, queueing, - `sendUserMessage`, turn completion, and reply. The ordinary OMP turn receives - a short message stub plus the full event context; peer content is never + `sendUserMessage`, and turn completion. The ordinary OMP turn receives a + short message stub plus the full event context; peer content is never submitted as a local slash command. - **cite:** ADR-0010 and the OMP extension lifecycle contract. ## 2. A dead listener leaves a healthy-looking but unreachable endpoint - **Failure:** The SPT listener exits while OMP remains open and bound. If the extension retries forever or merely logs the exit, the endpoint can stay advertised as online while no message can reach it. - **Invariant:** Unexpected listener exit triggers only a finite, deterministic restart schedule. A successful restart resumes delivery with custody intact. Exhausting the schedule performs SPT session-end and shuts down OMP loudly. There is no infinite restart loop and no healthy advertisement after the delivery path is gone. - **Mapping / notes:** Retry timers are extension-owned and cancellable during normal shutdown. The exhausted path uses the same serialized teardown seam as an explicit endpoint stop. - **cite:** ADR-0010; field issue HIGH-2/HIGH-4 successor invariant. ## 3. In-TUI session switching breaks endpoint identity - **Failure:** A bound endpoint switches, branches, creates, or resumes another OMP session from inside the TUI. The stable SPT endpoint id then points at a different transcript than queued messages, replies, history, digest, and durable mind state expect. - **Invariant:** One endpoint owns exactly one OMP session for its lifetime. The extension blocks every in-TUI action that would change that session. Selecting another session requires stopping the endpoint and relaunching it with the explicit native-resume role, producing a new deliberate bind. - **Mapping / notes:** This is stricter than merely rebinding on a session event. A rebind would preserve liveness while violating custody and history identity, so it is not an allowed recovery. - **cite:** ADR-0011. ## 4. The `omp` basename resolves to the wrong executable diff --git a/docs/PARITY.md b/docs/PARITY.md index 7affc01..7b5be77 100644 --- a/docs/PARITY.md +++ b/docs/PARITY.md @@ -1,145 +1,145 @@ # omp-spt capability parity record > This record compares `omp-spt` with its sister adapter, `claude-spt`. > Parity means the same user outcome, including agent-facing outcomes, through > the best OMP-native seam or a discoverable public `spt` command. It does not > require Claude command names, hooks, PTY translation, or source structure. > Worker endpoints remain intentionally excluded. ## Versioned comparison baseline -Current baseline: `omp-spt v0.3.4` → `SaberMage/claude-spt v0.21.0`. -`omp-spt` v0.2.1 was published at 2026-07-15 10:58:45 UTC. The first repository commit -after that release, `99287a24b8192dc280ad9baed84c2a15e6578d12`, landed at -2026-07-15 11:10:09 UTC and fixes the start of the work interval that produced v0.3.4. -`claude-spt` v0.21.0 was the latest published sister release at that instant, published from -`SaberMage/claude-spt` at 2026-07-15 08:48:31 UTC. The sister release lineage moved to -`BigscreenVR/claude-spt-bs` beginning with v0.22.0, after this parity baseline was fixed. - -This baseline identifies the exact sister behavior used to define v0.3.4 parity. It is not a +Current baseline: `omp-spt v0.3.5` → `BigscreenVR/claude-spt-bs v0.25.1`. +`omp-spt` v0.3.4 was published at 2026-07-16 10:48:22 UTC. The first repository commit +after that release, `413d6908d3a514edf93e0e53d4fb1f4b46ff7269`, landed at +2026-07-19 09:49:10 UTC and fixes the start of the work interval that produced v0.3.5. +`claude-spt-bs` v0.25.1 was the latest published sister release at that instant, published from +`BigscreenVR/claude-spt-bs` at 2026-07-19 04:55:53 UTC. + +This baseline identifies the exact sister behavior used to define v0.3.5 parity. It is not a claim that later `claude-spt` capabilities are covered. Any subsequent feature-parity work must first select and record the exact published `claude-spt` release being consulted. Every parity-informed `omp-spt` release must update this baseline to its own version; the release version-consistency gate rejects a stale `omp-spt` baseline. ## Proven shared endpoint surface The current adapters already share release install/update, broker-hosted fresh launch and attachment, native resume, ReadyAgent and LiveAgent roles, -post-spawn identity, inbound delivery and correlated replies, busy/idle +post-spawn identity, inbound delivery, explicit outbound messaging, busy/idle lifecycle, graceful shutdown, Psyche turns, commune/signoff storage, echo-commune, opaque history, digest extraction, and Windows x86-64 plus GNU Linux x86-64 release payloads. OMP keeps its stronger native invariants: immutable endpoint/session binding, one bounded custody queue, finite listener recovery, fail-closed exhaustion, -real OMP executable validation, and explicit failures rather than silent empty -outcomes. Capability parity does not weaken those guarantees. +real OMP executable validation, and strict separation between local assistant +output and explicit outbound peer messaging. Capability parity does not weaken +those guarantees. ## Agent-facing parity decisions Ordinary OMP sessions gain extension-native `/ready` and `/live` activation commands with argument completion or native selection dialogs. Explicit live auto-resume selects the most-recent compatible live identity; ordinary activation never guesses silently. The extension binds the current session and owns the authenticated listener, after which binding is immutable. Messages accepted during an active OMP turn enter at the first proven boundary before the next tool or model continuation. Custody and arrival order remain intact; a turn with no injectable boundary falls back to ordinary next-turn delivery rather than interruption. Cancelled, interrupted, and failed turns settle affected custody and restore receivability automatically. Only exhausted listener recovery closes the endpoint. Activated sessions receive a concise startup brief for identity, roster, messaging, continuity, lifecycle, subnet, version, and update operations. Targeted hints cover clear live-activation, identity, messaging, subnet, and checkpoint intent. Available compatible spt-core or adapter updates produce an actionable notice. Public OMP `omp-plugins` packaging supplies model-driven skills for commune, signoff, and durable-role inspection/editing. Commune checkpoint mode saves continuity, resets OMP context through native session APIs, and wakes the same endpoint without operator intervention. Setup is hybrid: an extension-native command owns deterministic probes and activation, while a packaged skill owns diagnosis, repair strategy, published installer use, subnet onboarding, and explicit operator handoffs for authentication or elevation. Assistant output may dispatch the explicit cross-harness peer-message shortform `@`. Ordinary `@` mentions have no side effect. Normal outbound messaging, roster, stop/shutdown, version, and subnet commands are taught through setup or startup context rather than duplicated as skills. OMP's native provider/profile routing satisfies alternate provider, account, and model routing parity; no `omp-spt:` analogue of Claude's CCS overlay is required. ## Release-target parity The supported target set is Windows x86-64 MSVC, GNU Linux x86-64, and a static Linux x86-64 musl helper compatibility tier for OMP-capable hosts where the GNU helper is incompatible. The musl tier requires full native endpoint acceptance on a representative target host; it does not imply generic Alpine support when OMP itself is unavailable. Neither sister adapter packages macOS or Arm64, so those remain explicit shared limitations rather than current parity gaps. The manifest version is canonical. Release gates reject disagreement in the helper crate, changelog heading, and versioned public documentation. Deterministic local documentation generation and drift checks gate changes. GitHub Pages publication runs the same gate before publishing. Each supported target retains a machine-readable release record naming the target, source commit and tag, artifact digests, acquisition result, and native -fresh/resume, message/reply, lifecycle, shutdown, and ReadyAgent/LiveAgent -acceptance outcomes. +fresh/resume, message/explicit-reply, lifecycle, shutdown, and +ReadyAgent/LiveAgent acceptance outcomes. ## Explicit non-goals - Worker endpoint advertisement or OMP-subagent endpoint topology. - macOS, Arm64, or 32-bit release payloads in this parity program. - A CCS adapter overlay where native OMP provider/profile routing supplies the same outcome. - Claude hooks, PTY translation, plugin reconciliation, or model-managed background polling. - Claude's retired `>>commune<<` output marker. - Public support promises for the helper binary's manifest-role subcommands. - Separate skills for send, roster, stop, version, or subnet. ## Delivery order Coverage lands in dependency order: 1. repair version and documentation truth, then prove packaged-skill discovery and injectable OMP event seams; 2. implement extension-owned ready/live activation, live auto-resume, safe-boundary delivery, and abnormal-turn receivability; 3. add startup briefs, targeted hints, update notices, packaged skills, checkpoint continuity, hybrid setup, and peer-message shortform; 4. add the musl target and durable machine-readable acceptance records for all supported targets. diff --git a/docs/adr/0010-native-delivery-self-heals-or-closes.md b/docs/adr/0010-native-delivery-self-heals-or-closes.md index 21a1dce..8c4a624 100644 --- a/docs/adr/0010-native-delivery-self-heals-or-closes.md +++ b/docs/adr/0010-native-delivery-self-heals-or-closes.md @@ -1,10 +1,10 @@ # Native delivery self-heals or closes the endpoint Status: accepted (2026-07-14) -The OMP SPT extension owns delivery custody from receipt through a correlated answer or explicit failure reply. If OMP rejects a submitted message, the extension reports the failure to that sender and advances the serialized queue; it never silently drops the message. If the SPT listener exits, the extension retries with bounded backoff. Exhausting that budget ends the SPT session and shuts down the hosted endpoint loudly, preventing a dead delivery path from remaining advertised as healthy. +The OMP SPT extension owns delivery custody from receipt through one serialized OMP turn, then releases it without creating an outbound message. Assistant output, submission errors, failed turns, and shutdown text remain local; a model or operator sends to a peer only through explicit `spt send` use or the `@<…@>` shortform. If the SPT listener exits, the extension retries with bounded backoff. Exhausting that budget ends the SPT session and shuts down the hosted endpoint loudly, preventing a dead delivery path from remaining advertised as healthy. Normal peer delivery uses the native OMP message-stub contract: the extension opens the turn with `` and supplies the complete SPT event envelope as context for that same turn. Peer text therefore remains opaque message content and cannot accidentally invoke an OMP slash command. diff --git a/tools/omp-spt/Cargo.lock b/tools/omp-spt/Cargo.lock index 7258d41..65f6273 100644 --- a/tools/omp-spt/Cargo.lock +++ b/tools/omp-spt/Cargo.lock @@ -3,81 +3,81 @@ version = 4 [[package]] name = "cfg-if" version = "1.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" [[package]] name = "getrandom" version = "0.3.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd" dependencies = [ "cfg-if", "libc", "r-efi", "wasip2", ] [[package]] name = "itoa" version = "1.0.18" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" [[package]] name = "libc" version = "0.2.186" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66" [[package]] name = "memchr" version = "2.8.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4" [[package]] name = "omp-spt" -version = "0.3.4" +version = "0.3.5" dependencies = [ "getrandom", "serde_json", ] [[package]] name = "proc-macro2" version = "1.0.106" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934" dependencies = [ "unicode-ident", ] [[package]] name = "quote" version = "1.0.46" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368" dependencies = [ "proc-macro2", ] [[package]] name = "r-efi" version = "5.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f" [[package]] name = "serde" version = "1.0.228" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e" dependencies = [ "serde_core", ] [[package]] name = "serde_core" diff --git a/tools/omp-spt/Cargo.toml b/tools/omp-spt/Cargo.toml index e716bd6..322761c 100644 --- a/tools/omp-spt/Cargo.toml +++ b/tools/omp-spt/Cargo.toml @@ -1,20 +1,20 @@ # OMP-native adapter helper. One dependency-light binary serves launch, # digest/history, Psyche, and echo-commune roles on Windows and Linux. # [impl->REQ-DIST-BINARY-CONSOLIDATE] [package] name = "omp-spt" -version = "0.3.4" +version = "0.3.5" edition = "2021" publish = false [[bin]] # The package and executable share the public adapter identity. name = "omp-spt" path = "src/main.rs" [dependencies] getrandom = "0.3" serde_json = "1" [profile.release] strip = true diff --git a/traceable-reqs.toml b/traceable-reqs.toml index 496dbbd..db7d0b0 100644 --- a/traceable-reqs.toml +++ b/traceable-reqs.toml @@ -39,81 +39,81 @@ roots = [ "ci/manifest/validate_manifest.py", "ci/publish/package-adapter.sh", "ci/publish/release-acquire-int.sh", "ci/digest/build.sh", "ci/digest/digest-proof-int.sh", "docs/RELEASE-RUNBOOK.md", "docs-site/README.md", "docs-site/src/reference/release-evidence.md", ".github/workflows/docs-pages.yml", "ci/docs/build-docs.py", "ci/release/check-version-consistency.py", "ci/release/validate-release-evidence.py", "ci/run-gates.sh", "tests/docs-gate.py", "tests/release-evidence.py", "tests/version-consistency.py", ] [policy] required_stages = [] [[requirements]] id = "REQ-OMP-NATIVE-TUI" title = "The hosted launch contract hands validated OMP its packaged extension as the broker PTY process" required_stages = ["doc", "impl", "unit", "int"] # Intentionally inactive until an actual release runs the ADR-0013 acceptance gate. Deterministic # fake-process launch evidence must never satisfy this live endpoint requirement. [[requirements]] id = "REQ-OMP-LIVE-RELEASE-GATE" title = "Pending live gate: a real OMP release must satisfy the ADR-0013 endpoint acceptance criteria" required_stages = [] [[requirements]] id = "REQ-OMP-EXECUTABLE-RESOLUTION" title = "Fresh, resumed, and daemon-driven OMP turns resolve and validate Oh My Pi, reject executable collisions, and fail loudly" required_stages = ["doc", "impl", "unit", "int"] [[requirements]] id = "REQ-OMP-EXTENSION-CUSTODY" -title = "The OMP extension serializes accepted deliveries and preserves sender custody through a correlated reply or explicit failure" +title = "The OMP extension serializes accepted deliveries while outbound peer messages require an explicit CLI or shortform action" required_stages = ["doc", "impl", "unit"] [[requirements]] id = "REQ-OMP-LISTENER-FAIL-CLOSED" title = "Unexpected listener exit retries within a finite budget and then performs SPT session-end plus OMP shutdown" required_stages = ["doc", "impl", "unit"] [[requirements]] id = "REQ-OMP-SESSION-IMMUTABLE" title = "One endpoint owns one OMP session for its lifetime and blocks every in-TUI session-changing action" required_stages = ["doc", "impl", "unit"] [[requirements]] id = "REQ-OMP-MESSAGE-CONTEXT" title = "Each peer delivery opens one ordinary OMP turn containing a message stub and the complete SPT event context" required_stages = ["doc", "impl", "unit"] [[requirements]] id = "REQ-OMP-READY-LIVE" title = "The adapter advertises exactly ReadyAgent and LiveAgent endpoint types on the same native OMP hosting path" required_stages = ["doc", "unit"] [[requirements]] id = "REQ-OMP-CONTINUITY-DROPS" title = "Commune and signoff drops resolve project-locally under .spt on the published v0.29.0 endpoint-cwd contract" required_stages = ["doc", "unit"] [[requirements]] id = "REQ-PSYCHE-EPHEMERAL-SHIM" title = "Each LiveAgent Psyche event runs as one bounded OMP turn with file-backed context and explicit reseed signaling" required_stages = ["doc", "impl", "unit"] [[requirements]] id = "REQ-HISTORY-FETCHER" title = "The history fetcher locates exactly one OMP session and streams its JSONL bytes verbatim" required_stages = ["doc", "impl", "unit"] [[requirements]] id = "REQ-DIST-DIGEST-EXTRACTOR" title = "The OMP digest fetcher maps native session JSONL into the published harness-neutral digest record stream"