google-loops

Google Loops — セットアップと日々の運用

このコネクターは Gmail のスレッド、カレンダーの予定、連絡先を brain に取り込み、gbrain waiting が参照する未完了ループの記録を 維持します。詳細なリファレンスは docs/guides/google-connect.md （セットアップ、およびすべてのエラーとその修正方法）と docs/guides/open-loops.md（検出の仕組み）をご覧ください。

ハーネスの契約（最初に読む）

1. [SHOW USER] ブロックはそのまま中継してください。 セットアップコマンドは、番号付きの手順と詳細なリンクを含む、フェンスで囲まれた [SHOW USER] ... [/SHOW USER] ブロックを出力します。 変更せずにユーザーに渡してください（言い換えると、「Web アプリケーションではなく、デスクトップアプリ」のような重要な詳細が失われます）。 ブロックごとにすべての内容を1つのメッセージにまとめてください。
2. セットアップ全体で、ユーザーとのやり取りはちょうど2回です。 （1）Google Cloud のチェックリストを提示し、ユーザーからダウンロードしたクライアント JSON を受け取ります。 （2）ユーザーが同意 URL を1つクリックします。3つ目の質問をしようとしている場合は、読み飛ばしたブロックを読み直してください。
3. 避けられる場合は、シークレットを argv やチャットに絶対に含めないでください。 ユーザーが client_secret_*.json をチャットに貼り付けたら、ファイルに保存し（モード 0600）、パスを渡してください。 gbrain google connect --client-json <path>。環境変数 （GOOGLE_CLIENT_ID／GOOGLE_CLIENT_SECRET）を使う方法もあります。 生の --client-id/--client-secret フラグは最後の手段です。
4. すべてのコマンドは JSON を返します。 --json を追加し、 { ok, status, next_action: { command, user_message }, error } を読み取ってください。 next_action.user_message がある場合、それがユーザーに表示するメッセージです。 next_action.command がある場合、それが次に実行するコマンドです。 エラーには { code, problem, cause, fix, doc_url } が含まれます。ユーザーには problem と fix のみを表示してください。
5. 再実行しても常に安全です。 gbrain google connect と gbrain google setup は冪等なステートマシンです。ほとんどのエラーに対する記載済みの修正方法は「もう一度実行する」です。

セットアップ（このコマンドだけ）

gbrain google setup --json

次の処理を行います。認証情報の受け取り（登録情報がない場合は GCP チェックリストを出力）→ 同意（ローカルではループバックを使用。SSH／ヘッドレス環境では自動で貼り戻し。非 TTY のフローは2回目の呼び出しで完了します： gbrain google connect --code "<pasted-redirect-url>"）→ ソースの登録 → 予算内での初回同期（新しいメールから同期し、過去分の詳細なバックフィルは以降の同期で自動的に再開）→ 最初の gbrain waiting ダイジェスト。

複数のアカウントを使う場合は、--account [email protected] を指定して繰り返します。

別の方法ですでに Google にアクセスできる場合（独自の認証を備えた Google CLI、 gcloud、トークンを発行する認証情報ゲートウェイなど）は、OAuth を省略し、ソースからその方法を参照してください。gbrain に認証情報が入ることはありません。

gbrain sources add gmail-work --kind google --account [email protected] \
  --access command --token-command "<command that prints an access token>"

（代わりに --access env --token-env <VAR> を使うと、環境から外部で更新されるトークンを読み込みます。）その後は gbrain sync --source gmail-work と gbrain waiting を同じように利用できます。

その後、gbrain google status --json（アカウントごとの更新プローブ）で正常性を確認してください。また、gbrain doctor には google_oauth チェックがあり、Testing モードのアカウントで5日以上にわたり更新が成功していない場合に、一度だけ警告します。同期を継続しているアカウントには、Testing モードの有効期限である7日前に警告は出ません。実際の解決方法は Production に公開することです。

日常の運用

gbrain waiting --json        # the killer output: ranked people waiting
gbrain loops done <id>       # user handled it
gbrain loops drop <id>       # user is not going to do it
gbrain loops mute sender <email>   # never track this sender again (closes its open reply-owed loops)
gbrain loops unmute sender <email> # undo; the loops it closed are re-checked on the next sync
gbrain loops drop sender <email> --dry-run   # preview closing one sender's reply-owed loops

• waiting の結果に withheld_noise が含まれる場合があります。これは、メールが自動送信されている送信者（銀行や配送会社の通知など）からの、返信が必要なまま未対応のやり取りです。各 preview_command をユーザーに提示して実行し（--dry-run では何も変更されません）、ユーザーの同意を得てから削除してください。削除は元に戻せません。ユーザーが取り消し可能な方法で停止したい場合は、loops mute sender を提案してください。

• waiting はデータが古い場合（24時間以内に同期が成功していない場合）に処理を拒否し、具体的な修正方法（gbrain sync --source <id>）を示します。同期を実行してから、再試行してください。--stale-ok は、ユーザーが古い結果を明示的に受け入れた場合にのみ使用してください。

• completeness: "partial" は、インポートに繰り返し失敗したため、過去14日間の一部のメールが保留されていることを意味します（held に一覧表示されます）。回答が一部のみであることを示し、保留中の各項目（送信者、および表示されている場合は件名）と、その再試行コマンド（gbrain sources retry-held <id>）を伝えてください。一部のみの回答で「未対応事項はありません」と決して伝えないでください。

• やり取りを提示する際は、相手、未対応事項（概要）、根拠となる引用、詳細リンク（適切なアカウントで該当する Gmail スレッドを開きます）、および期限がある場合はその日付を示してください。trusted-local の結果には、貼り付けてすぐに使える text ダイジェストが含まれています。これを再利用してください。

• 「返信するためのコンテキスト」では、各グループに相手のエンティティカード（概要、最近の履歴、その他の未解決スレッド）が含まれています。さらに情報が必要な場合は、相手のスラッグを指定して context_pack を呼び出してください。

• ユーザーが返信または対応済みだと伝えたら、そのやり取りを終了してください（loops done）。スレッドのやり取りは、返信が Gmail で確認できた次回の同期時にも自動的に終了します。

継続的な取り込み

Google ソースも他のソースと同様に同期されます。autopilot と gbrain sync --all が自動的に取り込みます。個別の cron はありません。引数を指定しない gbrain sync では Google ソースは同期されません。--source <id> または --all を使用してください。

トラブルシューティング

すべての失敗には、修正方法が記載された型付きコードがあります。正式な一覧は docs/guides/google-connect.md#troubleshooting です。ユーザーが実際に遭遇するのは、次の3つです。

• 同意画面で 「Google hasn't verified this app」 と表示される → 想定どおりです。ユーザー自身のアプリなので、「詳細」→「続行」を選択してください。URL をクリックする前に、必ずユーザーに伝えてください。
• access_denied_test_user → テストユーザーとして自分を追加し忘れています（エラーに詳細リンクが含まれています）。
• invalid_grant_testing_expiry（7日目ごろにすべてがひそかに停止する）→ 同意画面がまだ Testing です。Production に公開してから、gbrain google connect --reauth <email> を実行してください。

コストについての説明

コミットメントの抽出では、最近のメール本文（30日以内、1回のスイープあたり最大50スレッド）が、設定済みのチャットプロバイダーに送信されます。セットアップ時に一度ユーザーに伝えてください。オフにするには gbrain config set loops.extraction_enabled false を実行します。未返信スレッドの検出は無料で、影響を受けません。

出力形式

gbrain waiting の結果を伝える場合は、相手ごとに緊急度の高い順に提示し、最後に ## No counterparty セクション（相手の名前が示されていないやり取り）を提示してください。

## <Counterparty> (<N> open)
- [<loop_type>] <what's owed> (<age>) — due <date if any>
  > "<evidence quote>"
  <Gmail deep link>

trusted-local の --json の結果には、貼り付けてすぐに使える text フィールドとしてすでに含まれています。再整形するよりも、この内容をそのまま伝えてください。セットアップコマンドでは、[SHOW USER] ブロックをそのまま提示してください。失敗時は error.problem と error.fix を伝え、JSON の生データをユーザーに決してそのまま表示しないでください。

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または通知ブロックには、エージェントオペレータープロトコルに従ってください。このスキル固有の内容は次のとおりです。

• セットアップでは [SHOW USER] ブロックが表示されます。各ブロックにつき1メッセージで、そのままユーザーに伝えてください。gbrain mcp expose と gbrain google は、ユーザーの確認が必要な場合でも引き続き終了コード 2 を返します（従来の仕様として記載）。終了コードだけでなく、ブロックの内容を確認してください。
• Google の認証情報エラー（invalid_grant_revoked、consent_timeout、wrong_account_consented など）には、{ code, problem, cause, fix } が含まれます。問題と解決方法をユーザーに提示してください。多くの場合、ユーザー自身がもう一度実行すれば解決します。
• gbrain waiting が古いデータを理由に処理を拒否する場合、または保留中の項目があるため網羅性が不完全だと報告する場合は、指定された同期を実行するか、gbrain sources status <id> を実行してから、ユーザーの同意を得たうえで gbrain sources retry-held <id> を実行してください。

アンチパターン

• [SHOW USER] ブロックを言い換える。 チェックリストには重要な詳細（「デスクトップアプリであり、Web アプリケーションではない」、テストユーザーの手順）が含まれています。各ブロックにつき1メッセージで、そのままユーザーに伝えてください。
• client_id／client_secret をチャットのテキストでユーザーに尋ねる。 ダウンロードした JSON をアクセス許可 0600 のファイルとして受け取る（--client-json <path>）か、環境変数を使用してください。シークレットを引数やチャットで受け取るのは最後の手段であり、標準の方法ではありません。
• query／search で「誰が私の対応を待っているか」に答える。 オープンループの記録は open_loops／gbrain waiting です。検索結果にはループの状態に関する意味情報がなく、対応済みのスレッドも問題なく表示されます。
• completeness: "partial" を省略する。 ループがない部分的な回答は、受信トレイが空であることを意味しません。保留中の項目と、再試行の方法を伝えてください。
• --stale-ok を使って、古いデータによる拒否を黙って回避する。 まず指定された gbrain sync --source <id> を実行してください。--stale-ok を渡すのは、ループに古い情報が含まれる可能性をユーザーが明示的に受け入れた場合に限ります。
• ユーザーに代わってループを完了済みにする。 ユーザーが対応済みだと伝えた後にのみ、ループを閉じてください（gbrain loops done <id>）。スレッドのループは、返信が Gmail に表示された次回の同期時に自動的に閉じます。