agent-shell

Agent Shell

エージェントセッションでバックグラウンドのシェルを実行します。長時間かかるコマンドのためにターンを開いたままにする代わりに、agent-shell run でコマンドを開始し、応答を終了します。コマンドは分離されたスーパーバイザーの下で実行を続けます。実行中は、最後の出力行とともに2分ごとに進捗通知ターンがセッションに届き、終了時にはジョブ名と終了コードを知らせる完了通知ターンが1回届きます。出力は agent-shell show で読み取ります。muse メンバーは常に muse --yolo で実行されるため、承認を求めるプロンプトは表示されません。

以下の用語を全体で使用します。

• ジョブは、バックグラウンドで実行する1つのコマンドです。その id（sh-1234-5678 など）がジョブを指定する唯一の確実な方法です。name（build など）は、人間が使う短いラベルです。
• 進捗ターンは、ジョブの実行中に2分ごとにセッションへ届くメッセージです。shell job '<name>' still running (<elapsed> elapsed). Last line: ... の形式で、シェルが停止しているのか、作業中なのかを知らせます。操作は不要です。
• 完了ターンは、ジョブの終了時にセッションへ届く1回のメッセージです。shell job '<name>' done (exit <code>, <time>). Read with: agent-shell show <id> の形式で、出力全体は含まれません。

すべての操作には、PATH 上のグローバルバイナリである agent-shell コマンドを使用します。初めて実行する前に、agent-shell --version を実行してください。失敗した場合は、停止してユーザーに agent-shell CLI がインストールされていないことを伝えてください。curl -fsSL https://raw.githubusercontent.com/bdsanxz/agent-shell/main/install.sh | sh を実行すると ~/.local/bin/agent-shell にインストールされます。また、PATH 上に Bun が必要です。自分でインストールしてはいけません。次に agent-shell --help を実行し、続いて必要なコマンドについて agent-shell <command> --help を実行して、引数、デフォルト値、出力、終了コードを確認してください。ヘルプの実行では、ほかの処理は行われません。

運用ルール（必ず遵守）

1. タスクと待機を分けます。 コマンド全体、実行ディレクトリ、期待する出力を run の行に記述してください。ジョブに継続的な作業はなく、完了ターンでは終了したことだけが通知されます。
2. スリープやポーリングで待ってはいけません。 ジョブを開始したら、通常どおり応答を終了してください。進捗通知と完了通知は通常のターンとして届きます。ジョブが実行中でも失敗ではありません。sleep を呼び出したり、agent-shell list や agent-shell show をループで実行したり、シェルをブロックしたままにしたりしてはいけません。
3. 実行したら任せて、戻りを待ちます。 run はジョブ ID をすぐに返し、ブロックしません。--wait のようなオプションを渡してはいけません。また、ジョブの実行中にログを追跡してはいけません。
4. 完了通知を受けてから、1回だけ読み取ります。 進捗通知への対応は不要です。最後の出力行が表示されるだけです。完了通知でジョブが通知されたら、agent-shell show <id> で読み取ってください。その結果をもとに新しい作業を始めない限り、再度読み取ってはいけません。

ステップ1：自分が誰かを確認する

呼び出し元のコンテキストを出力し、通知先を確認します。

printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"

通知先は自分のペイン ID（$HERDR_PANE_ID）、または旧 herdr の外で実行している場合は herdr-core ターミナル（$HC_TERMINAL_ID）です。run はデフォルトでこれを使用するため、通知ターンは herdr agent prompt（または hc send）を通じてこのセッションに届きます。ユーザーが別のメンバー（herdr エージェント名、ペイン ID、hc ターミナル）を通知先に指定した場合は、--notify <target> で渡してください。どちらにも該当しない場合（HERDR_PANE_ID と HC_TERMINAL_ID の両方がない場合）もジョブは実行されますが、通知はスキップされます。その旨を伝え、ジョブの結果を明示的に読み取ってください。

ステップ 2：ジョブを開始する

agent-shell run --name build -- bun test
agent-shell run --notify framesmith-lead --cwd /path/to/dir -- sh -c 'sleep 30; echo done'
agent-shell run --name e2e --heartbeat 5m -- sh -c './scripts/e2e.sh'
agent-shell run --name quick --no-heartbeat -- sh -c './scripts/fast.sh'

コマンドは -- の後に指定します。パイプ、リダイレクト、&& などのシェル機能を使う場合は、sh -c '...' を使用してください。短いケバブケースの --name（build、test-e2e など）を指定し、コマンドを別の場所で実行する必要がある場合は --cwd も指定してください。デフォルトでは、各ジョブは 2 分ごとに最後の出力行を含む進捗ターンを送信するため、停止しているのか作業中なのかを判断できます。--heartbeat <duration>（最小値は 1s。例：30s、5m）で間隔を変更でき、--no-heartbeat で進捗ターンを無効にすると、完了ターンのみになります。出力には、ジョブ ID、通知先、ハートビートの設定、読み取りコマンドが表示されます。短時間で終わるコマンドの場合は、--wait <duration>（例：5s）を指定すると、ターンを終了せずに完了を待ち、出力と終了ステータスをその場で表示できます。そこでターンを終了してください。

ステップ 3：結果を読む

ジョブの実行中は 2 分ごとに進捗ターンが届きますが、対応は不要です。最後の行が更新されていれば作業中、変化がなければ停止している可能性があります。完了ターンは自動的に届きます。結果を使う前に、ジョブを一度確認してください。

agent-shell check <id>
agent-shell show <id>

check は各項目について、完了状態、記録された終了コード、読み取り可能な出力、通知の配信状況を示す ok または FAIL の行と、check <id>: 4/4 pass のサマリーを表示します。4 項目すべてに合格した場合にのみ、終了コード 0 で終了します。強制終了されたジョブはチェックに失敗します（出力が途中までで、通知もありません）。実行中のジョブは終了コード 2 で終了します。チェックに合格したら、show（状態、終了コード、通知の詳細、出力の末尾を表示）または tail で出力を読み取ってください。次のターンでその結果に対応します。失敗を報告する、修正する、または結果が必要だった作業を続けてください。

ステップ 4：ジョブを管理する

agent-shell list             # running first, then newest done
agent-shell kill <id>        # stop a running job; a killed job gets no notify
agent-shell clean            # remove finished jobs
agent-shell clean --older-than 7d

強制終了されたジョブの途中までの出力は引き続き読み取れますが、完了通知は届きません。show はハートビートの設定（heartbeat 120000ms または heartbeat off）と、進捗が送信済みの場合はその回数を表示します。clean は実行中のジョブには一切触れません。