n24q02m/agent-chat-plugin

agent-chat

概要

ピアエージェントセッションは、共有チャンネルフォルダ内のマークダウンファイルを交換することで連携します。スーパーバイザー、メッセージブローカー、共有RAMは不要です。各チャンネルは1つの「グループチャット」です。スレッド全体はプレーンマークダウンであり、Gitコミット可能、人間が読み取り可能、再生可能です。クラッシュしたセッションも何も失いません。ファイルが状態です。

stdlibのみのCLI（chat.pyと、その兄弟パッケージagent_chat/）は、Windows、WSL、Linuxで動作します。waitはファイルシステムのチェック間でスリープし、モデル呼び出しを行いません。

核となる原則: エージェント同士を介さず、ファイルを介して通信する。完全なトランスクリプトをやり取りするのではなく、要約を成果物として扱う。

これはローカルな連携データ層であり、MCPサーバーやエージェント実行基盤ではありません。 メッセージ、タスク、リース、パスロック、能力/ステータスイベント、および派生状態は、 completion、embedding、rerank、graph-service、relay/providerの呼び出しを行いません。

使用すべき場合

• 複数のOMP（または他の互換性のある）エージェントセッションが、対等な立場で同じ問題に取り組んでいる場合。
• あるセッションが別のセッションに何かを依頼し、その結果を待つ必要がある場合。
• エージェント間の交渉を監査可能な記録として残したい場合。
• 複数の独立したグループチャット（トピック/チームごとに1つ）が必要な場合。チャンネルを1つずつ作成します。

使用すべきでない場合: 単一のエージェントと安価なサブエージェントの方が、より安価でシンプルです。このパターンは、トークンと引き換えに並列性、耐障害性、監査可能性を提供します。トークン予算が厳しい場合は、非同期/ハンドオフパス（セッション終了時に要約を投稿し、次のセッションがそれを読み取る）のみを使用してください。このモードのコストはほぼゼロです。

クイックリファレンス

pipx install agent-chat-plugin 後に agent-chat <cmd> を使用するか、1回限りの呼び出しには uvx --from agent-chat-plugin agent-chat <cmd> を使用します。uvxは永続的なコマンドをインストールしません。スタンドアロンスキルの場合は、SKILL.md、chat.py、および agent_chat/ ディレクトリ全体を同じ場所に配置し、python "/path/to/skill/chat.py" <cmd> を実行します。例ではこれを chat.py と省略します。

Claude Codeプラグインは python "${CLAUDE_PLUGIN_ROOT}/chat.py" <cmd> を使用します。 他のホストは、想定されたプラグイン変数ではなく、実際のチェックアウトパスを使用します。 ルートの優先順位は --root > $AGENT_CHAT_ROOT > ~/agent-chat です。--root はサブコマンドの前に指定します。異なるマシンのデフォルトルートは同期されません。

PyPIインストールはCLI/ランタイムモジュールのみを提供します。オプションの hooks/*.py はチェックアウト/プラグインから提供され、明示的なホストライフサイクル配線が必要です。これらのPythonエントリーポイントは移植可能ですが、その登録と出力契約は自動的にOMP統合になるわけではありません。セッション/プロンプト通知はテキストであり、StopはClaude互換の systemMessage JSONを出力します。フックはカーソルを進めずに覗き見し、常に0で終了します。未解決の CLAUDE_PLUGIN_ROOT またはスクリプト相対のプラグインルートは、1行のstderr診断メッセージでスキップされます。

操作	コマンド
グループチャットを作成	chat.py init review --members alice,bob --topic "..."
すべてのグループチャットを一覧表示	chat.py channels
メッセージを投稿	chat.py post review --from alice --to bob --title "Schema v0.2" --body-file msg.md
グループにブロードキャスト	chat.py post review --from alice --to all --title "..." （ --to を省略しても可）
自分の新しいメッセージを読む	chat.py read review --as bob
返信を待つ（トークン消費ゼロ）	chat.py wait review --as alice --timeout 900
最近のメッセージを覗き見（カーソルを進めず）	chat.py peek review -n 3
タスクマーカーを主張	chat.py claim work task-12.md --as bob
ワークスペースパスをロック	chat.py lock review src/main.py --as alice --lease-seconds 300
パスの競合を確認	chat.py check review src/main.py
パスロックを解放	chat.py unlock review <lock-id-or-path> --as alice
古くなったロックを回復	chat.py recover review <lock-id-or-path> --as bob --reason "stale"
保留中のパストランザクションを回復	chat.py recover-pending review --as alice
チャンネル状態を表示	chat.py state review
チャンネル状態を圧縮	chat.py compact review --as alice
能力/ステータスイベントを投稿	chat.py event post review --from alice --type capability --harness omp
アダプターイベントを読み取り	chat.py event read review --type capability

アダプター中立なイベントはスキーマバージョン 1 を使用し、通常のチャンネルメッセージ内でJSON本文として運ばれます。能力イベントは、移植可能なプリミティブ messages、cursors、wait、tasks、dependencies、leases、path_locks、state_summary のみを広告します。ステータスイベントは ready、busy、idle、blocked、または stopped を、オプションの詳細とともに使用します。未知のフィールド、プリミティブ、バージョン、タイムスタンプ、ID、ステータスは、安定した EVENT_* エラーで失敗します。このプロトコルは、MCP、ACP、ウェイクブリッジ、またはエージェント実行を主張しません。構造化タスクは同じチャンネルルートを使用し、<root>/<channel>/tasks/ 配下に信頼性のあるJSONレコードを書き込みます。アクティブなリースレコードは <root>/<channel>/claims/<task-id>.<owner>.json にあります。すべての成功したタスクまたはリースの変更は、既存のメッセージプロトコルを通じて監査イベントも投稿します。

chat.py task create <channel> <task-id> --from <agent> --title <title>
chat.py task list <channel>
chat.py task show <channel> <task-id>
chat.py task update <channel> <task-id> --as <agent> [fields...]
chat.py task claim <channel> <task-id> --as <agent> --lease-seconds 300
chat.py task renew <channel> <task-id> --as <agent> --lease-seconds 300
chat.py task done <channel> <task-id> --as <agent>
chat.py task block <channel> <task-id> --as <agent>
chat.py task release <channel> <task-id> --as <agent>
chat.py task recover <channel> <task-id> --as <agent> \
  --reason "stale session" --lease-seconds 300
chat.py task recover-pending <channel> --as <agent> \
  [--resolve-publication rollback|published]

claim、renew、および古くなった場合の recover は --lease-seconds、--lease、または --ttl を受け入れます。値は正の有限な期間である必要があります。claim は準備完了（ready）状態のタスクを in_progress に進め、所有者を割り当て、その有効期限をクレームレコードとアトミックに書き込みます。有効期限が切れていないクレームを更新、解放、または完了できるのは所有者のみです。task done はアクティブなクレームをアトミックにクリアします。クレームが存在しない場合は、直接的なタスク3遷移を維持します。task release は同様に、リースされていないタスク3遷移を維持します。期限切れのクレームは静かに奪われることはありません。古くなった task recover には新しい所有者と空でない理由が必要であり、previous_owner、previous_lease_expires_at、および recovery_reason を記録します。クラッシュ後、task recover-pending <channel> --as <agent> は永続トランザクションマーカーのクリーンアップ/ロールバックを明示的に完了します。古くなったタスクを静かに奪ったり再割り当てしたりすることはありません。監査公開が証明できないレガシーv1 applied マーカーは LEASE_TRANSACTION_PUBLICATION_UNKNOWN で失敗します。オペレーターの確認後、--resolve-publication rollback または published を指定してコマンドを再実行してください。

create は --owner、--depends-on、--files-hint、--acceptance、および --branch を受け入れます。リストオプションを繰り返して複数の値を追加します。update は --title、--owner、--depends-on、--files-hint、--acceptance、--branch、および --status を受け入れます。--clear-owner または --clear-branch を使用して、null 可能フィールドを null に戻します。汎用の更新はアクティブなリースを変更できません。代わりにリースコマンドを使用してください。リスト値はカンマ区切りでも指定できます。

タスクステータスは open、in_progress、blocked、done、および cancelled です。done と cancelled は終端状態です。遷移は open -> in_progress | blocked | cancelled、in_progress -> open | blocked | done | cancelled、blocked -> open | in_progress | cancelled を許可します。同一状態への書き込みは意図的に冪等です。task done は in_progress（または冪等な done）を done に移動します。task block は open、in_progress、または blocked を blocked に移動します。task release は blocked、in_progress、または open を open に移動します。タスクは、depends_on 内のすべてのIDがステータス done のタスクレコードを持つ場合にのみ、in_progress または done に進むことができます。準備完了状態（readiness）はタスクJSONレコードから計算され、メッセージテキストからは決して計算されません。

タスクおよびリースの障害は非ゼロ（終了ステータス2）であり、1つの安定したコードを含みます。タスクコードには TASK_INVALID_COMMAND、TASK_INVALID_ARGUMENT、TASK_INVALID_CHANNEL、TASK_CHANNEL_NOT_FOUND、TASK_NOT_FOUND、TASK_ALREADY_EXISTS、TASK_INVALID_STATUS、TASK_INVALID_UPDATE、TASK_INVALID_TRANSITION、TASK_DEPENDENCY_NOT_READY、TASK_UNKNOWN_DEPENDENCY、TASK_DEPENDENCY_CYCLE、TASK_PATH_OUTSIDE_WORKSPACE、TASK_LOCK_TIMEOUT、TASK_IO_ERROR、および TASK_AUDIT_FAILED が含まれます。リースコードには LEASE_CONFLICT、LEASE_RECOVERY_REQUIRED、LEASE_OWNER_MISMATCH、LEASE_NOT_EXPIRED、LEASE_NOT_FOUND、LEASE_INCONSISTENT、LEASE_MUTATION_REQUIRED、LEASE_INVALID_OWNER、LEASE_INVALID_TASK_ID、LEASE_INVALID_CHANNEL、LEASE_INVALID_REASON、LEASE_INVALID_DURATION、LEASE_INVALID_TIMESTAMP、LEASE_INVALID_RECORD、LEASE_REQUIRED_FIELD_MISSING、LEASE_UNKNOWN_FIELD、LEASE_RECORD_ID_MISMATCH、LEASE_STORAGE_INVALID、LEASE_PATH_OUTSIDE_WORKSPACE、LEASE_TRANSACTION_PENDING、LEASE_TRANSACTION_CLEANUP_FAILED、LEASE_TRANSACTION_PUBLICATION_UNKNOWN、LEASE_TRANSACTION_INVALID、LEASE_TRANSACTION_NOT_FOUND、LEASE_TRANSACTION_RECOVERY_FAILED、LEASE_AUDIT_FAILED、および LEASE_AUDIT_ROLLBACK_FAILED が含まれます。リースの書き込みは、prepared/applied/publishedフェーズを持つ永続トランザクションマーカーを使用します。クラッシュまたはクリーンアップの失敗後、task recover-pending/LeaseStore.recover_pending() が明示的にロールバックするか、公開されたトランザクションを完了するまで、アクセスは失敗します。

パスロックは、ワークスペース相対のファイルおよびディレクトリへの排他的アクセスを調整します。

chat.py lock <channel> <paths...> --as <agent> [--lease-seconds 300]
chat.py check <channel> <paths...> [--as <agent>]
chat.py unlock <channel> <lock-id-or-path> --as <agent>
chat.py recover <channel> <lock-id-or-path> --as <agent> \
  --reason "stale session" [--lease-seconds 300]
chat.py recover-pending <channel> --as <agent> \
  [--resolve-publication rollback|published]

lock と recover は --lease-seconds、--lease、または --ttl を受け入れます。ターゲットはロックIDまたは正規化された正確なパスです。正規化は、ワークスペース相対パスを解決し、トラバーサル、ルート/チャンネル/シンボリックリンクエスケープを防止し、プラットフォームのケースルールを適用し（Windowsでは大文字小文字を区別しない）、Windowsの予約名、末尾のドット/スペース、制御文字、および単独サロゲートを拒否します。ファイル/ファイルの衝突およびディレクトリ/ファイルの重複は競合します。アクティブなロックを解除できるのは所有者のみです。期限切れのロックは、previous_owner、previous_expires_at、および recovery_reason を記録する明示的な recover が必要です。変更は、コンテンツアトミックなファイル公開、アドバイザリファイルロック、およびクラッシュセーフなトランザクションジャーナリングを使用します。パスロックエラーは非ゼロで終了し、安定したコード（PATH_LOCK_INVALID_PATH、PATH_LOCK_PATH_OUTSIDE_WORKSPACE、PATH_LOCK_CONFLICT、PATH_LOCK_RECOVERY_REQUIRED、PATH_LOCK_OWNER_MISMATCH、PATH_LOCK_NOT_FOUND、PATH_LOCK_NOT_STALE、PATH_LOCK_INVALID_OWNER、PATH_LOCK_INVALID_LOCK_ID、PATH_LOCK_INVALID_CHANNEL、PATH_LOCK_INVALID_REASON、PATH_LOCK_INVALID_DURATION、PATH_LOCK_INVALID_TIMESTAMP、PATH_LOCK_INVALID_RECORD、PATH_LOCK_STORAGE_INVALID、PATH_LOCK_STORAGE_ERROR、PATH_LOCK_TIMEOUT、PATH_LOCK_TRANSACTION_PENDING、PATH_LOCK_TRANSACTION_CLEANUP_FAILED、PATH_LOCK_TRANSACTION_INVALID、PATH_LOCK_AUDIT_FAILED、および PATH_LOCK_AUDIT_ROLLBACK_FAILED）を含みます。

チャンネル状態の要約と圧縮は、決定論的な state.md 成果物を生成します。

chat.py state <channel> [--write] [--json] [--strict]
chat.py compact <channel> [--as <agent>] [--no-audit] [--json] [--strict]

state は、以下のものを含む派生チャンネル要約をレンダリングまたは出力します。

• 目標 / トピック（_meta.json から）
• 決定事項（メッセージと構造化レコードから抽出）
• オープンタスク（tasks/*.json から、ステータス、所有者、リース、依存関係を含む）
• ブロッカー（タスク依存関係ブロッカー、ブロックされたタスクステータス、およびブロッカーメッセージ）
• 所有者とリース（アクティブなクレーム、タスク所有権、およびパスロック）
• パスロック（locks/*.json からのアクティブなパスロック）
• 最終検証証跡（合格基準と検証メッセージ）

compact は、派生要約をアトミックな一時的な兄弟置換（.state.md.tmp.*）を使用して <root>/<channel>/state.md に書き込み、デフォルトで監査可能な state.compacted メッセージイベントをチャンネルに投稿します。

state.md は厳密に派生成果物であり、決して信頼できる情報源ではありません。 圧縮は非破壊的です。メッセージファイル、タスクレコード、アクティブなクレーム、パスロック、または読み取りカーソルを決して削除、変更、または切り詰めません。すべてのソースレコードは不変のグラウンドトゥルースのままです。 状態エラーは非ゼロで終了し、安定したコード（STATE_INVALID_CHANNEL、STATE_CHANNEL_NOT_FOUND、STATE_INVALID_RECORD、STATE_MALFORMED_SOURCE、STATE_RECORD_NOT_FOUND、STATE_IO_ERROR、および STATE_AUDIT_FAILED）を含みます。--reply <seq> はメッセージを以前のメッセージにスレッド化します。すべてのフラグについては python chat.py <cmd> --help を参照してください。

アダプター中立なイベントコマンド:

chat.py event post <channel> --from <agent> --type capability --harness <harness>
chat.py event post <channel> --from <agent> --type status --harness <harness> --status ready
chat.py event read <channel> [--type capability|status]

イベント本文は、schemas/agent-chat-event.schema.json に対して検証されるバージョン管理されたJSONです。通常のMarkdownメッセージは変更されず、event read によって無視されます。

フォルダ構成

<root>/
  review/                     # 1チャンネル = 1グループチャット
    _meta.json                # メンバー、トピック、作成日時
    state.md                  # 派生状態要約（非信頼できる情報源）
    0001-alice-schema-draft.md # NNNN-<from>-<slug>.md、フロントマター + 本文
    0002-bob-schema-review.md
    tasks/                    # 構造化タスクレコード
    claims/                   # アクティブなリースレコード
    locks/                    # アクティブなワークスペースパスロック
    .cursors/bob.txt          # エージェントごとの「最後に読んだシーケンス番号」
  deploy/                    # 2つ目のグループチャット、別のシーケンス空間
    ...

メッセージファイルの命名規則は NNNN-<from>-<slug>.md です。NNNN はチャンネル内でゼロ埋めされたシーケンス番号です。<from> は --from で指定されたエージェント名です。<slug> は --title から生成されたスラッグです。フロントマターには seq、from、to（省略可能、all の場合は空または欠落）、title、created（ISO 8601タイムスタンプ）、およびオプションの reply_to（スレッド化のための seq）が含まれます。task/claim/lock コマンドの変更は、イベントメッセージも投稿します。

<root>/<channel>/
  tasks/                    # タスクJSONレコード
    audit/                  # トランザクションジャーナル（永続性）
      20250401T120000Z-alice-claim-task-12.md
  claims/                   # リースJSONレコード
    task-12.alice.json
  locks/                    # パスロックJSONレコード
    src-main.py.alice.lock
    audit/                  # パスロックトランザクションジャーナル

クレームとロックのリース

タスククレームとパスロックの両方は、アクティブなリースとして機能します。--lease-seconds はこれらのリースの有効期間を設定します。期限切れのリースは所有者を無効にし、recover による明示的な回復が必要です。回復は新しいリース期間を設定します。リースの書き込みは、クラッシュ後にクリーンな再起動を保証するために、prepared/applied/published フェーズを使用するトランザクションジャーナルによって保護されます。

• claim はタスクをアトミックに in_progress に遷移させ、リースレコードを作成し、変更をトランザクションジャーナルに記録します。
• renew は有効期限を延長します（タスクがアクティブなクレームを持っている場合のみ）。
• done / release はクレームをクリアし、リースレコードを削除します。
• recover は、トランザクションジャーナルエントリを使用して、期限切れのクレームを新しい所有者に移します。
• recover-pending は、準備済みだが適用されていないトランザクションを解決するために使用されます。

状態の要約と圧縮

state コマンドは、tasks/*.json および locks/*.json からの派生要約を出力します。 compact コマンドはこの要約を <root>/<channel>/state.md に書き込みます。 圧縮が行われると、state.compacted イベントが投稿され、state.md がその時点のチャンネル状態のスナップショットとして機能します。 state.md は常に非信頼できる情報源であることに注意してください。元のファイルがグラウンドトゥルースです。

エラーハンドリング

すべてのコマンドは、成功時は0、安定したエラーコードを含む明確なエラーの場合は2で終了します。エラーコードは上記のクイックリファレンスのサブセクションに文書化されています。コマンドは --help を受け付け、詳細な使用法のヘルプを出力します。

インストール

# 推奨：pipxを使用
pipx install agent-chat-plugin

# またはuvxで1回限り実行
uvx --from agent-chat-plugin agent-chat <cmd>

# スタンドアロンスキルとして使用する場合（SKILL.mdと同じディレクトリにchat.pyとagent_chat/があること）
python /path/to/skill/chat.py <cmd>

agent-chat は、pipx、uvx、またはスタンドアロンスクリプトとして使用できます。

ライセンス

MIT