cut-at-k ce qu'un flux coupé dit à votre client

Un flux qui s’arrête tôt n’a rien d’un cas rare

Une connexion tombe. Un proxy expire. Le producteur meurt au milieu d’une phrase, ou un lecteur appuie sur stop. Le flux se termine là où il se termine, et la bibliothèque cliente doit bien dire quelque chose à son appelant sur ce qui vient de se passer. Tester ce chemin suppose de choisir un point de coupure.

cut-at-k supprime ce choix. Il prend un flux, le fait passer dans votre client une fois entier puis une fois pour chaque préfixe, et pose deux questions à chaque coupure :

• La tête a-t-elle changé ? Une troncature peut perdre la fin. Elle ne doit jamais modifier ce qui précédait la coupure.
• Le consommateur le dit-il ? Une exécution interrompue ne doit pas rapporter ce que la même exécution rapporte lorsqu’elle va à son terme.

C’est à la seconde question que les choses se gâtent d’habitude, et elles se gâtent en silence : la promesse se résout, l’objet de résultat a l’air ordinaire, et rien dessus ne dit que la réponse n’est qu’une demi-réponse.

Il ne connaît rien à votre protocole

Vous fournissez les événements et une fonction de rejeu. Il fournit la boucle et la comparaison. Des server-sent events, des trames WebSocket, une fixture JSON Lines, un tableau construit à la main — il ne regarde jamais à l’intérieur d’un événement.

npm install cut-at-k

import { severAtEveryPoint } from 'cut-at-k';

await severAtEveryPoint({
  events,                                   // the stream, as an array
  label: 'checkout-run',
  replay: (prefix) => runMyClient(prefix)   // called whole, then per prefix
});

Trois points d’entrée portent le travail : severAtEveryPoint lance les rejeux, summarise les réduit en un rapport, format l’imprime. Zéro dépendance, dix fichiers, MIT.

Il refuse de crier au loup

Trois choses se ressemblent trait pour trait dans les chiffres bruts, et une seule est un vrai constat.

• Une coupure qui n’a rien perdu — elle tombe après le dernier événement de contenu et avant les écritures de clôture. Le consommateur rapporte la même chose parce que rien ne manque. Et il a raison.
• Un flux invalide à dessein. Les corpus de conformité en sont remplis, et couper avant l’erreur volontaire fait que le flux entier livre moins que le préfixe. La comparaison s’inverse, et elle ne veut plus rien dire.
• Une coupure qui a perdu du contenu et qui a été rapportée comme si de rien n’était. Celle-là, c’est le constat.

Donc summarise ne signale strictement aucun défaut tant que vous ne lui passez pas un prédicat lostContent. C’est vous qui décidez ce qui compte comme contenu dans votre protocole ; l’outil ne devinera pas à votre place. Les flux écartés comme invalides à dessein reviennent sous forme de décompte plutôt que de disparaître discrètement : vous voyez toujours quelle part d’un corpus a été mise de côté.

Cette leçon a été apprise en se trompant. La première version de summarise ne faisait aucune de ces distinctions et déclarait 154 coupures problématiques sur un corpus où il y en avait 54. Le README garde la phrase qui en est sortie : « Un outil qui crie au loup est pire que pas d’outil du tout. »

Passé sur AG-UI : 227 coupures, 54 qui ont perdu quelque chose en silence

AG-UI livre 68 fixtures de conformité écrites par les auteurs mêmes du protocole. Deux ne font qu’un seul événement et n’offrent aucun point de coupure : 66 ont donc été rejouées — chacune à travers un vrai HttpAgent, sur du vrai HTTP et du vrai SSE avec @ag-ui/client 1.0.0, entière puis coupée à chaque frontière d’événement.

48 streams, 227 cuts, 18 streams excluded as invalid on purpose
4 cuts threw during replay

reported the same as the whole run    : 154
  of which something was actually lost : 54
  of those, no terminal event either   : 52
spread across                          : 34 streams

Le plus petit cas est le plus clair. Prenez la fixture nommée conformant-run-is-quiet et coupez-la après son quatrième événement. L’appel tronqué et l’appel complet se résolvent tous les deux. Aucun des deux ne rejette. RunAgentResult ne porte aucun champ disant lequel a été interrompu. Le nombre de messages vaut 1 dans les deux cas. Un appelant qui vérifie si l’exécution a réussi, ou combien de messages sont revenus, s’entend dire exactement la même chose par une exécution allée à son terme et par une exécution arrêtée au milieu d’une phrase.

Quatre de ces 227 coupures ont levé une erreur pendant le rejeu. Elles restent dans le total et sont mises de côté avant la comparaison, car une coupure qui fait planter le client est un constat différent d’une coupure qui a rapporté la mauvaise chose.

Ce que cette page ne prétend pas

Un abonné peut détecter cela dès aujourd’hui. onRunFinishedEvent se déclenche sur l’exécution complète et pas sur l’exécution tronquée, tandis que onRunFinalized se déclenche sur les deux — la différence est donc observable si vous écoutez ce canal-là. L’affirmation faite ici est plus étroite : l’appel attendu, lui, ne la fait pas remonter. Il se trouve que c’est le canal qu’utilisent la plupart des appelants, ce qui vaut la peine d’être écrit, mais ce n’est pas la même chose que de dire que l’information est indisponible.

Rien de tout cela n’est une découverte non plus. Le comportement a été signalé le 3 août 2026 sous ag-ui-protocol/ag-ui#2300, et la PR #2354 est ouverte depuis le 7 août 2026 avec le correctif. Les deux étaient encore ouvertes à l’écriture de cette page. L’argument en faveur de l’outil n’est pas la nouveauté, c’est la portée : le bug a été trouvé une fois, à la main, sur un seul flux, et la boucle fait apparaître 54 coupures de cette forme sur 34 flux sans que personne ait eu à deviner où regarder.

Six bibliothèques, la même question, quatre réponses nettes

Le dépôt embarque des sondes qui demandent à cinq autres bases de code ce qu’elles disent à un appelant quand le flux est coupé. Quatre d’entre elles répondent correctement :

• Le Vercel AI SDK rapporte une raison de fin other sur une exécution coupée, ou lève une erreur quand aucun texte n’est passé du tout.
• LangGraph JS arrête son checkpoint là où le consommateur interrompu s’est arrêté, et indique où reprendre.
• La mémoire de Mastra contient encore ce qui a réellement été montré au consommateur.
• La réponse finale du OpenAI Node SDK conserve l’appel d’outil qu’elle a diffusé, et ne prétend jamais être allée à son terme.

Le MCP TypeScript SDK, lui, non. Quand la branche réponse d’un POST meurt, la requête attend l’expiration complète de son délai avant que l’appelant soit prévenu — à chaque point de coupure, y compris là où la moitié de la réponse était déjà arrivée.

Six interrogées en tout, AG-UI elle-même comprise — quatre nettes. Les deux qui répondent mal, AG-UI et le MCP SDK, avaient toutes deux été trouvées par quelqu’un d’autre avant. Voilà le compte honnête : c’est une manière de poser partout à la fois une vieille question, pas une source de constats inédits.

Les chiffres

• Version 0.1.3, première publication le 25 septembre 2026. MIT, zéro dépendance, 10 fichiers, livrée avec une attestation de provenance vérifiée.
• 21 tests. 21 passent, 0 échoue — dépôt cloné et tests exécutés le 28 septembre 2026.
• 579 téléchargements en trois jours d’existence — c’est le chiffre « dernière semaine » de npm. Le paquet a trois jours, c’est donc aussi le total du mois.
• 0 étoile sur GitHub, et trois jours d’existence. Lisez les tests avant de faire confiance à la sortie.

Le citer

La bibliothèque a son propre DOI : 10.5281/zenodo.23002965. Un fichier CITATION.cff est livré dans le dépôt, si bien que le bouton Cite this repository de GitHub est renseigné à partir de lui.

Mainteneur

Maintenue par Redouane — ROSH™ Company Labs. Les bugs et les demandes de fonctionnalités vont dans les issues GitHub. Le rapport le plus utile que ce projet puisse recevoir, c’est un corpus où le résumé a qualifié de constat quelque chose qui n’en était pas un.