From 4e75e6538d2a18d7c2a249e23a9db24303146a90 Mon Sep 17 00:00:00 2001 From: YEONGUK LEE Date: Wed, 28 Oct 2026 12:08:33 +0900 Subject: [PATCH] docs: prepare Python skill 0.4.1 maintenance guidance --- README.ja.md | 2 +- README.ko.md | 2 +- README.md | 2 +- README.zh-CN.md | 2 +- docs/usage.ja.md | 36 ++++++++++++++++++++++++++++---- docs/usage.ko.md | 36 ++++++++++++++++++++++++++++---- docs/usage.md | 36 ++++++++++++++++++++++++++++---- docs/usage.zh-CN.md | 36 ++++++++++++++++++++++++++++---- scripts/python-coverage.test.mjs | 34 +++++++++++++++++------------- session-peer/SKILL.md | 36 ++++++++++++++++++++++++++++---- 10 files changed, 184 insertions(+), 38 deletions(-) diff --git a/README.ja.md b/README.ja.md index 7e7ee62..16e04a9 100644 --- a/README.ja.md +++ b/README.ja.md @@ -16,7 +16,7 @@ ## クイックスタート -基本的な Python CLI コマンドには session-peer 0.9.1 以降が必要です。公開 Python CLI の機能範囲の基準は session-peer 1.3.0 です。オプションのペアリング済みデバイス転送には、Unix 上で Python 3.11 以降と `session-peer[relay]` が必要です。 +基本的な Python CLI コマンドには session-peer 0.9.1 以降が必要です。公開 Python CLI の機能範囲の基準は session-peer 1.3.2 です。オプションのペアリング済みデバイス転送には、Unix 上で Python 3.11 以降と `session-peer[relay]` が必要です。 v1.0.3 のセキュリティ修正を利用するには、Python ランタイム 1.0.3 以降を使用してください。上記の互換バージョンは CLI 機能の条件であり、セキュリティ上の推奨バージョンではありません。 ### インストール diff --git a/README.ko.md b/README.ko.md index d3895ea..a1eef39 100644 --- a/README.ko.md +++ b/README.ko.md @@ -16,7 +16,7 @@ ## 빠른 시작 -기본 Python CLI 명령에는 session-peer 0.9.1 이상이 필요합니다. 공개 Python CLI 기능 범위의 기준 버전은 session-peer 1.3.0입니다. 페어링 기기 전송은 선택 기능이며, Unix 환경에서 Python 3.11 이상과 `session-peer[relay]`가 필요합니다. +기본 Python CLI 명령에는 session-peer 0.9.1 이상이 필요합니다. 공개 Python CLI 기능 범위의 기준 버전은 session-peer 1.3.2입니다. 페어링 기기 전송은 선택 기능이며, Unix 환경에서 Python 3.11 이상과 `session-peer[relay]`가 필요합니다. v1.0.3 보안 수정을 적용하려면 Python 런타임 1.0.3 이상을 사용합니다. 위 호환 버전은 CLI(명령줄 인터페이스) 기능 지원 기준이며 보안 권장 버전과 별개입니다. ### 설치 diff --git a/README.md b/README.md index e455f07..4613d0c 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ The runtime demonstration shows Claude Code and Codex messaging; the skill provi ## Quick Start -Basic Python CLI commands require session-peer 0.9.1 or newer. The published Python CLI coverage reference is session-peer 1.3.0. Paired-device transport is optional and needs `session-peer[relay]` on Unix with Python 3.11+. +Basic Python CLI commands require session-peer 0.9.1 or newer. The published Python CLI coverage reference is session-peer 1.3.2. Paired-device transport is optional and needs `session-peer[relay]` on Unix with Python 3.11+. For the v1.0.3 security fixes, use Python runtime 1.0.3 or newer. The compatibility versions above are CLI feature thresholds, not security recommendations. ### Install diff --git a/README.zh-CN.md b/README.zh-CN.md index 7e5d6c0..4ebcf4d 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -16,7 +16,7 @@ ## 快速开始 -基本 Python CLI 命令需要 session-peer 0.9.1 或更高版本。已发布 Python CLI 功能的覆盖基准为 session-peer 1.3.0。配对设备传输为可选功能，需要 `session-peer[relay]` 附加依赖项（Unix、Python 3.11 或更高版本）。 +基本 Python CLI 命令需要 session-peer 0.9.1 或更高版本。已发布 Python CLI 功能的覆盖基准为 session-peer 1.3.2。配对设备传输为可选功能，需要 `session-peer[relay]` 附加依赖项（Unix、Python 3.11 或更高版本）。 如需获得 v1.0.3 安全修复，请使用 Python 运行时 1.0.3 或更高版本。上述兼容版本是 CLI 功能门槛，并非安全建议版本。 ### 安装 diff --git a/docs/usage.ja.md b/docs/usage.ja.md index bfe1d13..d4bec65 100644 --- a/docs/usage.ja.md +++ b/docs/usage.ja.md @@ -15,7 +15,7 @@ uv、pip、POSIX 向けスタンドアロンインストーラー、およびネ このスキルでは、session-peer 0.9.1 以降で共通して使える基本コマンドを案内します。`--allow-inactive-codex-home` と `--relay-login` は session-peer 1.0.0 以降でのみ使用できます。macOS/Linux の受信側ポリシーで使う `codexBin` と、`attemptId` で接続試行を関連付けた Relay 診断には session-peer 1.0.1 以降が必要です。オプションのペアリング済みデバイス転送には `session-peer[relay]` extra（Unix、Python 3.11 以降）が必要です。 -公開 Python CLI の機能範囲の基準は session-peer 1.3.0 です。 +公開 Python CLI の機能範囲の基準は session-peer 1.3.2 です。 ## ランタイム 1.0.3 のセキュリティと運用 @@ -37,7 +37,7 @@ Python 1.1.0 以降では、外部メッセージ本文のすべての行を引 ## Python 1.3 の利用手順 -以下のオプション手順には Python ランタイム 1.3.0 以降が必要です。基本 CLI の互換性下限は 0.9.1、公開 CLI の機能範囲の基準は 1.3.0 です。実際に選択されたランタイムのバージョンとコマンドのヘルプで対応を確認し、各機能のプラットフォームと権限の要件も確認します。受信機の `codexBin` 固有の最低バージョン 1.0.1 は維持します。実験的 handoff は `runtime-min-version` と `runtime-full-version` が示すコマンドの対応範囲に含めません。[公開済みランタイムのリリース](https://github.com/abruption/session-peer/releases/tag/v1.3.0)を参照してください。 +以下のオプション手順には Python ランタイム 1.3.0 以降が必要です。基本 CLI の互換性下限は 0.9.1、公開 CLI の機能範囲の基準は 1.3.2 です。実際に選択されたランタイムのバージョンとコマンドのヘルプで対応を確認し、各機能のプラットフォームと権限の要件も確認します。受信機の `codexBin` 固有の最低バージョン 1.0.1 は維持します。実験的 handoff は `runtime-min-version` と `runtime-full-version` が示すコマンドの対応範囲に含めません。[公開済みランタイムのリリース](https://github.com/abruption/session-peer/releases/tag/v1.3.0)を参照してください。 - [送信説明](https://github.com/abruption/session-peer/blob/v1.3.0/docs/cli-reference.md#delivery-explanation)：通常のメッセージ入力を受け取る `send --dry-run --explain` は、ローカル・SSH・ペアリング済み経路に対応し、テキストのみを出力します。`doctor --explain` は診断時点の状態を説明し、選択した対象の受信準備を判定するものではありません。`handoff status --explain` は保存済みの読み取り専用の根拠を説明します。JSON との組み合わせや、handoff SEND の correlation・ACK・observe・wait との組み合わせは拒否します。説明は既存の結果を再利用し、追加の検査・有効化・送信処理・受領確認の権限は生みません。既存の dry-run のバージョン検査は別です。ペアリング経路の追加情報は既存の検査で対応を確認し、許可リストと 8 KiB の上限を適用します。古い受信機では確認済みのネイティブ情報を維持し、不足する情報は unknown のままにします。プレビューは許可・対象の予約・ACK を与えません。終了コード 0 だけで未送信とは判断できず、unknown や想定外の送信処理も自動再送を許可しません。wake には引き続きユーザーの明示的な依頼が必要です。 - [経路プリセット](https://github.com/abruption/session-peer/blob/v1.3.0/docs/cli-reference.md#route-presets)と別個の[受信者アドレス帳](https://github.com/abruption/session-peer/blob/v1.3.0/docs/cli-reference.md#recipient-addressbook-v130)は、macOS・Linux のローカル・SSH Claude・Codex のみを対象とします。項目の管理はユーザーの依頼に基づいて行います。`preset show` は保存済みの経路と revision を読み、`list --preset` は現在のセッションを検索します。実際のプリセット送信には `--to` と `--preset-revision` が必要で、replace/remove は `--expect-revision` を使います。値のハッシュである `dp1` は同じ名前・経路に戻すと同じ値になり、後の変更で展開済みの呼び出しが取り消されることはありません。アドレスの add/reselect 前には、`address resolve` の結果を観測 revision の `as1` とともに確認します。実際の送信には現在の `--address-revision`（`ab1`）と正確な正規対象を示す `--confirm-target` が必要です。reselect/remove は revision を検査し、add/reselect のたびに新しい binding ID を作ります。Claude は `tg1` を維持します。Codex の `aw1` は再検査される writer の観測値であり、世代の識別は未対応で、ストレージ・実行インスタンスの原子的な一貫性も保証しません。SSH は実際の選択接続で検証した鍵を関連付け、送信時に固定します。discover は明示的に選択した最大 16 件のアドレスを検査し、同一の経路・ホーム・鍵の条件をまとめ、一部の失敗も保持します。ネットワークスキャン・ブロードキャスト・自動再選択は追加しません。ラベルや revision は人を認証せず、権限や ACK の証明にもなりません。非公開ストレージ・ACL・マウントの検査で拒否されたら運用者の確認のために中止し、権限の修復や自動的な別経路への切り替えはしません。 @@ -48,6 +48,34 @@ Python 1.1.0 以降では、外部メッセージ本文のすべての行を引 ランタイムの公開によって、別途管理されるこのスキルが公開・インストールされるわけではありません。別途承認された変更不能なスキルリリースについて、記録されたタグ・ソースコミット・SKILL ハッシュを検証してから採用します。Python ランタイムの互換コピーは、その正確な公開済みスキルソースから別途更新し、既存のランタイムリリースは変更しません。 +## Python 1.3.2 の保守に関する案内 + +この案内は[公開済み Python ランタイム 1.3.2](https://github.com/abruption/session-peer/releases/tag/v1.3.2)、ソース `f5e7c49554ff02771990a151e00b52f2abf3df0a` に基づきます。基本 CLI の互換性下限は 0.9.1 のままです。この改訂では新しい Direct 出力の解釈も案内するため、公開機能範囲の基準は 1.3.2 です。従来の 1.3.0 の利用手順に必要なバージョンと、受信機の `codexBin` 固有の下限 1.0.1 は別に維持します。 + +### オプションの MCP の導入とアップグレード + +基本 CLI は必須の外部依存関係なしで Python 3.9+ に対応します。オプションの MCP には Python 3.10+ と `session-peer[mcp]` extra が必要です。ランタイム 1.3.2 は MCP SDK `mcp>=1.30,<2` を要求します。新しい隔離環境に導入する場合、文書化されている pipx の例は次のとおりです。 + +```bash +pipx install 'session-peer[mcp]' +``` + +既存の MCP 環境では、インタープリターと選択済みの extra を維持し、従来の管理ツールで明示的にアップグレードします。新規導入の例で既存環境を置き換えたり、管理ツールを無断で変更したりしないでください。依存関係の宣言を変更しても、導入済みのパッケージは更新されません。`install.sh` や単体スクリプトの更新は MCP の依存関係を導入・更新しません。[固定版 MCP ガイド](https://github.com/abruption/session-peer/blob/v1.3.2/docs/mcp.md)を参照してください。 + +SDK の下限は上流プロジェクトの 1.x の修正を反映しています。標準入出力（stdio）のみを使うこのアプリケーションで、HTTP/OAuth/client の脆弱性が悪用可能だと確認したものでも、それらの転送方式を有効にするものでもありません。ランタイム CI は macOS/Linux と Python 3.10/3.13 で、SDK の正確な下限 1.30.0 と最新の互換 1.x を組み合わせた 8 環境を検査しました。解決された依存関係のグラフを監査したものであり、依存先がさらに要求するすべてのパッケージの最小バージョンを試験したものではありません。[検証範囲](https://github.com/abruption/session-peer/blob/v1.3.2/docs/mcp.md#validation)を参照してください。 + +### Direct 受信機の出力と運用者による更新 + +Python 1.3.2+ では、受信機の起動時出力で `ready:true` を維持し、`directReadyConfirmed:false` を追加します。前者はローカルのリスナーの準備を表し、どちらもリモート接続の受け入れ/TLS、認証済みアクセス、ネイティブ送信処理、消費や ACK を確認するものではありません。旧受信機では新しいフィールドが省略される場合があります。false や失敗を補わず、不明な証拠として扱ってください。実際に動いているバージョン、ヘルプ、出力の契約を確認します。TLS は認証前のペアリング初期処理である可能性があり、認証済み probe は別の証拠です。 + +既存の明示的な選択肢 `--diagnostic-events` には、`direct_transport` の段階 `accepted` と `peer_tls`、上限付きカウンター `accepted`、`tlsCompleted`、`tlsFailed` が追加されます。各段階は 60 秒当たり 1 記録、60 秒当たり合計 2 記録までを許可し、TLS の成功と失敗は同じ段階の枠を共有します。通常の終了時には、ゼロの値も含む `summary` をさらに 1 回記録しようとします。終了処理を繰り返しても再記録しません。記録の欠落やカウンターの不一致は起こり得ます。これは heartbeat、欠落のない履歴、ACK ではなく、同期 stderr は出力先が詰まった場合の厳密な期限を保証しません。[固定版 Direct リファレンス](https://github.com/abruption/session-peer/blob/v1.3.2/docs/paired-devices.md#macos-direct-listener-checks-341)を参照してください。 + +報告された 2 台の Mac の事例では、所有者が対象の Python アプリケーションへの着信を許可した後、元の公開版 1.3.1 でペアリングと認証済み probe が復旧しました。診断コードがネットワークを修復したわけではありません。必要に応じて、実際のアプリケーションの権限を所有者に確認してもらいます。ファイアウォールを有効にし、意図したプライベート bind、固定した TLS の識別情報と受信側ポリシーを維持します。`0.0.0.0` への自動拡張、キー/DB の初期化、アクセス方針の変更、結果が不確かなペアリング・送信の再試行は行いません。この事例は、あらゆる環境に当てはまる診断やネイティブ配送・ACK 対応を示すものではありません。 + +オプションの受信機モジュールは wheel/sdist に含まれ、単体の `session_peer.py` には内蔵されていません。単体ファイルの更新だけでは、既存の受信機環境は変わりません。運用者が承認された展開手順の下で、パッケージ環境を別途アップグレードし、受信機を明示的に再起動する必要があります。Python パッケージの公開によってサービスが展開されるわけではありません。 + +Node Control の Better Auth/core 1.7.7 の変更は Python 配布物の外にあり、サービスを別途更新する必要があります。検証用名前空間の変更により、進行中の OAuth サインインを最初からやり直す必要が生じる場合がありますが、セッションの一括失効、キーのローテーション、DB の再作成を行う根拠にはなりません。1.0.3 で導入された、アカウントセッションの作成時から 24 時間という制限は引き続き有効です。1 つのスタックでの展開は、すべての導入環境、登録方針、可用性、実際の OAuth やネイティブ ACK を検証するものではありません。[リリースと運用の境界](https://github.com/abruption/session-peer/blob/v1.3.2/docs/releases/v1.3.2.md#incident-and-compatibility-boundaries)を参照してください。 + ## スキルのインストール ```bash @@ -71,11 +99,11 @@ npx -y skills@latest list --global --json npx -y skills@latest update session-peer --global --yes ``` -特定のリリースに固定して導入する場合は、そのタグを使用します（例: `v0.4.0`）。 +特定のリリースに固定して導入する場合は、そのタグを使用します（例: `v0.4.1`）。 ```bash npx -y skills@latest add \ - https://github.com/abruption/session-peer-skill/tree/v0.4.0/session-peer \ + https://github.com/abruption/session-peer-skill/tree/v0.4.1/session-peer \ --skill session-peer --global \ --agent claude-code --agent codex --agent antigravity \ --copy --yes diff --git a/docs/usage.ko.md b/docs/usage.ko.md index b8c6e00..f1d5c31 100644 --- a/docs/usage.ko.md +++ b/docs/usage.ko.md @@ -15,7 +15,7 @@ uv, pip, POSIX 환경의 독립 실행형(standalone) 설치 프로그램, Windo 스킬은 session-peer 0.9.1 이상에서 공통으로 사용할 수 있는 기본 명령을 안내합니다. `--allow-inactive-codex-home`과 `--relay-login`은 session-peer 1.0.0 이상에서만 사용할 수 있습니다. macOS·Linux 수신기 정책의 `codexBin` 기능과 `attemptId`로 이벤트를 연결하는 Relay 진단에는 session-peer 1.0.1 이상이 필요합니다. 선택 기능인 페어링 기기 전송에는 `session-peer[relay]` extra(추가 설치 옵션, Unix·Python 3.11 이상)가 필요합니다. -공개 Python CLI 기능 범위의 기준 버전은 session-peer 1.3.0입니다. +공개 Python CLI 기능 범위의 기준 버전은 session-peer 1.3.2입니다. ## 런타임 1.0.3 보안 및 운영 @@ -41,7 +41,7 @@ Python 1.1.0 이상은 외부 메시지 본문의 모든 줄을 인용하고 발 ## Python 1.3 사용 절차 -아래 선택 절차에는 Python 런타임 1.3.0 이상이 필요합니다. 기본 CLI 호환성 하한은 0.9.1이며, 공개 CLI 기능 범위 기준은 1.3.0입니다. 실제 선택된 런타임 버전과 명령 도움말의 지원 여부를 확인하고, 각 기능의 플랫폼·권한 요구 사항도 확인합니다. 수신기 `codexBin`의 개별 최소 버전 1.0.1은 유지합니다. 실험적 handoff는 `runtime-min-version`과 `runtime-full-version`이 나타내는 명령 범위에서 제외합니다. [공개 런타임 릴리스](https://github.com/abruption/session-peer/releases/tag/v1.3.0)를 참고합니다. +아래 선택 절차에는 Python 런타임 1.3.0 이상이 필요합니다. 기본 CLI 호환성 하한은 0.9.1이며, 공개 CLI 기능 범위 기준은 1.3.2입니다. 실제 선택된 런타임 버전과 명령 도움말의 지원 여부를 확인하고, 각 기능의 플랫폼·권한 요구 사항도 확인합니다. 수신기 `codexBin`의 개별 최소 버전 1.0.1은 유지합니다. 실험적 handoff는 `runtime-min-version`과 `runtime-full-version`이 나타내는 명령 범위에서 제외합니다. [공개 런타임 릴리스](https://github.com/abruption/session-peer/releases/tag/v1.3.0)를 참고합니다. - [전송 설명](https://github.com/abruption/session-peer/blob/v1.3.0/docs/cli-reference.md#delivery-explanation): 일반 메시지 입력을 받는 `send --dry-run --explain`은 로컬·SSH·페어링 경로를 지원하며 텍스트로만 출력합니다. `doctor --explain`은 진단 시점의 상태를 설명하며 특정 대상의 수신 준비를 판정하지 않습니다. `handoff status --explain`은 저장된 읽기 전용 근거를 설명합니다. JSON 조합과 handoff SEND의 correlation·ACK·observe·wait 조합은 거부됩니다. 설명은 기존 결과를 재사용하며 추가 검사·활성화·제출·수신 확인 권한을 만들지 않습니다. 기존 dry-run 버전 검사는 별개입니다. 페어링 경로의 추가 정보는 기존 검사로 지원 여부를 협의하고 허용 목록과 8 KiB 한도를 적용합니다. 이전 수신기에서는 확인된 네이티브 정보만 유지하고 없는 정보는 unknown으로 남깁니다. 미리보기는 권한·대상 예약·ACK를 부여하지 않습니다. 종료 코드 0만으로 미제출을 단정할 수 없으며, unknown이나 예기치 않은 제출도 자동 재전송을 허용하지 않습니다. wake에는 여전히 사용자의 명시적 요청이 필요합니다. - [경로 프리셋](https://github.com/abruption/session-peer/blob/v1.3.0/docs/cli-reference.md#route-presets)과 별도의 [수신자 주소록](https://github.com/abruption/session-peer/blob/v1.3.0/docs/cli-reference.md#recipient-addressbook-v130)은 macOS·Linux의 로컬·SSH Claude·Codex만 지원합니다. 항목 관리는 사용자 요청에 따라 수행합니다. `preset show`는 저장된 경로와 revision을 읽고, `list --preset`은 현재 세션을 검색합니다. 실제 프리셋 전송에는 `--to`와 `--preset-revision`이 필요하며 replace/remove는 `--expect-revision`을 사용합니다. 값의 해시인 `dp1`은 같은 이름·경로를 복원하면 같은 값이 되며, 이후 변경으로 이미 경로를 해석한 호출이 취소되지는 않습니다. 주소를 add/reselect하기 전에는 `address resolve` 결과와 관측 revision인 `as1`을 검토합니다. 실제 전송에는 현재 `--address-revision`(`ab1`)과 정확한 정규 대상인 `--confirm-target`이 필요합니다. reselect/remove는 revision을 검사하고, add/reselect할 때마다 새 binding ID를 만듭니다. Claude는 `tg1`을 유지합니다. Codex의 `aw1`은 다시 검사하는 writer 관측값이며, 세대 구분은 지원하지 않고 저장소·실행 인스턴스의 원자적 일관성도 보증하지 않습니다. SSH는 실제 선택 연결에서 검증한 키를 연결 정보에 저장하고 전송 시 고정합니다. discover는 명시적으로 선택한 주소를 최대 16개 검사하며, 같은 경로·홈·키 조건을 묶고 일부 실패도 보존합니다. 네트워크 스캔·브로드캐스트·자동 재선택은 추가하지 않습니다. 이름표와 revision은 사람을 인증하거나 권한·ACK를 증명하지 않습니다. 비공개 저장소·ACL·마운트 검사에서 거부되면 운영자 검토를 위해 중단하고, 권한을 복구하거나 다른 경로로 자동 대체하지 않습니다. @@ -52,6 +52,34 @@ Python 1.1.0 이상은 외부 메시지 본문의 모든 줄을 인용하고 발 런타임 공개로 별도 관리되는 이 스킬이 발행되거나 설치되지는 않습니다. 별도로 승인된 변경 불가능한 스킬 릴리스의 기록된 태그·소스 커밋·SKILL 해시를 검증한 뒤에만 채택합니다. Python 런타임의 호환 사본은 그 정확한 공개 스킬 소스에서 별도로 갱신하며, 기존 런타임 릴리스는 변경하지 않습니다. +## Python 1.3.2 유지보수 안내 + +이 안내는 [공개 Python 런타임 1.3.2](https://github.com/abruption/session-peer/releases/tag/v1.3.2), 소스 `f5e7c49554ff02771990a151e00b52f2abf3df0a`를 기준으로 합니다. 기본 CLI 호환성 하한은 0.9.1입니다. 이번 개정판은 새 Direct 출력의 해석도 안내하므로 공개 기능 범위의 기준은 1.3.2입니다. 기존 1.3.0 사용 절차의 요구 버전과 수신기 `codexBin`의 개별 하한 1.0.1은 별개로 유지합니다. + +### 선택 기능 MCP의 설치와 업그레이드 + +기본 CLI는 필수 외부 의존성 없이 Python 3.9+를 지원합니다. 선택 기능인 MCP에는 Python 3.10+와 `session-peer[mcp]` extra가 필요합니다. 런타임 1.3.2는 MCP SDK `mcp>=1.30,<2`를 요구합니다. 새 격리 환경을 위한 pipx 설치 예시는 다음과 같습니다. + +```bash +pipx install 'session-peer[mcp]' +``` + +기존 MCP 환경은 인터프리터와 선택한 extra를 유지하면서 원래 사용한 관리자로 명시적으로 업그레이드합니다. 새 설치 예시로 기존 환경을 대체하거나 관리자를 임의로 바꾸지 않습니다. 의존성 선언이 바뀌어도 설치된 패키지는 자동으로 업그레이드되지 않습니다. `install.sh`와 독립 실행형 스크립트 업데이트는 MCP 의존성을 설치하거나 갱신하지 않습니다. [고정 MCP 안내](https://github.com/abruption/session-peer/blob/v1.3.2/docs/mcp.md)를 참고합니다. + +SDK 하한은 상위 프로젝트의 1.x 수정 사항을 반영합니다. 이것이 표준 입출력(stdio)만 사용하는 이 애플리케이션에서 HTTP/OAuth/client 취약점이 악용될 수 있음을 확인하거나 해당 전송 방식을 활성화한다는 뜻은 아닙니다. 런타임 CI는 macOS·Linux와 Python 3.10/3.13에서 정확한 SDK 1.30.0 및 최신 호환 1.x를 조합한 8개 환경을 검사했습니다. 각 환경에서 결정된 의존성 그래프를 감사했으며, 의존 패키지가 다시 요구하는 모든 패키지의 최소 버전을 시험한 것은 아닙니다. [검증 범위](https://github.com/abruption/session-peer/blob/v1.3.2/docs/mcp.md#validation)를 참고합니다. + +### Direct 수신기 출력과 운영자 업데이트 + +Python 1.3.2+의 수신기 시작 출력은 `ready:true`를 유지하고 `directReadyConfirmed:false`를 추가합니다. 앞의 필드는 로컬 리스너가 준비됐다는 뜻이며, 두 필드 모두 원격 연결 수락/TLS, 인증된 접근, 네이티브 제출, 소비나 ACK를 확인하지 않습니다. 이전 수신기는 새 필드를 생략할 수 있습니다. 이 경우 false나 실패를 임의로 만들지 말고 근거가 불명확한 상태로 유지합니다. 실제 실행 버전, 도움말과 출력 계약을 확인합니다. TLS는 인증 전 페어링 초기 단계일 수 있으며, 인증된 probe는 별도의 근거입니다. + +기존의 선택 옵션 `--diagnostic-events`에는 `direct_transport`의 `accepted`·`peer_tls` 단계와 상한이 있는 `accepted`·`tlsCompleted`·`tlsFailed` 카운터가 추가됩니다. 각 단계는 60초당 기록 1개를 허용하므로 60초당 총 2개까지이며, TLS 성공과 실패는 같은 단계의 한도를 공유합니다. 정상 종료 시에는 0인 카운터도 포함한 `summary` 1개를 추가로 기록하려고 시도하며, 종료 처리를 반복해도 다시 기록하지 않습니다. 기록이 빠지거나 카운터 합계가 맞지 않을 수 있습니다. 이는 heartbeat, 손실 없는 이력이나 ACK가 아니며, 동기식 stderr 출력은 수신 측이 막혔을 때 엄격한 제한 시간을 보장하지 않습니다. [고정 Direct 안내](https://github.com/abruption/session-peer/blob/v1.3.2/docs/paired-devices.md#macos-direct-listener-checks-341)를 참고합니다. + +보고된 두 Mac 사례에서는 소유자가 해당 Python 애플리케이션의 들어오는 연결을 허용한 뒤 원래 공개된 1.3.1에서 페어링과 인증된 probe가 복구됐습니다. 진단 코드가 네트워크를 고친 것은 아닙니다. 필요한 경우 소유자에게 실제 애플리케이션의 권한을 확인하도록 요청합니다. 방화벽을 켠 상태로 유지하고 의도한 사설 bind, 고정된 TLS 신원과 수신기 정책을 유지합니다. `0.0.0.0`으로 자동 확대하거나 키/DB를 초기화하거나 접근 정책을 바꾸거나 결과가 불확실한 페어링·전송을 재시도하지 않습니다. 이 사례는 모든 플랫폼에 적용할 진단이나 네이티브 전달·ACK 지원을 입증하지 않습니다. + +선택 수신기 모듈은 wheel/sdist에 포함되며 독립 실행형 `session_peer.py` 안에는 포함되지 않습니다. 독립 실행형 파일만 업데이트해도 기존 수신기 환경은 바뀌지 않습니다. 운영자가 승인된 배포 절차에 따라 해당 패키지 환경을 별도로 업그레이드하고 수신기를 명시적으로 다시 시작해야 합니다. Python 패키지를 발행한다고 서비스가 배포되지는 않습니다. + +Node Control의 Better Auth/core 1.7.7 변경은 Python 배포물 밖에 있으며 별도의 서비스 업데이트가 필요합니다. 검증 네임스페이스 변경으로 진행 중인 OAuth 로그인을 다시 시작해야 할 수 있으나, 세션 일괄 폐기·키 회전·DB 재생성의 근거는 아닙니다. 과거 1.0.3에서 적용한 계정 세션의 생성 시점으로부터 24시간 제한은 여전히 유효합니다. 한 스택의 배포가 모든 설치 환경, 가입 정책, 가용성, 실제 OAuth나 네이티브 ACK를 검증하는 것은 아닙니다. [릴리스와 운영의 경계](https://github.com/abruption/session-peer/blob/v1.3.2/docs/releases/v1.3.2.md#incident-and-compatibility-boundaries)를 참고합니다. + ## 스킬 설치 ```bash @@ -75,11 +103,11 @@ npx -y skills@latest list --global --json npx -y skills@latest update session-peer --global --yes ``` -특정 릴리스로 버전을 고정하여 설치하려면 해당 태그를 사용합니다(예: `v0.4.0`). +특정 릴리스로 버전을 고정하여 설치하려면 해당 태그를 사용합니다(예: `v0.4.1`). ```bash npx -y skills@latest add \ - https://github.com/abruption/session-peer-skill/tree/v0.4.0/session-peer \ + https://github.com/abruption/session-peer-skill/tree/v0.4.1/session-peer \ --skill session-peer --global \ --agent claude-code --agent codex --agent antigravity \ --copy --yes diff --git a/docs/usage.md b/docs/usage.md index 950797c..3b4ac2e 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -15,7 +15,7 @@ See the [session-peer installation options](https://github.com/abruption/session The skill documents basic commands shared by session-peer 0.9.1 and newer. `--allow-inactive-codex-home` and `--relay-login` require session-peer 1.0.0 or newer. macOS/Linux receiver policy `codexBin` and Relay diagnostics correlated by `attemptId` require session-peer 1.0.1 or newer. The optional paired-device transport requires the `session-peer[relay]` extra (Unix, Python 3.11+). -The published Python CLI coverage reference is session-peer 1.3.0. +The published Python CLI coverage reference is session-peer 1.3.2. ## Runtime 1.0.3 security and operations @@ -37,7 +37,7 @@ The separate [experimental handoff workflow](https://github.com/abruption/sessio ## Python 1.3 workflows -The following optional workflows require Python runtime 1.3.0 or newer. The basic CLI compatibility floor remains 0.9.1, and the published CLI coverage reference is 1.3.0. Check the resolved runtime version and affirmative command help, along with each feature's platform and permission requirements. Receiver `codexBin` retains its independent 1.0.1 floor. Experimental handoff is excluded from the command coverage represented by `runtime-min-version` and `runtime-full-version`. See the [published runtime release](https://github.com/abruption/session-peer/releases/tag/v1.3.0). +The following optional workflows require Python runtime 1.3.0 or newer. The basic CLI compatibility floor remains 0.9.1, and the published CLI coverage reference is 1.3.2. Check the resolved runtime version and affirmative command help, along with each feature's platform and permission requirements. Receiver `codexBin` retains its independent 1.0.1 floor. Experimental handoff is excluded from the command coverage represented by `runtime-min-version` and `runtime-full-version`. See the [published runtime release](https://github.com/abruption/session-peer/releases/tag/v1.3.0). - [Explanation](https://github.com/abruption/session-peer/blob/v1.3.0/docs/cli-reference.md#delivery-explanation): text-only `send --dry-run --explain` covers local, SSH and paired routes with normal message input. `doctor --explain` describes a diagnostic snapshot, not a selected target's readiness; `handoff status --explain` describes stored read-only evidence. JSON combinations and handoff SEND correlation/ACK/observe/wait combinations are refused. Explanations reuse existing results without extra probes, activation, submission or receipt authority; existing dry-run version checks are separate. Paired context is negotiated by the existing probe, allowlisted and bounded to 8 KiB; older receivers retain known native facts and leave missing context unknown. A preview grants no permission, reserves no target and provides no ACK evidence. Exit zero alone does not prove non-submission; unknown or unexpected submission never permits automatic resend. Wake still requires an explicit user request. - [Route presets](https://github.com/abruption/session-peer/blob/v1.3.0/docs/cli-reference.md#route-presets) and the separate [recipient addressbook](https://github.com/abruption/session-peer/blob/v1.3.0/docs/cli-reference.md#recipient-addressbook-v130) support macOS/Linux local/SSH Claude/Codex only. Manage entries only on user request. `preset show` reads stored route/revision data; `list --preset` discovers current sessions. Actual preset send requires `--to` and `--preset-revision`; replace/remove use `--expect-revision`. The `dp1` value hash repeats when identical name/route values are restored, and later changes do not cancel an already expanded invocation. For addresses, review `address resolve` before add/reselect, using its `as1` observation revision; actual send requires current `--address-revision` (`ab1`) and exact canonical `--confirm-target`. Reselect/remove use revision checks, and each add/reselect creates a new binding ID. Claude retains `tg1`; Codex `aw1` is a rechecked writer observation, with generation unsupported and no atomic storage/incarnation guarantee. SSH binds the verified key from the actual selection connection and pins it for send. Discover inspects at most 16 explicitly selected addresses, groups identical route/home/key contexts and preserves partial failures; it adds no network scan, broadcast or automatic reselection. Labels/revisions do not authenticate people, grant permission or prove ACK. Stop for operator review on private-storage/ACL/mount refusals; do not repair permissions or fall back automatically. @@ -48,6 +48,34 @@ The following optional workflows require Python runtime 1.3.0 or newer. The basi Runtime publication does not publish or install this independently managed skill. Adopt only a separately approved immutable skill release after verifying its recorded tag, source commit and SKILL hash. Update the Python runtime's compatibility snapshot in a separate change using that exact published skill source; existing runtime releases remain immutable. +## Python 1.3.2 maintenance + +These maintenance details refer to [published Python runtime 1.3.2](https://github.com/abruption/session-peer/releases/tag/v1.3.2), source `f5e7c49554ff02771990a151e00b52f2abf3df0a`. Basic CLI compatibility remains 0.9.1; the published coverage reference is 1.3.2 because this revision also guides interpretation of the new Direct output. The original 1.3.0 workflow requirements and receiver `codexBin` floor of 1.0.1 remain separate. + +### Optional MCP installation and upgrades + +The base CLI supports Python 3.9+ without mandatory external dependencies. Optional MCP requires Python 3.10+ and the `session-peer[mcp]` extra. Runtime 1.3.2 requires MCP SDK `mcp>=1.30,<2`. For a new isolated environment, the documented pipx example is: + +```bash +pipx install 'session-peer[mcp]' +``` + +For an existing MCP environment, explicitly upgrade through its original manager while preserving its interpreter and selected extras. Do not use a fresh-install example to replace that environment or silently switch managers. Changing a dependency declaration does not upgrade installed packages; `install.sh` and standalone script updates do not install or refresh MCP dependencies. See the [fixed MCP guide](https://github.com/abruption/session-peer/blob/v1.3.2/docs/mcp.md). + +The SDK floor accounts for upstream 1.x fixes; it does not establish an exploitable HTTP/OAuth/client vulnerability in this stdio-only application or enable those transports. The runtime CI tested exact SDK 1.30.0 and latest compatible 1.x on macOS/Linux with Python 3.10/3.13: eight combinations. Their resolved dependency graphs were audited; this is not a test of every transitive dependency's minimum version. See the [verification scope](https://github.com/abruption/session-peer/blob/v1.3.2/docs/mcp.md#validation). + +### Direct receiver output and operator updates + +In Python 1.3.2+, receiver startup preserves `ready:true` and adds `directReadyConfirmed:false`. The first means local listener setup; neither confirms remote accept/TLS, authenticated access, native submission, consumption or ACK. An older receiver can omit the new field: keep that evidence unknown rather than inventing false or failure. Check the actual running version, help and output contract. TLS may be an unauthenticated pairing bootstrap; an authenticated probe is separate evidence. + +Existing opt-in `--diagnostic-events` adds `direct_transport` stages `accepted` and `peer_tls`, with bounded `accepted`, `tlsCompleted` and `tlsFailed` counters. Each phase permits one record per 60 seconds, at most two per 60 seconds in total; TLS success and failure share the same phase slot. Normal close attempts one additional `summary`, including zero counts, without repeating it on repeated close. Missing records and unbalanced counters are possible. This is not a heartbeat, lossless history or ACK, and synchronous stderr has no hard deadline for a blocked sink. See the [fixed Direct reference](https://github.com/abruption/session-peer/blob/v1.3.2/docs/paired-devices.md#macos-direct-listener-checks-341). + +In the reported two-Mac incident, the owner allowed incoming connections for the expected Python application and recovered pairing/authenticated probes on the original released 1.3.1; diagnostic code did not repair the network. Ask the owner to verify the actual application's permission when appropriate. Keep the firewall enabled, the intended private bind, pinned TLS and receiver policy. Do not automatically widen to `0.0.0.0`, reset keys/DBs, change access policy or retry an uncertain pairing/send. This case does not establish a universal platform diagnosis or native delivery/ACK support. + +The optional receiver modules ship in wheel/sdist, not inside standalone `session_peer.py`. A standalone file update leaves an existing receiver environment unchanged. Its operator must separately upgrade that package environment and explicitly restart the receiver under an authorized rollout; publishing Python packages does not deploy services. + +Node Control's Better Auth/core 1.7.7 changes are outside Python artifacts and require a separate service update. A verification-namespace change may require restarting pending OAuth sign-ins, but does not justify mass session revocation, key rotation or database recreation. The historical 1.0.3 creation-time-plus-24-hour account-session limit remains valid. A deployment on one stack does not qualify all installations, signup policy, availability, live OAuth or native ACK. See the [release and operations boundaries](https://github.com/abruption/session-peer/blob/v1.3.2/docs/releases/v1.3.2.md#incident-and-compatibility-boundaries). + ## Install the skill ```bash @@ -71,11 +99,11 @@ npx -y skills@latest list --global --json npx -y skills@latest update session-peer --global --yes ``` -To pin a release exactly, install its tag, for example `v0.4.0`: +To pin a release exactly, install its tag, for example `v0.4.1`: ```bash npx -y skills@latest add \ - https://github.com/abruption/session-peer-skill/tree/v0.4.0/session-peer \ + https://github.com/abruption/session-peer-skill/tree/v0.4.1/session-peer \ --skill session-peer --global \ --agent claude-code --agent codex --agent antigravity \ --copy --yes diff --git a/docs/usage.zh-CN.md b/docs/usage.zh-CN.md index 65066e5..60fbd2b 100644 --- a/docs/usage.zh-CN.md +++ b/docs/usage.zh-CN.md @@ -15,7 +15,7 @@ uv、pip、POSIX 独立安装程序以及 Windows 原生环境的安装方式， 本技能介绍的基本命令由 session-peer 0.9.1 及更高版本共同支持。`--allow-inactive-codex-home` 和 `--relay-login` 需要 session-peer 1.0.0 或更高版本。macOS/Linux 接收端策略中的 `codexBin`，以及使用 `attemptId` 关联连接尝试的 Relay 诊断，需要 session-peer 1.0.1 或更高版本。可选的配对设备传输需要 `session-peer[relay]` 附加依赖项（extra）（Unix、Python 3.11 或更高版本）。 -已发布 Python CLI 功能的覆盖基准为 session-peer 1.3.0。 +已发布 Python CLI 功能的覆盖基准为 session-peer 1.3.2。 ## 运行时 1.0.3 的安全与运维 @@ -35,7 +35,7 @@ Python 1.1.0 及更高版本会引用外部消息正文的每一行，并将有 ## Python 1.3 使用流程 -以下可选流程需要 Python 运行时 1.3.0 或更高版本。基本 CLI 兼容性下限仍为 0.9.1，已发布 CLI 功能的覆盖基准为 1.3.0。应检查实际选用的运行时版本及命令帮助中明确的支持信息，同时核对各功能的平台和权限要求。接收器 `codexBin` 的独立最低版本仍为 1.0.1。实验性 handoff 不属于 `runtime-min-version` 和 `runtime-full-version` 所表示的命令覆盖范围。请参阅[已发布的运行时版本](https://github.com/abruption/session-peer/releases/tag/v1.3.0)。 +以下可选流程需要 Python 运行时 1.3.0 或更高版本。基本 CLI 兼容性下限仍为 0.9.1，已发布 CLI 功能的覆盖基准为 1.3.2。应检查实际选用的运行时版本及命令帮助中明确的支持信息，同时核对各功能的平台和权限要求。接收器 `codexBin` 的独立最低版本仍为 1.0.1。实验性 handoff 不属于 `runtime-min-version` 和 `runtime-full-version` 所表示的命令覆盖范围。请参阅[已发布的运行时版本](https://github.com/abruption/session-peer/releases/tag/v1.3.0)。 - [发送说明](https://github.com/abruption/session-peer/blob/v1.3.0/docs/cli-reference.md#delivery-explanation)：`send --dry-run --explain` 使用常规消息输入，支持本地、SSH 和配对路由，仅输出文本。`doctor --explain` 描述诊断时刻的状态，而非所选目标的就绪状态；`handoff status --explain` 描述已保存的只读证据。与 JSON 以及 handoff SEND 的 correlation、ACK、observe、wait 组合均被拒绝。说明复用现有结果，不增加探测、激活、提交或收据权限；原有 dry-run 版本检查另行执行。配对上下文由现有探测协商，受允许列表和 8 KiB 上限约束；较旧接收器保留已知的原生事实，缺失信息保持 unknown。预览不授予权限、不预留目标，也不证明 ACK。退出码 0 本身不能证明没有提交；unknown 或意外提交均不允许自动重发。wake 仍需用户明确要求。 - [路由预设](https://github.com/abruption/session-peer/blob/v1.3.0/docs/cli-reference.md#route-presets)和独立的[接收者地址簿](https://github.com/abruption/session-peer/blob/v1.3.0/docs/cli-reference.md#recipient-addressbook-v130)仅支持 macOS、Linux 的本地或 SSH Claude、Codex。仅按用户请求管理条目。`preset show` 读取已存路由及修订值，`list --preset` 搜索当前会话。实际预设发送要求 `--to` 和 `--preset-revision`；replace/remove 使用 `--expect-revision`。`dp1` 是值的哈希，恢复相同名称和路由会得到相同值；后续修改不会取消已完成路由展开的调用。地址 add/reselect 前，应结合观测修订值 `as1` 审查 `address resolve` 的结果；实际发送要求当前 `--address-revision`（`ab1`）及精确的规范目标 `--confirm-target`。reselect/remove 检查修订值，每次 add/reselect 都创建新的 binding ID。Claude 保留 `tg1`；Codex 的 `aw1` 是重新检查的 writer 观测值，不支持代次识别，也不保证存储或运行实例的原子一致性。SSH 绑定实际选择连接中验证的密钥，并在发送时固定使用。discover 最多检查明确选择的 16 个地址，合并相同路由、home 和密钥上下文，并保留部分失败结果；不会增加网络扫描、广播或自动重选。标签和修订值不认证人员、不授予权限，也不证明 ACK。私有存储、ACL 或挂载检查拒绝时，应停止并交由操作人员审查，不得修复权限或自动改走其他路由。 @@ -46,6 +46,34 @@ Python 1.1.0 及更高版本会引用外部消息正文的每一行，并将有 运行时发布不会发布或安装这个独立管理的技能。只有核实记录的标签、源码提交和 SKILL 哈希后，才可采用另行批准的不可变技能发布。Python 运行时的兼容副本依据该准确的已发布技能源码单独更新；既有运行时发布保持不可变。 +## Python 1.3.2 维护说明 + +这些维护说明以[已发布的 Python 运行时 1.3.2](https://github.com/abruption/session-peer/releases/tag/v1.3.2)、源码 `f5e7c49554ff02771990a151e00b52f2abf3df0a` 为准。基本 CLI 兼容性下限仍为 0.9.1；本次修订也指导读者解读新的 Direct 输出，因此已发布功能覆盖基准为 1.3.2。原有 1.3.0 使用流程的版本要求和接收器 `codexBin` 的独立下限 1.0.1 保持独立。 + +### 可选 MCP 的安装与升级 + +基本 CLI 支持 Python 3.9+，没有必需的外部依赖。可选 MCP 需要 Python 3.10+ 和 `session-peer[mcp]` extra。运行时 1.3.2 要求 MCP SDK `mcp>=1.30,<2`。对于新的隔离环境，文档给出的 pipx 安装示例如下： + +```bash +pipx install 'session-peer[mcp]' +``` + +对于现有 MCP 环境，应保留其解释器和所选 extra，通过原来的管理工具显式升级。不要用新安装示例替换该环境，也不要擅自切换管理工具。修改依赖声明不会升级已安装的软件包；`install.sh` 和独立脚本更新不会安装或刷新 MCP 依赖。参见[固定版本的 MCP 指南](https://github.com/abruption/session-peer/blob/v1.3.2/docs/mcp.md)。 + +SDK 下限反映了上游 1.x 的修复，但不代表已确认这个仅使用标准输入/输出（stdio）的应用存在可被利用的 HTTP/OAuth/client 漏洞，也不会启用这些传输方式。运行时 CI 在 macOS/Linux、Python 3.10/3.13 上分别测试了准确的 SDK 下限 1.30.0 和最新兼容的 1.x，共 8 种组合。审计的是这些环境实际解析得到的依赖图，并未测试每个传递依赖包的最低版本。参见[验证范围](https://github.com/abruption/session-peer/blob/v1.3.2/docs/mcp.md#validation)。 + +### Direct 接收器输出与运维更新 + +在 Python 1.3.2+ 中，接收器启动输出保留 `ready:true`，并增加 `directReadyConfirmed:false`。前者表示本地监听器已设置；两者均不确认远端连接接纳/TLS、已认证访问、原生提交、消费或 ACK。旧接收器可能不输出新字段：应保留为未知证据，不要擅自补成 false 或失败。请核对实际运行版本、帮助信息和输出契约。TLS 可能只是未认证的配对初始化；已认证 probe 是另一项独立证据。 + +现有的主动启用选项 `--diagnostic-events` 增加了 `direct_transport` 阶段 `accepted` 和 `peer_tls`，以及有上限的 `accepted`、`tlsCompleted`、`tlsFailed` 计数器。每个阶段每 60 秒最多输出 1 条记录，每 60 秒共最多 2 条；TLS 成功与失败共享同一阶段的额度。正常关闭时会额外尝试输出 1 条 `summary`，包括计数为零的情况；重复关闭不会重复输出。记录缺失或计数不平衡都可能发生。这不是 heartbeat、无损历史或 ACK；同步 stderr 在输出端阻塞时也没有严格的期限保证。参见[固定版本的 Direct 参考说明](https://github.com/abruption/session-peer/blob/v1.3.2/docs/paired-devices.md#macos-direct-listener-checks-341)。 + +在所报告的两台 Mac 事件中，所有者允许相应 Python 应用的传入连接后，原先已发布的 1.3.1 恢复了配对和已认证 probe；修复网络的并非诊断代码。适当时应请所有者核对实际应用的权限。保持防火墙启用，并保留预期的私有 bind、固定的 TLS 身份及接收器策略。不要自动扩大到 `0.0.0.0`、重置密钥/DB、更改访问策略，或重试结果不确定的配对/发送。该事件不能证明通用于所有平台的诊断，也不能证明原生交付/ACK 支持。 + +可选接收器模块包含在 wheel/sdist 中，不内置于独立的 `session_peer.py`。仅更新独立文件不会改变现有接收器环境。运维人员必须在获得授权的部署安排下，单独升级该软件包环境，并显式重启接收器；发布 Python 软件包不会自动部署服务。 + +Node Control 的 Better Auth/core 1.7.7 修改不属于 Python 制品，需要单独更新服务。验证命名空间变化可能要求重新开始尚未完成的 OAuth 登录，但不能据此批量撤销会话、轮换密钥或重新创建数据库。历史上 1.0.3 引入的账户会话“创建时刻加 24 小时”限制仍然有效。一个服务栈的部署不能验证所有安装环境、注册策略、可用性、实际 OAuth 或原生 ACK。参见[发布与运维边界](https://github.com/abruption/session-peer/blob/v1.3.2/docs/releases/v1.3.2.md#incident-and-compatibility-boundaries)。 + ## 安装技能 ```bash @@ -69,11 +97,11 @@ npx -y skills@latest list --global --json npx -y skills@latest update session-peer --global --yes ``` -需要固定某个版本时，请安装对应标签，例如 `v0.4.0`： +需要固定某个版本时，请安装对应标签，例如 `v0.4.1`： ```bash npx -y skills@latest add \ - https://github.com/abruption/session-peer-skill/tree/v0.4.0/session-peer \ + https://github.com/abruption/session-peer-skill/tree/v0.4.1/session-peer \ --skill session-peer --global \ --agent claude-code --agent codex --agent antigravity \ --copy --yes diff --git a/scripts/python-coverage.test.mjs b/scripts/python-coverage.test.mjs index cf386b8..f55d7e4 100644 --- a/scripts/python-coverage.test.mjs +++ b/scripts/python-coverage.test.mjs @@ -8,7 +8,7 @@ const text = (full = '1.3.0', codexBin = '1.0.1') => `receiver policy \`codexBin\` requires\n session-peer ${codexBin} or newer` test('coverage can advance while the receiver feature floor stays at 1.0.1', () => { - for (const full of ['1.0.1', '1.3.0']) { + for (const full of ['1.0.1', '1.3.0', '1.3.2']) { assert.deepEqual(validatePythonCoverage(text(full), '0.9.1', full), []) } }) @@ -46,13 +46,14 @@ test('minimum comparison is numeric across major, minor and patch components', ( }) // These literal documentation claims are independent of the validator's parser. -const currentFull = '1.3.0' +const currentFull = '1.3.2' +const previousFull = '1.3.0' const legacyFull = '1.0.1' const claims = { - en: 'The published Python CLI coverage reference is session-peer 1.3.0.', - ko: '공개 Python CLI 기능 범위의 기준 버전은 session-peer 1.3.0입니다.', - ja: '公開 Python CLI の機能範囲の基準は session-peer 1.3.0 です。', - zh: '已发布 Python CLI 功能的覆盖基准为 session-peer 1.3.0。' + en: 'The published Python CLI coverage reference is session-peer 1.3.2.', + ko: '공개 Python CLI 기능 범위의 기준 버전은 session-peer 1.3.2입니다.', + ja: '公開 Python CLI の機能範囲の基準は session-peer 1.3.2 です。', + zh: '已发布 Python CLI 功能的覆盖基准为 session-peer 1.3.2。' } const documents = [ ['README.md', 'en'], ['README.ko.md', 'ko'], @@ -64,16 +65,20 @@ const readDocument = path => readFileSync(new URL('../' + path, import.meta.url) const changedClaim = (body, claim, version) => body.replace(claim, claim.replace(currentFull, version)) for (const [path, locale] of documents) { - test(`${path}: actual current and legacy coverage pass independently of feature mentions`, () => { + test(`${path}: actual current, previous and legacy coverage pass independently of feature mentions`, () => { const body = readDocument(path) const claim = claims[locale] assert.ok(body.includes(claim), 'the actual document must contain its explicit coverage assertion') assert.deepEqual(validateLocalizedCoverage(path, body, currentFull), []) - const legacy = changedClaim(body, claim, legacyFull) - assert.deepEqual(validateLocalizedCoverage(path, legacy, legacyFull), []) + for (const supported of [previousFull, legacyFull]) { + const historical = changedClaim(body, claim, supported) + assert.deepEqual(validateLocalizedCoverage(path, historical, supported), []) + if (path.startsWith('docs/')) { + assert.deepEqual(validateLocalizedCodexBin(path, historical), []) + } + } if (path.startsWith('docs/')) { assert.deepEqual(validateLocalizedCodexBin(path, body), []) - assert.deepEqual(validateLocalizedCodexBin(path, legacy), []) } }) @@ -81,9 +86,10 @@ for (const [path, locale] of documents) { const body = readDocument(path) const claim = claims[locale] const wrong = changedClaim(body, claim, legacyFull) + const previous = changedClaim(body, claim, previousFull) const missing = body.replace(claim, '') - for (const mutation of [wrong, missing]) { - const withFeature = mutation + '\nExplain requires session-peer 1.3.0.\n' + for (const mutation of [wrong, previous, missing]) { + const withFeature = mutation + `\nAn independent feature requires session-peer ${currentFull}.\n` assert.ok(validateLocalizedCoverage(path, withFeature, currentFull).length > 0) } for (const mutation of [body, missing]) { @@ -99,12 +105,12 @@ for (const [path, locale] of documents) { test(`${path}: malformed claims and malformed expected coverage versions fail`, () => { const body = readDocument(path) const claim = claims[locale] - for (const version of ['+1.3.0', '-1.3.0', 'v1.3.0', '1.3', '1.3.0-preview', '1.3.0.2', '01.3.0']) { + for (const version of [`+${currentFull}`, `-${currentFull}`, `v${currentFull}`, '1.3', `${currentFull}-preview`, `${currentFull}.2`, `0${currentFull}`]) { const mutation = changedClaim(body, claim, version) assert.ok(validateLocalizedCoverage(path, mutation, currentFull).length > 0, version) assert.ok(validateLocalizedCoverage(path, mutation, version).length > 0, version) } - for (const version of [undefined, '', '+1.3.0', '-1.3.0', '1.3.0-preview']) { + for (const version of [undefined, '', `+${currentFull}`, `-${currentFull}`, `${currentFull}-preview`]) { assert.ok(validateLocalizedCoverage(path, body, version).length > 0, String(version)) } }) diff --git a/session-peer/SKILL.md b/session-peer/SKILL.md index cfb98b6..44e2cf6 100644 --- a/session-peer/SKILL.md +++ b/session-peer/SKILL.md @@ -3,9 +3,9 @@ name: session-peer description: Send user-requested messages to Claude Code, Codex, or a live registered Antigravity TUI on this machine, an SSH host, or a paired device using session-peer. Use for cross-session handoffs and notifications when the available native tools do not cover the requested target. allowed-tools: Bash, Read metadata: - version: "0.4.0" + version: "0.4.1" runtime-min-version: "0.9.1" - runtime-full-version: "1.3.0" + runtime-full-version: "1.3.2" --- # Session messaging @@ -21,7 +21,7 @@ exist only in 1.0.0 and newer; confirm them with `session-peer send --help` before use. For security fixes, recommend Python runtime 1.0.3 or newer; `runtime-min-version` and `runtime-full-version` describe CLI compatibility, not security currency. -The published CLI coverage reference is session-peer 1.3.0. +The published CLI coverage reference is session-peer 1.3.2. It excludes the separately identified experimental handoff workflow. If the command is missing, explain that installing the skill did not install the runtime and recommend one of the supported installation paths in the [repository README](https://github.com/abruption/session-peer#installation-options). @@ -292,7 +292,7 @@ the other sources' sessions. This applies to local and SSH listing. ## Python 1.3 workflows -The following optional workflows require Python runtime 1.3.0 or newer. The basic CLI compatibility floor remains 0.9.1, and the published CLI coverage reference is 1.3.0. Check the resolved runtime version and affirmative command help, along with each feature's platform and permission requirements. Receiver `codexBin` retains its independent 1.0.1 floor. Experimental handoff is excluded from the command coverage represented by `runtime-min-version` and `runtime-full-version`. See the [published runtime release](https://github.com/abruption/session-peer/releases/tag/v1.3.0). +The following optional workflows require Python runtime 1.3.0 or newer. The basic CLI compatibility floor remains 0.9.1, and the published CLI coverage reference is 1.3.2. Check the resolved runtime version and affirmative command help, along with each feature's platform and permission requirements. Receiver `codexBin` retains its independent 1.0.1 floor. Experimental handoff is excluded from the command coverage represented by `runtime-min-version` and `runtime-full-version`. See the [published runtime release](https://github.com/abruption/session-peer/releases/tag/v1.3.0). - [Explanation](https://github.com/abruption/session-peer/blob/v1.3.0/docs/cli-reference.md#delivery-explanation): text-only `send --dry-run --explain` covers local, SSH and paired routes with normal message input. `doctor --explain` describes a diagnostic snapshot, not a selected target's readiness; `handoff status --explain` describes stored read-only evidence. JSON combinations and handoff SEND correlation/ACK/observe/wait combinations are refused. Explanations reuse existing results without extra probes, activation, submission or receipt authority; existing dry-run version checks are separate. Paired context is negotiated by the existing probe, allowlisted and bounded to 8 KiB; older receivers retain known native facts and leave missing context unknown. A preview grants no permission, reserves no target and provides no ACK evidence. Exit zero alone does not prove non-submission; unknown or unexpected submission never permits automatic resend. Wake still requires an explicit user request. - [Route presets](https://github.com/abruption/session-peer/blob/v1.3.0/docs/cli-reference.md#route-presets) and the separate [recipient addressbook](https://github.com/abruption/session-peer/blob/v1.3.0/docs/cli-reference.md#recipient-addressbook-v130) support macOS/Linux local/SSH Claude/Codex only. Manage entries only on user request. `preset show` reads stored route/revision data; `list --preset` discovers current sessions. Actual preset send requires `--to` and `--preset-revision`; replace/remove use `--expect-revision`. The `dp1` value hash repeats when identical name/route values are restored, and later changes do not cancel an already expanded invocation. For addresses, review `address resolve` before add/reselect, using its `as1` observation revision; actual send requires current `--address-revision` (`ab1`) and exact canonical `--confirm-target`. Reselect/remove use revision checks, and each add/reselect creates a new binding ID. Claude retains `tg1`; Codex `aw1` is a rechecked writer observation, with generation unsupported and no atomic storage/incarnation guarantee. SSH binds the verified key from the actual selection connection and pins it for send. Discover inspects at most 16 explicitly selected addresses, groups identical route/home/key contexts and preserves partial failures; it adds no network scan, broadcast or automatic reselection. Labels/revisions do not authenticate people, grant permission or prove ACK. Stop for operator review on private-storage/ACL/mount refusals; do not repair permissions or fall back automatically. @@ -302,3 +302,31 @@ The following optional workflows require Python runtime 1.3.0 or newer. The basi - [Runtime notice preferences](https://github.com/abruption/session-peer/blob/v1.3.0/docs/cli-reference.md#updating): macOS/Linux local offline `update --dismiss-runtime-notice VERSION` or `--clear-runtime-notice-dismissal` changes only the automatic notice for an exact version. These commands do not check, install or approve a release; remote/SSH/check combinations are refused. Explicit checks retain real latest/outdated results; skill notices and global opt-out remain unchanged. Windows lacks this preference. Example versions are not release announcements. Runtime publication does not publish or install this independently managed skill. Adopt only a separately approved immutable skill release after verifying its recorded tag, source commit and SKILL hash. Update the Python runtime's compatibility snapshot in a separate change using that exact published skill source; existing runtime releases remain immutable. + +## Python 1.3.2 maintenance + +Optional MCP requires Python 3.10+ and the `session-peer[mcp]` extra; runtime +1.3.2 requires SDK `mcp>=1.30,<2`. The core CLI still supports Python 3.9 without +mandatory external dependencies. Separate a new extra installation from an +explicit upgrade using an existing environment's manager, interpreter and extras. +A standalone update does not update that environment. The dependency-floor change +does not establish exploitability in the stdio-only server; see the +[fixed MCP reference](https://github.com/abruption/session-peer/blob/v1.3.2/docs/mcp.md). + +For Direct receivers in Python 1.3.2+, startup `ready:true` means the local +listener is ready; `directReadyConfirmed:false` does not confirm remote access. +Keep a missing field on an older receiver unknown. TCP acceptance, TLS, +authenticated access, native submission and consumption/ACK are separate facts. +Opt-in `--diagnostic-events` provides bounded stage/counter and normal-close +summaries, not a heartbeat, lossless stream or ACK. Ask the owner to review the +expected Python application's incoming-connection permission if needed; do not +disable the firewall, widen binds, reset keys/DBs or retry uncertain operations. +See the [Direct diagnostic contract](https://github.com/abruption/session-peer/blob/v1.3.2/docs/paired-devices.md#macos-direct-listener-checks-341). + +Receiver modules are in wheel/sdist, not the standalone script; an operator must +separately update their package environment and explicitly restart the receiver. +Node Control's Better Auth/core 1.7.7 update is outside Python artifacts too. +Pending OAuth sign-ins may need restarting; that is not authority to revoke +sessions, rotate keys or recreate databases. Perform these operational changes +only on an explicit operator request; see the +[maintenance boundaries](https://github.com/abruption/session-peer/blob/v1.3.2/docs/releases/v1.3.2.md#incident-and-compatibility-boundaries).