HSB Application Runner

Utilise cette skill quand l'utilisateur souhaite découvrir, sélectionner et exécuter des applications d'exemple Holoscan Sensor Bridge sur un devkit avec une carte HSB connectée.

Cette skill suppose que le devkit est déjà configuré (SSH, conteneur de démonstration construit, hôte configuré, carte connectée). Si la configuration n'est pas terminée, demandez à l'utilisateur d'exécuter /hsb-setup d'abord.

Ce workflow exécute les applications à l'intérieur du conteneur de démonstration. Ne l'exécutez que lorsque l'utilisateur l'invoque explicitement.

Avant de commencer — portes requises (faites ceci en premier, dans l'ordre)

Porte 1 — Lire les variables d'environnement. Avant toute chose, vérifiez ces variables et affichez leurs valeurs résolues à l'utilisateur :

SSH_TARGET      Connexion au devkit distant (p. ex. nvidia@192.168.1.50). Demandez à l'utilisateur si non défini.
REMOTE_ROOT     Répertoire de travail distant (p. ex. /home/nvidia). Demandez à l'utilisateur si non défini.
REMOTE_SUDO     sudo / sudo -n / "" — utiliser « sudo » par défaut si non défini.
REMOTE_SSH_OPTS Options SSH supplémentaires (optionnel).
HSB_PLATFORM    Indice de plateforme (optionnel).

SSH_TARGET et REMOTE_ROOT sont obligatoires. Arrêtez et demandez-les à l'utilisateur s'ils manquent.

Porte 2 — Présenter le plan de phase et obtenir la confirmation. Avant d'effectuer une action :

Si la requête de l'utilisateur inclut déjà la plateforme, le type de carte et les capteurs, indiquez d'avance aussi :

• Vous analyserez examples/ et filtrerez les applications par type de capteur et plateforme de l'utilisateur
• Vous n'ajouterez PAS automatiquement --headless — seulement si l'utilisateur le demande explicitement
• Si l'utilisateur a spécifié un délai d'expiration (p. ex., « délai d'expiration de 60 secondes »), indiquez que vous l'utiliserez comme délai de surveillance
• Les applications s'exécutent à l'intérieur du conteneur de démonstration via docker run, en utilisant python3 pour les exemples basés sur Python

Affichez le plan de phase :

HSB App — Plan de phase
  Phase 0 : Vérifier la connectivité de la carte et la disponibilité du conteneur de démonstration
  Phase 1 : Découvrir la configuration de l'utilisateur et sélectionner l'application à exécuter
  Phase 2 : Exécuter l'application avec surveillance, analyse des défaillances et débogage itératif
  Phase 3 : Générer un rapport de session (avec option d'enregistrement)

Demandez ensuite explicitement : Dois-je procéder à la Phase 0 ? [O/n] — ne démarrez pas la Phase 0 avant que l'utilisateur confirme.

Porte 3 — Vérification du chemin rapide. Une fois que l'utilisateur a confirmé à la Porte 2, exécutez cette vérification avant d'exécuter les commandes de la Phase 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'"

Si la sortie contient _SESSION_VERIFIED=true, sautez la découverte de configuration des Phases 0 et 1 — allez directement à la sélection d'application et informez l'utilisateur.

Ce que cette skill doit faire

1. Vérifier que le devkit est accessible via SSH, que la carte HSB est connectée et réactive, et que le conteneur de démonstration est disponible. Lire la version FPGA actuelle et l'identité de la carte.
2. Interagir avec l'utilisateur pour comprendre sa configuration spécifique — emplacement du référentiel sur le devkit, version du logiciel HSB, type de carte (Lattice, etc.) et capteurs connectés (p. ex., dual IMX274, VB1940). Ensuite, analyser le guide de l'utilisateur du référentiel et le répertoire examples/ pour construire une liste d'applications compatibles avec la configuration de l'utilisateur. Présenter la liste et laisser l'utilisateur choisir une application à exécuter.
3. Exécuter l'application sélectionnée à l'intérieur du conteneur de démonstration, surveiller la sortie, et si l'application échoue, analyser la sortie du journal et guider l'utilisateur à travers le débogage — y compris la suggestion de modifications de code ou d'environnement et la réexécution de l'application.
4. Produire un rapport récapitulatif de la session — problèmes rencontrés, corrections appliquées et résultat. Proposer d'enregistrer le rapport dans un fichier.

Variables de wrapper compatibles Linux/Windows

Réutilisez les mêmes variables d'environnement des skills hsb-setup et hsb-flash :

• SSH_TARGET pour la cible de connexion distante (p. ex. nvidia@agx-thor-host)
• REMOTE_ROOT pour le répertoire de travail distant
• REMOTE_SUDO pour les commandes privilégiées
• REMOTE_SSH_OPTS pour les options SSH supplémentaires
• HSB_PLATFORM comme indice de plateforme optionnel

Si ces éléments sont définis, notifiez l'utilisateur de ces paramètres et utilisez-les sans poser à nouveau la question.

Avant la Phase 0, affichez les paramètres d'exécution distante résolus.

Motif d'interaction obligatoire

Première exécution dans une session (aucune vérification antérieure)

Quand aucun état de session valide n'existe, affichez le plan de phase complet :

• Phase 0 : Vérifier la connectivité de la carte et la disponibilité du conteneur de démonstration
• Phase 1 : Découvrir la configuration de l'utilisateur et sélectionner l'application à exécuter
• Phase 2 : Exécuter l'application avec surveillance, analyse des défaillances et débogage itératif
• Phase 3 : Générer un rapport de session (avec option d'enregistrement)

Exécutez ensuite une phase à la fois.

Exécutions ultérieures dans la même session (chemin rapide)

Quand le fichier d'état de session (/tmp/.claude_hsb_app_session/state.sh) existe et contient _SESSION_VERIFIED=true, la skill saute la découverte de configuration des Phases 0 et 1 car la connectivité et le matériel ont déjà été vérifiés. À la place, informez l'utilisateur et allez directement à la sélection d'application :

Session déjà vérifiée — vérifications de connectivité ignorées.
  Cible SSH : $SSH_TARGET
  Carte : HSB Lattice | FPGA : XXXX
  Plateforme : AGX Thor | Version HSB : X.X.X
  Capteurs : Dual IMX274

Passage direct à la sélection d'application.

Exécutez ensuite :

• Étapes 2–3 de la Phase 1 uniquement (analyser les exemples, présenter la liste d'applications, l'utilisateur sélectionne une application)
• Phase 2 : Exécuter l'application
• Phase 3 : Rapport de session

Quand réexécuter la Phase 0 depuis le début

La Phase 0 doit être réexécutée (en ignorant le chemin rapide) quand :

1. Nouvelle session : Aucun fichier d'état de session n'existe sur l'hôte distant, ou une nouvelle session Claude Code est démarrée.
2. Défaillance d'exécution suggérant une perte de connectivité : Si la Phase 2 échoue avec des symptômes indiquant que la carte ou le devkit est inaccessible (défaillance ping, délai d'expiration SSH, défaillance du lancement du conteneur, erreurs No such device), effacez _SESSION_VERIFIED de l'état de session et réexécutez la Phase 0 avant de réessayer.
3. L'utilisateur le demande explicitement : Si l'utilisateur dit « re-verify », « start over », « run from the beginning », ou invoque /hsb-app --full, exécutez la Phase 0 depuis le début.

Voir ## Phase gate ci-dessous pour le protocole de confirmation complet.

Si quelque chose échoue, ne videz pas simplement les journaux bruts. Résumez :

• la commande exacte qui a échoué
• la cause racine probable
• quelle action sûre vous recommandez
• si le problème bloque

Détails des phases

Voir references/phase-details.md pour les instructions étape par étape complètes des phases.

Règles d'exécution

Motif heredoc SSH

Utilisez le même modèle de session SSH persistante que hsb-setup et hsb-flash. Chaque phase s'exécute en tant que bloc heredoc SSH unique :

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

# restaurer l'état de la phase précédente
source /tmp/.claude_hsb_app_session/state.sh 2>/dev/null || true
cd "${_CLAUDE_CWD:-__REMOTE_ROOT__}"

# commandes de phase
echo "=== Phase N : description ==="
command1
command2

# enregistrer l'état pour la phase suivante (préserve _SESSION_VERIFIED s'il est déjà défini)
_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

Remplacez __REMOTE_ROOT__ par la valeur littérale de $REMOTE_ROOT lors de la composition du heredoc.

Utilisation du conteneur pour les applications

Les commandes d'application s'exécutent à l'intérieur du conteneur de démonstration. Utilisez le motif détaché avec un conteneur nommé.

Pour les applications avec --timeout, utilisez le motif de surveillance. Pour les applications à exécution indéfinie, diffusez les journaux et attendez que l'utilisateur demande un arrêt.

Nettoyage après les conteneurs d'application

Après chaque exécution d'application, arrêtez et supprimez le conteneur. Voir references/phase-details.md pour le motif de nettoyage.

Arrêt de session

Après la Phase 3 (ou en cas de défaillance qui arrête le workflow) :

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 gate — confirmation de l'utilisateur entre les phases

Après avoir complété chaque phase (Phases 0–2), demandez toujours à l'utilisateur une confirmation avant de démarrer la phase suivante.

Exception : Quand le mode --y (auto-approbation) est actif, les portes de phase sont ignorées. Voir la section « Mode auto-approbation (--y) ».

Procéder à la Phase <N+1> (<description de phase>) ? [O/n]

Gestion des réponses de l'utilisateur

Tous les invites de cette skill nécessitent des réponses explicitement tapées. Ne traitez jamais une entrée vide ou un appui sur Entrée uniquement comme une sélection — posez à nouveau la question à l'utilisateur à la place.

• « o », « oui », « O », « ok », « go », « continue », « next » → procéder à la phase suivante.
• « n », « non », « stop », « abort » → arrêter l'exécution. Affichez :

  Workflow d'application suspendu après la Phase N.
  Vous pouvez reprendre en invoquant à nouveau la skill.

  Exécutez ensuite l'arrêt de session.

• Tout autre texte → traiter comme une question ou une instruction relative à la phase actuelle. Répondez-y, puis posez à nouveau la question.
• « retry » → réexécuter la phase actuelle, afficher le résumé à nouveau, puis reposer la question.

Exceptions

• Phase 3 (rapport de session) est la phase finale — ne posez pas de question après, sauf si l'utilisateur souhaite exécuter une autre application. Affichez le rapport et proposez d'enregistrer.
• Si une phase ÉCHOUE et ne peut pas être récupérée, arrêtez et signalez clairement.

Aide intégrée (--help)

Si $ARGUMENTS contient --help ou -h, affichez ce qui suit et arrêtez :

HSB Application Runner Skill

UTILISATION
  /hsb-app [OPTIONS]

OPTIONS
  --help, -h        Afficher ce message d'aide et quitter
  --verbose         Afficher la sortie brute complète de chaque phase
  --y               Auto-approuver toutes les portes de phase (ignorer la confirmation
                    de l'utilisateur entre les phases). Non recommandé — un avertissement
                    de confirmation est affiché avant de continuer. Toute la sortie est
                    enregistrée dans un fichier journal horodaté.
  --timeout N       Définir la durée d'exécution de l'application en secondes (par défaut :
                    pas de délai d'expiration, l'application s'exécute jusqu'à ce que
                    l'utilisateur demande l'arrêt)
  --full            Forcer la vérification complète à partir de la Phase 0, même si la
                    session a déjà été vérifiée

VARIABLES D'ENVIRONNEMENT (à définir avant d'invoquer la skill)
  SSH_TARGET        Cible de connexion distante (p. ex. ubuntu@10.0.0.1)
  REMOTE_ROOT       Répertoire de travail distant
  REMOTE_SUDO       Escalade de privilèges : « sudo », « sudo -n » ou « »
  REMOTE_SSH_OPTS   Options SSH supplémentaires
  HSB_PLATFORM      Indice de plateforme
  HSB_REPO_DIR      Nom du répertoire du référentiel sous REMOTE_ROOT (par défaut :
                    holoscan-sensor-bridge)
                    Exemple : HSB_REPO_DIR=hololink → référentiel à
                    $REMOTE_ROOT/hololink

PHASES DU WORKFLOW
  Phase 0   Vérifier la connectivité de la carte et la disponibilité du conteneur
            de démonstration (ignorée lors des exécutions ultérieures dans la
            même session)
  Phase 1   Découvrir la configuration de l'utilisateur, analyser les exemples,
            sélectionner une application (découverte de la configuration ignorée
            lors des exécutions ultérieures)
  Phase 2   Exécuter l'application avec surveillance et débogage itératif
  Phase 3   Générer et enregistrer optionnellement le rapport de session

EXEMPLES
  /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

Exemples d'invocation

• /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

Mode verbosité (--verbose)

La skill supporte un drapeau --verbose :

Détection du drapeau

Vérifiez si $ARGUMENTS (le texte après la commande barre oblique) contient l'un des éléments suivants : --help / -h, --verbose, --y, --timeout N, ou --full (insensible à la casse). Supprimez tous les drapeaux (et leurs valeurs) des arguments avant tout traitement ultérieur.

Quand --full est présent, ignorez tout état de session en cache et exécutez la Phase 0 depuis le début.

Mode verbosité (quand activé)

• Afficher la sortie brute complète de chaque commande SSH
• Afficher la sortie d'application complète en ligne (tout stdout/stderr)
• Afficher les blocs d'état de phase détaillés

Mode concis (par défaut, sans --verbose)

• Afficher des résumés en points de balle après chaque phase
• Supprimer la sortie brute des commandes
• Afficher les lignes clés de la sortie d'application (démarrage, erreurs, résumé) mais pas chaque journal d'image
• Afficher les problèmes avec le format de 4 lignes (Symptôme, Cause, Résolution, Bloquant)

Mode auto-approbation (--y)

La skill supporte un drapeau --y qui ignore toutes les portes de phase et exécute le flux de travail complet du début à la fin sans attendre la confirmation de l'utilisateur entre les phases. Cela n'est pas recommandé pour une utilisation normale.

Avertissement de confirmation

Quand --y est détecté, affichez un avertissement et demandez à l'utilisateur de confirmer :

⚠  AVERTISSEMENT : Le mode auto-approbation (--y) est activé.

Ceci n'est PAS RECOMMANDÉ. Toutes les portes de phase seront ignorées et le flux
de travail complet s'exécutera sans pause pour votre confirmation entre les phases.

Vous ne pourrez pas examiner les résultats intermédiaires, poser de questions ou
interrompre entre les phases. Toute la sortie sera enregistrée dans un fichier
journal horodaté.

REMARQUE : En mode auto-approbation, la sélection d'application dans la Phase 1
nécessitera toujours votre entrée (vous devez choisir quelle application exécuter),
mais l'application s'exécutera avec les paramètres par défaut automatiquement. Les
itérations de débogage dans la Phase 2 seront ignorées — l'application s'exécute
une fois et le résultat est signalé.

Tapez « yes » pour confirmer le mode auto-approbation, ou n'importe quoi d'autre
pour annuler :

• Si l'utilisateur répond avec « yes » (correspondance exacte, insensible à la casse) → activer le mode auto-approbation.
• Toute autre réponse → annuler le mode auto-approbation et exécuter de façon interactive.

Comportement quand --y est actif

1. Les portes de phase sont ignorées entre les phases.
2. La sélection d'application nécessite toujours l'entrée de l'utilisateur — l'utilisateur doit choisir quelle application exécuter.
3. Les paramètres d'application par défaut sont utilisés automatiquement — l'invite « valeurs par défaut vs. personnaliser » est ignorée et l'application s'exécute avec ses options par défaut.
4. Le délai d'expiration par défaut est 30 secondes si aucun --timeout n'a été spécifié sur la ligne de commande (pour éviter les blocages indéfinis).
5. Les itérations de débogage sont ignorées — si l'application échoue dans la Phase 2, l'échec est enregistré mais aucun débogage interactif n'est effectué. Le flux de travail se poursuit directement vers le rapport.
6. Fichier journal : Créé au démarrage en tant que hsb-app-log-YYYY-MM-DD-HHMMSS.md dans $REMOTE_ROOT/ ou le répertoire courant.
7. Les résumés de phase sont toujours affichés en temps réel.
8. Les défaillances arrêtent toujours le flux de travail si elles sont bloquantes.

Combinaison avec d'autres drapeaux

• --y --verbose : Auto-approbation avec sortie brute complète.
• --y --timeout N : Auto-approbation avec une durée d'exécution d'application fixe.
• --y seul : Auto-approbation avec sortie concise et pas de délai d'expiration (l'application s'exécute pendant 30 secondes par défaut en mode auto-approbation pour éviter les blocages indéfinis).

Gestion du délai d'expiration (--timeout)

La skill supporte un drapeau --timeout N où N est le nombre de secondes pour exécuter l'application.

Détection du drapeau

Correspondre --timeout suivi d'un entier séparé par un espace dans $ARGUMENTS. Exemple : --timeout 60.

Comportement

• Quand défini : L'application s'exécute pendant exactement N secondes, puis est arrêtée via docker stop. La sortie collectée pendant cette fenêtre est affichée à l'utilisateur.
• Quand non défini (mode interactif) : L'application s'exécute indéfiniment jusqu'à ce que l'utilisateur demande l'arrêt. L'utilisateur est informé de comment demander un arrêt.
• Quand non défini (mode auto-approbation) : L'application s'exécute pendant 30 secondes par défaut pour éviter les blocages indéfinis.

Validation

• N doit être un entier positif
• Minimum : 5 secondes
• Maximum : 3600 secondes (1 heure)
• Si invalide, affichez une erreur et demandez à l'utilisateur de fournir un délai d'expiration valide