Trigger — 将来の仕事を起動する

Project Triggerは、時刻や文書条件を満たしたときに公開Workflowまたは新しいSessionを開始します。定期的なレビュー、一度だけの将来の仕事、Shared Documentが合意した状態になった後の作業に使います。既存Sessionへturnを追加することはありません。既存Sessionのfollow-upは別のSession機能で、再利用する仕事を今すぐ実行するときはWorkflow runを使います。

権限と起動先の準備

activeなProjectを使います。viewerは内容を確認でき、automationの作成・管理にはcollaborator/adminの権限が必要です。Agentが作るTriggerでは、その現在の人間ownerにもactiveなProject collaborator/admin権限が必要です。Sessionの起動先にはactiveなcollaborator/adminのAgentを選びます。開始時には実行ownerのruntimeとAgent設定が利用可能でなければなりません。予定を登録してもrepository、tool、本番操作の権限が増えることはありません。

WebUIではProjectのTriggersを開いてNew triggerを選ぶか、対応する新しいSession/Workflowの依頼を準備するときにWhenを使います。起動先、予定、timezone、入力を選び、previewを確認して保存します。Triggersの一覧と詳細に、次回の予定、履歴、実行可能な管理操作が表示されます。仕事の中身は起動したSessionやRunを開いて確認します。

以下のCLI操作は、Projectへアクセスできる実行中のaachat Session内のAgent向けです。すべてのchat triggerコマンドに--project <team>/<project>が必須で、cwdでは選択しません。結果を使う前に、応答のprojectを確認します。placeholderは実際の名前とIDへ置き換えます。

chat trigger list --project <team>/<project>
chat workflow list --project <team>/<project>
chat workflow show greeting --project <team>/<project>
chat project members <team>/<project> --runtime-profiles

同じautomationがないと判断する前に、listが返すnext_commandをnullになるまで辿ります。公開Workflowの正確なslug、またはactiveなAgentの正確な名前を使います。CLIが解決するので、内部UUIDに置き換えません。

平日のWorkflow Triggerを作る

先にWorkflowガイドのgreetingを作成・公開するか、実在するWorkflowを選び、showのschemaに入力を合わせます。次の完全な入力をWorkflow Bundleの外のtrigger.jsonへ保存します。例を使う前に日付を将来の期間へ更新してください。

{
  "name": "Weekday greeting",
  "description": "Generate a greeting on weekday mornings.",
  "schedule": {
    "kind": "calendar",
    "time": "09:00:00",
    "days": ["mon", "tue", "wed", "thu", "fri"],
    "timezone": "Asia/Singapore",
    "starts_on": "2026-09-07",
    "ends_on": "2026-12-31"
  },
  "target": {
    "kind": "workflow",
    "workflow": "greeting",
    "input": {"reader": "Alex"}
  }
}

予定だけをpreviewし、その後1回だけ作成します。

jq '{schedule}' trigger.json | chat trigger preview --project <team>/<project> --stdin
chat trigger create --project <team>/<project> --stdin < trigger.json
chat trigger show <trigger-id> --project <team>/<project>

previewはautomationを作らず、serverが正規化した予定と次の3回の時刻を返します。現地時刻、timezone、日付を確認します。createは有効なTriggerを作るため、条件を満たすと仕事が起動し得ます。IDを控え、showを読み、起動後に履歴を確認します。occurrenceのacceptedは起動先を開始したという意味で、仕事の成功ではありません。

名前はtrim後1–120文字、任意のdescriptionは1,000文字までです。Workflowのinputは作成・編集時と起動時に、その時点の公開入力schemaで検証されます。互換性のない入力契約を公開すると既存Triggerが自動pauseする場合があります。Triggerの起動先は公開Workflowで、親Workflow Revisionが固定する子とは異なり、作成時に公開参照先を固定しません。

新しいSessionを起動する

完全な入力のtargetをSession向けに置き換えます。例のmemberは実在するProject memberへ変更します。workspace_repoを指定する場合はProject repositoryまたはTeam default repositoryに一致させ、それ以外では省略して有効な設定済みrepositoryを使います。

{
  "kind": "session",
  "agent": "reviewer.yourname",
  "prompt": "Review the Project's latest results and record the next decision.",
  "launch": {
    "runtime_kind": "codex-acp",
    "config_overrides": []
  },
  "workspace_repo": "owner/repository",
  "working_branch": "main"
}

promptは空ではない依頼内容で、上限は100,000 bytesです。launch、workspace_repo、working_branchは任意です。launchを省略するとserverがAgentの既定設定を解決します。Runtimeのkindと型付きconfigは、chat project members <team>/<project> --runtime-profilesが示すものだけを使います。公開されているID optionなら、overrideは{"id":"mode","value":{"type":"id","value":"agent-full-access"}}という形です。そのAgentが示していないoptionはコピーしません。空のoverride listは独自optionを選択しません。working_branchには設定済みのProjectまたはTeam repositoryが必要です。別のrepositoryを選ぶ場合は先にProject/Teamのrepository設定を更新し、有効な設定済みrepositoryでよければworkspace_repoを省略します。どちらのrepositoryも存在しない場合はworking_branchも省略します。working branch名はrepositoryの選択であって、そこへの直接pushの許可ではありません。

予定のリファレンス

以下は個別のschedule objectで、createの完全な要求ではありません。UTC timestampは末尾にZを付け、有効なIANA timezoneを指定します。例の日付が期限切れになる前に置き換えてください。

{"kind":"once","at":"2026-09-07T01:00:00Z","timezone":"Asia/Singapore"}

{"kind":"calendar","time":"09:00:00","days":["mon"],"timezone":"Asia/Singapore","starts_on":"2026-09-07","ends_on":"2026-12-31"}

{"kind":"interval","every_seconds":3600,"starts_at":"2026-09-07T01:00:00Z","ends_at":"2026-09-30T01:00:00Z","timezone":"Asia/Singapore"}

calendarはtimezoneの夏時間規則に従います。現地時刻が重複する場合は早い方の時点に1回、存在しない現地時刻は1秒ずつ最大4時間進めて最初の有効な時刻を選びます。timezoneの切替時期はserverのpreviewを必ず確認します。intervalは経過秒数であり、「毎日同じ現地時刻」ではありません。これらの制約は既存Sessionのfollow-upとは別です。

文書が一致したら起動する

起動先を準備した完全なcreate入力で、次のscheduleを使います。

{"kind":"document_match","on":"reviews/release","match":{"status":"approved","ready":true}}

同じProjectのdocs/reviews/release.mdを監視します。一致するShared Documentのfrontmatter例です。

---
title: Release review
status: approved
ready: true
---

onは正確なkind/doc_idで、file pathや別Projectの文書ではありません。matchには少なくとも1つのfieldが必要です。値はstring、number、booleanの完全一致で、複数fieldはAND条件です。trueはboolean、"true"は別のstringです。array、object、nullは条件値に使えません。

文書条件は作成時や再検証時にすでに一致する可能性があります。以後の保存のたびに起動するのではなく、最大1回だけ起動します。監視文書の保存で条件が評価され、文書条件にrunは使えません。完了後に再び待ち受けるには、新しい文書条件を含む完全なeditを送ります。

既存Triggerを管理する

変更前にshowを読みます。state_versionは変更でも起動でも進むため、固定値を書いたり古い値を再利用したりしません。showは現在のversionを含む、再利用可能な完全なedit_inputも返します。nullでなければ保存し、確認したversionを保って必要なfieldを変更し、全体を置き換えます。

chat trigger show <trigger-id> --project <team>/<project> > trigger-state.json
jq '.edit_input' trigger-state.json > trigger-edit.json

chat trigger edit <trigger-id> --project <team>/<project> --stdin < trigger-edit.json

2つのコマンドの間にtrigger-edit.jsonを意図どおり編集してください。editは部分patchではなく全置換です。時刻予定を変える場合は送信前にpreviewします。起動先が利用できなければedit_inputはnullです。新しい起動先を選び、name、schedule、target、任意のdescription、最新のstate_versionを含む完全な入力を作ります。CLI/serverの版移行中に古いserverが起動先を利用不可として返し、edit inputを作れない場合もあります。UUIDで代替しません。返されたSessionのedit inputで、受理済みのrepository既定選択を保つならworking_branch: ""、指定branchを保つなら空でない値を維持します。

角括弧は任意引数です。一覧・履歴のlimitは1–100です。pauseとdeleteは、起動済みのSessionやWorkflow Runを取消・削除しません。必要で権限がある場合は起動先を別に管理します。

結果を読み、重複作業を避ける

Triggerの状態はactive、paused、completedです。occurrenceの状態はaccepted、skipped、failedです。acceptedならworkflow_run_idまたはsession_idと起動先の現在の状態を確認します。runはoccurrenceを同期的に返しますが、起動先の成果は待ちません。state_versionは進み、next_scheduled_forと定期予定は変わりません。

pause済み・completedのTriggerと文書条件は今すぐ実行できません。revisionが変わった場合や起動処理中の場合は、次の起動先を開始する前に競合します。強行せず返された操作に従います。

競合、pause、成否不明から復旧する

version競合では、エラーが返した正確なProject指定付きshowを実行し、新しい状態から判断し直します。何が変わったかを確認せず、古い要求のversionだけ差し替えません。

createは冪等ではありません。 構造化エラーが成否不明を示した場合、create JSONを再送しません。返された読み取り専用のlistを全page辿り、Triggerがすでにできていないか照合します。runの成否不明でも再実行せず、返されたshowとoccurrence履歴から開始済みか確認します。それでも証拠が足りなければ、重複作業を作らず未解決として扱います。これは、通信不明時に同一payloadを再送できるWorkflow completionとは異なります。

手動pauseと自動pauseでは復旧が異なります。

serverは変更時と起動時にProject、creator、実行ownerとの関係、起動先、Runtimeの権限を再確認します。previewや前回の成功は、次回も動く保証ではありません。起動先の成果を読み、実行そのものにはWorkflowの復旧手順やSessionガイドを使います。