Issue Session

Una issue session è un processo di scansione basato su IA che analizza la tua codebase e scopre automaticamente problemi, bug, miglioramenti e task. La session viene eseguita all’interno di una sandbox cloud, dando all’agente IA accesso completo al codice del tuo repository, e produce un elenco JSON strutturato di issue che vengono importate in CodeCourier per il tracciamento e la risoluzione. Oltre alle issue, le session generano domande e assunzioni - artefatti strutturati che catturano ciò di cui l’agente non era sicuro durante la scansione e ciò che ha assunto in assenza di indicazioni esplicite.

Cos’è una Issue Session?

Pensa a una issue session come a una code review automatizzata con un focus specifico. Fornisci un discovery prompt - ad esempio, “scansiona alla ricerca di vulnerabilità di sicurezza e problemi di performance” - e CodeCourier provisiona una sandbox, clona il tuo repository ed esegue un agente IA che analizza la codebase secondo le tue istruzioni. L’agente produce i risultati come un elenco strutturato di issue, ciascuna con titolo, descrizione, priorità e correzione suggerita. Registra anche le domande a cui non è riuscito a rispondere basandosi solo sulla codebase, e le assunzioni fatte procedendo senza risposte.

Configurare l’Issue Agent

Prima di avviare una session, configuri l’Issue Agent dalla pagina Issues Setup all’indirizzo /p/{projectId}/issues-setup. Questa configurazione si applica a tutte le issue session del progetto. La pagina di setup ti permette di specificare:

Avviare una session

Per avviare una issue session, vai alla pagina Issue e clicca su Nuova Session. Devi fornire:

1. Discovery Prompt(obbligatorio) - Istruzioni per l’agente IA che descrivono cosa cercare. Sii il più specifico possibile per ottenere risultati migliori.
2. Configurazione della sandbox (opzionale) - Sovrascrive le impostazioni predefinite della sandbox, inclusi template, memoria, numero di CPU e timeout.

Esempi di discovery prompt:

# 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."

Ciclo di vita di una session

Ogni issue session attraversa una serie di fasi:

1. Avvio

Quando invii la session, CodeCourier convalida la tua autenticazione e le tue API key, crea un record di session con stato active e invia un task in background di Trigger.dev per gestire il lavoro di scansione.

2. Esecuzione nella sandbox

Il task in background provisiona una sandbox E2B con la configurazione dell’ambiente del tuo progetto. Se è configurato un URL di repository GitHub, il repository viene clonato nella sandbox. L’agente IA viene quindi eseguito con il tuo discovery prompt, analizzando i file, tracciando i percorsi di codice e identificando le issue. L’agente scrive i suoi risultati in /home/user/issues.json e le sue domande in /home/user/questions.jsonall’interno della sandbox.

Il progresso della session viene tracciato tramite due contatori nel record della session:

• currentIteration- Il numero di iterazioni attuale dell’agente, aggiornato in tempo reale man mano che la session procede. Riflette quante passate di scansione o cicli di ragionamento l’agente ha completato.
• maxIterations - Il limite superiore configurato per le iterazioni. Una volta che currentIteration raggiunge maxIterations, l’agente conclude e scrive il suo output finale. Aumentare questo limite consente una scansione più profonda e approfondita a costo di runtime e token aggiuntivi.

3. Estrazione delle issue

Quando la session si completa (o viene terminata manualmente), CodeCourier legge l’output issues.json dalla sandbox. Il parser di estrazione gestisce più formati JSON:

• Array incapsulati: { "issues": [...] } o { "results": [...] }
• Array diretti: [{ "title": "...", "description": "..." }, ...]
• Nomi di campo alternativi: name mappato su title, goal mappato su description
• JSON parziale con estrazione regex di fallback per output malformato

4. Estrazione di domande e assunzioni

Oltre alle issue, la session estrae domande e assunzioni da questions.json. Queste vengono memorizzate nei campi questionsJson e assumptionsJsondel record della session. Ogni domanda cattura ciò di cui l’agente non era sicuro, e ogni assunzione cattura come l’agente ha proceduto in assenza di una risposta esplicita.

Queste domande e assunzioni costituiscono l’input per una Answering Session opzionale che viene eseguita dopo il completamento della Issue Session.

5. Creazione dei record di issue

Ogni issue estratta viene convalidata (titolo e descrizione devono essere presenti) e creata come record di issue individuale collegato alla session. La priorità viene normalizzata su uno dei quattro livelli supportati, con medium come predefinito se non specificata o non riconosciuta. Tutte le issue iniziano con stato new.

La session avvia anche l’invio dei learning e attiva qualsiasi hook di revisione configurato per il progetto, permettendo ai ruoli Judge ed Evaluator di partecipare alla valutazione della session prima che le issue vengano gestite.

Stati della session

Configurare i parametri della session

Quando avvii una session, puoi personalizzare la configurazione della sandbox:

Avviare una Answering Session

Una volta che una Issue Session si è completata e sono state estratte domande/assunzioni, puoi opzionalmente avviare una Answering Session direttamente dalla pagina di dettaglio della Issue Session. Clicca sul pulsante Avvia Answering Session per lanciare il flusso.

La Answering Session usa un Answering Agent separato (configurato nella pagina answering-setup) per esaminare le domande e produrre assunzioni raffinate e attuabili. Esamini quindi ogni assunzione individualmente - approvandola, rifiutandola o correggendola. Le assunzioni approvate vengono memorizzate come contesto strutturato che può essere iniettato nei workflow run quando vengono eseguite le issue risultanti.

Consulta la documentazione Answering Session per una guida completa a questo flusso.

Eseguire singole issue

Una volta estratte le issue da una session (o create manualmente), puoi eseguirle singolarmente:

1. Clicca su Esegui Issue sulla card della issue
2. Seleziona un blueprint di workflow da usare per l’esecuzione
3. Configura opzionalmente un URL di repository GitHub e un nome branch
4. Invia per avviare il workflow run

Il run usa il suggestedPrompt della issue se disponibile, altrimenti ricade sulla description come prompt. Quando per questa Issue Session è stata completata una Answering Session, le assunzioni approvate sono disponibili come contesto aggiuntivo per il run. Lo stato della issue passa a runninge viene sincronizzato automaticamente con l’esito del run.

Gestire le session

Dall’elenco delle session, puoi:

• Rinominare - Assegna alla session un nome descrittivo
• Terminare (Kill) - Termina una session attiva (i risultati parziali vengono recuperati)
• Archiviare - Sposta le session completate fuori dall’elenco attivo
• Eliminare - Eliminazione soft di una session
• Eliminazione in blocco - Elimina più session contemporaneamente
• Avvia Answering Session - Avvia una Answering Session per una session completata che ha domande/assunzioni

Prossimi passi