実例: StageX 自動更新ボット

stagehand は本番環境向けの ZeroClaw ボットです。アップストリームのリリースフィードを監視し、StageX パッケージのバージョンを更新してビルドし、ダイジェストで再現性を検証し、変更をプッシュしてドラフトのプルリクエストを作成し、結果を通知します。PR が作成されるまで、人間が触れることはありません。

これはリファレンス SOP デプロイメントです。パイプラインは決定論的な SOP であり、リリースフィードは AMQP チャネル経由で到着し、エージェントは sop_execute ツールで SOP を起動します。AMQP はライブの fan-in として SOP エンジンを直接駆動することもできます。この例では意図的にエージェントが起動するパターンを使用しており、チャネルが各リリースをエージェントループに持ち上げ、エージェントが実行を開始します。その分離こそが、このパターンを再利用可能にするものです。

コードベース内の具体的な定義に、以下のすべてのコマンド、設定キー、ツール名、ステータス値、監査キーが対応しています。

1. ビルド

stagehand には AMQP および Matrix チャネルがコンパイルされている必要があります。どちらもフィーチャーゲートで管理されており、デフォルトでは無効になっています。

cargo build --release --features channel-amqp,channel-matrix

結果として得られるのは、amqp および matrix チャネルタイプを読み込む zeroclaw バイナリです。channel-amqp なしでビルドされたバイナリは、起動時に amqp チャネルブロックを拒否し、それを読み込む代わりに警告をログに記録します。

2. 成果物

ZeroClaw のインストールルート配下には、次の3つが存在します。

この設定は、エージェントを2つのチャネル（amqp.anitya、matrix.announce）に接続し、完全な自律性で実行することで、ゲートなしでコミット、プッシュ、PRのオープンを行わせ、[sop] を deterministic 実行モードの shared/sops に向けます。エージェントは決してマージしません。メンテナーがブランチを採用し、署名付きコミットを介してマージします。

AMQP チャネル

amqp.anitya チャネルは、Fedora Messaging の公開フィードを消費します。amq.topic エクスチェンジ上で Anitya のバージョン更新ルーティングキーをバインドし、クライアント相互 TLS を使用して amqps:// 経由で接続します。Fedora のブローカーはクライアント証明書を必要とするため、このチャネルは設定された client_cert と client_key を提示します。チャネルは、読み込み時に設定を検証します。amqp_url は amqp:// または amqps:// を使用する必要があり、amqps:// URL には ca_cert が必要で、client_cert と client_key は両方一緒に指定する必要があり、エクスチェンジは空でない必要があり、少なくとも 1 つのルーティングキーがバインドされている必要があります。

各配信の JSON ボディは content_template によってエージェントの受信メッセージにマッピングされます。その {dotted.path} プレースホルダーはボディに対して解決され、リリース配信を 「新しいリリース: bzip2 1.0.9 (旧 1.0.8)。bzip2 の StageX パッケージを更新してください。」 に変換します。thread_id_field のドット区切りパスは、返信を元のイベントに関連付けます。配信はデフォルトで at-least-once です (durable_ack = true)。チャネルは、リリースが永続的にエージェントループへ引き渡された後にのみそれを確認応答するため、実行が開始される前にクラッシュが発生した場合、イベントを黙って破棄するのではなく再配信します。これは、無人で副作用を伴うパイプラインにとって重要です。リリースが失われると、パッケージが密かに置き去りにされてしまうからです。認証情報と証明書はデプロイ時に提供され、決してコミットされません。Codeberg のプッシュトークンはエージェントのシェルが読み取る環境変数であり、Matrix のアクセストークンは実行中のインスタンスに設定され、Fedora の CA 証明書とクライアント証明書はホスト上に配置されます。

3. 検証

zeroclaw sop のサーフェスは3つのサブコマンドで構成されます。run サブコマンドは存在せず、実行はトリガーまたは sop_execute ツールから開始されます。

zeroclaw sop list
zeroclaw sop validate stagex-update
zeroclaw sop show stagex-update

検証では、名前や説明が空である場合、トリガーがない場合、ステップがない場合（SOP.md が存在しないか空の場合）、ステップ番号に欠落がある場合に警告が表示されます。ステップが欠落しているという警告は、実行時に実行が失敗することを意味します。反復処理の際は、zerocode のターミナルインターフェースから同じチェックを実行してください。CLI は再現可能なデプロイ時のチェックです。

4. デプロイ

ボットは長時間稼働するデーモンとして動作するため、ブローカーと Matrix ルームへの接続が維持されます。

zeroclaw daemon

常時稼働のホストでは、マシンと共に再起動するマネージドサービスとして動作します（サービスとデーモンを参照）:

zeroclaw service install
zeroclaw service start

AMQP チャンネルはブローカーに接続し、ルーティングキーをバインドして、配信を消費します。アップストリームがリリースを出荷するまで、ボットはアイドル状態です。

5. リリースの流れ

Anitya はバージョン更新の配信を発行します。AMQP チャネルがそれを受信し、content_template を適用して、パッケージ名、新しいバージョン、古いバージョンを記載した受信メッセージをエージェントに渡します。エージェントはパイプラインを起動します。

// tool: sop_execute
// args: { "name": "stagex-update", "payload": "{\"project\":{\"name\":\"bzip2\"},\"version\":\"1.0.9\",\"old_version\":\"1.0.8\"}" }

sop_execute は手動トリガーで SopRun を開始し、payload を実行コンテキストに転送します。ここからのライフサイクルは他の実行と同一であり、唯一異なるのはトリガーソースのみです。

6. 実行

[sop] は deterministic モードで実行されるため、各ステップ間で LLM とのやり取りを行わず順次実行されます。各ステップの出力は次のステップへパイプされ、モデルを呼び出すのはパッチ取得のステップのみで、これはローカルで動作するため、パッケージのソースがホストの外に出ることはありません。チェックポイントステップでは人間による承認のために一時停止しますが、このパイプラインはドラフト PR まで一気に実行されます。

running → completed

SOPの## Stepsセクションから解析された8つのステップ:

エージェントは各ステップを sop_advance 呼び出しで締めくくり、結果を報告します:

// tool: sop_advance
// args: { "run_id": "<run-id>", "status": "completed", "output": "bzip2 1.0.8 → 1.0.9 にバージョンアップ。ソースハッシュを再生成して検証済み。" }

status は completed、failed、skipped のいずれかです。最後のステップが進行すると、実行は completed に遷移し、その completed_at タイムスタンプが設定されます。

エージェントのターンの任意の時点で進捗状況を確認できます。

// tool: sop_status
// args: { "sop_name": "stagex-update", "include_metrics": true }

ヘッドレス安全性

配信が到着した時点でステップを進めるためのアクティブなエージェントループが存在しない場合、ランタイムは作業を黙って破棄するのではなく、その実行を記録し、保留中の各アクションをログに残します。この実行は、それを前進させるエージェントのターンを待機します。

7. 監査証跡

SopAuditLogger は、すべての遷移を設定された Memory バックエンドのカテゴリ sop に永続化します。1 回の更新実行で、次のキーが残ります。

sop_status の include_metrics: true を指定すると SOP 固有の集計が追加され、include_gate_status: true を指定すると trust-phase と gate-evaluator の状態が追加されます。これらは Prometheus ではなく sop_status を通じて取得されます。/metrics エンドポイントは、observability バックエンドが prometheus の場合、一般的な zeroclaw_* ファミリーのみを公開します。

8. 保証

各保証はパイプラインまで追跡できます。

• ソースがホストの外に出ることはありません。 パッチのソース取得ステップはローカルモデルに対して実行されるため、パッケージのソースがリモートプロバイダーに渡ることはありません。
• ビルドが自身を証明します。 ステップ5では2回ビルドしてダイジェストを比較し、両者が一致した場合にのみPRがready（準備完了）としてマークされます。
• マージは人間が責任を持つ。 ボットは「ドラフトPRを開いた」段階で停止し、メンテナがブランチを引き継いで署名付きコミットでマージします。自動マージは決して行いません。
• この実行は再構成可能です。 実行スナップショットとすべてのステップ結果は、実行 ID をキーとして、カテゴリ sop に永続化されます。

9. パターン

インバウンドチャネルがイベントを取り込み、エージェントがsop_executeでSOPを発火し、決定論的なパイプラインが処理を実行します。AMQPフィードを任意のチャネルに、ステップを任意の手順に置き換えても、ライフサイクル、承認ゲート、監査キーは同一です。ステップに人間の判断が必要な場合は、それをチェックポイントとしてマークすると、実行は続行する前に承認を待って一時停止します。無人パスとの唯一の違いは、誰が実行を進めるかという点です。