hsb-app

What this skill does

# HSB Application Runner

Use this skill when the user wants to discover, select, and run Holoscan Sensor Bridge example applications on a devkit with a connected HSB board.

This skill assumes the devkit is already set up (SSH, demo container built, host configured, board connected). If setup is not complete, instruct the user to run `/hsb-setup` first.

This workflow runs applications inside the demo container. Only run it when the user explicitly invokes it.

## Before you start — required gates (do these first, in order)

**Gate 1 — Read environment variables.** Before doing anything else, check these variables and print their resolved values to the user:

```
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 and REMOTE_ROOT are required. Stop and ask the user for them if either is missing.**

**Gate 2 — Present the phase plan and get confirmation.** Before taking any action:

If the user's request already includes platform, board type, and sensors, also state upfront:
- You will scan `examples/` and filter apps by the user's sensor type and platform
- You will NOT add `--headless` automatically — only if the user explicitly requests it
- If the user specified a timeout (e.g., "60-second timeout"), state you will use that as the watchdog timeout
- Applications run inside the demo container via `docker run`, using `python3` for Python-based examples

Show the phase plan:

```
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)
```

Then ask explicitly: `Shall I proceed with Phase 0? [Y/n]` — do not start Phase 0 until the user confirms.

**Gate 3 — Fast path check.** After the user confirms in Gate 2, run this check before executing any Phase 0 commands:

```bash
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'"
```

If the output contains `_SESSION_VERIFIED=true`, skip Phase 0 and Phase 1 setup discovery — go directly to app selection and inform the user.

## What this skill must do

1. Verify that the devkit is reachable over SSH, the HSB board is connected and responsive, and the demo container is available. Read the current FPGA version and board identity.
2. Interact with the user to understand their specific setup — repo location on the devkit, HSB software version, board type (Lattice, etc.), and connected sensors (e.g., dual IMX274, VB1940). Then scan the repository's user guide and `examples/` directory to build a list of applications compatible with the user's setup. Present the list and let the user choose an app to run.
3. Run the selected application inside the demo container, monitor output, and if the app fails, analyze the log output and guide the user through debugging — including suggesting code or environment edits and re-running the app.
4. Produce a summary report of the session — issues encountered, fixes applied, and outcome. Offer to save the report to a file.

## Linux/Windows-friendly wrapper variables

Reuse the same environment variables from the `hsb-setup` and `hsb-flash` skills:

- `SSH_TARGET` for the remote login target (e.g. `nvidia@agx-thor-host`)
- `REMOTE_ROOT` for the remote working directory
- `REMOTE_SUDO` for privileged commands
- `REMOTE_SSH_OPTS` for additional SSH options
- `HSB_PLATFORM` as an optional platform hint

If these are set, notify the user of these settings and use them without re-asking.

Before Phase 0, print the resolved remote execution settings.

## Mandatory interaction pattern

### First run in a session (no prior verification)

When no valid session state exists, show the full 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)

Then execute one phase at a time.

### Subsequent runs in the same session (fast path)

When the session state file (`/tmp/.claude_hsb_app_session/state.sh`) exists **and** contains `_SESSION_VERIFIED=true`, the skill skips Phase 0 and Phase 1 setup discovery because connectivity and hardware were already verified. Instead, inform the user and jump directly to app selection:

```
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.
```

Then execute:
- Phase 1 Steps 2–3 only (scan examples, present app list, user selects app)
- Phase 2: Run application
- Phase 3: Session report

### When to re-run Phase 0 from the beginning

Phase 0 must be re-run (ignoring the fast path) when:

1. **New session**: No session state file exists on the remote host, or a new Claude Code session is started.
2. **Execution failure suggesting connectivity loss**: If Phase 2 fails with symptoms indicating the board or devkit is unreachable (ping failure, SSH timeout, container launch failure, `No such device` errors), clear `_SESSION_VERIFIED` from the session state and re-run Phase 0 before retrying.
3. **User explicitly requests it**: If the user says "re-verify", "start over", "run from the beginning", or invokes `/hsb-app --full`, run Phase 0 from scratch.

See [## Phase gate](#phase-gate--user-confirmation-between-phases) below for the full confirmation protocol.

If something fails, do **not** just dump raw logs. Summarize:

- the exact command that failed
- the likely root cause
- what safe action you recommend
- whether the issue is blocking

## Phase details

See [references/phase-details.md](references/phase-details.md) for full step-by-step phase instructions.

## Execution rules

### SSH heredoc pattern

Use the same persistent SSH session model as `hsb-setup` and `hsb-flash`. Each phase runs as a single SSH heredoc block:

```bash
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
```

Replace `__REMOTE_ROOT__` with the literal value of `$REMOTE_ROOT` when composing the heredoc.

### Container usage for applications

Application commands run inside the demo container. Use the detached pattern with a named container.

For apps with `--timeout`, use the watchdog pattern. For indefinite-run apps, stream logs and wait for the user to request a stop.

### Cleanup after app containers

After every app run, stop and remove the container. See [references/phase-details.md](references/phase-detail