heterogeneous-agent

異種エージェントの開発

バグや機能が通常のサーバー側エージェントランタイムではなく、外部 CLI エージェントのパイプラインにある場合に、このスキルを使用します。

このスキルの対象

• apps/desktop/src/main/modules/heterogeneousAgent/drivers/ 配下のドライバーの追加や変更
• packages/heterogeneous-agents/src/adapters/ 配下のアダプターの編集
• OpenClaw／Hermes を含む CLI／デスクトップのディスパッチランチャーの変更、またはタスクコメントの投稿者に関するデバッグ
• heteroAgentRawLine の転送、window.__HETERO_AGENT_TRACE、または executeHeterogeneousAgent のデバッグ
• 重複する部分チャンク／完全チャンク、壊れた message.id の境界、欠落した tool_result、TodoWrite の状態ずれ、サブエージェントのスレッドルーティングなど、Claude Code の stream-json のバグ修正
• 混在する複数ツールのメッセージ、壊れたターン境界、または欠落したツール結果のマッピングなど、Codex JSONL のバグ修正
• Claude Code／Codex フローにおけるステップ境界、ツールの永続化、サブエージェントのスレッド、または再開に関するバグ修正
• 複数ツールの混在、孤立したツールメッセージ、またはツール結果の読み込みが停止する問題の再現

パイプラインの概要

1. CLI の生の標準出力／JSONL
2. Electron のメインプロセスが CLI を起動し、heteroAgentRawLine をブロードキャストする
3. アダプターがプロバイダーの生イベントを HeterogeneousAgentEvent にマッピングする
4. executeHeterogeneousAgent がアシスタント／ツールのメッセージを永続化し、ストリームイベントを転送する
5. createGatewayEventHandler が UI にデータを反映する
6. この経路が正しく見えてから、agent-tracing または context-engine のデバッグに進みます

まず読むファイル

• apps/desktop/src/main/controllers/HeterogeneousAgentCtr.ts
• apps/desktop/src/main/modules/heterogeneousAgent/drivers/claudeCode.ts
• apps/desktop/src/main/modules/heterogeneousAgent/drivers/codex.ts
• packages/heterogeneous-agents/src/adapters/claudeCode.ts
• packages/heterogeneous-agents/src/adapters/codex.ts
• src/store/chat/slices/agentRun/actions/transports/hetero/heterogeneousAgentExecutor.ts
• src/store/chat/slices/agentRun/actions/__tests__/heterogeneousAgentExecutor.test.ts

デフォルトのデバッグ順序

1. UI コードに触れる前に、CLI の生の出力が正しいかを確認します。アプリは実際のセッションをすべて記録しています。claude -p で手作業の再現を作るのではなく、cat .heerogeneous-tracing/.last-live-trace で最新のセッションを読み取ってください（references/debug-workflow.md §2 を参照）。
2. 生の出力が正しい場合は、アダプターの出力と比較します。開発環境では、executeHeterogeneousAgent によって window.__HETERO_AGENT_TRACE を確認できます。
3. 変換後のイベントが正しい場合は、persistToolBatch、persistToolResult、ステップ遷移、サブエージェントのルーティングを調べます。
4. 修正する前に、再現ケースを焦点を絞ったテストにします。
5. 転送／アダプター／実行処理の経路が正常であると確認できてから、後段のメッセージ処理をデバッグしてください。

重要な不変条件

• 1 つの生のツール項目は、1 つの安定した ToolCallPayload.id に対応している必要があります。
• メインエージェントの新しいステップでは、新しいアシスタントにイベントを転送する前に境界シグナルを発行する必要があります。
• Claude Code では、同じ message.id を持つ複数のアシスタントイベントは、複数のターンではなく 1 つのターンです。
• Claude Code では、tool_result はアシスタントイベントではなく、type: 'user' イベントに含まれます。
• Claude Code の部分モードでは、message_delta.usage が優先されます。各アシスタントブロックで繰り返される使用量の値を信用しないでください。
• persistToolBatch は、ツールメッセージを作成する前にアシスタントの tools[] を事前登録する必要があります。
• 各ツールメッセージでは、parentId を所有するアシスタントと同じにし、tool_call_id をツール ID と同じにする必要があります。
• tool_result は、既存の toolMsgIdByCallId を解決する必要があります。
• サブエージェントのチャンクはスレッドのスコープ内にとどめ、メインアシスタントのストリームに転送してはなりません。
• メインステップの境界で、グローバルな toolMsgIdByCallId マップを消去してはなりません。

ディスパッチされた実行の ID

コネクターやデスクトッププロセス自体が、別のエージェントの会話内で実行されることがあります。継承された環境が示すのは起動元であり、ディスパッチされたエージェントではありません。

• 子の ID は現在のディスパッチ情報から構築してください。継承された LOBEHUB_AGENT_ID、LOBEHUB_ASSISTANT_MESSAGE_ID、LOBEHUB_TASK_ID、LOBEHUB_WORKSPACE_ID をクリアし、LOBEHUB_TOPIC_ID と LOBEHUB_OPERATION_ID をディスパッチされた値に置き換えてください。追加のコンテキストは、現在のディスパッチで指定されている場合にのみ注入してください。値がない場合は、祖先の ID を引き継いではいけません。
• 作成者の ID は認証とは切り離してください。LOBEHUB_JWT をクリアしたり、ユーザーの認証情報にフォールバックしたりしても、実行中のエージェントが変わることはありません。トピックの所有者やタスクの担当者から作成者を推測してはいけません。
• apps/cli/src/commands/task/lifecycle.ts で、トピックまたはオペレーションのコンテキストがあるにもかかわらず、エージェント ID が欠落している、または空白の場合、lh task comment は投稿を拒否しなければなりません。実行 ID のない通常のターミナルからのコメントは、ユーザーが作成したものとして扱います。エージェントの進捗が誤った作成者に帰属すると、後続のタスク実行で人間の <user_feedback> として扱われるおそれがあります。

この契約を変更したり、ランチャーを追加したりする際は、次の 4 つの起動経路をすべて確認してください。

経路	エントリーポイント
CLI エージェントのディスパッチ	apps/cli/src/device/agentRun.ts — spawnHeteroAgentRun（エージェント ID は apps/cli/src/commands/connect.ts から渡されます）
CLI OpenClaw/Hermes	apps/cli/src/tools/heteroTask.ts — runHeteroTask
デスクトップのエージェントディスパッチ	apps/desktop/src/main/controllers/HeterogeneousAgentImpl.ts — spawnLhHeteroExec
デスクトップ OpenClaw/Hermes	apps/desktop/src/main/controllers/GatewayConnectionCtr.ts — runHeteroTask

リグレッションテストでは、クリーンな環境、矛盾する祖先の ID、現在のエージェントまたは追加コンテキストの欠落を網羅する必要があります。CLI とデスクトップの両方で OpenClaw と Hermes を確認し、JWT へのフォールバック後のタスクコメントも確認してください。モックした spawn のアサーションで検証できるのは環境の構築であり、外部ランタイムを介したエンドツーエンドの伝播ではありません。

よくあるバグのパターン

• Claude Code でテキストや思考が重複する： 差分の一部と、後続の完全なアシスタントブロックの両方が出力されていないか確認してください。
• Claude Code でアシスタントメッセージが多く開かれる： message.id が変わったときだけでなく、すべてのアシスタントイベントでアダプターがステップを区切っていないか確認してください。
• Claude Code のツール結果が反映されない： コードがアシスタントイベントしか調べていないために、type: 'user' の tool_result ブロックが無視されていないか確認してください。
• Claude Code の TodoWrite カードが古い状態のままになる： ツール結果の時点で、合成された pluginState.todos がアタッチされているか確認してください。
• Claude Code のサブエージェントのトランスクリプトがメインの吹き出しに漏れる： parent_tool_use_id の処理と、サブエージェントのチャンクがメインゲートウェイのハンドラーに転送されていないか確認してください。
• 複数の Codex ツールが1つのアシスタントメッセージにまとめられる： まず、アダプターが newStep などの利用可能なステップ境界、または同等のターン変更シグナルを出力しているか確認してください。
• 孤立したツールメッセージ： まず、ステップ遷移の順序と、ツールメッセージの作成前に persistToolBatch の Phase 1 が実行されたかを確認してください。
• ツールの吹き出しが読み込み中のままになる： tool_result for unknown toolCallId と、result_msg_id のバックフィルが欠けていないか確認してください。
• サブエージェントのツールがメインの吹き出しに表示される： サブエージェントのチャンクがメインゲートウェイのハンドラーに到達していないか確認してください。
• 終端エラーのガイドが間違っている（例：ネットワーク切断に対して「使用制限に達しました」と表示される）： 構造化フィールドが存在するだけで、その意味だと判断して分岐している可能性があります。 そのフィールドを信頼する前に、実際のトレース内のすべてのイベント状態を grep で調べてください。references/debug-workflow.md §8 を参照してください（CC の rate_limit_info は status: "allowed" にも含まれます）。

参考資料

• コマンド、トレースの取得、不変条件、目的を絞ったテストコマンドについては、references/debug-workflow.md をお読みください。
• ライブ環境での公式モデル互換性チェックは、Claude Code で /testing-heterogeneous-agents、または Codex で $testing-heterogeneous-agents をユーザーが明示的に実行した場合に限り利用できます。診断中にこのスキルを自動的に読み込んだり実行したりしないでください。失敗したセルの証拠は、ここでの診断やコード修正に利用できます。