Hook di React

Esegui una sessione Beeuni in React con l’hook useSession.

@beeuni/sdk/react aggiunge hook React all’SDK. Questa pagina descrive useSession, l’hook che gestisce una sessione dall’inizio alla fine, e gli altri hook confermati stabili per le app React.

useSession(projectId, sessionId, options?)

useSession avvia la sessione, apre il trasporto degli eventi selezionato dal server e sincronizza messaggi, stato e prompt in sospeso. Chiamalo una volta per ogni vista della sessione.

import { useSession } from '@beeuni/sdk/react';

function Chat({ projectId, sessionId }: { projectId: string; sessionId: string }) {
  const s = useSession(projectId, sessionId);

  if (s.phase !== 'ready') return <Booting stage={s.stage} onRetry={s.retry} />;

  return (
    <>
      {s.messages.map(({ info, parts }) => (
        <Message key={info.id} info={info} parts={parts} />
      ))}
      <Composer busy={s.isBusy} onSend={s.send} onStop={s.cancel} />
    </>
  );
}

È il server a determinare se il runtime è pronto. Il runtime è pronto quando POST /start restituisce stage: 'ready'. useSession non esegue un controllo di integrità separato lato client.

Valori restituiti

Azioni

useSession restituisce anche removeQuestion e removePermission. Non usarli. Cancellano il prompt dallo stato locale ma non avvisano mai l’agente, quindi l’esecuzione resta bloccata. Usa invece answerQuestion, rejectQuestion o answerPermission.

Opzioni

L’invio è ottimistico. send mostra subito il tuo messaggio, poi gli eventi in streaming compongono la risposta dell’agente.

rewind(messageId) non crea mai una sessione. Usa la sessione canonica di POST /start. Il runtime ripristina lo stato dei file e mantiene recuperabile il percorso rimosso della trascrizione. Il successivo prompt accettato conferma il percorso sostitutivo.

Altri hook stabili

@beeuni/sdk/react esporta anche hook React Query per dati che non richiedono una sessione in esecuzione. Ciascuno rispecchia un metodo del client e non richiede alcun provider.

I tre hook delle notifiche usano userId (qk.notifications) come chiave della cache, quindi il cambio di utente nella stessa scheda non mostra mai la posta in arrivo dell’utente precedente. Passa l’ID dell’utente autenticato.

Le notifiche sono protette dal feature flag notification_center per progetto, disattivato per impostazione predefinita. Proteggi ogni hook con enabled: useFeatureFlag(projectId, 'notification_center').enabled, così un progetto con il flag disattivato non invia alcuna richiesta di notifica.

Link di configurazione dei connettori

Un agente può creare un link di connessione con un clic (/connect/<token>). I dati e la policy runtime del flusso risiedono nell’SDK; l’host visualizza una propria finestra di dialogo sopra di essi e inserisce i propri adapter.

Dati dei connettori

useConnectorQuery(projectId, slug, action, args, { account, enabled, staleTime }) legge l’output di un’azione del connettore come query memorizzata nella cache. error è un ConnectorCallError: visualizza un pulsante di connessione da error.connectUrl oppure un selettore di account da error.availableAccounts. Usalo solo per un’azione che legge; ogni fetch esegue l’azione e scrive un evento di audit. L’output rimane aggiornato per 30 s, il focus non esegue mai un nuovo fetch e viene ritentato solo un 429 o 503 upstream. Vedi Connettori dal codice.

Avviare in anticipo la lettura aperta

prefetchSessionOpen(queryClient, projectId, sessionId) avvia la lettura di apertura della sessione prima del montaggio della vista della sessione. Emette una singola richiesta GET .../snapshot (riga della sessione, turno, coda e i primi 40 messaggi della trascrizione) e inizializza da essa la cache della riga della sessione. useSession usa quindi quella richiesta invece di avviarne una propria.

Chiamalo quando una route identifica una sessione, oppure al passaggio del mouse, al focus o al tocco di un link della sessione. È di sola lettura: non chiama mai /start e non riattiva mai un computer. Non rifiuta mai la promise. Una chiamata ripetuta per la stessa sessione entro 30 secondi non invia alcuna richiesta.

import { prefetchSessionOpen } from '@beeuni/sdk/react';

<a
  href={`/projects/${projectId}/sessions/${sessionId}`}
  onFocus={() => void prefetchSessionOpen(queryClient, projectId, sessionId)}
/>;

Visualizzare dalla cache dopo un ricaricamento

Due store conservano ciò che l’utente ha già visto, così un ricaricamento o l’avvio a freddo dell’app lo visualizzano nel primo frame e lo aggiornano sul posto. Entrambi sono per utente e hanno dimensioni limitate; l’host li svuota al momento della disconnessione.

• createPersistedQueryCache conserva i risultati di React Query usati dall’utente per la navigazione: account, progetti, dettaglio del progetto, elenco paginato delle sessioni e righe delle sessioni (isPersistableQueryKey). Una voce ripristinata conserva la propria età originale, quindi esegue nuovamente il fetch al montaggio. I limiti predefiniti sono 1.000.000 di caratteri e 7 giorni.
• createSavedCopyStore conserva le ultime copie salvate delle trascrizioni inviate dal server. Registralo con setSavedCopyStore e useSession visualizza la copia conservata prima del primo frame. La copia del server viene quindi riconciliata al suo interno in base all’ID del messaggio e l’SDK la rilegge 3 secondi dopo la fine di ogni turno. I limiti predefiniti sono 12 sessioni, 1.500.000 di caratteri e 14 giorni. Una copia di oltre 300.000 caratteri conserva i messaggi più recenti che rientrano nel limite; i messaggi precedenti vengono caricati dal server quando l’utente scorre verso l’alto.

import {
  browserKeyValueStorage,
  createPersistedQueryCache,
  createSavedCopyStore,
  isPersistableQueryKey,
  setSavedCopyStore,
} from '@beeuni/sdk';

const storage = browserKeyValueStorage(); // null where there is no localStorage
if (storage) {
  const cache = createPersistedQueryCache({ storage, userId, shouldPersist: isPersistableQueryKey });
  cache.restore(queryClient); // synchronous with localStorage: no pending frame
  const stop = cache.persist(queryClient);
  setSavedCopyStore(createSavedCopyStore({ storage, userId }));
}

Su React Native, passa AsyncStorage come storage. restore restituisce quindi una promise.

Lo store delle copie salvate conserva solo le acquisizioni del server: il mirror della trascrizione che l’API scrive al termine di un turno. La trascrizione live non viene mai scritta sul dispositivo, quindi un turno interrotto non può tornare a essere in esecuzione. Una lettura del runtime che non restituisce messaggi mantiene sullo schermo i messaggi salvati: significa che il computer ha perso il proprio stato, non che la conversazione è vuota. La prima lettura del runtime con messaggi li riconcilia.

Disconnessione e cambio account

L’SDK conserva in memoria lo stato della sessione per utente: trascrizioni, domande e autorizzazioni in sospeso, ricevute dei turni e selezioni dei modelli. Chiama resetIdentityState() a ogni cambio di identità: alla disconnessione e quando accede un utente diverso. Questo include un accesso in un’altra scheda che cambia l’utente senza ricaricare la pagina.

Chiama questo gestore quando il tuo flusso di autenticazione esegue l’accesso o la disconnessione di un utente.

import { resetIdentityState } from '@beeuni/sdk/react';

let previousUserId: string | null = null;

function onIdentityChange(userId: string | null) {
  if (userId !== previousUserId) {
    queryClient.clear();
    resetIdentityState();
  }
  previousUserId = userId;
}

resetIdentityState() rimuove anche la voce localStorage dell’archivio dei modelli. Non svuota le cache proprie dell’host, come React Query, né la sorgente del token passata a createBeeuni. Reimpostale nello stesso gestore. Non genera mai eccezioni.

Con gli archivi di Rendering dalla cache durante un ricaricamento, svuotali nello stesso gestore: await cache.clear(), quindi await savedCopies.clear() e setSavedCopyStore(null). Nessuno dei due archivi ripristina mai dati per un utente diverso, ma un dispositivo da cui è stato effettuato il logout non dovrebbe conservarli.

Prossimi passi

• Sessioni — l’handle di sessione useSession esegue il wrapping e i tipi BeeuniSendError.
• Riferimento — l’intera superficie REST da cui leggono questi hook.

Cronologia salvata durante l’avvio

useSession(projectId, sessionId) mostra la cronologia delle chat salvata mentre il computer si avvia. L’SDK legge il database indipendentemente dalla disponibilità del runtime. I messaggi live vengono poi riconciliati tramite i relativi ID originali. Gli host non hanno bisogno di una richiesta separata per la cronologia né di un archivio dei messaggi.

La cronologia salvata viene visualizzata esattamente come la trascrizione live: testo, ragionamento e ogni chiamata di strumento con input, output ed errore. La vista completa di un sub-agente legge la trascrizione salvata del sub-agente stesso: passa l’ambito del genitore e savedChild: true a useSessionSync(subAgentSessionId, { beeuniSessionScope, savedChild: true }). La finestra iniziale contiene i 40 messaggi più recenti, fino a un massimo di 1.000.000 di caratteri. Scorrendo verso l’alto vengono caricate finestre precedenti dalla cronologia salvata, anche mentre il computer è spento. Gli allegati che richiedono il computer diventano disponibili quando il runtime è pronto.

savedTranscript indica all’host cosa visualizzare mentre il computer si avvia. È loading mentre potrebbe ancora arrivare una copia salvata, shown quando i messaggi si trovano in messages e none quando non è possibile mostrare nulla prima che il runtime risponda. Uno stato sconosciuto è loading, mai none.

conversationEmpty è true quando non c’è nulla da attendere. La copia salvata dimostra che la conversazione è vuota: una lettura completa del runtime della sessione non ha trovato messaggi. Da allora non è terminato alcun turno e non c’è nulla di aperto o in coda. I record mancanti non lo rendono true, quindi una sessione più vecchia con cronologia non viene mai mostrata come vuota. Una sessione riceve questa conferma al primo avvio con la cronologia salvata attiva.

if (s.messages.length === 0) {
  // Nothing saved and nothing to wait for: the user can type now.
  if (s.conversationEmpty) return <Composer />;
  // One round trip for a saved copy; the computer can take minutes.
  return s.savedTranscript === 'none' ? <Booting stage={s.stage} /> : <MessageSkeleton />;
}

Le chiamate di strumento salvate prima del 2026-09-28 hanno perso input e output. Il server serve ciascuna chiamata con l’input dimostrato dal titolo o dai metadati conservati: il comando e l’output di un comando, il percorso di una chiamata a un file, il modello di ricerca di una ricerca, la descrizione di un sub-agente, l’URL di un fetch, un elenco di attività, il nome di una skill. Al successivo avvio della sessione viene salvata nuovamente l’intera cronologia, 1.

Prompt in attesa

useSessionPrompts(projectId, sessionId) invia il prompt alla casella di posta persistente della sessione. Il server esegue automaticamente i prompt in attesa, ciascuno come turno separato.

Passa placement: 'transcript' per visualizzare un messaggio in attesa nella conversazione. Viene eseguito prima di ogni voce composer e termina la risposta attiva dopo il completamento della chiamata di strumento corrente. Passa placement: 'composer' per mantenerlo nell’elenco modificabile sopra l’input. Attende il completamento della risposta attiva. Ogni posizione conserva l’ordine di invio. Passa delivery: 'steer' | 'queue' | 'interrupt' per indicare come il prompt raggiunge un turno in esecuzione. steer lo consegna al turno al passaggio successivo; il turno non si interrompe. queue attende la fine del turno. interrupt termina il turno dopo lo strumento in esecuzione. Con il solo delivery, l’SDK invia la posizione implicata: interrupt è transcript, le altre sono composer. Una riga di orientamento che non può orientare mostra delivery: 'queue' con steer_fallback impostato su unsupported, not_prompter o turn_ended. interrupt(promptId) (“Interrompi e invia”) trasforma una riga in attesa in una voce della trascrizione; una riga già in invio risponde 409.

Il composer web invia Invio come steer mentre è in esecuzione un turno e come invio nella trascrizione quando la sessione è inattiva. Command+Invio (Control+Invio su Windows/Linux) posiziona il composer. Maiusc+Invio inserisce una nuova riga.

Le righe dell’elenco includono full_text per anteprime complete dopo un ricaricamento. text rimane l’anteprima limitata per i client meno recenti. I byte degli allegati sono esclusi dalle risposte dell’elenco. Delete restituisce il prompt completo per consentire un annullamento senza perdita.

Consegna dei prompt in attesa e risposte attive

useSessionWorking() mantiene state: 'working' mentre un prompt attende nella casella di posta persistente. In questo modo Stop rimane disponibile. pendingDelivery: true contrassegna un prompt ancora in transito verso il runtime; l’app web mostra un unico indicatore di attività ogni volta che state è working, indipendentemente dal valore di quel flag. I turni runtime attivi e le nuove attività runtime lo cancellano. Una cancellazione scaduta non conferma che l’esecuzione sia terminata.

Una richiesta di elaborazione verifica solo l’ammissione e mantiene il prompt in attesa. La consegna inizia dopo che l’ammissione è riuscita. Un turno attivo confermato cancella la visualizzazione del prompt in attesa anche se l’istantanea precedente della casella di posta elenca ancora quel prompt. L’attività runtime conserva l’ID del messaggio del turno attivo durante questo passaggio.

Il composer web chiama Command/Ctrl+Invio Queue List e il comando “Stop and send” di una riga Quick Queue. Le voci Quick Queue vengono eseguite per prime. Una voce Quick Queue in attesa è una bolla colorata dopo i turni consegnati, senza testo di stato. Le voci Queue List rimangono modificabili fino all’inizio della consegna. Il server recupera gli eventi di completamento persi da prove runtime esatte, anche dopo un ricaricamento, senza considerare un runtime irraggiungibile come un turno completato.

Ogni Invio distinto visualizza immediatamente il relativo prompt in attesa, anche mentre una richiesta di accettazione precedente è ancora irrisolta. Solo un errore di consegna aggiunge testo: la causa, Retry e Remove. La casella di posta del server continua a gestire l’ordine di esecuzione.

L’hook legge le modifiche alla coda dal flusso di controllo della sessione (GET .../sessions/:id/events?channels=control), una connessione per sessione indipendentemente dal numero di componenti che lo montano. Ogni scrittura di una riga della casella di posta arriva come frame beeuni.control.queue. Il polling GET .../prompts viene eseguito solo quando quel flusso non è connesso.

Perché è terminato un turno

La trascrizione di un turno interrotto contiene solo MessageAbortedError. Il piano di controllo conserva ciò che sa su come è terminato ogni turno: la causa indicata dalla sandbox, ad esempio SandboxMemoryGuard, e quali turni sono terminati senza una causa indicata. Un’interruzione richiesta da qualcuno — il pulsante Stop, abort(), un prompt inviato a una sessione occupata — viene registrata come richiesta e non viene mai segnalata come errore.

useSessionTurnOutcome(projectId, sessionId) restituisce last_ended, recent_failures e l’ora di lettura atMs dalla cache useSessionWorking() mantiene i dati aggiornati. Non effettua alcuna richiesta. Passa il risultato a turnEndNotice, insieme a ciò che la trascrizione indica sul turno:

const outcome = useSessionTurnOutcome(projectId, sessionId);
const notice = turnEndNotice(outcome, turn.userMessage.info.id, {
  hasError: Boolean(turnError),
  isAbort: turnErrorIsAbort,
});
// notice: { kind: 'sandbox-memory', usedPct: 97, detail: 'sandbox memory at 97% …' }
//       | { kind: 'cause', name: 'SomeGuard', message: '…' }
//       | { kind: 'unexplained' }
//       | null

L’host associa ogni kind alla propria copia e non analizza mai il messaggio della sandbox. null significa “mostra ciò che mostra la trascrizione”: un errore reale rimane, un’interruzione non visualizza nulla. Un errore inspiegato viene segnalato solo quando la lettura è di alcuni secondi successiva alla fine del turno, perché spesso la causa arriva un frame dopo l’interruzione. turnEndCause(outcome, messageId) restituisce la causa registrata non elaborata, oppure null.