pipa-time-tracking

Pipa の時間追跡

ユーザーの時間追跡リクエスト -> Pipa の認証情報 -> 汎用 time_tracking/time_entry ユーティリティレコード。

重要：汎用 Pipa エージェントユーティリティレコード API 経由で、Toggl 形式の時間エントリーのみを使用してください。Clockify、Toggl、スクリーンショット、給与計算、請求書発行、生産性スコアリング、受動的なアクティビティの再構成、/v1/time-tracking/* ラッパーエンドポイントは使用しないでください。

簡潔な ToDo リストを維持してください：モード、認証情報、不足している質問、ペイロードの検証、API 呼び出し、最終回答。

ワークフロー

1. モードを選択します。 次のいずれか 1 つだけを選んでください。

   • タイマーを開始：「これの追跡を開始」「Acme のタイマーを開始」「フロントエンドの修正に時間を記録」 -> start。
   • 作業を切り替え：「Acme QA に切り替え」 -> switch。
   • 現在のタイマーを停止 -> stop。
   • 実行中のものを確認 -> current。
   • 過去の時間を記録：「9 時から 9 時 45 分までの 45 分を記録」 -> backfill。
   • エントリーを表示／時間を要約 -> review。
   • エントリーを更新／削除／キャンセル／アーカイブ -> update/archive。
   • クレジットを購入／チャージ、クレジット残高を確認、または変更を伴うリクエストが insufficient_credits で失敗 -> top-up。
   • 給与計算、請求書発行、スクリーンショット、受動的な再構成、外部トラッカーとの同期、繰り返しタイマー、自動アイドル検出 -> V1 では未対応であることを説明し、停止します。

   会話内に成功した API レスポンスがすでにあり、ユーザーがその結果について尋ねている場合は、把握しているレスポンスに基づいて回答してください。未対応のレポートエンドポイントを呼び出さないでください。

2. 認証情報を読み込みます。 API を呼び出す前に、次の情報が必要です。

   • PIPA_API_BASE_URL
   • PIPA_API_KEY
   • PIPA_EMAIL
   • PIPA_USER_TIMEZONE

   別名：

   • PIPA_FOLLOW_UP_API_KEY -> PIPA_API_KEY
   • PIPA_FOLLOW_UP_EMAIL -> PIPA_EMAIL
   • 同じソース内に正規名と別名の両方の値がある場合は、正規名を優先します。

   検索順：

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

   隠しパスに関するルール：

   • .pipa/credentials の検索に glob／ファイル検索を当てにしないでください。隠しディレクトリはスキップされたり、誤って処理されたりすることがあります。
   • 明示的なパスを直接確認してください：<workspace-root>/.pipa/credentials、次に ~/.pipa/credentials。
   • シェルヘルパー：cwd または git rev-parse --show-toplevel からルートを特定し、Path(root) / ".pipa" / "credentials" を読み込みます。
   • glob で .pipa/credentials が No files found となっても、結論にはなりません。ユーザーに認証情報を尋ねる前に、直接読み込んでください。

   認証情報ファイルは JSON ではなく dotenv 形式です：

   PIPA_API_BASE_URL=https://pailflow-chat-gateway.fly.dev
   PIPA_API_KEY=<API_KEY>
   PIPA_EMAIL=<EMAIL>
   PIPA_USER_TIMEZONE=<IANA_TIMEZONE>
   

   旧形式：

   PIPA_API_BASE_URL=https://pailflow-chat-gateway.fly.dev
   PIPA_FOLLOW_UP_API_KEY=<API_KEY>
   PIPA_FOLLOW_UP_EMAIL=<EMAIL>
   PIPA_USER_TIMEZONE=<IANA_TIMEZONE>
   

   可能な限り、API キーをチャット／ログ／Markdown／シェル履歴／プロセス引数に含めないでください。シェルヘルパーはスクリプト内で認証情報を読み込み、秘密情報ではない結果のみを出力します。

   PIPA_API_BASE_URL と API キーがある場合は、選択したモードに進んでください。モードで現地日の解釈が必要なのにタイムゾーンがない場合は、手順 3 に進みます。

3. 必要な場合に限り、不足している認証情報を設定します。 不足している項目のうち、最小限のものを補ってください。

   • PIPA_USER_TIMEZONE がなく、現地の日付／曖昧な時刻の指定がある -> 次の文をそのまま尋ねてください：What timezone should I use? 停止します。
   • PIPA_API_BASE_URL がない -> ユーザーが別のゲートウェイを指定していない限り、https://pailflow-chat-gateway.fly.dev をデフォルトにします。
   • PIPA_API_KEY と PIPA_FOLLOW_UP_API_KEY がない -> ユーザーのメールアドレスを尋ねます。

   メールコードの設定：

   1. メールコード認証によって Pipa エージェントユーティリティキーが作成／置換されることを説明します。ユーザーがすでにキーを持っている可能性がある場合に限り、キーの置換によって以前のキーが無効になることも伝えます。
   2. product に agent-utilities を指定して POST /v1/key/email-code/start を実行します。
   3. 1 回限りのメールコードを尋ねます。
   4. challenge id、code、product agent-utilities を指定して POST /v1/key/email-code/verify を実行します。
   5. 環境変数が一時的な場合、ユーザーが保存を希望しない場合、または書き込みに失敗した場合を除き、返されたキーを保存します。
   6. リポジトリローカルのスキルにはリポジトリローカルの .pipa/credentials、グローバルなスキルには ~/.pipa/credentials を優先します。
   7. リポジトリローカルに書き込む前に、.pipa/ が gitignore 対象であることを確認します。ファイルモードは 600 を使用します。
   8. 保存先のパスをユーザーに伝えます。明示的に求められない限り、キーを表示しないでください。
   9. 認証情報を再読み込みし、選択したモードに進みます。

4. API コントラクト。 次のみを使用してください：

   • GET /v1/agent-utility-records
   • POST /v1/agent-utility-records
   • GET /v1/agent-utility-records/:id
   • PATCH /v1/agent-utility-records/:id
   • DELETE /v1/agent-utility-records/:id
   • POST /v1/key/email-code/start
   • POST /v1/key/email-code/verify
   • POST /v1/topups/checkout-sessions

   クレジット残高：

   • 残高取得用のエンドポイントを捏造しないでください。現在のクレジット残高は、許可された API レスポンスに credits_remaining が含まれている場合にのみ確認できます。
   • ユーザーが残高を尋ねたとき、最新の許可されたレスポンスに credits_remaining がない場合は、このスキルでは現在の残高を直接照会できないと伝えてください。
   • insufficient_credits に topup_limits が含まれている場合は、次の操作でその上限を使用してください。
   • チェックアウト URL はユーザーが操作するための支払いリンクとして扱ってください。明示的に求められない限り、保存したり、長いチェックアウト URL をそのまま出力したりしないでください。

   このスキルで使用する一覧クエリパラメーター：

   • utility_type
   • record_type
   • status
   • started_at_gte
   • started_at_lt

   API レスポンスまたはドキュメントに記載がない限り、他の一覧フィルターは使用しないでください。アーカイブ済みの絞り込みができない場合は、取得後にアーカイブ済みのレコードを除外してください。

   認証ヘッダー：

   Authorization: Bearer ${PIPA_API_KEY}
   

   時間記録レコード：

   {
     "utility_type": "time_tracking",
     "record_type": "time_entry",
     "status": "running",
     "title": "Work description",
     "started_at": "2026-06-30T13:00:00.000Z",
     "project_label": "optional project",
     "client_label": "optional client",
     "flex_label": "optional tag/task/phase",
     "rate_amount": 150,
     "rate_currency": "USD",
     "metadata": { "notes": "optional extras" }
   }
   

   ルール：

   • running には started_at が必要で、ended_at は省略します。
   • completed には started_at と ended_at が必要です。
   • ended_at は started_at 以降でなければなりません。
   • ユーザーごとに、アーカイブされていない実行中の time_tracking/time_entry は 1 件のみです。
   • 削除するとアーカイブされます。完全削除とは説明しないでください。
   • 正確なタイムスタンプを保存してください。所要時間の丸めはユーザー向けの応答でのみ行ってください。

5. 開始モード。

   1. タイトルはリクエストから取得します。「start timer」のみの場合は Untitled work を使用します。
   2. 明らかなラベルのみを解析します：プロジェクト、クライアント、タスク／タグ／フェーズ。ラベルを捏造しないでください。
   3. GET /v1/agent-utility-records?utility_type=time_tracking&record_type=time_entry&status=running。
   4. 実行中のタイマーがある場合は、ID／タイトル／開始時刻を報告します。次の文をそのまま尋ねて、停止します：Do you want me to switch from that timer to [new title]?
   5. 実行中のタイマーがない場合は、現在の UTC ISO started_at を指定して running レコードを作成します。
   6. 作成には新しい Idempotency-Key を使用します。
   7. 成功したら、開始テンプレートのステップ 14 に進みます。

   作成ペイロード：

   {
     "utility_type": "time_tracking",
     "record_type": "time_entry",
     "status": "running",
     "title": "Acme frontend fixes",
     "started_at": "2026-06-30T13:00:00.000Z",
     "project_label": "Acme",
     "client_label": "Acme Co",
     "flex_label": "frontend"
   }
   

6. 切り替えモード。

   1. ステップ 5 に従って実行中のタイマーを取得します。
   2. 実行中のタイマーがない場合は、開始モードで新しい実行中タイマーを作成します。以前のタイマーは停止していないと伝えてください。
   3. 実行中のタイマーがある場合は、status=completed、ended_at=now に更新します。
   4. 停止に成功した後、新しい Idempotency-Key を使用して新しい実行中タイマーを作成します。
   5. 停止には成功したものの作成に失敗した場合は、その旨を正確に伝え、新しいタイマーは実行中でないと報告します。
   6. 停止したタイマーの所要時間と、新しい実行中レコードの ID を返します。

7. 停止モード。

   1. ステップ 5 に従って実行中のタイマーを取得します。
   2. 実行中のタイマーがない場合は、現在実行中のタイマーはないと伝えて停止します。
   3. 実行中のレコードを status=completed、ended_at=now に更新します。
   4. ID、タイトル、開始時刻、終了時刻、所要時間、ラベルを確認します。

   更新ペイロード：

   { "status": "completed", "ended_at": "2026-06-30T14:15:00.000Z" }
   

8. 現在の状態モード。

   1. ステップ 5 に従って実行中のタイマーを取得します。
   2. 実行中のタイマーがない場合は、現在実行中のタイマーはないと伝えます。
   3. 実行中のタイマーがある場合は、ID、タイトル、開始時刻、経過時間、ラベルを報告します。
   4. 作成、停止、変更は行わないでください。

9. 遡及入力モード。

   1. PIPA_USER_TIMEZONE を使用して日付／時刻の範囲を確定します。
   2. 日付／時刻／所要時間／タイムゾーンが曖昧な場合は、直接的な確認を 1 つだけ尋ねて停止します。
   3. started_at／ended_at を UTC ISO に変換します。
   4. completed レコードを作成します。
   5. 作成したエントリーを確認して返します。

   ユーザーが「9:00から45分記録して」と言い、タイムゾーンと日付が分かっている場合は、終了時刻をすぐに計算します。追加の確認は不要です。

10. レビュー・モード。

    1. 範囲を具体的な started_at_gte と started_at_lt の UTC ISO に確定します。「今日」の場合は PIPA_USER_TIMEZONE を使用します。
    2. utility_type=time_tracking、record_type=time_entry、範囲フィルターを指定して GET /v1/agent-utility-records を実行します。
    3. ユーザーがアーカイブ済み／キャンセル済みを求めない限り、アーカイブ済みのレコードを除外します。
    4. レスポンス内のレコードをグループ化／合計します。レポート用エンドポイントを呼び出したり、捏造したりしないでください。
    5. 実行中のエントリーは別に含めてください。所要時間は変化します。

11. 更新／アーカイブ・モード。

    1. req、context、または短い候補リストからレコード ID を特定します。
    2. 参照先が曖昧な場合は、直接的な質問を 1 つだけして終了します。
    3. タイトル、タイムスタンプ、ラベル、レート、メタデータには PATCH /v1/agent-utility-records/:id を使用します。
    4. 明示的な削除／キャンセル／除去／アーカイブの指示がある場合に限り、DELETE /v1/agent-utility-records/:id を使用します。
    5. 実行中のタイマーをアーカイブした場合は、完了ではなく、キャンセル／アーカイブしたと伝えます。

12. トップアップモード。

    Time Tracking の利用料金は、30 日間で Pipa クレジット 10 枚です。自動更新はありません。有効期限が切れた後に次の変更操作を行うと、アクセスパスが再度課金されます。

    残高の確認：

    • 許可されたレスポンスに credits_remaining が含まれていない限り、このスキルでは現在のクレジット残高を照会できません。
    • ユーザーからクレジット残高を尋ねられ、現在のレスポンスに credits_remaining が含まれていない場合は、その旨を伝え、使用中のゲートウェイ URL を記載します。
    1. insufficient_credits が発生した場合、または購入／トップアップを求められた場合に使用します。
    2. リクエストされた整数のクレジット数を選びます。
    3. 数量が指定されていない場合は、次のとおり正確に尋ねて終了します。How many Pipa credits do you want to buy?
    4. { "credits": amount } を指定して POST /v1/topups/checkout-sessions を呼び出します。
    5. 金額とともに、checkout_url を Markdown リンク（例：[Open checkout](...)）で共有します。
    6. チェックアウトを利用できず、API に billing_url のみが含まれている場合は、請求ページへのリンクを共有します。
    7. 支払い確認後、最初の変更リクエストを再試行します。

    insufficient_credits または invalid_topup_credits で上限・下限が返された場合は、その値を使用します。例：10 credits is below the minimum. Smallest top-up is 100 credits for $10. Want me to create that checkout session?

13. API の失敗。 次に行う最小限の操作を実行します。

    • running_timer_exists：実行中のタイマーを取得して状況を説明し、切り替えるかどうかを尋ねます。
    • insufficient_credits：手順 12 に従います。
    • invalid_api_key：キーの再発行によりアカウントキーがローテーションされることを説明し、手順 3 に従います。
    • started_at_required、completed_entry_requires_ended_at、running_entry_cannot_have_ended_at、ended_at_before_started_at：ペイロードを修正します。指定時刻が曖昧な場合に限り、確認します。
    • agent_utility_record_not_found：レコード ID を尋ねます。または、ユーザーが「あのエントリ」について尋ねている場合は、最近の候補を一覧表示します。
    • invalid_topup_credits：API レスポンスに基づき、有効な次の操作として最小限のものを提示します。例：10 credits is below the minimum. Smallest top-up is 100 credits for $10. Want me to create that checkout session? チェックアウトを利用できない場合を除き、billing_url は共有しません。
    • failed_to_create_agent_utility_record、failed_to_patch_agent_utility_record、failed_to_archive_agent_utility_record：失敗前に変更があったかどうかを明示します。タイマーが変更されたかのように伝えてはいけません。
    • API キーがない場合：手順 3 に従います。

    エラーで必要とされない限り、ワークフロー全体を最初からやり直してはいけません。

14. 報告。 簡潔で、実務的かつ監査可能な内容にします。

    開始時のテンプレート：

    タイマーを開始しました。
    
    - レコード ID：`[id]`
    - タイトル：`[title]`
    - 開始時刻：`[started_at]`
    - ラベル：`[project/client/flex or none]`
    

    停止時のテンプレート：

    タイマーを停止しました。
    
    - レコード ID：`[id]`
    - タイトル：`[title]`
    - 時間：`[started_at]` から `[ended_at]`
    - 所要時間：`[rounded duration]`
    - ラベル：`[project/client/flex or none]`
    

    ルール：

    • 必須情報に不足がある場合、または曖昧な場合に限り確認します。
    • 1 回につき、直接的な追加質問を 1 つだけします。
    • API メタデータをそのまま大量に出力してはいけません。
    • スキルファイルにシークレットを保存してはいけません。
    • API が残りクレジットを返した場合は、その数を伝えます。
    • 失敗時は、失敗前にレコードが変更されたかどうかを伝えます。