hsb-app

HSB アプリケーションランナー

ユーザーが、HSB ボードを接続した開発キット上で Holoscan Sensor Bridge のサンプルアプリケーションを検索、選択、実行したい場合に、このスキルを使用します。

このスキルでは、開発キットのセットアップ（SSH、デモコンテナのビルド、ホストの設定、ボードの接続）が完了していることを前提とします。セットアップが完了していない場合は、まず /hsb-setup を実行するようユーザーに案内してください。

このワークフローでは、デモコンテナ内でアプリケーションを実行します。ユーザーが明示的に呼び出した場合にのみ実行してください。

開始前 — 必須ゲート（以下の順に実行してください）

ゲート 1 — 環境変数を読み取る。 ほかのことをする前に、次の変数を確認し、解決後の値をユーザーに表示してください。

SSH_TARGET      Remote devkit login (e.g. [email protected]). Ask the user if not set.
REMOTE_ROOT     Remote working directory (e.g. /home/nvidia). Ask the user if not set.
REMOTE_SUDO     sudo / sudo -n / "" — default to "sudo" if not set.
REMOTE_SSH_OPTS Additional SSH options (optional).
HSB_PLATFORM    Platform hint (optional).

SSH_TARGET と REMOTE_ROOT は必須です。いずれかが未設定の場合は停止し、ユーザーに値を尋ねてください。

ゲート 2 — フェーズ計画を提示して確認を得る。 何らかの操作を行う前に、次のことを確認してください。

ユーザーのリクエストにプラットフォーム、ボードの種類、センサーがすでに含まれている場合は、あわせて以下を事前に伝えてください。

• examples/ をスキャンし、ユーザーのセンサーの種類とプラットフォームに合うアプリを絞り込みます
• --headless は自動的に追加しません。ユーザーが明示的に要求した場合にのみ追加します
• ユーザーがタイムアウト（例：「60秒のタイムアウト」）を指定した場合、それをウォッチドッグのタイムアウトとして使用します
• アプリケーションは docker run を使ってデモコンテナ内で実行し、Python ベースのサンプルでは python3 を使用します

フェーズ計画を表示してください。

HSB App — Phase Plan
  Phase 0: Verify board connectivity and demo container readiness
  Phase 1: Discover user setup and select application to run
  Phase 2: Run application with monitoring, failure analysis, and iterative debugging
  Phase 3: Generate session report (with option to save)

続けて、明示的に次のように尋ねてください。Shall I proceed with Phase 0? [Y/n] — ユーザーの確認を得るまで、フェーズ 0 を開始しないでください。

ゲート 3 — ファストパスの確認。 ゲート 2 でユーザーの確認を得た後、フェーズ 0 のコマンドを実行する前に、この確認を実行してください。

ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET \
  "grep _SESSION_VERIFIED /tmp/.claude_hsb_app_session/state.sh 2>/dev/null || echo 'no session'"

出力に _SESSION_VERIFIED=true が含まれている場合は、フェーズ 0 とフェーズ 1 のセットアップ確認をスキップし、アプリの選択に直接進んで、その旨をユーザーに伝えてください。

このスキルで行うこと

1. SSH 経由で開発キットに接続できること、HSB ボードが接続され応答すること、デモコンテナが利用可能であることを確認します。現在の FPGA バージョンとボードの識別情報を読み取ります。
2. 開発キット上のリポジトリの場所、HSB ソフトウェアのバージョン、ボードの種類（Lattice など）、接続されているセンサー（デュアル IMX274、VB1940 など）をユーザーに確認し、具体的なセットアップ内容を把握します。その後、リポジトリのユーザーガイドと examples/ ディレクトリをスキャンし、ユーザーのセットアップに対応するアプリケーションの一覧を作成します。一覧を提示し、実行するアプリをユーザーに選んでもらいます。
3. 選択されたアプリケーションをデモコンテナ内で実行し、出力を監視します。アプリが失敗した場合は、ログ出力を分析してデバッグ方法を案内します。コードや環境設定の変更を提案し、アプリを再実行することも含みます。
4. セッションの概要レポートを作成します。発生した問題、適用した修正、結果を記載し、レポートをファイルに保存するかユーザーに確認します。

Linux/Windows 対応のラッパー変数

hsb-setup および hsb-flash スキルと同じ環境変数を再利用してください。

• SSH_TARGET：リモートログイン先（例：nvidia@agx-thor-host）
• REMOTE_ROOT：リモート作業ディレクトリ
• REMOTE_SUDO：特権コマンド用
• REMOTE_SSH_OPTS：追加の SSH オプション
• HSB_PLATFORM：任意のプラットフォームヒント

これらが設定されている場合は、設定内容をユーザーに伝え、改めて質問せずに使用してください。

フェーズ 0 の前に、解決後のリモート実行設定を表示してください。

必須のやり取りパターン

セッションでの初回実行（事前確認なし）

有効なセッション状態が存在しない場合は、フェーズ計画の全体を表示してください。

• フェーズ 0：ボードの接続状態とデモコンテナの準備状況を確認
• フェーズ 1：ユーザーのセットアップを確認し、実行するアプリケーションを選択
• フェーズ 2：アプリケーションを監視しながら実行し、失敗を分析して段階的にデバッグ
• フェーズ 3：セッションレポートを作成（保存するオプションあり）

その後、フェーズを一つずつ実行してください。

同じセッションでの2回目以降の実行（高速パス）

セッション状態ファイル（/tmp/.claude_hsb_app_session/state.sh）が存在し、かつ_SESSION_VERIFIED=trueが含まれている場合、接続とハードウェアの確認はすでに完了しているため、このスキルではPhase 0とPhase 1のセットアップ検出をスキップします。代わりにユーザーにその旨を伝え、アプリの選択に直接進みます。

Session already verified — skipping connectivity checks.
  SSH target: $SSH_TARGET
  Board: HSB Lattice | FPGA: XXXX
  Platform: AGX Thor | HSB version: X.X.X
  Sensors: Dual IMX274

Proceeding directly to application selection.

その後、次を実行します。

• Phase 1のStep 2～3のみ（サンプルをスキャンし、アプリ一覧を提示して、ユーザーがアプリを選択）
• Phase 2：アプリケーションを実行
• Phase 3：セッションレポート

Phase 0を最初から再実行する場合

次の場合は、高速パスを無視してPhase 0を再実行する必要があります。

1. 新しいセッション：リモートホストにセッション状態ファイルが存在しない場合、または新しいClaude Codeセッションが開始された場合。
2. 接続の喪失を示す実行失敗：Phase 2で、ボードまたは開発キットに到達できないことを示す症状（pingの失敗、SSHタイムアウト、コンテナの起動失敗、No such deviceエラー）が発生した場合は、セッション状態から_SESSION_VERIFIEDをクリアし、再試行の前にPhase 0を再実行します。
3. ユーザーから明示的に要求された場合：ユーザーが「再確認」「最初からやり直す」「最初から実行」と言った場合、または/hsb-app --fullを呼び出した場合は、Phase 0を最初から実行します。

完全な確認プロトコルについては、以下の## Phaseゲートを参照してください。

問題が発生した場合、生のログをそのまま出力してはいけません。次の内容を要約してください。

• 失敗した正確なコマンド
• 考えられる根本原因
• 推奨する安全な対処方法
• 問題が実行を妨げているかどうか

Phaseの詳細

Phaseごとの手順については、references/phase-details.mdを参照してください。

実行ルール

SSHヒアドキュメントのパターン

hsb-setupおよびhsb-flashと同じ永続SSHセッションモデルを使用します。各Phaseは、単一のSSHヒアドキュメントブロックとして実行します。

ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET bash -s <<'REMOTE'
set -e

# restore state from previous phase
source /tmp/.claude_hsb_app_session/state.sh 2>/dev/null || true
cd "${_CLAUDE_CWD:-__REMOTE_ROOT__}"

# phase commands
echo "=== Phase N: description ==="
command1
command2

# save state for next phase (preserves _SESSION_VERIFIED if already set)
_PREV_VERIFIED="${_SESSION_VERIFIED:-}"
mkdir -p /tmp/.claude_hsb_app_session
{
  echo "export _CLAUDE_CWD=\"$(pwd)\""
  echo "export PATH=\"$PATH\""
  echo "export REPO_DIR=\"$REPO_DIR\""
  echo "export VERSION=\"$VERSION\""
  echo "export HSB_PLATFORM=\"$HSB_PLATFORM\""
  echo "export BOARD_TYPE=\"$BOARD_TYPE\""
  echo "export SENSORS=\"$SENSORS\""
  echo "export FPGA_VERSION=\"$FPGA_VERSION\""
  echo "export SELECTED_APP=\"$SELECTED_APP\""
  echo "export APP_OPTIONS=\"$APP_OPTIONS\""
  echo "export APP_TIMEOUT=\"$APP_TIMEOUT\""
  [ "$_PREV_VERIFIED" = "true" ] && echo "export _SESSION_VERIFIED=true"
} > /tmp/.claude_hsb_app_session/state.sh
REMOTE

ヒアドキュメントを作成する際は、__REMOTE_ROOT__を$REMOTE_ROOTの値そのもので置き換えます。

アプリケーションでのコンテナの使用

アプリケーションのコマンドはデモ用コンテナ内で実行します。名前付きコンテナを使用したデタッチパターンを使います。

--timeoutを指定するアプリでは、ウォッチドッグパターンを使用します。無期限実行のアプリでは、ログをストリーミングし、ユーザーが停止を要求するまで待機します。

アプリコンテナのクリーンアップ

アプリを実行するたびに、コンテナを停止して削除します。クリーンアップのパターンについては、references/phase-details.mdを参照してください。

セッションの終了処理

Phase 3の後、またはワークフローを停止するエラーが発生した場合：

docker ps --filter "name=hsb_app_" --format '{{.Names}}' | xargs -r docker stop -t 2 2>/dev/null || true
ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET "rm -rf /tmp/.claude_hsb_app_session"

Phaseゲート — Phase間のユーザー確認

各Phase（Phase 0～2）の完了後、次のPhaseを開始する前に必ずユーザーに確認を求めてください。

例外：--y（自動承認モード）が有効な場合、Phaseゲートはスキップされます。「自動承認モード（--y）」のセクションを参照してください。

Proceed to Phase <N+1> (<phase description>)? [Y/n]

ユーザー応答の処理

このスキルでのすべてのプロンプトには、明示的な入力が必要です。空欄やEnterキーだけの入力を選択として扱ってはいけません。代わりにユーザーに再入力を求めてください。

• 「y」、「yes」、「Y」、「ok」、「go」、「continue」、「next」 → 次のPhaseに進みます。
• 「n」、「no」、「stop」、「abort」 → 実行を停止します。次を出力します。

  App workflow paused after Phase N.
  You can resume by re-invoking the skill.
  

  その後、セッションの終了処理を実行します。
• その他のテキスト → 現在のPhaseに関する質問または指示として扱います。回答した後、再度入力を求めます。
• 「retry」 → 現在のPhaseを再実行し、要約を再表示した後、再度入力を求めます。

例外

• Phase 3（セッションレポート）は最終Phaseです。ユーザーが別のアプリの実行を希望しない限り、完了後に確認を求めないでください。レポートを表示し、保存するかどうかを尋ねます。
• Phaseが失敗し、復旧できない場合は、処理を停止して明確に報告します。

組み込みヘルプ（--help）

$ARGUMENTSに--helpまたは-hが含まれている場合、次を出力して停止します。

HSB Application Runner Skill

USAGE
  /hsb-app [OPTIONS]

OPTIONS
  --help, -h        Show this help message and exit
  --verbose         Show full raw command output for every phase
  --y               Auto-approve all phase gates (skip user confirmation
                    between phases). Not recommended — a confirmation
                    warning is shown before proceeding. All output is
                    saved to a timestamped log file.
  --timeout N       Set app runtime in seconds (default: no timeout,
                    app runs until user asks to stop)
  --full            Force full verification from Phase 0, even if the
                    session was already verified

ENVIRONMENT VARIABLES (set before invoking the skill)
  SSH_TARGET        Remote login target (e.g. [email protected])
  REMOTE_ROOT       Remote working directory
  REMOTE_SUDO       Privilege escalation: 'sudo', 'sudo -n', or ''
  REMOTE_SSH_OPTS   Additional SSH options
  HSB_PLATFORM      Platform hint
  HSB_REPO_DIR      Repo directory name under REMOTE_ROOT (default: holoscan-sensor-bridge)
                    Example: HSB_REPO_DIR=hololink → repo at $REMOTE_ROOT/hololink

WORKFLOW PHASES
  Phase 0   Verify board connectivity and demo container readiness
            (skipped on repeat runs in the same session)
  Phase 1   Discover user setup, scan examples, select application
            (setup discovery skipped on repeat runs)
  Phase 2   Run application with monitoring and iterative debugging
  Phase 3   Generate and optionally save session report

EXAMPLES
  /hsb-app
  /hsb-app --verbose
  /hsb-app --timeout 60
  /hsb-app --timeout 30 --verbose
  /hsb-app --y
  /hsb-app --y --timeout 120
  /hsb-app --full
  /hsb-app --help

呼び出し例

• /hsb-app
• /hsb-app --verbose
• /hsb-app --timeout 60
• /hsb-app --timeout 30 --verbose
• /hsb-app --y
• /hsb-app --y --timeout 120
• /hsb-app --full
• /hsb-app --full --verbose
• /hsb-app --help

詳細モード（--verbose）

このスキルは--verboseフラグに対応しています。

フラグの検出

$ARGUMENTS（スラッシュコマンドの後ろのテキスト）に次のいずれかが含まれているかを確認します: --help / -h、--verbose、--y、--timeout N、または --full（大文字と小文字は区別しません）。以降の解析の前に、すべてのフラグ（およびその値）を引数から取り除きます。

--full が存在する場合、キャッシュされたセッション状態を無視して、フェーズ 0 を最初から実行します。

詳細モード（設定時）

• すべての SSH コマンドの生の出力を完全に表示します
• アプリの出力全体をインラインで表示します（すべての stdout/stderr）
• 詳細なフェーズステータスブロックを表示します

簡潔モード（デフォルト、--verbose なし）

• 各フェーズの後に箇条書きの要約を表示します
• コマンドの生の出力は表示しません
• アプリの主要な出力行（起動、エラー、要約）は表示しますが、すべてのフレームログは表示しません
• 問題は 4 行形式（症状、原因、解決策、ブロッキング）で表示します

自動承認モード（--y）

このスキルは --y フラグをサポートしており、すべてのフェーズゲートをスキップし、フェーズ間でユーザーの確認を待たずにワークフロー全体を最初から最後まで実行します。これは通常の使用では推奨されません。

確認の警告

--y が検出されると、警告を表示し、ユーザーに確認を求めます:

⚠  WARNING: Auto-approve mode (--y) is enabled.

This is NOT RECOMMENDED. All phase gates will be skipped and the entire
workflow will run without pausing for your confirmation between phases.

You will not be able to review intermediate results, ask questions, or
abort between phases. All output will be saved to a timestamped log file.

NOTE: In auto-approve mode, the app selection in Phase 1 will still
require your input (you must choose which app to run), but the app will
run with default settings automatically. Debug iterations in Phase 2
will be skipped — the app runs once and the result is reported.

Type 'yes' to confirm auto-approve mode, or anything else to cancel:

• ユーザーが "yes"（完全一致、大文字と小文字は区別しません）で応答した場合 → 自動承認モードを有効にします。
• それ以外の応答の場合 → 自動承認モードをキャンセルし、対話形式で実行します。

--y が有効な場合の動作

1. フェーズ間のフェーズゲートはスキップされます。
2. アプリの選択には引き続きユーザー入力が必要です — ユーザーは実行するアプリを選択する必要があります。
3. デフォルトのアプリ設定が自動的に使用されます — 「デフォルトかカスタマイズか」のプロンプトはスキップされ、アプリはデフォルトのオプションで実行されます。
4. コマンドラインで --timeout が指定されていない場合、タイムアウトはデフォルトで 30 秒になります（無限にハングするのを防ぐため）。
5. デバッグの反復はスキップされます — フェーズ 2 でアプリが失敗した場合、失敗は記録されますが、対話形式のデバッグは行われません。ワークフローは直接レポートに進みます。
6. ログファイル: 開始時に $REMOTE_ROOT/ またはカレントディレクトリに hsb-app-log-YYYY-MM-DD-HHMMSS.md として作成されます。
7. フェーズの要約は引き続きリアルタイムで表示されます。
8. 失敗がブロッキングである場合、ワークフローは引き続き停止します。

他のフラグとの組み合わせ

• --y --verbose: 完全な生の出力で自動承認します。
• --y --timeout N: 固定のアプリ実行時間で自動承認します。
• --y 単独: 簡潔な出力で自動承認し、タイムアウトなし（自動承認モードでは無限にハングするのを防ぐため、アプリはデフォルトで 30 秒間実行されます）。

タイムアウトの処理（--timeout）

このスキルは --timeout N フラグをサポートしており、N はアプリケーションを実行する秒数です。

フラグの検出

$ARGUMENTS 内で --timeout に続く空白区切りの整数を照合します。例: --timeout 60。

動作

• 設定時: アプリは正確に N 秒間実行され、その後 docker stop で停止されます。その間に収集された出力がユーザーに表示されます。
• 未設定時（対話モード）: アプリはユーザーが停止を要求するまで無期限に実行されます。ユーザーには停止を要求する方法が通知されます。
• 未設定時（自動承認モード）: 無限にハングするのを防ぐため、アプリはデフォルトで 30 秒間実行されます。

検証

• N は正の整数である必要があります
• 最小: 5 秒
• 最大: 3600 秒（1 時間）
• 無効な場合は、エラーを表示し、ユーザーに有効なタイムアウトを指定するよう求めます