@ai-matrx/agents 0.5.1 → 0.6.0

package/dist/stream/sse.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../stream/sse.ts"],"names":[],"mappings":"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","file":"sse.cjs","sourcesContent":["/**\n * `@ai-matrx/agents/stream/sse` — the Matrx SSE frame kernel.\n *\n * Two Matrx clients hand-rolled the identical `text/event-stream` framing —\n * the same separator regex, the same field parsing, the same CRLF incident —\n * for the durable rejoin endpoints (`/runtime/.../events/stream`,\n * `/runs/.../events/stream`). This module is that framing extracted ONCE, as a\n * pure incremental parser, so a host keeps only what is genuinely host policy:\n * the fetch, the stall timer, the retry budget, and what each event MEANS.\n *\n * Contract, mirroring `stream/ndjson`:\n * - Pure and effect-free: no fetch, no timers, no globals. Importing this\n *   module performs no work.\n * - Incremental across arbitrary chunk boundaries: a frame split anywhere —\n *   mid-line, mid-separator, mid-UTF-8 when using the byte reader — parses\n *   identically to one delivered whole.\n * - All three SSE line terminators (`\\r\\n`, `\\n`, `\\r`) and all three frame\n *   separators are handled — the CRLF-vs-LF divergence that bit production is\n *   covered by construction and by test.\n * - Comment-only frames (heartbeats, `:` lines) ARE emitted (with\n *   `data === null`) because hosts use any parsed frame as liveness proof to\n *   reset stall timers and retry budgets. Frames with data join multi-line\n *   `data:` fields with `\\n` per the SSE spec.\n * - `id:` is surfaced raw AND, when it is a safe integer, as `seq` — the\n *   `Last-Event-ID` cursor both Matrx rejoin endpoints use for durable replay.\n *   Cursor ADVANCEMENT (`seq > cursor`) stays host-side, next to the retry.\n */\n\nexport interface MatrxSseFrame {\n  /** `event:` field; the SSE default \"message\" when absent. */\n  event: string;\n  /** `id:` field, raw, when present. */\n  id: string | null;\n  /**\n   * `id:` parsed as a non-negative safe integer, else null. Matrx rejoin\n   * streams use integer ids as the `Last-Event-ID` replay cursor.\n   */\n  seq: number | null;\n  /**\n   * Joined `data:` lines (`\\n`-separated per spec), or null for a frame with\n   * no data field at all (e.g. a comment-only heartbeat). An empty-string\n   * data field is `\"\"`, not null.\n   */\n  data: string | null;\n}\n\nconst FRAME_SEPARATOR = /\\r\\n\\r\\n|\\n\\n|\\r\\r/;\nconst LINE_SEPARATOR = /\\r\\n|\\n|\\r/;\n\n/** Parse ONE complete frame's text (no trailing separator). */\nexport function parseMatrxSseFrame(frame: string): MatrxSseFrame {\n  let event = \"message\";\n  let id: string | null = null;\n  const dataLines: string[] = [];\n  let sawData = false;\n\n  for (const line of frame.split(LINE_SEPARATOR)) {\n    if (line.startsWith(\":\")) continue;\n    if (line.startsWith(\"event:\")) event = line.slice(6).trim();\n    else if (line.startsWith(\"data:\")) {\n      sawData = true;\n      dataLines.push(line.slice(5).replace(/^ /, \"\"));\n    } else if (line.startsWith(\"id:\")) id = line.slice(3).trim();\n  }\n\n  const seqCandidate = id !== null && id !== \"\" ? Number(id) : NaN;\n  const seq =\n    Number.isSafeInteger(seqCandidate) && seqCandidate >= 0\n      ? seqCandidate\n      : null;\n\n  return { event, id, seq, data: sawData ? dataLines.join(\"\\n\") : null };\n}\n\nexport interface MatrxSseFramer {\n  /** Feed a decoded text chunk; returns every frame it completed. */\n  push(chunk: string): MatrxSseFrame[];\n  /**\n   * Signal end of input. A non-empty trailing buffer is an UNTERMINATED frame:\n   * per the SSE spec it was never dispatched, so it is returned separately for\n   * the host to treat as diagnostic, never as a delivered event.\n   */\n  flush(): { incomplete: string | null };\n}\n\n/** Incremental SSE framer over already-decoded text. */\nexport function createMatrxSseFramer(): MatrxSseFramer {\n  let buffer = \"\";\n  return {\n    push(chunk: string): MatrxSseFrame[] {\n      buffer += chunk;\n      const frames: MatrxSseFrame[] = [];\n      for (;;) {\n        const sep = FRAME_SEPARATOR.exec(buffer);\n        if (sep === null) break;\n        // A lone trailing `\\r` could be the first half of `\\r\\n\\r\\n`'s final\n        // newline — but the separator regex only matched what is already\n        // complete, so the slice below is always safe.\n        const frame = buffer.slice(0, sep.index);\n        buffer = buffer.slice(sep.index + sep[0].length);\n        frames.push(parseMatrxSseFrame(frame));\n      }\n      return frames;\n    },\n    flush() {\n      const rest = buffer;\n      buffer = \"\";\n      return { incomplete: rest.length > 0 ? rest : null };\n    },\n  };\n}\n\nexport interface ReadMatrxSseOptions {\n  /**\n   * Called with any unterminated trailing text at stream end (a frame the\n   * server never finished — diagnostic, not a delivered event).\n   */\n  onIncomplete?: (text: string) => void;\n}\n\n/**\n * Async-iterate the frames of a byte stream (e.g. `response.body`), handling\n * split UTF-8 across chunk boundaries. Cancellation follows the reader: abort\n * the fetch and the iterator ends; a transport error after complete frames\n * were yielded surfaces AFTER those frames, with its original cause.\n */\nexport async function* readMatrxSseStream(\n  stream: ReadableStream<Uint8Array>,\n  options: ReadMatrxSseOptions = {},\n): AsyncGenerator<MatrxSseFrame, void, undefined> {\n  const reader = stream.getReader();\n  const decoder = new TextDecoder();\n  const framer = createMatrxSseFramer();\n  try {\n    for (;;) {\n      const { value, done } = await reader.read();\n      if (done) break;\n      const frames = framer.push(decoder.decode(value, { stream: true }));\n      for (const frame of frames) yield frame;\n    }\n    const tail = framer.push(decoder.decode());\n    for (const frame of tail) yield frame;\n    const { incomplete } = framer.flush();\n    if (incomplete !== null) options.onIncomplete?.(incomplete);\n  } finally {\n    reader.releaseLock();\n  }\n}\n"]}
+{"version":3,"sources":["../../stream/sse.ts"],"sourcesContent":["/**\n * `@ai-matrx/agents/stream/sse` — the Matrx SSE frame kernel.\n *\n * Two Matrx clients hand-rolled the identical `text/event-stream` framing —\n * the same separator regex, the same field parsing, the same CRLF incident —\n * for the durable rejoin endpoints (`/runtime/.../events/stream`,\n * `/runs/.../events/stream`). This module is that framing extracted ONCE, as a\n * pure incremental parser, so a host keeps only what is genuinely host policy:\n * the fetch, the stall timer, the retry budget, and what each event MEANS.\n *\n * Contract, mirroring `stream/ndjson`:\n * - Pure and effect-free: no fetch, no timers, no globals. Importing this\n *   module performs no work.\n * - Incremental across arbitrary chunk boundaries: a frame split anywhere —\n *   mid-line, mid-separator, mid-UTF-8 when using the byte reader — parses\n *   identically to one delivered whole.\n * - All three SSE line terminators (`\\r\\n`, `\\n`, `\\r`) and all three frame\n *   separators are handled — the CRLF-vs-LF divergence that bit production is\n *   covered by construction and by test.\n * - Comment-only frames (heartbeats, `:` lines) ARE emitted (with\n *   `data === null`) because hosts use any parsed frame as liveness proof to\n *   reset stall timers and retry budgets. Frames with data join multi-line\n *   `data:` fields with `\\n` per the SSE spec.\n * - `id:` is surfaced raw AND, when it is a safe integer, as `seq` — the\n *   `Last-Event-ID` cursor both Matrx rejoin endpoints use for durable replay.\n *   Cursor ADVANCEMENT (`seq > cursor`) stays host-side, next to the retry.\n */\n\nexport interface MatrxSseFrame {\n  /** `event:` field; the SSE default \"message\" when absent. */\n  event: string;\n  /** `id:` field, raw, when present. */\n  id: string | null;\n  /**\n   * `id:` parsed as a non-negative safe integer, else null. Matrx rejoin\n   * streams use integer ids as the `Last-Event-ID` replay cursor.\n   */\n  seq: number | null;\n  /**\n   * Joined `data:` lines (`\\n`-separated per spec), or null for a frame with\n   * no data field at all (e.g. a comment-only heartbeat). An empty-string\n   * data field is `\"\"`, not null.\n   */\n  data: string | null;\n}\n\nconst FRAME_SEPARATOR = /\\r\\n\\r\\n|\\n\\n|\\r\\r/;\nconst LINE_SEPARATOR = /\\r\\n|\\n|\\r/;\n\n/** Parse ONE complete frame's text (no trailing separator). */\nexport function parseMatrxSseFrame(frame: string): MatrxSseFrame {\n  let event = \"message\";\n  let id: string | null = null;\n  const dataLines: string[] = [];\n  let sawData = false;\n\n  for (const line of frame.split(LINE_SEPARATOR)) {\n    if (line.startsWith(\":\")) continue;\n    if (line.startsWith(\"event:\")) event = line.slice(6).trim();\n    else if (line.startsWith(\"data:\")) {\n      sawData = true;\n      dataLines.push(line.slice(5).replace(/^ /, \"\"));\n    } else if (line.startsWith(\"id:\")) id = line.slice(3).trim();\n  }\n\n  const seqCandidate = id !== null && id !== \"\" ? Number(id) : NaN;\n  const seq =\n    Number.isSafeInteger(seqCandidate) && seqCandidate >= 0\n      ? seqCandidate\n      : null;\n\n  return { event, id, seq, data: sawData ? dataLines.join(\"\\n\") : null };\n}\n\nexport interface MatrxSseFramer {\n  /** Feed a decoded text chunk; returns every frame it completed. */\n  push(chunk: string): MatrxSseFrame[];\n  /**\n   * Signal end of input. A non-empty trailing buffer is an UNTERMINATED frame:\n   * per the SSE spec it was never dispatched, so it is returned separately for\n   * the host to treat as diagnostic, never as a delivered event.\n   */\n  flush(): { incomplete: string | null };\n}\n\n/** Incremental SSE framer over already-decoded text. */\nexport function createMatrxSseFramer(): MatrxSseFramer {\n  let buffer = \"\";\n  return {\n    push(chunk: string): MatrxSseFrame[] {\n      buffer += chunk;\n      const frames: MatrxSseFrame[] = [];\n      for (;;) {\n        const sep = FRAME_SEPARATOR.exec(buffer);\n        if (sep === null) break;\n        // A lone trailing `\\r` could be the first half of `\\r\\n\\r\\n`'s final\n        // newline — but the separator regex only matched what is already\n        // complete, so the slice below is always safe.\n        const frame = buffer.slice(0, sep.index);\n        buffer = buffer.slice(sep.index + sep[0].length);\n        frames.push(parseMatrxSseFrame(frame));\n      }\n      return frames;\n    },\n    flush() {\n      const rest = buffer;\n      buffer = \"\";\n      return { incomplete: rest.length > 0 ? rest : null };\n    },\n  };\n}\n\nexport interface ReadMatrxSseOptions {\n  /**\n   * Called with any unterminated trailing text at stream end (a frame the\n   * server never finished — diagnostic, not a delivered event).\n   */\n  onIncomplete?: (text: string) => void;\n}\n\n/**\n * Async-iterate the frames of a byte stream (e.g. `response.body`), handling\n * split UTF-8 across chunk boundaries. Cancellation follows the reader: abort\n * the fetch and the iterator ends; a transport error after complete frames\n * were yielded surfaces AFTER those frames, with its original cause.\n */\nexport async function* readMatrxSseStream(\n  stream: ReadableStream<Uint8Array>,\n  options: ReadMatrxSseOptions = {},\n): AsyncGenerator<MatrxSseFrame, void, undefined> {\n  const reader = stream.getReader();\n  const decoder = new TextDecoder();\n  const framer = createMatrxSseFramer();\n  try {\n    for (;;) {\n      const { value, done } = await reader.read();\n      if (done) break;\n      const frames = framer.push(decoder.decode(value, { stream: true }));\n      for (const frame of frames) yield frame;\n    }\n    const tail = framer.push(decoder.decode());\n    for (const frame of tail) yield frame;\n    const { incomplete } = framer.flush();\n    if (incomplete !== null) options.onIncomplete?.(incomplete);\n  } finally {\n    reader.releaseLock();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA8CA,IAAM,kBAAkB;AACxB,IAAM,iBAAiB;AAGhB,SAAS,mBAAmB,OAA8B;AAC/D,MAAI,QAAQ;AACZ,MAAI,KAAoB;AACxB,QAAM,YAAsB,CAAC;AAC7B,MAAI,UAAU;AAEd,aAAW,QAAQ,MAAM,MAAM,cAAc,GAAG;AAC9C,QAAI,KAAK,WAAW,GAAG,EAAG;AAC1B,QAAI,KAAK,WAAW,QAAQ,EAAG,SAAQ,KAAK,MAAM,CAAC,EAAE,KAAK;AAAA,aACjD,KAAK,WAAW,OAAO,GAAG;AACjC,gBAAU;AACV,gBAAU,KAAK,KAAK,MAAM,CAAC,EAAE,QAAQ,MAAM,EAAE,CAAC;AAAA,IAChD,WAAW,KAAK,WAAW,KAAK,EAAG,MAAK,KAAK,MAAM,CAAC,EAAE,KAAK;AAAA,EAC7D;AAEA,QAAM,eAAe,OAAO,QAAQ,OAAO,KAAK,OAAO,EAAE,IAAI;AAC7D,QAAM,MACJ,OAAO,cAAc,YAAY,KAAK,gBAAgB,IAClD,eACA;AAEN,SAAO,EAAE,OAAO,IAAI,KAAK,MAAM,UAAU,UAAU,KAAK,IAAI,IAAI,KAAK;AACvE;AAcO,SAAS,uBAAuC;AACrD,MAAI,SAAS;AACb,SAAO;AAAA,IACL,KAAK,OAAgC;AACnC,gBAAU;AACV,YAAM,SAA0B,CAAC;AACjC,iBAAS;AACP,cAAM,MAAM,gBAAgB,KAAK,MAAM;AACvC,YAAI,QAAQ,KAAM;AAIlB,cAAM,QAAQ,OAAO,MAAM,GAAG,IAAI,KAAK;AACvC,iBAAS,OAAO,MAAM,IAAI,QAAQ,IAAI,CAAC,EAAE,MAAM;AAC/C,eAAO,KAAK,mBAAmB,KAAK,CAAC;AAAA,MACvC;AACA,aAAO;AAAA,IACT;AAAA,IACA,QAAQ;AACN,YAAM,OAAO;AACb,eAAS;AACT,aAAO,EAAE,YAAY,KAAK,SAAS,IAAI,OAAO,KAAK;AAAA,IACrD;AAAA,EACF;AACF;AAgBA,gBAAuB,mBACrB,QACA,UAA+B,CAAC,GACgB;AAChD,QAAM,SAAS,OAAO,UAAU;AAChC,QAAM,UAAU,IAAI,YAAY;AAChC,QAAM,SAAS,qBAAqB;AACpC,MAAI;AACF,eAAS;AACP,YAAM,EAAE,OAAO,KAAK,IAAI,MAAM,OAAO,KAAK;AAC1C,UAAI,KAAM;AACV,YAAM,SAAS,OAAO,KAAK,QAAQ,OAAO,OAAO,EAAE,QAAQ,KAAK,CAAC,CAAC;AAClE,iBAAW,SAAS,OAAQ,OAAM;AAAA,IACpC;AACA,UAAM,OAAO,OAAO,KAAK,QAAQ,OAAO,CAAC;AACzC,eAAW,SAAS,KAAM,OAAM;AAChC,UAAM,EAAE,WAAW,IAAI,OAAO,MAAM;AACpC,QAAI,eAAe,KAAM,SAAQ,eAAe,UAAU;AAAA,EAC5D,UAAE;AACA,WAAO,YAAY;AAAA,EACrB;AACF;","names":[]}

package/dist/stream/sse.js

@@ -59,7 +59,9 @@ async function* readMatrxSseStream(stream, options = {}) {
     reader.releaseLock();
   }
 }
-
-export { createMatrxSseFramer, parseMatrxSseFrame, readMatrxSseStream };
-//# sourceMappingURL=sse.js.map
+export {
+  createMatrxSseFramer,
+  parseMatrxSseFrame,
+  readMatrxSseStream
+};
 //# sourceMappingURL=sse.js.map

package/dist/stream/sse.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../stream/sse.ts"],"names":[],"mappings":"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","file":"sse.js","sourcesContent":["/**\n * `@ai-matrx/agents/stream/sse` — the Matrx SSE frame kernel.\n *\n * Two Matrx clients hand-rolled the identical `text/event-stream` framing —\n * the same separator regex, the same field parsing, the same CRLF incident —\n * for the durable rejoin endpoints (`/runtime/.../events/stream`,\n * `/runs/.../events/stream`). This module is that framing extracted ONCE, as a\n * pure incremental parser, so a host keeps only what is genuinely host policy:\n * the fetch, the stall timer, the retry budget, and what each event MEANS.\n *\n * Contract, mirroring `stream/ndjson`:\n * - Pure and effect-free: no fetch, no timers, no globals. Importing this\n *   module performs no work.\n * - Incremental across arbitrary chunk boundaries: a frame split anywhere —\n *   mid-line, mid-separator, mid-UTF-8 when using the byte reader — parses\n *   identically to one delivered whole.\n * - All three SSE line terminators (`\\r\\n`, `\\n`, `\\r`) and all three frame\n *   separators are handled — the CRLF-vs-LF divergence that bit production is\n *   covered by construction and by test.\n * - Comment-only frames (heartbeats, `:` lines) ARE emitted (with\n *   `data === null`) because hosts use any parsed frame as liveness proof to\n *   reset stall timers and retry budgets. Frames with data join multi-line\n *   `data:` fields with `\\n` per the SSE spec.\n * - `id:` is surfaced raw AND, when it is a safe integer, as `seq` — the\n *   `Last-Event-ID` cursor both Matrx rejoin endpoints use for durable replay.\n *   Cursor ADVANCEMENT (`seq > cursor`) stays host-side, next to the retry.\n */\n\nexport interface MatrxSseFrame {\n  /** `event:` field; the SSE default \"message\" when absent. */\n  event: string;\n  /** `id:` field, raw, when present. */\n  id: string | null;\n  /**\n   * `id:` parsed as a non-negative safe integer, else null. Matrx rejoin\n   * streams use integer ids as the `Last-Event-ID` replay cursor.\n   */\n  seq: number | null;\n  /**\n   * Joined `data:` lines (`\\n`-separated per spec), or null for a frame with\n   * no data field at all (e.g. a comment-only heartbeat). An empty-string\n   * data field is `\"\"`, not null.\n   */\n  data: string | null;\n}\n\nconst FRAME_SEPARATOR = /\\r\\n\\r\\n|\\n\\n|\\r\\r/;\nconst LINE_SEPARATOR = /\\r\\n|\\n|\\r/;\n\n/** Parse ONE complete frame's text (no trailing separator). */\nexport function parseMatrxSseFrame(frame: string): MatrxSseFrame {\n  let event = \"message\";\n  let id: string | null = null;\n  const dataLines: string[] = [];\n  let sawData = false;\n\n  for (const line of frame.split(LINE_SEPARATOR)) {\n    if (line.startsWith(\":\")) continue;\n    if (line.startsWith(\"event:\")) event = line.slice(6).trim();\n    else if (line.startsWith(\"data:\")) {\n      sawData = true;\n      dataLines.push(line.slice(5).replace(/^ /, \"\"));\n    } else if (line.startsWith(\"id:\")) id = line.slice(3).trim();\n  }\n\n  const seqCandidate = id !== null && id !== \"\" ? Number(id) : NaN;\n  const seq =\n    Number.isSafeInteger(seqCandidate) && seqCandidate >= 0\n      ? seqCandidate\n      : null;\n\n  return { event, id, seq, data: sawData ? dataLines.join(\"\\n\") : null };\n}\n\nexport interface MatrxSseFramer {\n  /** Feed a decoded text chunk; returns every frame it completed. */\n  push(chunk: string): MatrxSseFrame[];\n  /**\n   * Signal end of input. A non-empty trailing buffer is an UNTERMINATED frame:\n   * per the SSE spec it was never dispatched, so it is returned separately for\n   * the host to treat as diagnostic, never as a delivered event.\n   */\n  flush(): { incomplete: string | null };\n}\n\n/** Incremental SSE framer over already-decoded text. */\nexport function createMatrxSseFramer(): MatrxSseFramer {\n  let buffer = \"\";\n  return {\n    push(chunk: string): MatrxSseFrame[] {\n      buffer += chunk;\n      const frames: MatrxSseFrame[] = [];\n      for (;;) {\n        const sep = FRAME_SEPARATOR.exec(buffer);\n        if (sep === null) break;\n        // A lone trailing `\\r` could be the first half of `\\r\\n\\r\\n`'s final\n        // newline — but the separator regex only matched what is already\n        // complete, so the slice below is always safe.\n        const frame = buffer.slice(0, sep.index);\n        buffer = buffer.slice(sep.index + sep[0].length);\n        frames.push(parseMatrxSseFrame(frame));\n      }\n      return frames;\n    },\n    flush() {\n      const rest = buffer;\n      buffer = \"\";\n      return { incomplete: rest.length > 0 ? rest : null };\n    },\n  };\n}\n\nexport interface ReadMatrxSseOptions {\n  /**\n   * Called with any unterminated trailing text at stream end (a frame the\n   * server never finished — diagnostic, not a delivered event).\n   */\n  onIncomplete?: (text: string) => void;\n}\n\n/**\n * Async-iterate the frames of a byte stream (e.g. `response.body`), handling\n * split UTF-8 across chunk boundaries. Cancellation follows the reader: abort\n * the fetch and the iterator ends; a transport error after complete frames\n * were yielded surfaces AFTER those frames, with its original cause.\n */\nexport async function* readMatrxSseStream(\n  stream: ReadableStream<Uint8Array>,\n  options: ReadMatrxSseOptions = {},\n): AsyncGenerator<MatrxSseFrame, void, undefined> {\n  const reader = stream.getReader();\n  const decoder = new TextDecoder();\n  const framer = createMatrxSseFramer();\n  try {\n    for (;;) {\n      const { value, done } = await reader.read();\n      if (done) break;\n      const frames = framer.push(decoder.decode(value, { stream: true }));\n      for (const frame of frames) yield frame;\n    }\n    const tail = framer.push(decoder.decode());\n    for (const frame of tail) yield frame;\n    const { incomplete } = framer.flush();\n    if (incomplete !== null) options.onIncomplete?.(incomplete);\n  } finally {\n    reader.releaseLock();\n  }\n}\n"]}
+{"version":3,"sources":["../../stream/sse.ts"],"sourcesContent":["/**\n * `@ai-matrx/agents/stream/sse` — the Matrx SSE frame kernel.\n *\n * Two Matrx clients hand-rolled the identical `text/event-stream` framing —\n * the same separator regex, the same field parsing, the same CRLF incident —\n * for the durable rejoin endpoints (`/runtime/.../events/stream`,\n * `/runs/.../events/stream`). This module is that framing extracted ONCE, as a\n * pure incremental parser, so a host keeps only what is genuinely host policy:\n * the fetch, the stall timer, the retry budget, and what each event MEANS.\n *\n * Contract, mirroring `stream/ndjson`:\n * - Pure and effect-free: no fetch, no timers, no globals. Importing this\n *   module performs no work.\n * - Incremental across arbitrary chunk boundaries: a frame split anywhere —\n *   mid-line, mid-separator, mid-UTF-8 when using the byte reader — parses\n *   identically to one delivered whole.\n * - All three SSE line terminators (`\\r\\n`, `\\n`, `\\r`) and all three frame\n *   separators are handled — the CRLF-vs-LF divergence that bit production is\n *   covered by construction and by test.\n * - Comment-only frames (heartbeats, `:` lines) ARE emitted (with\n *   `data === null`) because hosts use any parsed frame as liveness proof to\n *   reset stall timers and retry budgets. Frames with data join multi-line\n *   `data:` fields with `\\n` per the SSE spec.\n * - `id:` is surfaced raw AND, when it is a safe integer, as `seq` — the\n *   `Last-Event-ID` cursor both Matrx rejoin endpoints use for durable replay.\n *   Cursor ADVANCEMENT (`seq > cursor`) stays host-side, next to the retry.\n */\n\nexport interface MatrxSseFrame {\n  /** `event:` field; the SSE default \"message\" when absent. */\n  event: string;\n  /** `id:` field, raw, when present. */\n  id: string | null;\n  /**\n   * `id:` parsed as a non-negative safe integer, else null. Matrx rejoin\n   * streams use integer ids as the `Last-Event-ID` replay cursor.\n   */\n  seq: number | null;\n  /**\n   * Joined `data:` lines (`\\n`-separated per spec), or null for a frame with\n   * no data field at all (e.g. a comment-only heartbeat). An empty-string\n   * data field is `\"\"`, not null.\n   */\n  data: string | null;\n}\n\nconst FRAME_SEPARATOR = /\\r\\n\\r\\n|\\n\\n|\\r\\r/;\nconst LINE_SEPARATOR = /\\r\\n|\\n|\\r/;\n\n/** Parse ONE complete frame's text (no trailing separator). */\nexport function parseMatrxSseFrame(frame: string): MatrxSseFrame {\n  let event = \"message\";\n  let id: string | null = null;\n  const dataLines: string[] = [];\n  let sawData = false;\n\n  for (const line of frame.split(LINE_SEPARATOR)) {\n    if (line.startsWith(\":\")) continue;\n    if (line.startsWith(\"event:\")) event = line.slice(6).trim();\n    else if (line.startsWith(\"data:\")) {\n      sawData = true;\n      dataLines.push(line.slice(5).replace(/^ /, \"\"));\n    } else if (line.startsWith(\"id:\")) id = line.slice(3).trim();\n  }\n\n  const seqCandidate = id !== null && id !== \"\" ? Number(id) : NaN;\n  const seq =\n    Number.isSafeInteger(seqCandidate) && seqCandidate >= 0\n      ? seqCandidate\n      : null;\n\n  return { event, id, seq, data: sawData ? dataLines.join(\"\\n\") : null };\n}\n\nexport interface MatrxSseFramer {\n  /** Feed a decoded text chunk; returns every frame it completed. */\n  push(chunk: string): MatrxSseFrame[];\n  /**\n   * Signal end of input. A non-empty trailing buffer is an UNTERMINATED frame:\n   * per the SSE spec it was never dispatched, so it is returned separately for\n   * the host to treat as diagnostic, never as a delivered event.\n   */\n  flush(): { incomplete: string | null };\n}\n\n/** Incremental SSE framer over already-decoded text. */\nexport function createMatrxSseFramer(): MatrxSseFramer {\n  let buffer = \"\";\n  return {\n    push(chunk: string): MatrxSseFrame[] {\n      buffer += chunk;\n      const frames: MatrxSseFrame[] = [];\n      for (;;) {\n        const sep = FRAME_SEPARATOR.exec(buffer);\n        if (sep === null) break;\n        // A lone trailing `\\r` could be the first half of `\\r\\n\\r\\n`'s final\n        // newline — but the separator regex only matched what is already\n        // complete, so the slice below is always safe.\n        const frame = buffer.slice(0, sep.index);\n        buffer = buffer.slice(sep.index + sep[0].length);\n        frames.push(parseMatrxSseFrame(frame));\n      }\n      return frames;\n    },\n    flush() {\n      const rest = buffer;\n      buffer = \"\";\n      return { incomplete: rest.length > 0 ? rest : null };\n    },\n  };\n}\n\nexport interface ReadMatrxSseOptions {\n  /**\n   * Called with any unterminated trailing text at stream end (a frame the\n   * server never finished — diagnostic, not a delivered event).\n   */\n  onIncomplete?: (text: string) => void;\n}\n\n/**\n * Async-iterate the frames of a byte stream (e.g. `response.body`), handling\n * split UTF-8 across chunk boundaries. Cancellation follows the reader: abort\n * the fetch and the iterator ends; a transport error after complete frames\n * were yielded surfaces AFTER those frames, with its original cause.\n */\nexport async function* readMatrxSseStream(\n  stream: ReadableStream<Uint8Array>,\n  options: ReadMatrxSseOptions = {},\n): AsyncGenerator<MatrxSseFrame, void, undefined> {\n  const reader = stream.getReader();\n  const decoder = new TextDecoder();\n  const framer = createMatrxSseFramer();\n  try {\n    for (;;) {\n      const { value, done } = await reader.read();\n      if (done) break;\n      const frames = framer.push(decoder.decode(value, { stream: true }));\n      for (const frame of frames) yield frame;\n    }\n    const tail = framer.push(decoder.decode());\n    for (const frame of tail) yield frame;\n    const { incomplete } = framer.flush();\n    if (incomplete !== null) options.onIncomplete?.(incomplete);\n  } finally {\n    reader.releaseLock();\n  }\n}\n"],"mappings":";AA8CA,IAAM,kBAAkB;AACxB,IAAM,iBAAiB;AAGhB,SAAS,mBAAmB,OAA8B;AAC/D,MAAI,QAAQ;AACZ,MAAI,KAAoB;AACxB,QAAM,YAAsB,CAAC;AAC7B,MAAI,UAAU;AAEd,aAAW,QAAQ,MAAM,MAAM,cAAc,GAAG;AAC9C,QAAI,KAAK,WAAW,GAAG,EAAG;AAC1B,QAAI,KAAK,WAAW,QAAQ,EAAG,SAAQ,KAAK,MAAM,CAAC,EAAE,KAAK;AAAA,aACjD,KAAK,WAAW,OAAO,GAAG;AACjC,gBAAU;AACV,gBAAU,KAAK,KAAK,MAAM,CAAC,EAAE,QAAQ,MAAM,EAAE,CAAC;AAAA,IAChD,WAAW,KAAK,WAAW,KAAK,EAAG,MAAK,KAAK,MAAM,CAAC,EAAE,KAAK;AAAA,EAC7D;AAEA,QAAM,eAAe,OAAO,QAAQ,OAAO,KAAK,OAAO,EAAE,IAAI;AAC7D,QAAM,MACJ,OAAO,cAAc,YAAY,KAAK,gBAAgB,IAClD,eACA;AAEN,SAAO,EAAE,OAAO,IAAI,KAAK,MAAM,UAAU,UAAU,KAAK,IAAI,IAAI,KAAK;AACvE;AAcO,SAAS,uBAAuC;AACrD,MAAI,SAAS;AACb,SAAO;AAAA,IACL,KAAK,OAAgC;AACnC,gBAAU;AACV,YAAM,SAA0B,CAAC;AACjC,iBAAS;AACP,cAAM,MAAM,gBAAgB,KAAK,MAAM;AACvC,YAAI,QAAQ,KAAM;AAIlB,cAAM,QAAQ,OAAO,MAAM,GAAG,IAAI,KAAK;AACvC,iBAAS,OAAO,MAAM,IAAI,QAAQ,IAAI,CAAC,EAAE,MAAM;AAC/C,eAAO,KAAK,mBAAmB,KAAK,CAAC;AAAA,MACvC;AACA,aAAO;AAAA,IACT;AAAA,IACA,QAAQ;AACN,YAAM,OAAO;AACb,eAAS;AACT,aAAO,EAAE,YAAY,KAAK,SAAS,IAAI,OAAO,KAAK;AAAA,IACrD;AAAA,EACF;AACF;AAgBA,gBAAuB,mBACrB,QACA,UAA+B,CAAC,GACgB;AAChD,QAAM,SAAS,OAAO,UAAU;AAChC,QAAM,UAAU,IAAI,YAAY;AAChC,QAAM,SAAS,qBAAqB;AACpC,MAAI;AACF,eAAS;AACP,YAAM,EAAE,OAAO,KAAK,IAAI,MAAM,OAAO,KAAK;AAC1C,UAAI,KAAM;AACV,YAAM,SAAS,OAAO,KAAK,QAAQ,OAAO,OAAO,EAAE,QAAQ,KAAK,CAAC,CAAC;AAClE,iBAAW,SAAS,OAAQ,OAAM;AAAA,IACpC;AACA,UAAM,OAAO,OAAO,KAAK,QAAQ,OAAO,CAAC;AACzC,eAAW,SAAS,KAAM,OAAM;AAChC,UAAM,EAAE,WAAW,IAAI,OAAO,MAAM;AACpC,QAAI,eAAe,KAAM,SAAQ,eAAe,UAAU;AAAA,EAC5D,UAAE;AACA,WAAO,YAAY;AAAA,EACrB;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/agents",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Portable AI Matrx agent stream protocol, event projection, and safe result-presentation primitives.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -99,12 +99,27 @@
         "types": "./dist/matrx/index.d.cts",
         "default": "./dist/matrx/index.cjs"
       }
+    },
+    "./react": {
+      "import": {
+        "types": "./dist/react/index.d.ts",
+        "default": "./dist/react/index.js"
+      },
+      "require": {
+        "types": "./dist/react/index.d.cts",
+        "default": "./dist/react/index.cjs"
+      }
     }
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
+    "@testing-library/react": "^16.3.3",
     "@types/node": "^24.10.1",
+    "@types/react": "^19.2.17",
+    "jsdom": "^30.0.1",
     "publint": "^0.3.24",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.6"
@@ -117,8 +132,19 @@
     "node": ">=20"
   },
   "sideEffects": false,
+  "dependencies": {
+    "@ai-matrx/data": "latest"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "scripts": {
-    "build": "tsup",
+    "build": "pnpm clean && tsup",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "check:package": "pnpm build && publint && pnpm verify:tarball",
     "typecheck": "tsc --noEmit",