77 lines
5.0 KiB
YAML
77 lines
5.0 KiB
YAML
name: ssh-console
|
|
description: |
|
|
AI と人間が共有する SSH コンソール。タスクに 1 つの PTY セッションを開き、
|
|
両者がコマンドを打ち、出力を見られる。長時間の対話作業、TUI が必要な
|
|
操作 (vim/top/less/tmux 等)、複数ラウンドの調査に向く。
|
|
|
|
選ぶべき場合: 「リモートサーバーで色々確認したい」「ログを tail しながら作業」
|
|
「対話的に shell を触りたい」
|
|
選ぶべきでない場合: 1 コマンドの単発実行 (ssh-ops piece が適切)、ファイル転送だけ
|
|
|
|
事前条件:
|
|
- admin が config.yaml で ssh.enabled: true / ssh.console.enabled: true を設定済み
|
|
- 利用する SSH 接続が登録され、TOFU host key 検証が完了している
|
|
- ジョブ owner に接続への grant がある
|
|
triggers:
|
|
keywords: ["対話", "shell", "console", "ターミナル", "tmux", "vim", "tail", "対話的"]
|
|
max_movements: 80
|
|
initial_movement: interact
|
|
|
|
movements:
|
|
- name: interact
|
|
edit: true
|
|
persona: ops-operator
|
|
instruction: |
|
|
## 詳細ドキュメント (必ず最初に読む)
|
|
ReadToolDoc({name: "SshConsoleEnsure"}) で 3 ツール (Ensure / Send / Snapshot) の
|
|
完全な仕様と典型 flow が見られる。引数と return shape、TUI 操作のコツ、エラー
|
|
コードのリカバリ手順まで網羅。alias なので SshConsoleSend / SshConsoleSnapshot
|
|
でも同じ doc が返る。SshListConnections は ReadToolDoc({name: "SshListConnections"})。
|
|
|
|
## 標準 flow
|
|
1. タスク本文を読み、どのリモートホストでどんな作業をするか把握する
|
|
2. connection_id (UUID) がタスク本文に無ければ SshListConnections({}) で発見する
|
|
- **必ず id フィールドを使う**。label ("terminal" など) や host ("192.168.1.x" など) を connection_id として渡してはいけない
|
|
- UUID を覚えていないからといって**勝手に UUID をでっち上げない** — 必ず SshListConnections で確認する
|
|
3. SshConsoleEnsure({connection_id}) でセッションを開く (冪等)
|
|
4. SshConsoleSend / SshConsoleSnapshot を呼ぶ
|
|
- **2 回目以降の呼び出しでは connection_id を省略するのが推奨** (active session が自動採用される)
|
|
- ジョブ間で UUID を覚え直す必要がなくなる
|
|
|
|
## 使い方の要点
|
|
- 1 行コマンド: SshConsoleSend({input: "ls -la\n"}) — connection_id は省略
|
|
- 連続入力 (heredoc / 複数行 stdin): input に \n 含めて送る
|
|
- TUI に入る: SshConsoleSend({input: "vim test.txt\n", wait_ms: 1000}) → SshConsoleSnapshot で画面確認
|
|
- control 文字: \x03 Ctrl-C / \x04 Ctrl-D / \x1b Esc / \t Tab を input にそのまま含めて送れる
|
|
- vim 抜ける: SshConsoleSend({input: "\x1b:q!\n"})
|
|
|
|
## エラーリカバリ
|
|
- "this task already has an active session on connection X" → 表示されている X を connection_id に使う (or 省略する)。
|
|
本当に別接続に切り替えたいときだけ SshConsoleEnsure({connection_id, force_replace: true})
|
|
- "this task has an active session on connection X, not Y" → 同上 (Send/Snapshot 側のエラー)
|
|
- "no live session for this task" → 初回 ensure が必要。SshConsoleEnsure({connection_id}) を呼ぶ
|
|
|
|
## ファイル転送 (SFTP, PTY とは独立)
|
|
- 設定ファイルを置いて反映したい / リモートのログや成果物を手元で解析したい場合は
|
|
SshUpload / SshDownload を使う。これらは SFTP 経路で動き、active console session
|
|
とは別チャンネルなので PTY を閉じる必要はない (転送後に SshConsoleSend で
|
|
リロードコマンドを送ればよい)
|
|
- リモートパスは接続の remote_path_prefix 配下のみ。ローカルパスは workspace の
|
|
output/ または input/ 配下を使う。詳細・エラーコードは ReadToolDoc({name: "SshUpload"})
|
|
/ ReadToolDoc({name: "SshDownload"})
|
|
|
|
## 注意
|
|
- shell 状態 (cd / env / foreground プロセス) はタスク内で維持される。毎ターン cd し直す必要なし
|
|
- 機密値はコマンド文字列に直接書かない (audit log に hash で残る)
|
|
- 大量出力で screen_after が切れた場合は SshConsoleSnapshot({kind: "scrollback"}) で全文取得
|
|
- command_rejected が出たら admin に許可パターン追加を相談する (ローカルで回避してはいけない)
|
|
|
|
## 終了
|
|
- 完了: complete({status: "success", result: "..."})
|
|
- 中断: complete({status: "aborted", abort_reason: "..."})
|
|
- 確認待ち: complete({status: "needs_user_input", missing_info: "..."})
|
|
allowed_tools: [SshConsoleEnsure, SshConsoleSend, SshConsoleSnapshot, SshUpload, SshDownload, SshListConnections, Read, Write, Bash, Glob, Grep]
|
|
allowed_ssh_connections: ['*']
|
|
default_next: COMPLETE
|
|
rules: []
|