​

File de commandes (2026-01-16)

​

Pourquoi

• Les exécutions d’auto-réponse peuvent être coûteuses (appels LLM) et entrer en collision lorsque plusieurs messages entrants arrivent à peu d’intervalle.
• La sérialisation évite la concurrence pour des ressources partagées (fichiers de session, journaux, stdin du CLI) et réduit le risque de limites de débit en amont.

​

Fonctionnement

• Une file FIFO consciente des lanes draine chaque lane avec un plafond de concurrence configurable (par défaut 1 pour les lanes non configurées ; la lane principale est à 4 par défaut, la lane subagent à 8).
• runEmbeddedPiAgent met en file par clé de session (lane session:<key>) afin de garantir une seule exécution active par session.
• Chaque exécution de session est ensuite mise en file dans une lane globale (main par défaut) afin que le parallélisme global soit plafonné par agents.defaults.maxConcurrent.
• Lorsque la journalisation verbeuse est activée, les exécutions en file émettent un bref avis si elles ont attendu plus d’environ ~2 s avant de démarrer.
• Les indicateurs de saisie se déclenchent toujours immédiatement lors de la mise en file (lorsque le canal le prend en charge), de sorte que l’expérience utilisateur reste inchangée pendant l’attente.

​

Modes de file (par canal)

• steer : injecte immédiatement dans l’exécution en cours (annule les appels d’outil en attente après la prochaine frontière d’outil). En l’absence de streaming, revient au suivi.
• followup : met en file pour le prochain tour de l’agent après la fin de l’exécution en cours.
• collect : fusionne tous les messages en file en un seul tour de suivi (par défaut). Si les messages ciblent des canaux/fils différents, ils sont drainés individuellement pour préserver le routage.
• steer-backlog (alias steer+backlog) : oriente maintenant et conserve le message pour un tour de suivi.
• interrupt (hérité) : abandonne l’exécution active pour cette session, puis exécute le message le plus récent.
• queue (alias hérité) : identique à steer.

• Toutes les surfaces → collect

{
  messages: {
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect" },
    },
  },
}

​

Options de la file d’attente

• debounceMs : attendre une période de calme avant de démarrer un tour de suivi (empêche « continuer, continuer »).
• cap : nombre maximal de messages en file par session.
• drop : politique de dépassement (old, new, summarize).

​

Remplacements par session

• Envoyez /queue <mode> comme commande autonome pour enregistrer le mode pour la session en cours.
• Les options peuvent être combinées : /queue collect debounce:2s cap:25 drop:summarize
• /queue default ou /queue reset efface le remplacement de session.

​

Portée et garanties

• S’applique aux exécutions d’agents en auto-réponse sur tous les canaux entrants qui utilisent le pipeline de réponse de la Gateway (passerelle) (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat, etc.).
• La lane par défaut (main) est à l’échelle du processus pour les entrants + battements de cœur principaux ; définissez agents.defaults.maxConcurrent pour autoriser plusieurs sessions en parallèle.
• Des lanes supplémentaires peuvent exister (par ex. cron, subagent) afin que les tâches en arrière-plan puissent s’exécuter en parallèle sans bloquer les réponses entrantes.
• Les lanes par session garantissent qu’une seule exécution d’agent touche une session donnée à la fois.
• Aucune dépendance externe ni threads de workers en arrière-plan ; TypeScript pur + promesses.

​

Problemes courants

• Si des commandes semblent bloquées, activez les journaux verbeux et recherchez les lignes « queued for …ms » pour confirmer que la file se vide.
• Si vous avez besoin de la profondeur de file, activez les journaux verbeux et surveillez les lignes de temporisation de la file.