Awaitless

Awaitless

コーディングエージェント向けの、適応型で永続性のある実行機能です。

コマンドを単一の実行レイヤー経由で実行します。短い処理はインラインで返され、時間のかかる処理やキューに入った処理は、ローカル、SSH、Slurm にまたがって永続化されます。ワークロードは、すでに所有しているインフラストラクチャ上で実行されます。

エージェントは処理を送信し、実行は Awaitless が担います。

Awaitless は、コーディングエージェントとエージェントが利用するコンピューティング環境の間に位置する、適応型の永続実行レイヤーです。エージェントに安定した単一のジョブ契約を提供しながら、その基盤ではローカルマシン、SSH ホスト、Slurm クラスターを再利用します。

简体中文 · ドキュメント · ベンチマーク · PyPI

既存のコンピューティング環境全体で一貫したジョブのライフサイクル

Coding agent → submit work → Awaitless owns the job lifecycle → Local / SSH / Slurm

永続的なジョブ	名前付きの希少リソースキュー	完了と復旧
安定した ID、状態、キャンセル、上限付きログ、Artifacts は、クライアントが切断されても保持されます。	永続的な FIFO 方式の受付により、名前付きリソースに同時に入るジョブ数が多くなりすぎるのを防ぎます。	終了コードと結果は、ジョブ ID または再生可能な完了カーソルから引き続き取得できます。

Awaitless が担うのはジョブのライフサイクルであり、ハードウェアではありません。リソースの検出、GPU トポロジーの把握、複数リソースの割り当て、クラスターのスケジューラーの置き換えは行いません。オペレーターがキューに名前を付けて同時実行数を固定し、Slurm は引き続き --gpus 2 --mem 64G のような要求と、物理クラスター全体のスケジューリングを処理します。

コーディングエージェントには、ジョブの面倒を見るのではなく、コードを書いてほしい

エージェントは独自の run → sleep → check ループを作成できます。より難しいのは、長時間のワークロードや変化するセッションにまたがって、ジョブ ID の管理、切断からの復旧、キューへの受付、キャンセル、結果の配信を確実に行うことです。この実行レイヤーがなければ、エージェントは増え続ける同じログを何度もコンテキストに読み込みます。

ssh gpu 'run_benchmark > job.log 2>&1 &'
ssh gpu 'tail -n 200 job.log'  # again...
ssh gpu 'tail -n 200 job.log'  # and again...

Awaitless は、このライフサイクルを適応型の単一の実行呼び出しと、単一の結果境界にまとめます。

awaitless run --json --host gpu --artifact results.json -- ./run_benchmark
# quick: {"state":"succeeded","delivery":"inline","exit_code":0,...}
# longer: {"job_id":"job_019F...","state":"running","delivery":"detached",...}

awaitless wait job_019F... --json
# {"state":"succeeded","exit_code":0,"parsed_results":{...}}

デタッチ時の JSON には、job_state、wait_state、delivery_state、コピーしてすぐ使える next_command も含まれます。クライアント側の待機タイムアウトは、ワークロードの失敗を意味しません。直近にデタッチされたジョブには awaitless wait --last --json を使うか、返されたコマンドと安定したジョブ ID を使ってください。ベンチマークの行を大きな末尾ログを読まずに確認するには、awaitless logs <job-id> --grep 'PASS|FAIL|median|CV' を使います。

すべての run は、起動前に永続化されます。インライン待機時間内に完了すれば通常のコマンド結果のように見え、それを超えると待機者だけがデタッチされます。待機を中断したり、MCP クライアントを閉じたり、新しいエージェントセッションを開始したりしても、ジョブの実行は継続し、安定した ID から結果を復旧できます。

名前付きリソースが空くまでジョブをキューに入れる

永続的な FIFO キューを一度作成し、すべてのコマンドをすぐに送信します。

awaitless queue create gpu0 --concurrency 1

awaitless submit --queue gpu0 -- python train_a.py
awaitless submit --queue gpu0 -- python train_b.py
awaitless submit --queue gpu0 -- python train_c.py

最初のコマンドが実行され、残りのコマンドは queued を返します。各コマンドは、空き容量ができると自動的に開始されます。これは、名前付きの希少なリソースに対する永続的なアドミッション制御です。並行実行数は固定で、FIFO 順に処理され、優先順位付けやプリエンプションはありません。Awaitless は、後から到着したジョブのために実行中のジョブを停止することはありません。

運用担当者は、アダプティブ実行をグローバルまたはホストごとにキューへ割り当てることもできます。

[hosts.gpu]
hostname = "gpu.example.com"
queue = "gpu0"

これにより、エージェントはキューを選んだり、事前に GPU を調べたりせずに run を呼び出せます。

このキューは、リソースの検出、GPU トポロジーの把握、デバイスの動的割り当て、リースの発行、または GPU 2 基とメモリ 64 GB のようなリクエストの組み合わせには対応していません。そうした役割には Slurm などのスケジューラーを使用してください。Awaitless は、そのスケジューラーを利用するエージェント向けに、ジョブのライフサイクルを提供します。

次に完了したジョブを受け取る

v0.7 では、クライアント側でカーソルを管理せずに、小規模な並列ジョブのセットを 1 回の呼び出しで消費するための completions ... --drain --json が追加されました。長時間実行するジョブは、wait --progress-interval 30s で構造化されたハートビート更新を出力できます。コマンドが所有するログには --capture-log PATH を、明示的な排他的アドミッションには --resource gpu=0 または --device 0 を使用します。ターミナル結果には、上限付きのログ、診断情報、実行時間、環境、および SHA-256 で識別されるスナップショットが固定されます。

独立した作業は先にすべて送信し、各ジョブ ID を保持したうえで、1 つの永続的な完了境界で待機します。

awaitless completions job_A job_B job_C --json
# {"completions":[...],"next_cursor":"cmp_...","active_job_ids":[...]}

awaitless completions job_A job_B job_C --after cmp_... --json

最初の呼び出しでは、すでに完了した作業があればすぐに返され、なければ選択したジョブが少なくとも 1 つ完了するまでブロックします。バッチを処理してから next_cursor に進んでください。以前のカーソルを再利用すれば、同じ完了 ID を安全に再取得できます。クライアントが終了しても、新しいセッションで保存済みのカーソルから続行できます。Awaitless は続行結果を永続的に利用可能にしますが、エージェントの次の推論ステップを実行することも、常駐型の通知サービスを必要とすることもありません。

v0.8 のエビデンススイートでは、従来の呼び出し回数のデモに代わり、4 つの問いを検証します。エージェントはプロトコルを正しく選択するか、ジョブは重複起動することなく障害を乗り越えるか、Awaitless は実行管理の状態を推論ループの外に保つか、そしてアダプティブな run は短いコマンドでも手軽さを維持するか、です。v0.8 エビデンス計画を参照してください。

v0.8 のエビデンス状況

リリースエビデンスは、モデルとコミットに固有のものです。チェックイン済みのスイートには、以前のバージョンや別のモデルの数値は含まれていません。v0.8 のベンチマークを実行してすべての生データを確認したうえで、モデル、設定ハッシュ、Git コミット、スキップしたワークロード、およびすべての失敗を分母に含む、日付入りのレポートを公開してください。レビュー済みの v0.8 エビデンスレポートには、選別したスコアではなく、完全な生データと分析の要約が含まれています。

30 秒でリカバリーの流れを試す

Linux、Python 3.10 以降、Bash が必要です。永続的にインストールせず、組み込みのデモを実行します。

uvx --from awaitless-runner awaitless demo --json

このデモでは、ローカルジョブを 2 つ送信し、最初の完了待機クライアントを終了してから、新しいクライアントを使い、カーソルで両方の上限付き結果と JSON Artifact を取得します。

通常の CLI 利用の場合：

uv tool install awaitless-runner
awaitless doctor --json

pip install awaitless-runner も使用できます。

コーディングエージェントに導入する

クライアントの設定に stdio MCP サーバーを 1 つ追加します（外側のキーはクライアントに合わせてください）。

{
  "mcpServers": {
    "awaitless": {
      "command": "uvx",
      "args": ["awaitless-runner"]
    }
  }
}

推奨される run ツールは、短時間で完了するコマンドの結果をインラインで返し、時間のかかる作業やキューに入った作業には永続的なハンドルを自動で割り当てます。Tasks に対応するクライアントでは引き続き run_job を使用できます。また、低レベルのクライアントでは submit_job と wait_for_job を引き続き利用できます。同じ client_request_id を指定して負荷の高い送信を再試行しても、ジョブが重複して起動することはありません。並列処理では、MCP Tasks のサポート状況にかかわらず、すべてのクライアントが wait_for_completions を使用できます。ID、ライフサイクル、続行、完了、Artifact、および互換性に関する規範的な契約については、Awaitless Agent Job Protocolを参照してください。

Codex プラグイン

このリポジトリは Codex プラグインでもあります。マニフェストには、Awaitless エージェントスキルと stdio MCP サーバーが含まれており、Codex はこれを uvx 経由で起動します。リポジトリをローカルの Codex マーケットプレイスからインストールし、新しい Codex タスクを開始すると、スキルと MCP ツールがまとめて読み込まれます。

このプラグインには PATH 上の uvx が必要です。初回の MCP 起動時に、まだキャッシュされていない場合は PyPI から awaitless-runner がダウンロードされます。

CLI を直接使う場合、一連の流れは次のとおりです。

awaitless run --json --name tests -- python -m pytest -q
# If delivery is detached, save the returned job_id, then:
awaitless wait <job-id> --json
# Or recover the most recent detached job:
awaitless wait --last --json

1 つのインターフェイスで 3 つの実行環境に対応

バックエンド	Awaitless が提供する機能
ローカル	プロセスグループの永続的な追跡、キャンセル、上限付きログ、名前付きキューのトランザクション処理。
SSH	同じジョブ契約に加え、リモートデーモンなしで対象ホスト上のキューを調整します。
Slurm	実際の sbatch によるスケジューリングに加え、Slurm ID、キュー／アカウンティング状態、終了コード、ログ、キャンセル、アーティファクトを永続的に管理します。

--backend、--host、または構成のデフォルト値を使って対象を切り替えられます。エージェントによるジョブの送信方法や結果の収集方法を変える必要はありません。

シェルや tmux だけでは不十分な理由

ツール	得意な用途	エージェント側で実装が必要なもの
ブロッキングシェル呼び出し	素早い確認や対話型の作業	エンジニアリングコマンドが想定以上に長く実行された場合のライフサイクル管理。
シェルでのポーリング／nohup	基本的なコマンドの実行継続	ID、状態、終了コードの復旧、上限付きログ、キャンセル、重複排除、結果の解析。
tmux	人間が対話型シェル、REPL、TUI からデタッチすること	信頼性の高い非対話型ジョブプロトコルとラッパーの接続処理。
Awaitless	エージェントによるビルド、テスト、ベンチマーク、リモートジョブ、クラスター処理	コマンドと、必要に応じて返却する JSON アーティファクトのみ。

Awaitless は対話型ターミナルや Slurm を置き換えるものではありません。ローカル／SSH マシン上で、コーディングエージェントが永続的な固定並列数のキューを使えるようにし、クラスターのリソーススケジューリングは Slurm に委ねます。

仕組み

flowchart LR
    A["Coding agent"] -->|"run"| B["Awaitless MCP / CLI"]
    B --> C[("SQLite job record")]
    C --> Q["Optional queue admission"]
    Q -->|"capacity available"| D{"Backend"}
    D --> L["Local process"]
    D --> S["SSH host"]
    D --> H["Slurm allocation"]
    L --> I{"Finished inline?"}
    S --> I
    H --> I
    I -->|"yes: result"| A
    I -->|"no: durable handle"| A
    A -. "reconnect with stable ID" .-> C
    C --> E["Durable completion cursor"]
    E -->|"state + exit code + bounded logs + Artifacts"| A

Awaitless デーモン、HTTP サービス、ホスト型サンドボックスはありません。呼び出しのたびに同じ SQLite ストアを開きます。送信されたランナーとスケジューラージョブは、それらを作成した stdio サーバーの終了後も実行を継続します。完全なログはディスクに保持され、エージェントのコンテキストに渡されるのは上限付きの末尾部分のみです。

ドキュメント

• ドキュメント一覧
• 製品の位置付けと進化の原則
• v0.6 適応型実行
• v0.7 不変の完了スナップショット
• v0.5 永続的な完了フィード
• CLI、構成、SSH、Slurm、永続化、アーティファクト、トラブルシューティング
• MCP Tasks プロトコルと互換性
• ベンチマークの定義、方法、解釈
• 実際の MCP → Slurm 切断の証拠
• アーキテクチャと設計の根拠

ライセンス

MIT