Hooks React

Exécutez une session Beeuni dans React avec le hook useSession.

@beeuni/sdk/react ajoute des hooks React au SDK. Cette page présente useSession, le hook qui exécute une session de bout en bout, ainsi que les autres hooks confirmés stables pour les applications React.

useSession(projectId, sessionId, options?)

useSession démarre la session, ouvre le transport d’événements sélectionné par le serveur et synchronise les messages, l’état et les demandes en attente. Appelez-le une fois par vue de session.

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} />
    </>
  );
}

Le serveur fait autorité sur la disponibilité. L’environnement d’exécution est prêt lorsque POST /start renvoie stage: 'ready'. useSession n’effectue pas de vérification de santé distincte côté client.

Valeurs renvoyées

Actions

useSession renvoie aussi removeQuestion et removePermission. Ne les utilisez pas. Ils effacent la demande de l’état local sans jamais avertir l’agent ; l’exécution reste donc bloquée. Utilisez plutôt answerQuestion, rejectQuestion ou answerPermission.

Options

L’envoi est optimiste. send affiche votre message immédiatement, puis les événements du flux complètent la réponse de l’agent.

rewind(messageId) ne crée jamais de session. Il utilise la session canonique de POST /start. L’environnement d’exécution restaure l’état des fichiers et conserve le parcours supprimé de la transcription récupérable. Le prochain prompt accepté valide le parcours de remplacement.

Autres hooks stables

@beeuni/sdk/react exporte également des hooks React Query pour les données qui ne nécessitent pas de session en cours d’exécution. Chacun correspond à une méthode du client et ne nécessite aucun fournisseur.

Les trois hooks de notification utilisent userId (qk.notifications) comme clé de cache, afin qu’un changement d’utilisateur dans le même onglet n’affiche jamais la boîte de réception de l’utilisateur précédent. Passez l’identifiant de l’utilisateur connecté.

Les notifications sont contrôlées par le feature flag notification_center propre à chaque projet, désactivé par défaut. Conditionnez chaque hook avec enabled: useFeatureFlag(projectId, 'notification_center').enabled, afin qu’un projet où ce flag est désactivé n’envoie aucune requête de notification.

Liens de configuration des connecteurs

Un agent peut générer un lien de connexion en un clic (/connect/<token>). Les données du parcours et la politique du runtime résident dans le SDK ; l’hôte affiche sa propre boîte de dialogue à partir de ces éléments et y injecte ses adaptateurs.

Données des connecteurs

useConnectorQuery(projectId, slug, action, args, { account, enabled, staleTime }) lit la sortie d’une action de connecteur sous forme de requête mise en cache. error est un ConnectorCallError : affichez un bouton de connexion à partir de error.connectUrl, ou un sélecteur de compte à partir de error.availableAccounts. Utilisez-le uniquement pour une action de lecture ; chaque récupération exécute l’action et écrit un événement d’audit. La sortie reste à jour pendant 30 s, la prise de focus ne recharge jamais les données, et seul un 429 ou 503 en amont fait l’objet d’une nouvelle tentative. Voir Connecteurs depuis le code.

Anticiper la lecture d’ouverture

prefetchSessionOpen(queryClient, projectId, sessionId) lance la lecture d’ouverture de session avant le montage de la vue de session. Il émet une requête GET .../snapshot (enregistrement de session, tour, file d’attente et les 40 premiers messages de la transcription) et initialise le cache de l’enregistrement de session à partir de celle-ci. useSession utilise ensuite cette requête au lieu d’en lancer une autre.

Appelez-le lorsqu’une route désigne une session, ou au survol, à la prise de focus ou au toucher d’un lien de session. Il est en lecture seule : il n’appelle jamais /start et ne réveille jamais un ordinateur. Il ne rejette jamais sa promesse. Un nouvel appel pour la même session dans les 30 secondes n’envoie aucune requête.

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

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

Afficher depuis le cache lors d’un rechargement

Deux magasins conservent ce qu’un utilisateur a déjà vu, afin qu’un rechargement ou un démarrage à froid de l’application l’affiche dès la première image et l’actualise sur place. Tous deux sont propres à chaque utilisateur et bornés, et l’hôte les efface tous deux à la déconnexion.

• createPersistedQueryCache conserve les résultats React Query utilisés par l’utilisateur pour naviguer : comptes, projets, détail du projet, liste paginée des sessions et enregistrements de session (isPersistableQueryKey). Une entrée restaurée conserve son ancienneté d’origine, et ses données sont donc rechargées au montage. Les limites par défaut sont de 1 000 000 caractères et 7 jours.
• createSavedCopyStore conserve les dernières copies enregistrées des transcriptions envoyées par le serveur. Enregistrez-le avec setSavedCopyStore, et useSession affiche la copie conservée avant la première image. La copie du serveur est ensuite réconciliée avec elle par identifiant de message, et le SDK la relit 3 secondes après la fin de chaque tour. Les limites par défaut sont de 12 sessions, 1 500 000 caractères et 14 jours. Une copie de plus de 300 000 caractères conserve ses messages les plus récents qui tiennent dans cette limite ; les messages plus anciens sont chargés depuis le serveur lorsque l’utilisateur fait défiler vers le haut.

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 }));
}

Sur React Native, passez AsyncStorage comme storage. restore renvoie alors une promesse.

Le magasin de copies enregistrées ne conserve que les captures du serveur : le miroir de la transcription que l’API écrit à la fin d’un tour. La transcription en direct n’est jamais écrite sur l’appareil, afin qu’un tour arrêté ne puisse pas réapparaître comme étant en cours. Une lecture du runtime qui ne renvoie aucun message conserve les messages enregistrés à l’écran : cela signifie que l’ordinateur a perdu son état, pas que la conversation est vide. La première lecture du runtime contenant des messages les réconcilie.

Déconnexion et changement de compte

Le SDK conserve en mémoire l’état des sessions par utilisateur : transcriptions, questions et autorisations en attente, reçus de tours et choix de modèles. Appelez resetIdentityState() à chaque changement d’identité : déconnexion et connexion d’un autre utilisateur. Cela inclut une connexion dans un autre onglet qui change l’utilisateur sans rechargement de page.

Appelez ce gestionnaire lorsque votre flux d’authentification connecte ou déconnecte un utilisateur.

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() supprime également l’entrée localStorage du magasin de modèles. Il ne vide pas les caches propres à l’hôte, comme React Query, ni la source de jetons transmise à createBeeuni. Réinitialisez-les dans le même gestionnaire. Il ne lève jamais d’exception.

Avec les magasins de Afficher depuis le cache lors d’un rechargement, videz-les dans le même gestionnaire : await cache.clear(), puis await savedCopies.clear() et setSavedCopyStore(null). Aucun des deux magasins ne restaure de données pour un autre utilisateur, mais un appareil déconnecté ne doit pas les conserver.

Suite

• Sessions — le handle de session encapsulé par useSession et les types BeeuniSendError.
• Référence — l’ensemble de l’interface REST utilisée en lecture par ces hooks.

Historique enregistré pendant le démarrage

useSession(projectId, sessionId) affiche l’historique de discussion enregistré pendant le démarrage de son ordinateur. Le SDK lit la base de données indépendamment de la disponibilité de l’environnement d’exécution. Les messages en direct sont ensuite rapprochés à l’aide de leurs identifiants d’origine. Les hôtes n’ont pas besoin d’une requête d’historique ni d’un magasin de messages distincts.

L’historique enregistré s’affiche exactement comme la transcription en direct : texte, raisonnement et chaque appel d’outil avec son entrée, sa sortie et son erreur. La vue complète d’un sous-agent lit la transcription enregistrée propre à ce sous-agent : transmettez la portée du parent et savedChild: true à useSessionSync(subAgentSessionId, { beeuniSessionScope, savedChild: true }). La fenêtre initiale contient les 40 messages les plus récents, dans la limite de 1 000 000 de caractères. Faire défiler vers le haut charge des fenêtres plus anciennes de l’historique enregistré, même lorsque l’ordinateur est éteint. Les pièces jointes qui nécessitent l’ordinateur deviennent disponibles lorsque l’environnement d’exécution est prêt.

savedTranscript indique à l’hôte quoi afficher pendant le démarrage de l’ordinateur. Il vaut loading tant qu’une copie enregistrée peut encore arriver, shown une fois que les messages sont dans messages, et none lorsque rien ne peut s’afficher avant la réponse de l’environnement d’exécution. Un état inconnu vaut loading, jamais none.

conversationEmpty vaut true lorsqu’il n’y a rien à attendre. La copie enregistrée prouve que la conversation est vide : une lecture complète de l’environnement d’exécution de la session n’a trouvé aucun message. Aucun tour ne s’est terminé depuis, et rien n’est ouvert ni en file d’attente. Des enregistrements manquants ne le font jamais passer à true ; une ancienne session avec un historique n’est donc jamais affichée comme vide. Une session obtient cette preuve à son premier démarrage avec l’historique enregistré activé.

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 />;
}

Les appels d’outils enregistrés avant le 2026-09-28 ont perdu leurs entrées et sorties. Le serveur fournit chacun d’eux avec l’entrée attestée par le titre ou les métadonnées conservés : la commande et la sortie d’une commande, le chemin d’un appel de fichier, le motif d’une recherche, la description d’un sous-agent, l’URL d’une récupération, une liste de tâches, le nom d’une compétence. Au prochain démarrage de la session, l’historique entier est à nouveau enregistré, à l’identique.

Prompts en attente

useSessionPrompts(projectId, sessionId) soumet les prompts à la boîte de réception persistante de la session. Le serveur exécute automatiquement les prompts en attente, chacun dans son propre tour.

Transmettez placement: 'transcript' pour afficher un message en attente dans la conversation. Il s’exécute avant chaque entrée composer et met fin à la réponse active après la fin de l’appel d’outil en cours. Transmettez placement: 'composer' pour le conserver dans la liste modifiable au-dessus du champ de saisie. Il attend que la réponse active se termine. Chaque emplacement conserve l’ordre de soumission. Transmettez delivery: 'steer' | 'queue' | 'interrupt' pour indiquer comment le prompt parvient à un tour en cours. steer le transmet au tour à son étape suivante ; le tour ne s’arrête pas. queue attend la fin du tour. interrupt met fin au tour après l’outil en cours. Avec seulement delivery, le SDK envoie l’emplacement qu’il implique : interrupt correspond à transcript, les autres à composer. Une ligne de réorientation qui ne peut pas réorienter affiche delivery: 'queue' avec steer_fallback défini sur unsupported, not_prompter ou turn_ended. interrupt(promptId) (« Stop and send ») transforme une ligne en attente en entrée de transcription ; une ligne déjà en cours de transmission renvoie 409.

L’éditeur web envoie avec Entrée sous la forme steer lorsqu’un tour est en cours, et comme un envoi dans la transcription lorsque la session est inactive. Commande+Entrée (Ctrl+Entrée sous Windows/Linux) utilise l’emplacement de l’éditeur. Maj+Entrée insère un saut de ligne.

Les lignes de la liste incluent full_text pour des aperçus complets après rechargement. text reste l’aperçu limité destiné aux anciens clients. Les octets des pièces jointes sont exclus des réponses de liste. La suppression renvoie le prompt complet pour permettre une annulation sans perte.

Transmission en attente et réponses actives

useSessionWorking() conserve state: 'working' tant qu’un prompt attend dans la boîte de réception persistante. Cela maintient Stop disponible. pendingDelivery: true signale un prompt encore en cours de transmission vers l’environnement d’exécution ; l’application web affiche un indicateur d’activité dès que state vaut working, quelle que soit la valeur de cet indicateur. Les tours actifs et l’activité récente de l’environnement d’exécution l’effacent. Une annulation ayant expiré ne confirme pas l’arrêt de l’exécution.

La prise en charge par un worker vérifie uniquement l’admission et laisse le prompt en attente. La transmission commence après une admission réussie. Un tour actif confirmé efface la présentation en attente, même si l’instantané précédent de la boîte de réception répertorie encore ce prompt. L’activité de l’environnement d’exécution préserve l’identifiant de message du tour actif pendant ce transfert.

L’éditeur web nomme Commande/Ctrl+Entrée Queue List et l’action « Stop and send » d’une ligne Quick Queue. Les entrées Quick Queue s’exécutent en premier. Une entrée Quick Queue en attente est une bulle teintée après les tours transmis, sans texte d’état. Les entrées Queue List restent modifiables jusqu’au début de la transmission. Le serveur récupère les événements de fin manqués à partir de preuves exactes de l’environnement d’exécution, y compris après rechargement, sans considérer un environnement d’exécution inaccessible comme un tour terminé.

Chaque pression distincte sur Entrée affiche immédiatement son prompt en attente, même si une demande d’acceptation précédente reste sans réponse. Seul un échec de transmission ajoute du texte : sa cause, Retry et Remove. La boîte de réception du serveur reste responsable de l’ordre d’exécution.

Le hook lit les modifications de la file d’attente depuis le flux de contrôle de la session (GET .../sessions/:id/events?channels=control), avec une connexion par session, quel que soit le nombre de composants qui le montent. Chaque écriture d’une ligne de la boîte de réception arrive sous forme de trame beeuni.control.queue. L’interrogation périodique GET .../prompts ne s’exécute que lorsque ce flux n’est pas connecté.

Pourquoi un tour s’est terminé

La transcription d’un tour interrompu ne contient que MessageAbortedError. Le plan de contrôle conserve ce qu’il sait de la fin de chaque tour : la cause indiquée par la sandbox, par exemple SandboxMemoryGuard, et les tours qui se sont arrêtés sans cause indiquée. Un arrêt demandé par quelqu’un — le bouton Stop, abort(), un prompt envoyé dans une session occupée — est enregistré comme une demande et n’est jamais signalé comme un échec.

useSessionTurnOutcome(projectId, sessionId) renvoie last_ended, recent_failures et l’heure de lecture atMs depuis le cache que useSessionWorking() maintient à jour. Il n’effectue aucune requête. Transmettez le résultat à turnEndNotice, avec ce que la transcription indique sur le tour :

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’hôte associe chaque kind à son propre texte et n’analyse jamais le message de la sandbox. null signifie « afficher ce que la transcription affiche » : une véritable erreur reste affichée, une interruption n’affiche rien. Un échec inexpliqué n’est signalé que lorsque la lecture survient quelques secondes après la fin du tour, car la cause arrive souvent une trame après l’interruption. turnEndCause(outcome, messageId) renvoie la cause brute enregistrée, ou null.