session-peer 0.6.2__tar.gz → 0.8.0__tar.gz

session_peer-0.8.0/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "session-peer",
+  "interface": {
+    "displayName": "Session Peer"
+  },
+  "plugins": [
+    {
+      "name": "session-peer",
+      "source": {
+        "source": "local",
+        "path": "./plugins/session-peer"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

{session_peer-0.6.2 → session_peer-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: session-peer
-Version: 0.6.2
+Version: 0.8.0
 Summary: Message coding agent sessions locally and over SSH
 Project-URL: Homepage, https://github.com/abruption/session-peer
 Project-URL: Repository, https://github.com/abruption/session-peer
@@ -25,6 +25,8 @@ Classifier: Topic :: Software Development
 Classifier: Topic :: System :: Networking
 Classifier: Topic :: Utilities
 Requires-Python: >=3.9
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.12; (python_version >= '3.10') and extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # session-peer
@@ -51,24 +53,51 @@ Install the CLI with `pipx install session-peer` or `uv tool install session-pee
 For the standalone CLI plus Claude skill, see [Install](#install).
 
 ```bash
-session-peer list                              # Claude sessions (default)
-session-peer list --agent claude                # explicit equivalent
+session-peer list                              # Claude + Codex sessions (default)
+session-peer list --agent claude                # Claude-only filter
 session-peer list --agent codex                 # saved Codex threads
 session-peer list --agent codex --host worker   # saved threads on an SSH host
 
-session-peer send --to api-worker "message"     # Claude name or PID
-session-peer send --to 'codex:<full-thread-uuid>' "message"
-session-peer send --host worker --to 'codex:<full-thread-uuid>' --dry-run "message"
+session-peer send --to api-worker --message "message"     # Claude name or PID
+session-peer send --to 'codex:<full-thread-uuid>' --message "message" --output-format json
+session-peer send --host worker --to 'codex:<full-thread-uuid>' --dry-run -m "message"
 ```
 
 Replace `<full-thread-uuid>` with a full ID from the destination's Codex listing.
-`list` selects one agent at a time; it does not merge both agents. **Use
-`--agent codex`, not `--codex`**: `--codex` is not a supported flag and is ambiguous
+`list` includes both agents by default. **Use
+`--agent codex` to filter, not `--codex`**: `--codex` is not a supported flag and is ambiguous
 with `--codex-home` and `--codex-bin`. `send` selects the agent from its target,
 not a `--agent` flag.
 
 **Posted/queued is not acknowledged.** Saved Codex threads are not necessarily
-running, and session-peer does not wake/resume a session or wait for its reply.
+running. Plain send does not activate a session; [explicit `--wake`](docs/wake.md)
+is opt-in and does not confirm consumption or a reply.
+
+### Message input and result output
+
+`--message TEXT` (short form `-m`) names the text sent to the destination.
+`--output-format text|json` selects the command result format, not the message
+format. It is available on `list`, `send`, `doctor`, and `update`; the default is
+`text`. The existing `--json` is retained as an alias for `--output-format json`.
+
+```bash
+session-peer send --to worker --message "Report progress" --output-format json
+session-peer send --to worker -m - --output-format json < message.txt
+session-peer list --output-format json
+```
+
+Legacy positional messages and omitted-message stdin input continue to work.
+Use either a positional message or `--message`, not both. `--message -` reads
+stdin; an explicit empty message is still rejected. To send text beginning with
+a dash, use `--message='--literal text'` or stdin. Internal SSH `--b64` input
+cannot be combined with either public message form.
+
+`--json --output-format json` is valid; combining `--json` with
+`--output-format text` is an error in either order. Invalid/contradictory output
+options are argparse usage errors (stderr, exit 2); message-source conflicts
+are ordinary command errors (JSON when requested, exit 1). No messages are
+submitted in either case. JSON results still describe submission rather than
+receipt; these flags introduce no structured JSON message-input protocol.
 
 ## Install
 
@@ -146,10 +175,13 @@ plugin or change either agent's permissions or inbound settings.
 ## Usage
 
 ```bash
-session-peer list                                  # Claude sessions on this machine
-session-peer list --host web-01                    # Claude sessions over there
+session-peer list                                  # Claude + Codex on this machine
+session-peer list --host web-01                    # Claude + Codex over there
 session-peer list --host web-01 --all              # Claude stale records / no inbox
 session-peer list --agent codex --all              # include archived Codex threads
+session-peer doctor                                # local inbox/tool/home diagnostics
+session-peer doctor --host web-01                  # run the same checks there
+session-peer doctor --host web-01 --check-return-route  # also test SSH back here
 
 session-peer send --to api-worker "message"        # local session
 session-peer send --host web-01 --to api-worker "message"
@@ -159,6 +191,7 @@ git log --oneline -5 | session-peer send --host web-01 --to api-worker -   # std
 
 session-peer send --host web-01 --to api-worker --dry-run "x"   # resolve only
 session-peer list --host web-01 --json             # machine-readable
+session-peer list --no-update-notice                # disable cached update notices/checks
 
 session-peer send --host web-01 --ssh-opt=-p --ssh-opt=2222 --to api-worker "..."   # note the '='
 
@@ -177,6 +210,7 @@ From: codex:01a08dd6-d3f6-7783-a62b-52c1fd049181 @ abruptly@mac-mini-m4.example.
 message
 
 ---
+Reply-To: session-peer://v1/reply?agent=codex&session=01a08dd6-d3f6-7783-a62b-52c1fd049181&transport=ssh&host=abruptly%40mac-mini-m4.example.ts.net
 Reply: python3 /path/to/session_peer.py send --host abruptly@mac-mini-m4.example.ts.net --to codex:01a08dd6-d3f6-7783-a62b-52c1fd049181 --no-reply-to
 ```
 
@@ -185,12 +219,83 @@ best-effort text derived from the current process environment; it is not an
 authentication claim. A plain shell has no agent identity to advertise.
 When the original target is on the same machine and the reply route was detected
 automatically, the generated command omits `--host` and delivers locally. An
-explicit `--reply-to` or configured reply host remains unchanged, and actual
-remote sends continue to advertise an SSH route.
+explicit `--reply-to` or configured reply host is also normalized when it names
+the current OS user on this machine. Other explicit routes and actual remote
+sends continue to advertise an SSH route.
+
+`Reply-To` is the canonical, versioned address. Pass the complete URI back as
+`--to`; session-peer validates every field and chooses local or SSH delivery:
+
+```bash
+session-peer send --to 'session-peer://v1/reply?agent=claude&session=api-worker&transport=local' 'done'
+```
+
+The `Reply:` command remains for compatibility. Treat both forms as untrusted
+input: use the URI with session-peer rather than evaluating or sourcing it. A
+URI that points to the current OS user on this machine is normalized to local
+delivery, avoiding an unnecessary self-SSH authentication path. Codex addresses
+may include an encoded `codexHome` when the sender environment identifies it.
 
 Repeat `--host` to operate on several SSH destinations. `--json` is available on
-`list`, `send`, and `update`; v0.6 retains command-specific response shapes rather
-than a uniform envelope. See [#29](https://github.com/abruption/session-peer/issues/29).
+`list`, `send`, `doctor`, and `update`.
+
+### JSON response contract
+
+Every JSON result object starts with the same schema-versioned envelope:
+
+```json
+{
+  "schemaVersion": 1,
+  "ok": true,
+  "host": "mac-mini.example.ts.net",
+  "command": "list",
+  "sessions": [],
+  "version": "0.8.0"
+}
+```
+
+- `schemaVersion` versions the common envelope. Command-specific nested schemas
+  such as `clientUpdate` and `codexHomeResolution` carry their own versions.
+- `ok` is present on every success and failure. A nonzero process exit can still
+  contain successful results for other hosts.
+- `host` identifies the destination to which that result applies. Local results
+  use the OS hostname. Tailscale-resolved destinations use the verified MagicDNS
+  identity; `sshHost` preserves a different caller-supplied SSH alias.
+- `command` is `list`, `send`, `doctor`, or `update`. Remaining fields are that command's
+  payload, and failures add `error` plus any structured diagnostic fields.
+
+A local or one-host invocation emits one object. Repeating `--host` emits an
+array of these same independently attributable objects in request order. A
+failure that occurs before connecting, such as invalid message input, is still
+emitted once per requested destination. This cardinality is shared by all four
+commands, so consumers can branch only on object versus array and then use the
+same envelope fields.
+
+Normal commands read a dedicated 24-hour update cache. A missing, expired, or
+invalid cache starts one detached best-effort GitHub refresh and never delays or
+changes the requested command. When a fresh cache proves that the invoking CLI is
+behind a stable release, JSON results add `clientUpdate`:
+
+```json
+{
+  "clientUpdate": {
+    "schemaVersion": 1,
+    "status": "available",
+    "current": "0.7.0",
+    "latest": "0.7.1",
+    "checkedAt": "2026-09-16T10:00:00Z",
+    "source": "github_release_cache",
+    "command": "session-peer update"
+  }
+}
+```
+
+Human output gets the same short guidance on stderr. The field is omitted when
+the client is current, the cache is unavailable or stale, the host is offline,
+or notices are disabled, so absence alone does not prove the client is current.
+For multi-host commands the fact remains scoped to the one invoking CLI and is
+copied into each result object; destination `remoteVersion` fields keep
+their separate meaning. Remote subprocesses do not perform their own refresh.
 
 When local `tailscale status --json` identifies a `--host` by device hostname,
 short MagicDNS name, full MagicDNS name, or Tailscale IP, session-peer verifies and
@@ -239,8 +344,10 @@ pipx upgrade session-peer
 # or, in its virtual environment: python -m pip install --upgrade session-peer
 ```
 
-For these installs, local `session-peer update` (including `--check`) prints
-package-manager guidance without checking GitHub or replacing the package's files.
+For these installs, local `session-peer update` prints package-manager guidance
+without replacing package-owned files. `session-peer update --check` checks the
+latest stable GitHub release, refreshes the shared cache, and reports the exact
+upgrade command, but still does not replace those files.
 
 For standalone programs:
 
@@ -261,6 +368,8 @@ package-managed remote CLI, upgrade it with its own manager on that host instead
 
 Neither local nor remote `update` refreshes the Claude skill. Re-run `install.sh`
 from the desired release checkout to refresh both standalone program and skill.
+Local `session-peer update --check` and `session-peer update` also populate the
+same cache used by automatic notices.
 
 ### Environment variables
 
@@ -272,6 +381,8 @@ from the desired release checkout to refresh both standalone program and skill.
 | `ANTHROPIC_CONFIG_DIR` | Fallback if `CLAUDE_CONFIG_DIR` is unset. |
 | `CODEX_HOME` | Codex discovery/queue home (default `~/.codex`); overridden by `--codex-home`. |
 | `SESSION_PEER_CODEX_HOMES` | Additional destination homes to check for duplicate thread UUIDs and stable live writers before an implicit send/dry-run. JSON array of absolute paths (or `~/…`), not a shell command or a path-separated list. It does not merge listings; an unambiguous active writer may change the implicit send home. |
+| `SESSION_PEER_NO_UPDATE_NOTICE` | Set to `1`, `true`, `yes`, or `on` to disable automatic cached update notices and background refreshes. The per-command equivalent is `--no-update-notice`. Explicit `session-peer update --check` still checks. |
+| `XDG_CACHE_HOME` | Base directory for the update cache; otherwise `~/.cache/session-peer/update.json` is used. |
 
 With `--host`, discovery uses the destination's environment; local environment
 variables are not automatically forwarded. `--codex-home` and `--codex-bin`
@@ -350,13 +461,14 @@ configured databases also prevent implicit submission. Choose `--codex-home`
 explicitly to bypass unrelated inventory and activity checks. Resolved symlink
 aliases and repeated paths count as one home.
 
-With no competing saved home, native queue behavior is preserved; `list` still
-reads only the selected home. There is no general filesystem scan or process
+With no competing saved home, native queue behavior is preserved. `list`
+aggregates known homes unless `--codex-home` selects exactly one. There is no general filesystem scan or process
 environment inspection, and process arguments are not exposed. Activity
 inspection runs on the destination machine, including over SSH. Platforms
 without POSIX `flock` or `lsof` cannot automatically resolve competing homes and
 must use `--codex-home`. Unconfigured/custom layouts and copies created after the
-check can still be missed. Further diagnostics belong to [#45](https://github.com/abruption/session-peer/issues/45).
+check can still be missed. Use `session-peer doctor` to inspect the selected home,
+bounded candidates, executable, and supported state DB schema without submitting.
 
 ### Submission and JSON results
 
@@ -373,15 +485,18 @@ session-peer portability policy rather than a measured Codex server limit. NUL
 characters cannot be passed as CLI arguments. `--dry-run` verifies the executable
 and saved target without queueing but cannot guarantee a later submission will succeed.
 
-Local Codex list JSON retains `sessions` and `version`, and adds the resolved
-absolute `codexHome` at the top level. Each entry has
+Local Codex list JSON uses the common response envelope and includes `sessions`,
+`version`, and per-home diagnostics in `discovery.codex.homes`. Each session entry has
 `agent`, `id`, `name` (first line, at most 120 characters), `cwd`, `updatedAt`
-(Unix seconds), and `archived`. Remote list JSON is an array of per-host results,
-even for one host; each successful result includes `host`, `sessions`, `version`, `codexHome`
-and an optional `remoteVersion` for an installed standalone copy.
+(Unix seconds), `archived`, canonical `codexHome`, and `stateDb`. Top-level
+`codexHome` is retained only for a single candidate home without inventory errors.
+Each successful remote result includes the same fields and an optional `remoteVersion` for an
+installed standalone copy. One remote host returns an object; repeated hosts
+return an array.
 
-Codex send JSON retains `target: {agent, id}`, `status: queued` (or `validated`
-under dry-run), `ok`, `chars`, `dryRun`, and optional `queueId`. It adds:
+Within the common envelope, Codex send JSON includes `target: {agent, id}`,
+`status: queued` (or `validated` under dry-run), `chars`, `dryRun`, and optional
+`queueId`. It also includes:
 
 - `codexHome`: the resolved absolute destination home, not a sender-side guess.
 - `codexHomeResolution`: schema-versioned `status`, `selected`, `reason`, and
@@ -391,21 +506,40 @@ under dry-run), `ok`, `chars`, `dryRun`, and optional `queueId`. It adds:
 - `submitted`: `true` only after successful queue CLI completion, `false` for dry-run.
 - `consumptionConfirmed`: always `false`; neither queued nor validated establishes consumption.
 
-Errors keep the existing `{ok: false, error}` fields (plus host on remote results)
-and add `codexHomeResolution` when home evidence caused the failure.
+Errors set the common envelope's `ok` to `false`, add `error`, and include
+`codexHomeResolution` when home evidence caused the failure.
 A timeout has an unknown submission outcome; missing `submitted` on an error
 must not be interpreted as proof that nothing was queued. Listing results do
-not describe a submission and have no submission/consumption fields. The changes
-are additive, not the cross-command envelope redesign tracked in [#29](https://github.com/abruption/session-peer/issues/29).
+not describe a submission and have no submission/consumption fields.
 
-A remote send to one host returns a flat object with `host`; multiple hosts return an array.
-Claude output stays compatible. When `CODEX_THREAD_ID` (or the compatibility
+For every command, one remote host returns a flat object and multiple hosts
+return an array. When `CODEX_THREAD_ID` (or the compatibility
 fallback `CODEX_SESSION_ID`) is present, the message envelope and reply command
 identify the originating Codex thread.
 
-`doctor`, reply waiting/`--wait`, structured reply URIs and optional wake are
-future work, not v0.6 features: see the [v0.7](https://github.com/abruption/session-peer/issues/45)
-and [v0.8](https://github.com/abruption/session-peer/issues/46) roadmaps.
+### Diagnostics and reply observation
+
+`doctor` performs read-only checks on the machine that owns the sessions. It
+reports Claude's configured sessions directory and inbox availability, Codex's
+executable and bounded home/state DB candidates, unsupported DB schemas, and
+permission or unknown failures as distinct codes. It does not connect to an
+inbox, write a queue, scan arbitrary directories, or alter agent/SSH settings.
+
+Reverse SSH is checked only with `--check-return-route`. The destination runs a
+fixed `ssh ... true` probe with prompts, password authentication, host-key
+enrollment, and config mutation disabled. Forward SSH success is never reused as
+proof that the reverse path works. Use `--reply-to USER@HOST` when automatic
+Tailscale detection cannot identify the origin. JSON details and status values
+are documented in [docs/diagnostics.md](docs/diagnostics.md).
+
+There is deliberately no general `--wait`. Claude Code has a native
+same-machine `notify_when_idle` facility, but it does not cover remote sessions,
+subagents, or Codex, and a successful socket/queue submission is not an
+acknowledgement. session-peer therefore reports
+`capabilities.replyObservation.status: unsupported` instead of tailing mutable
+transcripts and risking a false match. Ask the target to send an explicit reply
+to the supplied `Reply-To` address when completion matters. Optional wake remains
+tracked in [#46](https://github.com/abruption/session-peer/issues/46).
 
 ## Moving from cc-peer
 
@@ -508,9 +642,10 @@ not as the user typing approval.
   Outside that context, it may omit it. This is not an authenticated identity
   protocol; environment variables and session registries are local hints.
 - **Advertised replies need a working return path.** When an agent sender and
-  reply host can be determined, a `Reply:` line supplies an SSH return command.
-  Forward SSH success does not prove reverse SSH access. v0.6 does not verify
-  that route, correlate a reply, or wait for one; the address grants no access.
+  reply host can be determined, `Reply-To` and a compatibility `Reply:` line
+  describe a return route. Forward SSH success does not prove reverse SSH
+  access; use the opt-in doctor check. The address grants no access and
+  session-peer does not correlate or wait for a reply.
 - **Tailscale status is a local routing hint.** A known online peer is addressed
   by its current MagicDNS name and a known offline peer is rejected before SSH.
   An unknown destination remains ordinary SSH; session-peer does not claim that
@@ -525,7 +660,8 @@ not as the user typing approval.
 - **Windows support.** Claude's named pipe transport is supported.
   `install.sh` and the standalone remote installer/updater use POSIX shell;
   use a Python package manager on native Windows. Live Codex verification
-  for v0.6 was on macOS, not Windows.
+  remains macOS-only; the Codex home, Reply-To, doctor, and JSON fixtures run in
+  Windows CI.
 
 ## Tests
 
@@ -533,7 +669,7 @@ not as the user typing approval.
 python3 -m unittest discover -s tests -v
 ```
 
-The suite needs no live agent, SSH server or network. It includes legacy
+The default suite needs no live agent, SSH server or network. It includes legacy
 compatibility tests, shared CLI helpers, fixture-based Codex discovery and queue
 subprocess tests, and isolated standalone installation/coexistence checks.
 Codex coverage includes argv/payload handling, destination home selection,
@@ -544,6 +680,9 @@ homes, unique/multiple/changing writer evidence, fail-closed inventory errors,
 explicit selection, alias deduplication, single-home compatibility and structured
 home/submission metadata. They never infer a live writer from a saved row or
 submit messages to real sessions.
+Update-notice coverage checks freshness and expiry, strict stable versions,
+atomic private writes, single-flight background refresh, opt-out behavior,
+package-manager guidance, multi-host scope, and failure isolation.
 
 CI runs tests on Ubuntu/macOS with Python 3.9 and 3.13, and Windows with Python
 3.13 (POSIX installer tests are skipped there). Separate jobs check shell syntax
@@ -554,6 +693,31 @@ tests remain tracked in [#28](https://github.com/abruption/session-peer/issues/2
 
 ## Verified
 
+### session-peer v0.8.0 candidate (2026-09-16)
+
+- Integrates unified Claude/Codex listing, optional MCP tools and a Codex plugin,
+  explicit bounded Codex wake, multi-home Codex listing, and named message and output
+  formatting options from #76, #77, #78, #80, and #82.
+- See [v0.8.0 release notes](docs/releases/v0.8.0.md) for JSON compatibility,
+  optional dependencies, the Codex 0.154.0 wake boundary, and validation limits.
+- 301 local tests passed with the MCP SDK; standalone runs skip two optional
+  SDK tests. Wheel and sdist installed independently and report v0.8.0.
+- Release preparation does not publish a GitHub release or upload to PyPI.
+
+### session-peer v0.7.0 (2026-09-16)
+
+- 240 local tests passed for cached update notices, the shared JSON envelope,
+  read-only diagnostics, structured Reply-To parsing/routing, same-machine
+  normalization, and opt-in reverse-route classification.
+- CI covers Ubuntu and macOS with Python 3.9/3.13, Windows with Python 3.13,
+  package build and isolated installs, standalone install smoke tests, shellcheck,
+  and secret scanning.
+- Wheel and sdist contents were inspected and installed independently. Both
+  artifacts report v0.7.0 and exclude the frozen legacy `cc_peer.py`.
+- A real SSH doctor run found Claude inboxes and bounded default/Orca Codex homes.
+  Its opt-in reverse probe reported authentication failure independently of the
+  successful forward connection. No live message was submitted.
+
 ### session-peer v0.6.2 (2026-09-15)
 
 - 198 local tests and the release build checks passed for UUID-specific Codex
@@ -621,3 +785,40 @@ agent build.
 ## License
 
 MIT
+
+### Combined session discovery
+
+Default `list` and `list --json` query Claude and Codex together. Use
+`--agent claude` to retain the previous Claude-only default, or `--agent codex`
+for Codex only. Every session row includes `agent: "claude" | "codex"`;
+agent-specific fields such as PID and thread UUID remain unchanged. Combined
+human output includes an AGENT column. Claude rows precede Codex rows, preserving
+Claude discovery ordering; Codex rows sort by descending update time, then home and UUID.
+
+List responses include `discovery`, keyed by each requested agent, with
+`status: "ok" | "not_installed" | "error"` (the middle state is Codex-only)
+and an `error` explanation for failed sources.
+Any discovery failure returns `ok: false`, a top-level error summary, and exit
+code 1 while retaining successfully discovered sessions. No automatically discovered
+Codex installation is a normal empty result (`not_installed`, exit 0); a missing
+explicitly configured home is an error. A missing Claude sessions directory is an empty result.
+Neither is evidence of a running Codex process. Malformed individual Claude
+records continue to be skipped as before.
+
+These semantics apply locally and over SSH. Repeated hosts retain independent
+results in the existing ordered array; any failure makes the overall exit code 1.
+Codex listing includes default, environment-selected, Orca, and configured homes.
+Use `--codex-home PATH` to inspect only that home.
+`--all` retains Claude stale/no-inbox records and includes archived Codex threads.
+
+### Optional MCP / Codex plugin
+
+For structured, destination-restricted `list_sessions` and `send_message` tools,
+install `session-peer[mcp]` with Python 3.10+ and follow [MCP setup](docs/mcp.md).
+The default policy permits local listing only. The standalone CLI and shell
+installer retain their existing dependency requirements.
+
+For opt-in activation of queued Codex sessions, see [explicit wake](docs/wake.md).
+
+See [multi-home Codex listing](docs/multi-home-list.md) for candidate sources,
+per-home errors, duplicate UUIDs, and selecting the exact home for send.