Issue Sessions

Une issue session est un processus de scan piloté par l’IA qui analyse votre codebase et découvre automatiquement des problèmes, des bugs, des améliorations et des tâches. La session s’exécute dans une sandbox cloud, donnant à l’agent IA un accès complet au code de votre repository, et produit une liste JSON structurée d’issues qui sont importées dans CodeCourier pour le suivi et la résolution. En plus des issues, les sessions génèrent des questions et des hypothèses - des artefacts structurés qui capturent ce dont l’agent n’était pas certain pendant le scan et ce qu’il a supposé en l’absence de directives explicites.

Qu’est-ce qu’une Issue Session ?

Imaginez une issue session comme une revue de code automatisée avec un focus spécifique. Vous fournissez un prompt de découverte - par exemple, “scanne les vulnérabilités de sécurité et les problèmes de performance” - et CodeCourier provisionne une sandbox, clone votre repository, et exécute un agent IA qui examine la codebase selon vos instructions. L’agent produit ses résultats sous forme de liste structurée d’issues, chacune avec un titre, une description, une priorité et une correction suggérée. Il enregistre également les questions auxquelles il n’a pas pu répondre à partir de la seule codebase, ainsi que les hypothèses qu’il a formulées en poursuivant sans réponses.

Configurer l’Issue Agent

Avant de lancer une session, vous configurez l’Issue Agent depuis la page Issues Setup à l’adresse /p/{projectId}/issues-setup. Cette configuration s’applique à toutes les issue sessions du projet. La page de configuration vous permet de spécifier :

Lancer une session

Pour lancer une issue session, accédez à la page Issues et cliquez sur Nouvelle session. Vous devez fournir :

1. Prompt de découverte(requis) - Instructions pour l’agent IA décrivant ce qu’il doit rechercher. Soyez aussi spécifique que possible pour de meilleurs résultats.
2. Configuration de sandbox (optionnelle) - Remplacez les paramètres de sandbox par défaut, notamment le template, la mémoire, le nombre de CPU et le timeout.

Exemples de prompts de découverte :

# Security-focused scan
"Analyze the codebase for security vulnerabilities including XSS, SQL injection,
authentication bypasses, and insecure defaults. Focus on API routes and user input handling."

# Performance scan
"Identify performance bottlenecks, memory leaks, N+1 queries, unnecessary re-renders,
and large bundle size contributors."

# General code quality
"Find bugs, error handling gaps, untested edge cases, and code that doesn't follow
the project's established patterns and conventions."

# Architecture review
"Identify architectural inconsistencies, missing abstractions, leaky abstractions,
and components that have grown beyond a single responsibility."

Cycle de vie d’une session

Chaque issue session traverse une série de phases :

1. Initiation

Lorsque vous soumettez la session, CodeCourier valide votre authentification et vos clés API, crée un enregistrement de session avec le statut active, et envoie une tâche en arrière-plan Trigger.dev pour gérer le travail de scan.

2. Exécution en sandbox

La tâche en arrière-plan provisionne une sandbox E2B avec la configuration d’environnement de votre projet. Si une URL de repository GitHub est configurée, le repository est cloné dans la sandbox. L’agent IA s’exécute ensuite avec votre prompt de découverte, analysant les fichiers, traçant les chemins de code et identifiant les issues. L’agent écrit ses résultats dans /home/user/issues.json et ses questions dans /home/user/questions.json au sein de la sandbox.

La progression de la session est suivie via deux compteurs sur l’enregistrement de session :

• currentIteration- Le nombre d’itérations actuel de l’agent, mis à jour en temps réel au fur et à mesure de la progression de la session. Cela reflète combien de passes de scan ou de cycles de raisonnement l’agent a effectués.
• maxIterations - La limite supérieure configurée pour les itérations. Une fois que currentIteration atteint maxIterations, l’agent conclut et écrit sa sortie finale. Augmenter cette limite permet un scan plus profond et plus approfondi, au prix d’un temps d’exécution et de tokens supplémentaires.

3. Extraction des issues

Lorsque la session se termine (ou est arrêtée manuellement), CodeCourier lit la sortie issues.jsondepuis la sandbox. Le parseur d’extraction gère plusieurs formats JSON :

• Tableaux encapsulés : { "issues": [...] } ou { "results": [...] }
• Tableaux directs : [{ "title": "...", "description": "..." }, ...]
• Noms de champs alternatifs : name mappé sur title, goal mappé sur description
• JSON partiel avec extraction par regex de secours en cas de sortie malformée

4. Extraction des questions et hypothèses

En plus des issues, la session extrait les questions et hypothèses de questions.json. Elles sont stockées dans les champs questionsJson et assumptionsJson de l’enregistrement de session. Chaque question capture ce dont l’agent n’était pas certain, et chaque hypothèse capture la manière dont l’agent a procédé en l’absence de réponse explicite.

Ces questions et hypothèses constituent l’entrée d’une Answering Session optionnelle qui s’exécute après la fin de l’Issue Session.

5. Création des enregistrements d’issue

Chaque issue extraite est validée (le titre et la description doivent être présents) et créée comme un enregistrement d’issue individuel lié à la session. La priorité est normalisée vers l’un des quatre niveaux pris en charge, avec medium par défaut si non spécifiée ou non reconnue. Toutes les issues démarrent avec le statut new.

La session déclenche également l’envoi de learnings et active tous les hooks de revue configurés pour le projet, permettant aux rôles Judge et Evaluator de participer à l’évaluation de la session avant que les issues ne soient traitées.

Statuts de session

Configurer les paramètres de session

Lors du lancement d’une session, vous pouvez personnaliser la configuration de sandbox :

Lancer une Answering Session

Une fois qu’une Issue Session est terminée et que les questions/hypothèses ont été extraites, vous pouvez optionnellement lancer une Answering Session directement depuis la page de détail de l’Issue Session. Cliquez sur le bouton Démarrer une Answering Session pour lancer le flux.

L’Answering Session utilise un Answering Agent distinct (configuré dans la page answering-setup) pour examiner les questions et produire des hypothèses affinées et exploitables. Vous examinez ensuite chaque hypothèse individuellement - en l’approuvant, la refusant ou la corrigeant. Les hypothèses approuvées sont stockées comme contexte structuré pouvant être injecté dans les workflow runs lors de l’exécution des issues résultantes.

Consultez la documentation Answering Sessions pour un guide complet de ce flux.

Exécuter des issues individuelles

Une fois les issues extraites d’une session (ou créées manuellement), vous pouvez exécuter chacune individuellement :

1. Cliquez sur Exécuter l’issue sur la carte d’issue
2. Sélectionnez un blueprint de workflow à utiliser pour l’exécution
3. Configurez optionnellement une URL de repository GitHub et un nom de branche
4. Soumettez pour lancer le workflow run

Le run utilise le suggestedPromptde l’issue s’il est disponible, sinon il se rabat sur la descriptioncomme prompt. Lorsqu’une Answering Session a été complétée pour cette Issue Session, les hypothèses approuvées sont disponibles comme contexte supplémentaire pour le run. Le statut de l’issue passe à running et est automatiquement synchronisé avec le résultat du run.

Gérer les sessions

Depuis la liste des sessions, vous pouvez :

• Renommer - Donner à la session un nom descriptif
• Arrêter (Kill) - Terminer une session active (les résultats partiels sont récupérés)
• Archiver - Retirer les sessions terminées de la liste active
• Supprimer - Suppression douce d’une session
• Suppression en masse - Supprimer plusieurs sessions à la fois
• Démarrer une Answering Session - Lancer une Answering Session pour une session terminée disposant de questions/hypothèses

Prochaines étapes