deepagent-stream-token-usage

適用シーン

• agent.stream(input, { streamMode: ["updates", "messages"] }) が二要素タプル chunk [mode, payload] を返す。
• 本セッション合計の input/output/total が必要、または メイン オーケストレーション / 各 subagent ごとに使用量を分割したい場合。

使用量がどこに現れるか（test/agent-stream.txt と組み合わせ）

1. mode === "messages"
payload = [messageChunk, bundleMetadata]。
   単一のモデル生成がほぼ終了する際、messageChunk に以下が現れます：

   • usage_metadata（優先）：input_tokens、output_tokens、total_tokens、およびオプションの input_token_details（例：cache_read）。
   • response_metadata.usage（OpenAI 形式）：prompt_tokens、completion_tokens、total_tokens など。
     同じストリーム内に同じ id（例：chatcmpl-…）を持つ chunk が連続して複数出現する可能性があります。完全な数値を持つ usage_metadata は通常生成の末尾に現れます（サンプルではおよそ 13–14 行目がメイン オーケストレーション、23–24 行目が tools: サブグラフ）。

2. mode === "updates" かつ model_request（または model）が存在する場合
   内部の messages にある AI メッセージも usage_metadata / response_metadata.usage を持つ可能性があります（サンプル 15 行目）。
   注意：同一の chatcmpl-* 上で、response_metadata.usage の prompt_tokens と usage_metadata.input_tokens が 一致しない場合があります（グラフ内累計 vs 単一呼び出し）。集計時は usage_metadata を優先します。usage_metadata がない場合のみ、prompt_tokens / completion_tokens を input/output の推定として使用します。

3. 中間フラグメント
   多数の chunk の response_metadata.usage は空オブジェクト {} です。累加しないでください。そうするとミス判定につながります。

セッション合計使用量アルゴリズム（推奨）

1. Map<completionId, { input, output, total }> を維持します。completionId はメッセージ上の kwargs.id / id（chatcmpl-… または等価）から取得します。
2. 各 chunk を反復処理します：
   • messages：payload[0] から使用量を解析します。usage_metadata があり total_tokens が有効な数値の場合、map.set(id, { input, output, total }) を実行します（後の書き込みが前の書き込みを上書きし、同じ id で複数セグメントが繰り返される場合も結果は一貫しています）。
   • updates → model_request.messages（および互換性のある model）：その中の各 AI メッセージについて同様に解析し、同じ map に対して set を実行します（ストリーム末尾と同じ id の場合は重複排除し、最後の書き込みのみ保持。updates のみにその id が現れた場合も記録されます）。
3. セッション合計：sumInput = Σ v.input、sumOutput = Σ v.output、sumTotal = Σ v.total（または sumInput + sumOutput で検証。キャッシュ課金の対象かどうかはプロバイダーに確認してください）。
4. しないこと：response_metadata.usage.total_tokens と usage_metadata を混在させて加算しないこと。同一 id では 1 セットのみ保持し、usage_metadata を優先します。

main / subagent ごとの分割（オプション）

「Subagent の帰属」ルールと同じです：

• payload[1].checkpoint_ns が tools: で始まらない → このメッセージの使用量は main に記録します。
• tools: で始まる → 現在の 解析済み task の subagent_type に記録します（updates.model_request の処理時に pendingSubagent を維持し、updates.tools の task ToolMessage 後にクリアする必要があります）。

各 (completionId) に同時に agentKey（main / hello_agent / …）のタグを付け、その後 agentKey で input/output をグループ化して合計を求めます（注意：同じ subagent の複数回呼び出しは複数の completion id を生成し、グループ化して合算するだけです）。

実装のヒント（TypeScript）

• LangChain シリアル化オブジェクトから読み取ります：msg.kwargs?.usage_metadata、msg.kwargs?.response_metadata?.usage、msg.kwargs?.id。
• ランタイム クラス インスタンス：トップレベルの usage_metadata / id である可能性があり、両方と互換性がある必要があります。
• usage_metadata がない場合は、prompt_tokens/completion_tokens を input/output にマッピングしてから map に書き込みます。

制限事項

• 使用量は プロバイダーが返す課金フィールド に基づきます。サブグラフとメイン オーケストレーションは各自 1 回の completion に対応する 1 つの chatcmpl-* に相当し、セッション合計 = 各 completion の合計です。
• フレームワークまたはプロバイダーのアップグレード後にフィールド名が変わる可能性があります。実際の chunk に基づいてサンプリング回帰テストを行ってください。