@ai-matrx/agents 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,18 +1,34 @@
 # Changelog
 
+## 0.3.0 — 2026-08-24
+
+- Added a transport-independent incremental NDJSON framer for fragmented text
+  and bytes, including split UTF-8 and unterminated trailing input.
+- Added exact valid-envelope observation, physical-line malformed diagnostics,
+  cancellation proof, bounded configurable read-ahead, and ordered partial
+  transport failure behavior.
+- Preserved top-level `stream_seq` through wire normalization so projector
+  replay suppression receives the server's transport sequence.
+- Aligned tool status semantics with execution: server `tool_started` remains
+  streaming; only `tool_delegated` suspends for client work.
+- Bounded workflow render-block assembly by open sets, frames, and UTF-8 bytes;
+  malformed or invalid completions now produce typed diagnostics instead of
+  disappearing silently.
+- Expanded TypeScript checking to include every projection source and test.
+
 ## 0.2.1 — 2026-08-24
 
 - Published the documented workflow projection entry point that workspace
   consumers already used but the immutable 0.2.0 registry artifact omitted.
+- Added the portable workflow `node_stream` projection inlet with strict
+  answer/reasoning separation, bounded render-block assembly, replay
+  suppression, and shadowed-text state.
 - Added every request and workflow projection test to the normal package test
   gate; the previous Vitest include list silently ran only stream and
   presentation tests.
 
 ## 0.2.0 — 2026-08-22
 
-- Added the portable workflow `node_stream` projection inlet with strict
-  answer/reasoning separation, bounded render-block assembly, replay
-  suppression, and shadowed-text state.
 - Added a framework-free request event projector for identity, status, answer/reasoning, phases, operations, tools, render blocks, Content IR metadata, completion, and errors.
 - Added golden lifecycle fixtures, replay suppression, and copy-on-write guarantees.
 - Added conditional ESM/CommonJS artifacts and loader canaries for mixed Vite, Next.js, and Jest consumers.

package/README.md

@@ -1,8 +1,8 @@
 # @ai-matrx/agents
 
-Portable client-side primitives for AI Matrx agent applications. Version 1 is
-intentionally narrow: it standardizes the stream wire boundary and the safe
-Creator-facing result boundary without importing React, Redux, Next.js, or any
+Portable client-side primitives for AI Matrx agent applications. The package
+standardizes the stream wire, pure request/workflow projection, and safe
+Creator-facing result boundaries without importing React, Redux, Next.js, or
 application code.
 
 ## Install
@@ -25,8 +25,30 @@ for await (const envelope of readMatrxNdjsonStream(response.body!, {
 ```
 
 The reader preserves split UTF-8, drains the network independently of consumer
-work, supports cancellation, normalizes full and compact Matrx envelopes, and
-reports malformed or unknown input through explicit callbacks.
+work up to the configurable `maxReadAhead` bound, supports cancellation,
+normalizes full and compact Matrx envelopes, and reports malformed or unknown
+input through explicit callbacks. `onValidEnvelope` observes the exact parsed
+wire value before normalization without consuming it. Full-envelope
+`stream_seq` is preserved for projector replay suppression.
+
+## Frame non-ReadableStream transports
+
+```ts
+import { createMatrxNdjsonFramer } from "@ai-matrx/agents/stream/ndjson";
+
+const framer = createMatrxNdjsonFramer({
+  onMalformedLine: reportProtocolDamage,
+  onValidEnvelope: persistRawEnvelope,
+});
+
+handleEvents(framer.pushBytes(extensionMessageBytes));
+handleEvents(framer.pushText(desktopBridgeFragment));
+handleEvents(framer.finish());
+```
+
+The same incremental framer works with browser-extension messages, desktop
+bridges, WebSockets, and tests. `finish()` flushes split UTF-8 and diagnoses an
+invalid unterminated final line with `atCompletion: true`.
 
 ## Present a settled result safely
 
@@ -55,7 +77,9 @@ node = projectWorkflowNodeEvent(node, nodeStreamFrame);
 This is the single workflow presentation inlet. It keeps answer and private
 reasoning separate, rejects replayed frames, assembles bounded server
 `render_block` snapshots, and prevents shadowed text from being interpreted as
-a second copy of the same content.
+a second copy of the same content. Configure `maxOpenFrameSets`,
+`maxFramesPerBlock`, and `maxBytesPerBlock` when creating the projection;
+rejected or malformed blocks are observable through `lastRenderBlockIssue`.
 
 ## Runtime support
 

package/dist/index.cjs

@@ -1,13 +1,19 @@
 'use strict';
 
 // stream/ndjson.ts
+var DEFAULT_MATRX_NDJSON_READ_AHEAD = 64;
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function normalizeMatrxStreamEnvelope(value) {
   if (!isRecord(value)) return null;
   if (typeof value.event === "string") {
-    return { event: value.event, data: value.data };
+    const streamSeq = typeof value.stream_seq === "number" && Number.isFinite(value.stream_seq) ? value.stream_seq : void 0;
+    return {
+      event: value.event,
+      data: value.data,
+      ...streamSeq === void 0 ? {} : { stream_seq: streamSeq }
+    };
   }
   if (value.e === "c" && typeof value.t === "string") {
     return { event: "chunk", data: { text: value.t } };
@@ -17,74 +23,179 @@ function normalizeMatrxStreamEnvelope(value) {
   }
   return null;
 }
-async function* readMatrxNdjsonStream(body, options = {}) {
-  const queue = [];
-  let wakeConsumer = null;
-  let readerFinished = false;
-  const enqueue = (item) => {
-    queue.push(item);
-    const wake = wakeConsumer;
-    wakeConsumer = null;
-    wake?.();
-  };
-  const reader = body.getReader();
+function createMatrxNdjsonFramer(options = {}) {
   const decoder = new TextDecoder();
-  const parseLine = (line) => {
+  let buffer = "";
+  let lineNumber = 0;
+  let finished = false;
+  const assertOpen = () => {
+    if (finished) throw new Error("Matrx NDJSON framer is already finished");
+  };
+  const parseLine = (line, atCompletion) => {
+    const currentLineNumber = ++lineNumber;
     const trimmed = line.trim();
-    if (!trimmed) return;
+    if (!trimmed) return null;
     let parsed;
     try {
       parsed = JSON.parse(trimmed);
     } catch (error) {
-      options.onMalformedLine?.({ line: trimmed, error });
-      return;
+      options.onMalformedLine?.({
+        line: trimmed,
+        error,
+        lineNumber: currentLineNumber,
+        atCompletion
+      });
+      return null;
     }
     const envelope = normalizeMatrxStreamEnvelope(parsed);
-    if (envelope) {
-      enqueue({ kind: "event", value: envelope });
-    } else {
+    if (!envelope) {
       options.onUnknownEnvelope?.(parsed);
+      return null;
+    }
+    options.onValidEnvelope?.({
+      raw: parsed,
+      envelope,
+      line: trimmed,
+      lineNumber: currentLineNumber,
+      atCompletion
+    });
+    return envelope;
+  };
+  const pushDecodedText = (fragment) => {
+    buffer += fragment;
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+    const envelopes = [];
+    for (const line of lines) {
+      const envelope = parseLine(line, false);
+      if (envelope) envelopes.push(envelope);
     }
+    return envelopes;
   };
+  return {
+    pushText(fragment) {
+      assertOpen();
+      return pushDecodedText(decoder.decode() + fragment);
+    },
+    pushBytes(fragment) {
+      assertOpen();
+      return pushDecodedText(decoder.decode(fragment, { stream: true }));
+    },
+    finish() {
+      assertOpen();
+      finished = true;
+      const envelopes = pushDecodedText(decoder.decode());
+      if (buffer.length > 0) {
+        const envelope = parseLine(buffer, true);
+        buffer = "";
+        if (envelope) envelopes.push(envelope);
+      }
+      return envelopes;
+    }
+  };
+}
+function readAheadLimit(value) {
+  const limit = value ?? DEFAULT_MATRX_NDJSON_READ_AHEAD;
+  if (!Number.isSafeInteger(limit) || limit < 1) {
+    throw new RangeError("maxReadAhead must be a positive safe integer");
+  }
+  return limit;
+}
+async function* readMatrxNdjsonStream(body, options = {}) {
+  const maxReadAhead = readAheadLimit(options.maxReadAhead);
+  const queue = [];
+  let queuedEventCount = 0;
+  let wakeConsumer = null;
+  let wakeProducer = null;
+  let readerFinished = false;
+  let consumerClosed = false;
+  const wakeWaitingConsumer = () => {
+    const wake = wakeConsumer;
+    wakeConsumer = null;
+    wake?.();
+  };
+  const wakeWaitingProducer = () => {
+    const wake = wakeProducer;
+    wakeProducer = null;
+    wake?.();
+  };
+  const enqueueTerminal = (item) => {
+    if (consumerClosed) return;
+    queue.push(item);
+    wakeWaitingConsumer();
+  };
+  const enqueueEvent = async (value) => {
+    while (queuedEventCount >= maxReadAhead && !consumerClosed && !options.signal?.aborted) {
+      await new Promise((resolve) => {
+        wakeProducer = resolve;
+      });
+    }
+    if (consumerClosed || options.signal?.aborted) return false;
+    queue.push({ kind: "event", value });
+    queuedEventCount += 1;
+    wakeWaitingConsumer();
+    return true;
+  };
+  const waitForReadCapacity = async () => {
+    while (queuedEventCount >= maxReadAhead && !consumerClosed && !options.signal?.aborted) {
+      await new Promise((resolve) => {
+        wakeProducer = resolve;
+      });
+    }
+    return !consumerClosed && !options.signal?.aborted;
+  };
+  const reader = body.getReader();
+  const framer = createMatrxNdjsonFramer(options);
   const onAbort = () => {
+    wakeWaitingProducer();
+    wakeWaitingConsumer();
     void reader.cancel(options.signal?.reason).catch(() => void 0);
   };
   options.signal?.addEventListener("abort", onAbort, { once: true });
+  if (options.signal?.aborted) onAbort();
   const readerPromise = (async () => {
-    let buffer = "";
     try {
-      while (!options.signal?.aborted) {
+      while (!options.signal?.aborted && !consumerClosed) {
+        if (!await waitForReadCapacity()) return;
         const { value, done } = await reader.read();
         if (done) break;
-        buffer += decoder.decode(value, { stream: true });
-        const lines = buffer.split("\n");
-        buffer = lines.pop() ?? "";
-        for (const line of lines) parseLine(line);
+        for (const envelope of framer.pushBytes(value)) {
+          if (!await enqueueEvent(envelope)) return;
+        }
+      }
+      if (!options.signal?.aborted && !consumerClosed) {
+        for (const envelope of framer.finish()) {
+          if (!await enqueueEvent(envelope)) return;
+        }
       }
-      buffer += decoder.decode();
-      if (!options.signal?.aborted && buffer.trim()) parseLine(buffer);
     } catch (error) {
-      const aborted = options.signal?.aborted || error instanceof Error && error.name === "AbortError";
-      if (!aborted) enqueue({ kind: "error", error });
+      const aborted = options.signal?.aborted || consumerClosed || error instanceof Error && error.name === "AbortError";
+      if (!aborted) enqueueTerminal({ kind: "error", error });
     } finally {
       readerFinished = true;
       reader.releaseLock();
-      enqueue({ kind: "done" });
+      enqueueTerminal({ kind: "done" });
     }
   })();
   try {
     while (true) {
       if (queue.length === 0) {
+        if (options.signal?.aborted || readerFinished) return;
         await new Promise((resolve) => {
           wakeConsumer = resolve;
         });
       }
       const item = queue.shift();
+      if (item?.kind === "event") queuedEventCount -= 1;
+      wakeWaitingProducer();
       if (!item || item.kind === "done") return;
       if (item.kind === "error") throw item.error;
       yield item.value;
     }
   } finally {
+    consumerClosed = true;
+    wakeWaitingProducer();
+    wakeWaitingConsumer();
     options.signal?.removeEventListener("abort", onAbort);
     if (!readerFinished) {
       await reader.cancel().catch(() => void 0);
@@ -300,7 +411,7 @@ function projectAgentEvent(current, event) {
       const status = toolStatus(lifecycle);
       return {
         ...next,
-        status: status === "started" || status === "delegated" ? "awaiting-tools" : status === "completed" || status === "error" ? "streaming" : next.status,
+        status: status === "delegated" ? "awaiting-tools" : status === "completed" || status === "error" ? "streaming" : next.status,
         tools: {
           ...current.tools,
           [callId]: {
@@ -357,7 +468,33 @@ function projectAgentEvents(initial, events) {
 }
 
 // projection/workflow.ts
-var MAX_OPEN_FRAME_SETS = 32;
+var DEFAULT_WORKFLOW_PROJECTION_LIMITS = {
+  maxOpenFrameSets: 32,
+  maxFramesPerBlock: 256,
+  maxBytesPerBlock: 1048576
+};
+function positiveSafeInteger(name, value) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new RangeError(`${name} must be a positive safe integer`);
+  }
+  return value;
+}
+function resolveLimits(limits) {
+  return {
+    maxOpenFrameSets: positiveSafeInteger(
+      "maxOpenFrameSets",
+      limits?.maxOpenFrameSets ?? DEFAULT_WORKFLOW_PROJECTION_LIMITS.maxOpenFrameSets
+    ),
+    maxFramesPerBlock: positiveSafeInteger(
+      "maxFramesPerBlock",
+      limits?.maxFramesPerBlock ?? DEFAULT_WORKFLOW_PROJECTION_LIMITS.maxFramesPerBlock
+    ),
+    maxBytesPerBlock: positiveSafeInteger(
+      "maxBytesPerBlock",
+      limits?.maxBytesPerBlock ?? DEFAULT_WORKFLOW_PROJECTION_LIMITS.maxBytesPerBlock
+    )
+  };
+}
 function createWorkflowNodeProjection(input) {
   return {
     runId: input.runId,
@@ -368,6 +505,8 @@ function createWorkflowNodeProjection(input) {
     renderBlocks: {},
     renderBlockOrder: [],
     openFrames: {},
+    limits: resolveLimits(input.limits),
+    lastRenderBlockIssue: null,
     chunksReceived: 0,
     charsStreamed: 0,
     lastStreamingTs: null,
@@ -386,6 +525,9 @@ function asString2(value) {
 function asNumber2(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
+function utf8ByteLength(value) {
+  return new TextEncoder().encode(value).byteLength;
+}
 function toRenderBlock(value) {
   const data = asRecord2(value);
   if (!data) return null;
@@ -403,44 +545,139 @@ function toRenderBlock(value) {
     metadata: asRecord2(data.metadata)
   };
 }
+function withIssue(next, event, code, frameId, message, openFrames = next.openFrames) {
+  return {
+    ...next,
+    openFrames,
+    lastRenderBlockIssue: {
+      code,
+      frameId,
+      streamSeq: event.stream_seq,
+      message
+    }
+  };
+}
+function withoutFrame(frames, frameId) {
+  if (!Object.hasOwn(frames, frameId)) return frames;
+  const next = { ...frames };
+  delete next[frameId];
+  return next;
+}
 function projectRenderFrame(current, event, next) {
   const frameId = event.frame_id;
   const frameCount = event.frame_count ?? 1;
   const frameIndex = event.frame_index ?? 0;
-  if (!frameId || frameCount < 1 || frameIndex < 0 || frameIndex >= frameCount) {
-    return next;
+  if (!frameId || !Number.isSafeInteger(frameCount) || !Number.isSafeInteger(frameIndex) || frameCount < 1 || frameIndex < 0 || frameIndex >= frameCount) {
+    return withIssue(
+      next,
+      event,
+      "invalid_frame_metadata",
+      frameId ?? null,
+      "Render block frame metadata is invalid"
+    );
+  }
+  if (frameCount > current.limits.maxFramesPerBlock) {
+    return withIssue(
+      next,
+      event,
+      "frame_limit_exceeded",
+      frameId,
+      `Render block declares ${frameCount} frames; limit is ${current.limits.maxFramesPerBlock}`,
+      withoutFrame(current.openFrames, frameId)
+    );
   }
   const prior = current.openFrames[frameId];
+  if (prior && prior.frameCount !== frameCount) {
+    return withIssue(
+      next,
+      event,
+      "frame_count_mismatch",
+      frameId,
+      `Render block frame count changed from ${prior.frameCount} to ${frameCount}`,
+      withoutFrame(current.openFrames, frameId)
+    );
+  }
+  const priorSlice = prior?.slices[frameIndex];
+  const byteLength = (prior?.byteLength ?? 0) - (priorSlice === void 0 ? 0 : utf8ByteLength(priorSlice)) + utf8ByteLength(event.delta);
+  if (byteLength > current.limits.maxBytesPerBlock) {
+    return withIssue(
+      next,
+      event,
+      "byte_limit_exceeded",
+      frameId,
+      `Render block exceeds ${current.limits.maxBytesPerBlock} UTF-8 bytes`,
+      withoutFrame(current.openFrames, frameId)
+    );
+  }
   const set = {
     frameCount,
-    slices: { ...prior?.frameCount === frameCount ? prior.slices : {}, [frameIndex]: event.delta }
+    slices: { ...prior?.slices ?? {}, [frameIndex]: event.delta },
+    byteLength
   };
-  const openFrames = { ...current.openFrames, [frameId]: set };
-  const keys = Object.keys(openFrames);
-  const oldestKey = keys[0];
-  if (keys.length > MAX_OPEN_FRAME_SETS && oldestKey !== void 0) {
-    delete openFrames[oldestKey];
+  const openFrames = { ...current.openFrames };
+  let limitIssue = null;
+  if (!prior && Object.keys(openFrames).length >= current.limits.maxOpenFrameSets) {
+    const oldestFrameId = Object.keys(openFrames)[0];
+    if (oldestFrameId !== void 0) {
+      delete openFrames[oldestFrameId];
+      limitIssue = {
+        code: "open_frame_limit_exceeded",
+        frameId: oldestFrameId,
+        streamSeq: event.stream_seq,
+        message: `Evicted incomplete render block after reaching ${current.limits.maxOpenFrameSets} open frame sets`
+      };
+    }
+  }
+  openFrames[frameId] = set;
+  if (Object.keys(set.slices).length !== frameCount) {
+    return {
+      ...next,
+      openFrames,
+      lastRenderBlockIssue: limitIssue ?? current.lastRenderBlockIssue
+    };
   }
-  if (Object.keys(set.slices).length !== frameCount) return { ...next, openFrames };
   delete openFrames[frameId];
-  let block = null;
+  const serialized = Array.from(
+    { length: frameCount },
+    (_, index) => set.slices[index] ?? ""
+  ).join("");
+  let parsed;
   try {
-    block = toRenderBlock(JSON.parse(
-      Array.from({ length: frameCount }, (_, index) => set.slices[index] ?? "").join("")
-    ));
-  } catch {
-    return { ...next, openFrames };
+    parsed = JSON.parse(serialized);
+  } catch (error) {
+    const detail = error instanceof Error ? `: ${error.message}` : "";
+    return withIssue(
+      next,
+      event,
+      "malformed_json",
+      frameId,
+      `Completed render block is not valid JSON${detail}`,
+      openFrames
+    );
+  }
+  const block = toRenderBlock(parsed);
+  if (!block) {
+    return withIssue(
+      next,
+      event,
+      "invalid_render_block",
+      frameId,
+      "Completed render block is missing blockId, blockIndex, or type",
+      openFrames
+    );
   }
-  if (!block) return { ...next, openFrames };
   return {
     ...next,
     openFrames,
+    lastRenderBlockIssue: limitIssue ?? current.lastRenderBlockIssue,
     renderBlocks: { ...current.renderBlocks, [block.blockId]: block },
     renderBlockOrder: Object.hasOwn(current.renderBlocks, block.blockId) ? current.renderBlockOrder : [...current.renderBlockOrder, block.blockId]
   };
 }
 function projectWorkflowNodeEvent(current, event) {
-  if (event.run_id !== current.runId || (event.node_id ?? "") !== current.nodeId) return current;
+  if (event.run_id !== current.runId || (event.node_id ?? "") !== current.nodeId) {
+    return current;
+  }
   if (event.stream_seq <= current.lastTransportSeq) return current;
   const next = {
     ...current,
@@ -468,7 +705,10 @@ function projectWorkflowNodeEvent(current, event) {
   }
 }
 
+exports.DEFAULT_MATRX_NDJSON_READ_AHEAD = DEFAULT_MATRX_NDJSON_READ_AHEAD;
+exports.DEFAULT_WORKFLOW_PROJECTION_LIMITS = DEFAULT_WORKFLOW_PROJECTION_LIMITS;
 exports.createAgentRequestProjection = createAgentRequestProjection;
+exports.createMatrxNdjsonFramer = createMatrxNdjsonFramer;
 exports.createWorkflowNodeProjection = createWorkflowNodeProjection;
 exports.normalizeMatrxStreamEnvelope = normalizeMatrxStreamEnvelope;
 exports.projectAgentEvent = projectAgentEvent;