twill-cloud-coding-agent

Twill Cloud Coding Agent

このスキルを使用すると、パブリックな v1 API を通じて Twill のワークフローを実行できます。

セットアップ

API キーと任意のベース URL を設定します。

export TWILL_API_KEY="your_api_key"
export TWILL_BASE_URL="${TWILL_BASE_URL:-https://twill.ai}"

すべての API 呼び出しには、次を使用します。

Authorization: Bearer $TWILL_API_KEY

繰り返しを減らすには、このヘルパーを使用します。

api() {
  curl -sS "$@" -H "Authorization: Bearer $TWILL_API_KEY" -H "Content-Type: application/json"
}

API キーはクラウドワークスペースに属し、そのワークスペースのクラウドタスクにのみアクセスできます。個人用ワークスペースのキーは拒否されます。また、ローカルプロジェクトのチャット（Twill Desktop）は API から参照できず、404 が返されるか、一覧から省略されます。

エラーは JSON { "error": { "code", "message", "details"? } } 形式です。レート制限はキーごとに 1 分あたり 100 リクエスト、1 時間あたり 1,000 リクエストです。429 には Retry-After が含まれます。

エンドポイントの対応範囲（パブリック v1）

• GET /api/v1/auth/me
• GET /api/v1/repositories
• POST /api/v1/tasks
• GET /api/v1/tasks
• GET /api/v1/tasks/:taskIdOrSlug
• POST /api/v1/tasks/:taskIdOrSlug/messages
• GET /api/v1/tasks/:taskIdOrSlug/jobs
• POST /api/v1/tasks/:taskIdOrSlug/cancel
• POST /api/v1/tasks/:taskIdOrSlug/archive
• GET /api/v1/tasks/:taskIdOrSlug/teleport/claude
• GET /api/v1/jobs/:jobId/logs/stream
• POST /api/v1/jobs/:jobId/cancel
• GET /api/v1/scheduled-tasks
• POST /api/v1/scheduled-tasks
• GET /api/v1/scheduled-tasks/:scheduledTaskId
• PATCH /api/v1/scheduled-tasks/:scheduledTaskId
• DELETE /api/v1/scheduled-tasks/:scheduledTaskId
• POST /api/v1/scheduled-tasks/:scheduledTaskId/pause
• POST /api/v1/scheduled-tasks/:scheduledTaskId/resume

プラン承認用のエンドポイントはありません。プランやネイティブの権限に関する質問には、Twill のタスクチャットで回答します。

認証と検出

キーとワークスペースのコンテキストを検証します。

curl -sS "$TWILL_BASE_URL/api/v1/auth/me" -H "Authorization: Bearer $TWILL_API_KEY"

workspaceId、userId、apiKeyId、workspaceName、workspaceSlug が返されます。

ワークスペースで利用可能な GitHub リポジトリを一覧表示します。

curl -sS "$TWILL_BASE_URL/api/v1/repositories" -H "Authorization: Bearer $TWILL_API_KEY"

{ repositories: [{ fullName, defaultBranch, description }] } が返されます。

タスク

タスクの作成

api -X POST "$TWILL_BASE_URL/api/v1/tasks" -d '{"command":"Fix flaky tests in CI"}'

リポジトリとブランチは、リクエスト本文では指定できません。エージェントは実行時に、ワークスペースに接続されているリポジトリから選択します。

必須フィールド：

• command

任意のフィールド：

• agent：完全な provider/model ID。例：claude-code/sonnet、claude-code/opus、codex/gpt-5.5、open-code/openai/gpt-5.4。codex などプロバイダーのみの値は拒否されます。ワークスペースのルーティングのデフォルトを使用するには、省略してください。
• userIntent（SWE、DEV_ENVIRONMENT、SCHEDULE）：デフォルトは SWE です。従来の PLAN、ASK、GOAL も引き続き受け付けられますが、SWE として実行されます。
• reasoningEffort（low、medium、high、xhigh、max、ultra）
• parentId（このタスクの起点となる既存タスクの ID）
• title
• files（{ filename, mediaType, url } の配列。url は data:text/plain;base64,... などの data: URL である必要があります。リモートの http(s): URL は拒否されます）

エージェントに最初にプランを作成させるには、command の先頭に /plan を付けます。ユーザーは Twill のタスクチャットでプランを確認して承認します。

レスポンス（201）は { task: { id, slug, title, url }, job: { id, status } } です。必ず task.url をユーザーに伝えてください。

タスクの一覧表示

curl -sS "$TWILL_BASE_URL/api/v1/tasks?limit=20&cursor=BASE64_CURSOR" -H "Authorization: Bearer $TWILL_API_KEY"

limit（デフォルトは 20、最大 100）と cursor によるカーソルページネーションに対応しています。レスポンスは { tasks, nextCursor } です。各タスクには id、slug、title、url、createdAt、latestJobStatus、および { repoFullName, prNumber, prUrl, title, state } の配列である prs が含まれます。state は open、merged、closed のいずれかです。

タスクの詳細を取得

curl -sS "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG" -H "Authorization: Bearer $TWILL_API_KEY"

task（id、slug、title、url、createdAt、updatedAt、prs）と、latestJob（id、status、type、agentProvider、startedAt、completedAt、plan、planOutcome、finalAnswer）が返されます。該当するジョブがない場合、latestJob: null が返されます。

フォローアップメッセージを送信する

api -X POST "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/messages" -d '{"message":"Please prioritize login flow first"}'

メッセージを送信すると、タスクで実行中のジョブがキャンセルされ、このメッセージで新しい実行が開始されます。レスポンスは { job: { id, status } } です。

任意のフィールド：userIntent、reasoningEffort、files（作成時と同じルール）、agent。agent はモデルを変更できますが、ハーネスは変更できません。claude-code/... から codex/... への切り替えは 400 を返します。別のハーネスを使うには、新しいタスクを開始してください。

タスクのジョブ一覧を取得する

curl -sS "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/jobs?limit=30&cursor=BASE64_CURSOR" -H "Authorization: Bearer $TWILL_API_KEY"

カーソルページネーションに対応しています。

• limit のデフォルトは 30（最大 100）です
• cursor は古いページを取得します
• レスポンスは { jobs, nextCursor } です。各ジョブには id、status、type、agentProvider、finalAnswer、plan、planOutcome、error、createdAt、completedAt が含まれます

タスクをキャンセルする

api -X POST "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/cancel" -d '{}'

タスクをアーカイブする

api -X POST "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/archive" -d '{}'

Claude Teleport セッションをエクスポートする

curl -sS "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/teleport/claude" -H "Authorization: Bearer $TWILL_API_KEY" -o session.tar

タスクの Claude Code セッションの JSONL ファイルを tar 形式で返します（ヘッダーは X-Twill-Session-Id、X-Twill-Job-Id、X-Twill-File-Count）。Claude Code タスクで、タスクのサンドボックスがまだ稼働している場合にのみ機能します。それ以外の場合は 400、404、または 409 を返します。

ジョブ

ジョブログをストリーム配信する（SSE）

curl -N "$TWILL_BASE_URL/api/v1/jobs/JOB_ID/logs/stream" -H "Authorization: Bearer $TWILL_API_KEY" -H "Accept: text/event-stream"

各 data: 行は、type を含む JSON オブジェクトです。

• connected：最初のイベントです。
• 完了したジョブ：trace_url（url、expiresAt）は、完全なトレースをダウンロードするための有効期間の短い署名付き URL です。その後、historical_complete と complete（status：completed、failed、cancelled）が続きます。
• 実行中のジョブ：履歴用の trace_chunks（署名付きチャンク URL）と trace_records が続き、その後 historical_complete、さらに complete までライブのログおよびステータスイベントが続きます。
• error：ストリームが失敗しました。

トレースを解析せずにジョブの結果を取得するには、Get Task Details または List Task Jobs の finalAnswer を使用してください。

ジョブをキャンセルする

api -X POST "$TWILL_BASE_URL/api/v1/jobs/JOB_ID/cancel" -d '{}'

スケジュール済みタスク

スケジュール済みタスクの作成には有料プラン（Pro または Max）が必要です。それ以外の場合、API は 403 を返します。

一覧表示と作成

curl -sS "$TWILL_BASE_URL/api/v1/scheduled-tasks" -H "Authorization: Bearer $TWILL_API_KEY"

api -X POST "$TWILL_BASE_URL/api/v1/scheduled-tasks" -d '{
  "title":"Daily triage",
  "message":"Review urgent issues and open tasks",
  "cronExpression":"0 9 * * 1-5",
  "timezone":"America/New_York",
  "agentProviderId":"claude-code/sonnet"
}'

必須項目：title（最大 200 文字）、message、cronExpression。

任意項目：timezone（IANA 名。デフォルトは "UTC"）、agentProviderId（provider/model 形式の完全なオーバーライド。例：claude-code/sonnet、codex/gpt-5.5）。サーバーは保存時に agentProviderId を検証しないため、無効な ID はスケジュールの実行時にのみ失敗します。

リポジトリとブランチはスケジュール済みタスクのペイロードに含まれません。単発タスクと同様に、各実行時にディスパッチされるリポジトリが選択されます。

レスポンスは { scheduledTask: { id, workspaceId, createdById, title, message, cronExpression, timezone, nextRunAt, lastRunAt, enabled, agentProviderId, createdAt, updatedAt } } です。

読み取り、更新、削除

curl -sS "$TWILL_BASE_URL/api/v1/scheduled-tasks/SCHEDULED_TASK_ID" -H "Authorization: Bearer $TWILL_API_KEY"

api -X PATCH "$TWILL_BASE_URL/api/v1/scheduled-tasks/SCHEDULED_TASK_ID" -d '{
  "message":"Updated instructions",
  "cronExpression":"0 10 * * 1-5",
  "agentProviderId":"codex/gpt-5.5"
}'

curl -sS -X DELETE "$TWILL_BASE_URL/api/v1/scheduled-tasks/SCHEDULED_TASK_ID" -H "Authorization: Bearer $TWILL_API_KEY"

PATCH では title、message、cronExpression、timezone、agentProviderId の任意の組み合わせを指定できます（オーバーライドをクリアするには null を渡します）。DELETE は { "success": true } を返します。

一時停止と再開

api -X POST "$TWILL_BASE_URL/api/v1/scheduled-tasks/SCHEDULED_TASK_ID/pause" -d '{}'
api -X POST "$TWILL_BASE_URL/api/v1/scheduled-tasks/SCHEDULED_TASK_ID/resume" -d '{}'

動作

• userIntent には SWE（デフォルト）、DEV_ENVIRONMENT、または SCHEDULE を使用します。計画を立てる場合は、PLAN を送る代わりにコマンドの先頭に /plan を付けます。
• タスクでは repository／branch を、スケジュール済みタスクでは repositoryUrl／baseBranch を送信しないでください。Twill はワークスペースのコンテキストから、実行時にリポジトリとブランチを選択します。
• agent／agentProviderId には、必ず完全な provider/model 形式の ID を渡してください。
• 添付ファイルは data: URL としてインラインで指定してください。
• タスクを作成し、task.url を報告してください。ポーリングやログのストリーミングは、依頼された場合にのみ行ってください。
• 計画の承認と権限に関する質問は、Twill のタスクチャットで行われます。フォローアップメッセージでは回答できません。
• TWILL_API_KEY がない場合は、ユーザーに提示を求めてください。
• API キーやその他のシークレットを出力しないでください。