cut-at-k 0.1.1 → 0.1.2

package/README.md

@@ -61,7 +61,8 @@ problem on a corpus where 54 were. A tool that cries wolf is worse than no tool.
 [AG-UI](https://github.com/ag-ui-protocol/ag-ui) ships 68 conformance fixtures — real
 event streams, written by the protocol's authors, with the outcome each one requires.
 Two are a single event long and have no cut point, so 66 were replayed: each through a
-real `HttpAgent` over real HTTP/SSE, whole and then cut at every event boundary. Both
+real `HttpAgent` over real HTTP/SSE — `@ag-ui/client@1.0.0` — whole and then cut at every
+event boundary. Both
 steps are in `results/` and the recording is committed, so the block below is one
 command away:
 
@@ -89,16 +90,43 @@ after k events with no further frames and no terminal event. From
 > having succeeded.
 
 The smallest case, from their `conformant-run-is-quiet` fixture cut after its fourth
-event:
+event. What `runAgent()` actually resolves to, verbatim:
 
 ```
-truncated   settled {"result":null,"newMessages":1}   text "Hello, "
-            events  RUN_STARTED STEP_STARTED TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT
-completed   settled {"result":null,"newMessages":1}   text "Hello, world."
+truncated   events   RUN_STARTED STEP_STARTED TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT
+            resolved {"newMessages":[{"id":"m-1","role":"assistant","content":"Hello, "}]}
+completed   resolved {"newMessages":[{"id":"m-1","role":"assistant","content":"Hello, world."}]}
 ```
 
-The awaited call reports the same value either way. A subscriber sees no terminal
-event at all. Neither channel says the run was cut.
+Both calls resolve. Neither rejects, and `RunAgentResult` has no field that says which
+one was cut short — its `result` member is `undefined` in both, so `JSON.stringify`
+omits it entirely. The two values are not identical: the truncated one carries less
+text. But the caller has nothing to compare it against, and the message count is 1
+either way, so a caller that checks whether the call succeeded, or how many messages
+came back, is told the same thing by a run that finished and a run that stopped
+halfway through a sentence.
+
+Be precise about the limit of that, because it matters: a subscriber **can** detect
+this today. `onRunFinishedEvent` fires on the completed run and not on the truncated
+one, while `onRunFinalized` fires on both. So the claim is not that the client hides
+the truncation everywhere — it is that the awaited call does not surface it, which is
+the channel most callers use.
+
+### This is already known, and someone has written the fix
+
+None of the above is a discovery. It was reported on 2026-08-03 as
+[ag-ui-protocol/ag-ui#2300](https://github.com/ag-ui-protocol/ag-ui/issues/2300) —
+"a stream that ends without RUN_FINISHED/RUN_ERROR resolves as success" — and
+[#2354](https://github.com/ag-ui-protocol/ag-ui/pull/2354) has been open since
+2026-08-07 with the fix: `verifyEvents` asserting that a terminal event arrived, so a
+stream that just stops becomes an error instead of a silent success. Both were open at
+the time of writing.
+
+That is the argument for this tool rather than against it. The bug was found once, by
+hand, on one stream. Running the same corpus through this loop surfaces **54** cuts of
+that shape across **34** streams without anyone guessing where to look — and when
+#2354 merges, re-running the recording is how you find out which of the 54 it actually
+fixed.
 
 `results/run-ag-ui.mjs` reproduces the table from the recorded observations, through
 this library's own summary rather than separate arithmetic, so the numbers above and
@@ -106,7 +134,10 @@ the numbers the tool prints cannot drift apart.
 
 ### What this is not
 
-It is one protocol, one client, at one commit, cut at event boundaries. Cutting inside
+It is one protocol, cut at event boundaries, and one client at one version:
+`@ag-ui/client@1.0.0`. The figures move with the client, so the version is part of the
+result rather than a footnote — replaying the same corpus through `0.0.58` gives
+141/49/47/31, because that older client rejects four fixtures this one parses. Cutting inside
 a frame — mid-UTF-8 sequence, mid-SSE frame, mid tool-call JSON — is not covered yet
 and is where the more interesting failures probably live. Other frameworks have no
 validator of their own to use as an oracle, so for those the harness would have to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cut-at-k",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Cut a stream at every point and check what the consumer is left with",
   "type": "module",
   "exports": {
@@ -31,6 +31,7 @@
     "type": "git",
     "url": "git+https://github.com/roshcompanylabs/cut-at-k.git"
   },
+  "funding": "https://github.com/sponsors/roshcompanylabs",
   "engines": {
     "node": ">=18"
   }

package/results/record.mjs

@@ -14,6 +14,7 @@
 import { createServer } from 'node:http';
 import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { join, basename } from 'node:path';
+import { createRequire } from 'node:module';
 import { HttpAgent } from '@ag-ui/client';
 
 const CORPUS = process.argv[2];
@@ -137,7 +138,16 @@ for (const fx of fixtures) {
 }
 process.stderr.write('\n');
 
-writeFileSync(OUT, JSON.stringify({ rows }, null, 1));
+// Which client produced this. Without it the figures cannot be re-recorded by anyone,
+// which is the whole point of committing the observations rather than the numbers.
+const clientVersion = JSON.parse(
+  readFileSync(createRequire(import.meta.url).resolve('@ag-ui/client/package.json'), 'utf8'),
+).version;
+
+writeFileSync(
+  OUT,
+  JSON.stringify({ client: { name: '@ag-ui/client', version: clientVersion }, rows }, null, 1),
+);
 console.log(`fixtures seen: ${fixtures.length}`);
 console.log(`fixtures replayed (>=2 events): ${new Set(rows.map((r) => r.fixture)).size}`);
 console.log(`rows (cuts): ${rows.length}`);

package/results/sever-results.json

@@ -1,4 +1,8 @@
 {
+ "client": {
+  "name": "@ag-ui/client",
+  "version": "1.0.0"
+ },
  "rows": [
   {
    "fixture": "activity-delta-missing-target-tolerated",
@@ -817,7 +821,7 @@
    "wholeMessages": "reasoning:Let me check.\u0001assistant:Checked.",
    "wholeMessagesCount": 2,
    "wholeMessagesContentOnly": "Let me check.\u0001Checked.",
-   "wholeMessagesJson": "[{\"id\":\"d31f897f-0ee1-4029-a0c2-69fb23c2466d\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
+   "wholeMessagesJson": "[{\"id\":\"91d1f950-44ea-4c5b-af92-a5639d912c4b\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
   },
   {
    "fixture": "era-0-0-45-thinking-translated",
@@ -834,7 +838,7 @@
    "wholeMessages": "reasoning:Let me check.\u0001assistant:Checked.",
    "wholeMessagesCount": 2,
    "wholeMessagesContentOnly": "Let me check.\u0001Checked.",
-   "wholeMessagesJson": "[{\"id\":\"d31f897f-0ee1-4029-a0c2-69fb23c2466d\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
+   "wholeMessagesJson": "[{\"id\":\"91d1f950-44ea-4c5b-af92-a5639d912c4b\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
   },
   {
    "fixture": "era-0-0-45-thinking-translated",
@@ -845,13 +849,13 @@
    "cutMessages": "reasoning:",
    "cutMessagesCount": 1,
    "cutMessagesContentOnly": "",
-   "cutMessagesJson": "[{\"id\":\"4ab7a141-a534-436e-8698-1c6b03970162\",\"role\":\"reasoning\",\"content\":\"\"}]",
+   "cutMessagesJson": "[{\"id\":\"982cc4a1-d6bb-4e41-aee4-142c44a626dc\",\"role\":\"reasoning\",\"content\":\"\"}]",
    "wholeDelivered": "RUN_STARTED REASONING_START REASONING_MESSAGE_START REASONING_MESSAGE_CONTENT REASONING_MESSAGE_END REASONING_END TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT TEXT_MESSAGE_END RUN_FINISHED",
    "wholeSettled": "{\"result\":null,\"newMessages\":2}",
    "wholeMessages": "reasoning:Let me check.\u0001assistant:Checked.",
    "wholeMessagesCount": 2,
    "wholeMessagesContentOnly": "Let me check.\u0001Checked.",
-   "wholeMessagesJson": "[{\"id\":\"d31f897f-0ee1-4029-a0c2-69fb23c2466d\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
+   "wholeMessagesJson": "[{\"id\":\"91d1f950-44ea-4c5b-af92-a5639d912c4b\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
   },
   {
    "fixture": "era-0-0-45-thinking-translated",
@@ -862,13 +866,13 @@
    "cutMessages": "reasoning:Let me check.",
    "cutMessagesCount": 1,
    "cutMessagesContentOnly": "Let me check.",
-   "cutMessagesJson": "[{\"id\":\"574d9cdf-838f-44d4-860c-52c9fc436f00\",\"role\":\"reasoning\",\"content\":\"Let me check.\"}]",
+   "cutMessagesJson": "[{\"id\":\"bbf406ed-71b2-4d36-8598-63068d7c4d61\",\"role\":\"reasoning\",\"content\":\"Let me check.\"}]",
    "wholeDelivered": "RUN_STARTED REASONING_START REASONING_MESSAGE_START REASONING_MESSAGE_CONTENT REASONING_MESSAGE_END REASONING_END TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT TEXT_MESSAGE_END RUN_FINISHED",
    "wholeSettled": "{\"result\":null,\"newMessages\":2}",
    "wholeMessages": "reasoning:Let me check.\u0001assistant:Checked.",
    "wholeMessagesCount": 2,
    "wholeMessagesContentOnly": "Let me check.\u0001Checked.",
-   "wholeMessagesJson": "[{\"id\":\"d31f897f-0ee1-4029-a0c2-69fb23c2466d\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
+   "wholeMessagesJson": "[{\"id\":\"91d1f950-44ea-4c5b-af92-a5639d912c4b\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
   },
   {
    "fixture": "era-0-0-45-thinking-translated",
@@ -879,13 +883,13 @@
    "cutMessages": "reasoning:Let me check.",
    "cutMessagesCount": 1,
    "cutMessagesContentOnly": "Let me check.",
-   "cutMessagesJson": "[{\"id\":\"b5922af2-1b83-41ae-be60-f26c786bf644\",\"role\":\"reasoning\",\"content\":\"Let me check.\"}]",
+   "cutMessagesJson": "[{\"id\":\"71dbfb22-7fef-42a3-b4f1-27b895858747\",\"role\":\"reasoning\",\"content\":\"Let me check.\"}]",
    "wholeDelivered": "RUN_STARTED REASONING_START REASONING_MESSAGE_START REASONING_MESSAGE_CONTENT REASONING_MESSAGE_END REASONING_END TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT TEXT_MESSAGE_END RUN_FINISHED",
    "wholeSettled": "{\"result\":null,\"newMessages\":2}",
    "wholeMessages": "reasoning:Let me check.\u0001assistant:Checked.",
    "wholeMessagesCount": 2,
    "wholeMessagesContentOnly": "Let me check.\u0001Checked.",
-   "wholeMessagesJson": "[{\"id\":\"d31f897f-0ee1-4029-a0c2-69fb23c2466d\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
+   "wholeMessagesJson": "[{\"id\":\"91d1f950-44ea-4c5b-af92-a5639d912c4b\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
   },
   {
    "fixture": "era-0-0-45-thinking-translated",
@@ -896,13 +900,13 @@
    "cutMessages": "reasoning:Let me check.",
    "cutMessagesCount": 1,
    "cutMessagesContentOnly": "Let me check.",
-   "cutMessagesJson": "[{\"id\":\"ebafc06e-6dfe-437a-83a4-a5f0f751525f\",\"role\":\"reasoning\",\"content\":\"Let me check.\"}]",
+   "cutMessagesJson": "[{\"id\":\"32b14f8b-b9a9-479d-87ff-eefb7794ed58\",\"role\":\"reasoning\",\"content\":\"Let me check.\"}]",
    "wholeDelivered": "RUN_STARTED REASONING_START REASONING_MESSAGE_START REASONING_MESSAGE_CONTENT REASONING_MESSAGE_END REASONING_END TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT TEXT_MESSAGE_END RUN_FINISHED",
    "wholeSettled": "{\"result\":null,\"newMessages\":2}",
    "wholeMessages": "reasoning:Let me check.\u0001assistant:Checked.",
    "wholeMessagesCount": 2,
    "wholeMessagesContentOnly": "Let me check.\u0001Checked.",
-   "wholeMessagesJson": "[{\"id\":\"d31f897f-0ee1-4029-a0c2-69fb23c2466d\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
+   "wholeMessagesJson": "[{\"id\":\"91d1f950-44ea-4c5b-af92-a5639d912c4b\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
   },
   {
    "fixture": "era-0-0-45-thinking-translated",
@@ -913,13 +917,13 @@
    "cutMessages": "reasoning:Let me check.\u0001assistant:",
    "cutMessagesCount": 2,
    "cutMessagesContentOnly": "Let me check.\u0001",
-   "cutMessagesJson": "[{\"id\":\"8a5893e4-877f-4f50-8152-9cab1fae76e6\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"\"}]",
+   "cutMessagesJson": "[{\"id\":\"517d746e-90a2-4f2b-a9ab-b67f417f1fa1\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"\"}]",
    "wholeDelivered": "RUN_STARTED REASONING_START REASONING_MESSAGE_START REASONING_MESSAGE_CONTENT REASONING_MESSAGE_END REASONING_END TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT TEXT_MESSAGE_END RUN_FINISHED",
    "wholeSettled": "{\"result\":null,\"newMessages\":2}",
    "wholeMessages": "reasoning:Let me check.\u0001assistant:Checked.",
    "wholeMessagesCount": 2,
    "wholeMessagesContentOnly": "Let me check.\u0001Checked.",
-   "wholeMessagesJson": "[{\"id\":\"d31f897f-0ee1-4029-a0c2-69fb23c2466d\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
+   "wholeMessagesJson": "[{\"id\":\"91d1f950-44ea-4c5b-af92-a5639d912c4b\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
   },
   {
    "fixture": "era-0-0-45-thinking-translated",
@@ -930,13 +934,13 @@
    "cutMessages": "reasoning:Let me check.\u0001assistant:Checked.",
    "cutMessagesCount": 2,
    "cutMessagesContentOnly": "Let me check.\u0001Checked.",
-   "cutMessagesJson": "[{\"id\":\"9767d7cd-9828-4e10-a2dc-aebdec9cc971\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]",
+   "cutMessagesJson": "[{\"id\":\"2c1bea1e-769d-4568-8925-a231053d19a5\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]",
    "wholeDelivered": "RUN_STARTED REASONING_START REASONING_MESSAGE_START REASONING_MESSAGE_CONTENT REASONING_MESSAGE_END REASONING_END TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT TEXT_MESSAGE_END RUN_FINISHED",
    "wholeSettled": "{\"result\":null,\"newMessages\":2}",
    "wholeMessages": "reasoning:Let me check.\u0001assistant:Checked.",
    "wholeMessagesCount": 2,
    "wholeMessagesContentOnly": "Let me check.\u0001Checked.",
-   "wholeMessagesJson": "[{\"id\":\"d31f897f-0ee1-4029-a0c2-69fb23c2466d\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
+   "wholeMessagesJson": "[{\"id\":\"91d1f950-44ea-4c5b-af92-a5639d912c4b\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
   },
   {
    "fixture": "era-0-0-45-thinking-translated",
@@ -947,13 +951,13 @@
    "cutMessages": "reasoning:Let me check.\u0001assistant:Checked.",
    "cutMessagesCount": 2,
    "cutMessagesContentOnly": "Let me check.\u0001Checked.",
-   "cutMessagesJson": "[{\"id\":\"15b56ff3-5d97-4644-9175-ba1cc8c42319\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]",
+   "cutMessagesJson": "[{\"id\":\"47127635-ebf9-4ed2-8912-fa06aac11e12\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]",
    "wholeDelivered": "RUN_STARTED REASONING_START REASONING_MESSAGE_START REASONING_MESSAGE_CONTENT REASONING_MESSAGE_END REASONING_END TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT TEXT_MESSAGE_END RUN_FINISHED",
    "wholeSettled": "{\"result\":null,\"newMessages\":2}",
    "wholeMessages": "reasoning:Let me check.\u0001assistant:Checked.",
    "wholeMessagesCount": 2,
    "wholeMessagesContentOnly": "Let me check.\u0001Checked.",
-   "wholeMessagesJson": "[{\"id\":\"d31f897f-0ee1-4029-a0c2-69fb23c2466d\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
+   "wholeMessagesJson": "[{\"id\":\"91d1f950-44ea-4c5b-af92-a5639d912c4b\",\"role\":\"reasoning\",\"content\":\"Let me check.\"},{\"id\":\"era45-m1\",\"role\":\"assistant\",\"content\":\"Checked.\"}]"
   },
   {
    "fixture": "era-0-0-47-upgrades-binary-content",