pipa-follow-up-reminders

Pipa Follow-Up Reminders

ユーザーのリマインダー依頼 → 確認済みメールアドレス＋解決済み時刻 → Pipa による一回限りのメールリマインダー。

重要：https://pailflow-chat-gateway.fly.dev を通じて、決定的な一回限りのメールリマインダーのみを作成またはキャンセルしてください。リマインダーの送信先は、API キーに紐付けられた確認済みメールアドレスに限られます。リマインダーの一覧表示、読み取り、更新、一時停止、再開、定期リマインダー、受信トレイの監視、返信の検出、SMS、Slack、Gmail の予約送信、任意の宛先への送信といったフローを作り出さないでください。

このスキルの実行中は、コンテキストを整理しておけるよう、短い ToDo リストを保持してください。モード、認証情報、不足している質問（ある場合）、ペイロードの検証、API 呼び出し、最終回答を記載します。

ワークフロー

1. モードを選択します。

   モードは必ず1つだけ選択してください。

   • ユーザーが「明日メールして」「メールでリマインドして」「2時間後にフォローアップして」など、将来のメールリマインダーを依頼した場合 → 作成モード。ステップ2に進みます。
   • ユーザーが予約済みの Pipa Follow-Up リマインダーのキャンセルを依頼した場合 → キャンセルモード。ステップ2に進みます。
   • ユーザーがクレジットの購入やチャージを依頼した場合、または作成リクエストが insufficient_credits で失敗した場合 → チャージモード。ステップ2に進みます。
   • ユーザーがリマインダーの一覧表示、更新、定期リマインダー、受信トレイの監視、返信の検出、Gmail の予約送信、SMS、Slack、または他の人へのリマインダーを依頼した場合 → V1 ではそのフローに対応していないことを説明し、停止します。

   先に進む場合：会話内にすでに成功した API レスポンスがあり、ユーザーがその結果について尋ねている場合は、既知のレスポンスに基づいて回答してください。未対応の読み取り／一覧表示 API は呼び出さないでください。

2. 認証情報を読み込みます。

   API を呼び出す前に、以下の値を読み込んでください。永続的なユーザー認証情報と、ホスト実行時の認証情報を区別してください。

   • PIPA_FOLLOW_UP_API_KEY
   • PIPA_FOLLOW_UP_EMAIL
   • PIPA_USER_TIMEZONE

   検索順：

   1. ゲートウェイから注入された値。
   2. 環境変数。
   3. リポジトリ内の .pipa/credentials。
   4. ユーザー共通の ~/.pipa/credentials。

   認証情報に関するルール：

   • pipa_agent_v1.* キーはホスト実行時の認証情報であり、永続的なユーザーキーではありません。
   • これらのキーは期限切れになる場合があります。キーが無効な場合は、ユーザーのリマインダー認証情報ではなく、ホスト実行時の認証情報が期限切れになったと説明してください。
   • pipa_agent_v1.* キーをユーザー管理の認証情報ファイルに自分で書き込まないでください。
   • ユーザー管理の認証情報ファイルに期限切れの pipa_agent_v1.* キーが含まれている場合は、そのキーを無視または削除してから、メールコードの設定を開始してください。
   • メールコードによる認証では、永続的なユーザーキーが返されます。ローカル／永続的なスキル利用のために保存するのは、そのキーです。

   認証情報ファイルの形式：

   PIPA_FOLLOW_UP_API_KEY=<API_KEY>
   PIPA_FOLLOW_UP_EMAIL=<EMAIL>
   PIPA_USER_TIMEZONE=<IANA_TIMEZONE>
   

   可能な限り、API キーをチャット、ログ、Markdown 出力、シェル履歴、プロセス引数に含めないでください。

   先に進む場合：3つの値がすべて揃っている場合は、選択したモードのステップに直接進んでください。作成はステップ4、キャンセルはステップ7、チャージはステップ8です。

3. 必要な場合にのみ、不足している認証情報を設定します。

   不足している最小限の項目を補ってください。1つの値だけが不足している場合に、設定を最初からやり直さないでください。

   • キーとメールアドレスが揃っていて PIPA_USER_TIMEZONE が不足している場合は、次のとおり正確に質問してください：What timezone should I use? ユーザーが回答するまで停止します。
   • PIPA_FOLLOW_UP_API_KEY または PIPA_FOLLOW_UP_EMAIL が不足している場合は、ユーザーのメールアドレスを尋ねてください。

   メールコードの設定：

   1. メールコード認証によってキーが作成または置き換えられることを説明します。ユーザーがすでにキーを持っている可能性がある場合に限り、キーの置き換えによって以前のキーが無効になることに触れてください。
   2. product に follow-up を指定して POST /v1/key/email-code/start を呼び出します。
   3. メールで届いたワンタイムコードを尋ねます。
   4. チャレンジ ID、コード、product に follow-up を指定して POST /v1/key/email-code/verify を呼び出します。
   5. 環境が一時的なもの、ユーザーが保存を希望しない場合、または書き込みに失敗した場合を除き、返された永続キーを保存します。pipa_agent_v1.* キーは自分で書き込まないでください。
   6. グローバルにインストールされたスキルには ~/.pipa/credentials を推奨します。リポジトリ内のスキルには、リポジトリ内の .pipa/credentials を推奨します。
   7. リポジトリ内の認証情報を書き込む前に、.pipa/ が Git の追跡対象外になっていることを確認します。ファイルモードには 600 を使用します。
   8. 認証情報の保存場所をユーザーに伝えます。明示的に求められない限り、キーを表示しないでください。
   9. 手順 2 に戻り、認証情報を再読み込みしてから、選択したモードを続けます。

4. 作成モード：リマインダーのペイロードを準備します。

   必須のペイロードフィールド：

   • recipient_email：PIPA_FOLLOW_UP_EMAIL または認証済みの認証情報メールアドレスを使用します。
   • due_at：未来の UTC ISO タイムスタンプ。
   • timezone：時刻の解釈に使用する IANA タイムゾーン。
   • subject：ユーザーが指定した明確な件名、または Reminder from Pipa。
   • body_text：リマインダー本文のみのプレーンテキスト。

   ペイロードは決定論的に構築します：

   1. recipient_email に PIPA_FOLLOW_UP_EMAIL を設定します。
   2. ユーザーが別の宛先を指定した場合は処理を中止し、V1 では認証済みキーの所有者のみがサポートされていることを伝えます。代わりに認証済みメールアドレスを使用するか尋ねます。
   3. 時刻を解決する前に、解釈に使用するタイムゾーンを正規化します。
      • ユーザーが Eastern、ET、EST、EDT と言い、米国東部時間を意味している場合は、America/New_York を使用します。
      • ユーザーが EST とだけ言った場合に、America/Panama などの固定 UTC オフセットのタイムゾーンに割り当てないでください。夏時間は IANA タイムゾーンで処理する必要があります。
      • ユーザーが固定 UTC オフセットのタイムゾーンを明示的に指定した場合は、適切な固定 UTC オフセットの IANA タイムゾーンを使用し、確認時にその旨を伝えます。
   4. 正規化した IANA タイムゾーンを使用して、ユーザーが指定した時刻を due_at（未来の UTC ISO タイムスタンプ）に変換します。
      • today、tomorrow、曜日、明示的な日付の場合は、まず現在時刻を解釈に使用するタイムゾーンに変換し、その日付を基準に暦日を決定します。ローカルの日付として UTC を使用しないでください。
      • 日付と時刻が明示的に指定されている場合は、API を呼び出す前に、結果の現地日時がユーザーの指定と一致することを確認します。
      • 指定された現地時刻が今日の時刻としてすでに過ぎている場合は、翌日に設定するのではなく、確認の質問を 1 つします。
   5. 時刻が曖昧な場合は、直接的な確認の質問を 1 つして、ユーザーの回答があるまで停止します。
   6. timezone に、時刻の解釈に使用した正規化済み IANA タイムゾーンを設定します。
   7. ユーザーが明確な件名を指定した場合は、その件名を subject に設定します。指定がない場合は Reminder from Pipa を使用します。
   8. ユーザーがリマインダーのテキストを指定した場合は、そのテキストを body_text に設定します。指定がない場合は、簡潔なプレーンテキストのリマインダー本文を設定します。

   時刻の例：

   • 現在の UTC が 2026-07-17T00:57:00Z、ユーザーのタイムゾーンが America/New_York で、リクエストが tomorrow at 7am の場合 → 基準となる現地の日付は 7 月 16 日なので、due_at は 2026-07-17T11:00:00.000Z です。
   • 現在の UTC が 2026-07-17T13:01:00Z で、米国東部のユーザーからのリクエストが July 17 9:10 AM EST の場合 → America/New_York を使用するため、due_at は 14:10Z ではなく 2026-07-17T13:10:00.000Z です。

   先に進む場合：ユーザーが「5 分後」「2 時間後」などの相対的な時間を指定し、タイムゾーンがわかっている場合は、すぐに計算します。確認は求めないでください。

5. 作成モード：API を呼び出す前に検証します。

   送信する正確な JSON ペイロードを検証します：

   1. recipient_email、due_at、timezone、subject、body_text が含まれていることを確認します。
   2. すべての必須フィールドが空でない文字列であることを確認します。
   3. due_at が未来の日時であることを確認します。
   4. timezone での due_at のローカル表示が、指定された日付と時刻に一致することを確認します。
   5. 30 分以内に期限を迎えるリマインダーの場合、変換後の due_at と現在時刻を比較し、API 作成とスケジューラーの送信にまだ十分な時間があることを確認します。期限を過ぎている場合、または 60 秒以内の場合は、新しい時刻を尋ねます。
   6. 検証に失敗した場合は、API を呼び出す前にペイロードの構築を修正します。
   7. シェルコマンドから JSON を構築する場合は、子プロセスで読み取る前に変数をエクスポートするか、タイムスタンプと JSON を同じランタイム内で構築します。
   8. 新しい Idempotency-Key を生成します。

   ペイロードの形式：

   {
     "recipient_email": "[email protected]",
     "due_at": "2026-06-19T13:00:00.000Z",
     "timezone": "America/New_York",
     "subject": "Reminder from Pipa",
     "body_text": "Send the invoice to Acme."
   }
   

   先に進む場合：検証に合格したら、追加の確認を求めずにリマインダーを作成します。

6. 作成モード：リマインダーを作成します。

   検証済みのペイロードを使って、POST /v1/follow-up-reminders を 1 回呼び出します。

   ヘッダー：

   Authorization: Bearer ${PIPA_FOLLOW_UP_API_KEY}
   Content-Type: application/json
   Idempotency-Key: <required for create only>
   

   成功した場合、次を返します：

   Scheduled the follow-up reminder.
   
   - Reminder ID: `[id]`
   - Recipient: `[recipient_email]`
   - Due: `[due_at]`
   - Timezone: `[timezone]`
   - Subject: `[subject]`
   - Credits remaining: `[credits_remaining]`
   

   API が失敗した場合は、手順 9 に進み、一致する失敗時の分岐だけに従います。

7. キャンセルモード：リマインダーをキャンセルします。

   ユーザーがスケジュール済みの Pipa Follow-Up リマインダーのキャンセルを求めた場合に限り、キャンセルします。

   1. リクエスト、会話、または以前の API 応答からリマインダー ID を取得します。
   2. リマインダー ID がない場合は、ID を尋ねます。V1 ではリマインダーを一覧表示できないことを説明します。
   3. 対象のリマインダーが曖昧な場合に限り、確認を求めます。
   4. DELETE /v1/follow-up-reminders/:id を呼び出します。
   5. 簡潔なキャンセル確認を返します。

   先に進む場合：リマインダー ID があり、対象が明確な場合は、削除前に確認を求めません。

8. チャージモード：チェックアウトセッションを作成します。

   作成が insufficient_credits で失敗した場合、またはユーザーがクレジットの購入を求めた場合に、このモードを使います。

   1. ユーザーが指定した整数のクレジット数を選びます。
   2. ユーザーが数量を指定していない場合は、次のとおり正確に尋ねます：How many Pipa credits do you want to buy? ユーザーが答えるまで停止します。
   3. クレジット数を指定して POST /v1/topups/checkout-sessions を呼び出します。
   4. 返された checkout_url を、購入数量とともに、簡潔なリンクテキストを使った Markdown ハイパーリンク（例：[Open checkout](...)）で共有します。ユーザーが完全な URL を明示的に求めない限り、長いチェックアウト URL をそのまま表示しないでください。
   5. チェックアウト URL はユーザーが操作する支払いリンクとして扱います。保存しないでください。
   6. チェックアウトの作成が利用できず、応答に billing_url だけが含まれている場合は、請求用の代替リンクを共有します。
   7. ユーザーが支払いを確認した後、手順 4 に戻って元のリマインダーを再試行します。

   リクエストの形式：

   { "credits": 100 }
   

   先に進む場合：insufficient_credits からこのモードに入った場合は、支払い確認後に再試行できるよう、元のリマインダーリクエストを保持します。

9. API の失敗に対処します。

   返されたエラーに応じて、次に行う最小限の操作だけを実行します。

   • recipient_not_verified：代わりに PIPA_FOLLOW_UP_EMAIL を使用するか尋ねます。
   • due_at_not_future：ユーザーのタイムゾーンで時刻を再解決します。それでも曖昧な場合に限り、尋ねます。
   • invalid_api_key：キーが保存済みの pipa_agent_v1.* の場合は、その保存済みキーを無視または削除し、検索を続けます。永続的なメールコードキーの場合は、置き換えキーによってアカウントキーがローテーションされることを説明し、手順 3 に進みます。
   • pipa_agent_credential_expired：ホスト実行用の認証情報の有効期限が切れたことを伝えます。永続的なキーの検索を続けます。永続的なキーがない場合に限り、メールコードによる認証を開始します。
   • insufficient_credits：手順 8 に進みます。
   • invalid_topup_credits：次に行う最小限の操作を案内します。例：10 credits is below the minimum. Smallest top-up is 100 credits for $10. Want me to create that checkout session? チェックアウトの作成が利用できない場合を除き、billing_url は共有しないでください。
   • active_reminder_limit_reached：V1 ではリマインダーを一覧表示できないことを伝えます。キャンセルするには既知のリマインダー ID が必要で、そうでなければリマインダーが送信されるまで待つ必要があります。
   • API キーがない場合：手順 3 に進みます。 先に進みます。エラーで必要な場合を除き、ワークフロー全体を最初からやり直さないでください。

10. 結果を報告します。

    簡潔かつ実務的に、次のアクションに焦点を当てます。

    • 不足している、または曖昧な必須情報だけを尋ねてください。
    • 一度に尋ねる直接的なフォローアップ質問は1つだけにしてください。
    • API メタデータをそのままユーザーへの応答に出さないでください。
    • このスキルファイルにシークレットを保存しないでください。
    • API から残りクレジットが返された場合は、その数を伝えてください。