SKILLOfficialdevelopment

boltz-check-status

プラグイン: boltz
ソース: GitHub で見る ↗

説明

ジョブ（実行タスク）の状態確認と結果の復旧に対応します。次のような場合に使用: ジョブ一覧の表示、進行状況の確認、ダウンロードの再開、結果の復旧、既存のジョブIDでのダウンロード ※新しいジョブを開始する場合には使用しません。

原文を表示

Boltz job status and result recovery. Use when listing jobs, checking progress, resuming downloads, recovering results, or downloading an existing job ID. Not for starting new jobs.

ユースケース

ジョブ一覧を表示するとき
進行状況を確認するとき
ダウンロードを再開するとき
結果を復旧するとき
既存のジョブIDでダウンロードするとき

本文（日本語訳）

ワークフロー

boltz-api が PATH（プログラム検索パス）にない場合は、再度試みる前に boltz-cli-setup を使用してインストール・更新の案内を確認してください。

コマンドが認証の欠落・期限切れを報告した場合は、ユーザーの許可を求めずに boltz-cli-setup で boltz-api auth login --device-code を開始してから再度試みてください。

エージェント実行環境が boltz-api のインストール・認証・API呼び出しをブロックしている場合は、boltz-cli-setup を使用してホスト実行環境のバイパス・権限昇格をリクエストしてから再度試みてください。これにより、ユーザー全体のCLI（コマンドラインツール）インストール、ブラウザログイン、認証情報の保存、一時ファイル、API接続が可能になります。

このスキルは、セッション間での状態復帰、および以前のBoltzジョブ結果の確認・ダウンロードに使用します。ペイロード（送信データ）の作成は行いません — このスキルは list・retrieve・download-results・download-status の呼び出しのみを実行します。

次の4つのモードで使用します：

ローカル進捗確認: ユーザーが実行名・実行ディレクトリを把握している場合、リモートAPIを呼び出す前に download-status を優先します。
最近のジョブ一覧: 6つのリソース全体を列挙し、統合してから created_at（作成日時）で降順ソートします。
特定のジョブを取得: ジョブID（先頭部分）が判明している場合はそれを使用します。不明な場合はリソースを順に試し、成功するまで続けます。
再開・結果ダウンロード: 可能な限り元の実行名で download-results を実行します。再開のため start を再び実行しないでください。

ADMEジョブは adme_pred_* というプレフィックス（接頭辞）を使用し、モード1～2（list・retrieve）に他と同様に表示されます。ただしADMEは download-results・アーカイブステップを持たないため、モード3～4は適用されません — retrieve を再実行してスコアを復帰させるか（output.molecules[] を読む）、またはローカルの run.json から取得してください。

ドロップされたセッション、ジョブIDプレフィックスのマッピング、または download-results の実行名選択の方法については、references/resume.md を参照してください。リソースごとの list 列、retrieve フィールド、結果の意味については references/api.md を参照してください。

コマンドパターン

# プレースホルダーを実行前に具体的な絶対パスに置き換えてください。

# ローカルヘルパー: APIを呼び出さずにローカルのチェックポイント状態を確認。
boltz-api --format json download-status \
  --name "<run-name>" \
  --root-dir "/absolute/path/boltz-experiments"

# モード1: 6つのリソース全体で最近のジョブを一覧表示。
# 注記: CLIは1ページ当たり1つのJSONオブジェクトを出力（ストリーム配信、{data:[]}ラッパーなし）。
# --limit はページあたりの件数で、CLIは自動ページネーション（複数ページ自動取得）するため、
# 各コマンドは head で件数を制限してください。
boltz-api predictions:structure-and-binding list --limit 20 --format jsonl | head -20
boltz-api predictions:adme list --limit 20 --format jsonl | head -20
boltz-api small-molecule:library-screen list --limit 20 --format jsonl | head -20
boltz-api small-molecule:design list --limit 20 --format jsonl | head -20
boltz-api protein:library-screen list --limit 20 --format jsonl | head -20
boltz-api protein:design list --limit 20 --format jsonl | head -20

# モード2: IDで取得。ワークフロー注記の上記IDプレフィックスからリソースを選びます。
# プレフィックスが不明な場合は、成功するまで1つずつ実行してください。
boltz-api predictions:structure-and-binding retrieve --id "<job-id>" --format json
boltz-api predictions:adme retrieve --id "<job-id>" --format json
boltz-api small-molecule:library-screen retrieve --id "<job-id>" --format json
boltz-api small-molecule:design retrieve --id "<job-id>" --format json
boltz-api protein:library-screen retrieve --id "<job-id>" --format json
boltz-api protein:design retrieve --id "<job-id>" --format json

# モード3: 結果ダウンロード再開。実行環境の長時間実行・ノンブロッキングコマンド機能経由で起動してください
# （不明な場合は boltz-cli-setup を参照）。
boltz-api download-results \
  --id "<job-id>" --name "<run-name>" \
  --root-dir "/absolute/path/boltz-experiments" \
  --poll-interval-seconds 30

常に実施すること

ユーザーが実行名・スラッグ、または実行ディレクトリを持ち、ローカルダウンローダー状態のみが必要な場合は、retrieve より前に download-status を優先してください。
絶対パスの出力ルートを使用し、--root-dir で一貫して渡し続けてください。実行ディレクトリに cd しないでください。そうするとその後の相対パスが実行ディレクトリ内を指すようになり、ユーザーのワークスペースを指しません。
不慣れなジョブIDの場合、モード3（ダウンロード）の前にモード2（取得）を実行して idempotency_key（重複排除キー）を取得してください。
ジョブIDではなく、元の実行名スラッグを --name として優先してください — 既存ディレクトリにカーソル位置付きで再開します。
権限制御付き実行環境では、各Boltzコマンドを boltz-api で始まる最上位レベルのコマンドとして保ちます。シェルループから生成するより6つの list・retrieve コマンドを明示的に実行してください。ストリーム配信の暴走を防ぐため、一覧表示時に固定の | head -20 制限を付けることは問題ありません。
download-results を実行環境のドキュメントに記載された機構（長時間実行・ノンブロッキング機能）経由で実行してください。シェル & や nohup で切り離さないでください。実行環境がシェル背景実行をサポートしている場合を除き、.boltz-run.json が書き込まれる前に子プロセスが回収される場合があります。この実行環境の長時間実行コマンドの扱いが不明な場合は boltz-cli-setup を参照してください。
ダウンロード開始後、手動で完了待ちや臨時のポーリングループを実行しないでください。実行環境がフォローアップチェック（ハートビート、スケジュール済みタスク、リマインダー）を予定できる場合は、download-status を定期的に実行するものをスケジュールしてください。これは重要な状態変化またはターミナル（終了）完了・失敗のみを投稿し、ターミナル状態に達したら停止します。できない場合は、自動次回チェックを主張しないでください。ジョブID、実行名、出力ディレクトリ、および download-status 確認に必要なコマンドを報告してください。
download-results は機械可読なJSONL形式の進捗をデフォルトで stderr に出力します。人間が読める形式のログを明示的に求める場合のみ --progress-format text --verbose を追加してください。
ローカルのチェックポイント状態は download-status を優先してください。スケジュール済みフォローアップはこれを使用し、保存されたセッションハンドルは対話的でユーザー要求による進捗確認の場合のみポーリングしてください。ユーザーが最新のリモート状態を望む場合を除き retrieve をループしないでください。
retrieve が {"code":"VALIDATION_ERROR","message":"Request validation failed"} のみをフィールドパスなしで表示する場合、これは predictions:structure-and-binding エラー時の予想動作です — 他のエンドポイントはフィールドパスを含みます。
失敗・中断されたジョブで start を再び実行しないでください。ペイロードを修正して新しい idempotency-key で送信するか、または単に download-results で再開してください。

バックアップ手段

Python SDK リファレンス（リソースごとの list・retrieve メソッド）: https://api.boltz.bio/docs/api/python
CLI フラグ名: boltz-api <resource> list --help、boltz-api <resource> retrieve --help、boltz-api download-results --help、boltz-api download-status --help

出力

ローカルヘルパー・モード1・モード2は構造化データを標準出力に表示します。テーブル形式で提示してください。
モード3は復帰したアーティファクト（成果物）を <output-root>/<run-name>/ 下に書き込みます — 新規実行と同じレイアウトです。再開動作については references/resume.md を参照してください。

原文（English）を表示

Workflow

If boltz-api is missing from PATH, use boltz-cli-setup for install/update guidance before retrying. If a command reports missing or expired authentication, use boltz-cli-setup to start boltz-api auth login --device-code before retrying; do not ask permission first. If the agent host sandbox blocks boltz-api install/auth/API calls, use boltz-cli-setup to request the host sandbox bypass/escalation needed for user-wide CLI install, browser login, credential storage, temp files, or API access before retrying.

Use this skill to recover state across sessions and to inspect or download results for prior Boltz jobs. No payload authoring — this skill only calls list / retrieve / download-results / download-status.

Use four modes:

Local progress: if the user knows the run name / run dir, prefer download-status before remote API calls.
List recent jobs: enumerate all six resources, merge, and sort by created_at descending.
Retrieve one job: use the job ID prefix when known; otherwise probe resources until one succeeds.
Resume/download results: run download-results with the original run name when possible. Never run start again to resume.

ADME jobs use the prefix adme_pred_* and show up in Modes 1-2 (list / retrieve) like the others. ADME has no download-results/archive step, so Modes 3-4 don't apply — recover its scores by re-running retrieve (read output.molecules[]) or from the local run.json.

Read references/resume.md before recovering a dropped session, mapping job ID prefixes, or choosing a run name for download-results. Read references/api.md for per-resource list columns, retrieve fields, and result semantics.

Command Pattern

# Replace placeholders with concrete absolute paths before running.

# Local helper: inspect local checkpoint state without API calls.
boltz-api --format json download-status \
  --name "<run-name>" \
  --root-dir "/absolute/path/boltz-experiments"

# Mode 1: list recent jobs across all 6 resources.
# Note: the CLI emits one JSON object per record (streamed, no {data:[]} wrapper).
# --limit is per-page and the CLI auto-paginates, so cap each explicit command with head.
boltz-api predictions:structure-and-binding list --limit 20 --format jsonl | head -20
boltz-api predictions:adme list --limit 20 --format jsonl | head -20
boltz-api small-molecule:library-screen list --limit 20 --format jsonl | head -20
boltz-api small-molecule:design list --limit 20 --format jsonl | head -20
boltz-api protein:library-screen list --limit 20 --format jsonl | head -20
boltz-api protein:design list --limit 20 --format jsonl | head -20

# Mode 2: retrieve by ID. Pick the resource from the ID prefix in the workflow
# notes above. If the prefix is unknown, run these one at a time until one succeeds.
boltz-api predictions:structure-and-binding retrieve --id "<job-id>" --format json
boltz-api predictions:adme retrieve --id "<job-id>" --format json
boltz-api small-molecule:library-screen retrieve --id "<job-id>" --format json
boltz-api small-molecule:design retrieve --id "<job-id>" --format json
boltz-api protein:library-screen retrieve --id "<job-id>" --format json
boltz-api protein:design retrieve --id "<job-id>" --format json

# Mode 3: resume download. Launch it through the runtime's long-running/non-blocking
# command facility (consult boltz-cli-setup if unsure).
boltz-api download-results \
  --id "<job-id>" --name "<run-name>" \
  --root-dir "/absolute/path/boltz-experiments" \
  --poll-interval-seconds 30

Always Do This

If the user has a run name / slug or run dir and only wants local downloader state, prefer download-status before retrieve.
Use an absolute output root and keep passing it through --root-dir. Do not cd into the run directory; that makes later relative paths point at the run directory instead of the user's workspace.
On an unfamiliar job ID, run Mode 2 (retrieve) before Mode 3 (download) so you capture idempotency_key.
Prefer the original run-name slug over the job ID as --name — it resumes into the existing dir with cursor.
In permission-gated runtimes, keep each Boltz call as a top-level command that starts with boltz-api. Prefer running the six list / retrieve commands explicitly over generating them from a shell loop; a fixed | head -20 cap is okay when listing to avoid runaway streamed output.
Run download-results through the runtime's long-running or non-blocking command facility, using the mechanism the runtime documents rather than tool arguments you assume exist. Do not detach it with shell & or nohup unless the runtime documents shell backgrounding as its supported mode; some tool runners reap shell-backgrounded children before .boltz-run.json is written. If unsure how this runtime handles long-running commands, consult boltz-cli-setup.
After the download starts, do not manually wait on it or run ad hoc polling loops. If the runtime can schedule follow-up checks (a heartbeat, scheduled task, or reminder), schedule one that runs download-status periodically, posts only material status changes or terminal completion/failure, and stops once terminal. If it cannot, do not claim an automatic next check; report the job ID, run name, output directory, and the command needed to check download-status.
download-results now emits machine-readable JSONL progress on stderr by default. Add --progress-format text --verbose only when you explicitly want human-readable logs.
Prefer download-status for local checkpoint state. Use it for any scheduled follow-up, and poll a saved session handle only for interactive, user-requested progress checks. Don't loop retrieve unless the user wants fresh remote status.
If retrieve surfaces only {"code":"VALIDATION_ERROR","message":"Request validation failed"} with no details, that's expected for predictions:structure-and-binding failures — other endpoints include field paths.
Never run start again on a failed or interrupted job. Fix the payload and submit with a new idempotency-key, or just resume with download-results.

Escape Hatch

Python SDK reference (per-resource list / retrieve methods): https://api.boltz.bio/docs/api/python
CLI flag names: boltz-api <resource> list --help, boltz-api <resource> retrieve --help, boltz-api download-results --help, boltz-api download-status --help

Outputs

Local helper / Mode 1 / Mode 2 print structured data to stdout; present as a table.
Mode 3 writes recovered artifacts under <output-root>/<run-name>/ — same layout as a fresh run. Read references/resume.md for resume behavior.

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。