@ai-matrx/agents 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # 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 a framework-free request event projector for identity, status, answer/reasoning, phases, operations, tools, render blocks, Content IR metadata, completion, and errors.

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
 
@@ -40,6 +62,25 @@ The projection removes provider-private reasoning blocks and signature material
 without mutating the execution value. It is only for display, JSON views, and
 exports. Never persist the projected result or use it to continue an agent run.
 
+## Project workflow live output
+
+```ts
+import {
+  createWorkflowNodeProjection,
+  projectWorkflowNodeEvent,
+} from "@ai-matrx/agents/projection/workflow";
+
+let node = createWorkflowNodeProjection({ runId, nodeId });
+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. Configure `maxOpenFrameSets`,
+`maxFramesPerBlock`, and `maxBytesPerBlock` when creating the projection;
+rejected or malformed blocks are observable through `lastRenderBlockIssue`.
+
 ## Runtime support
 
 The package is framework-free ESM targeting modern browsers, browser-based

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]: {
@@ -356,11 +467,254 @@ function projectAgentEvents(initial, events) {
   return events.reduce(projectAgentEvent, initial);
 }
 
+// projection/workflow.ts
+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,
+    nodeId: input.nodeId,
+    answer: "",
+    reasoning: "",
+    blockShadowed: false,
+    renderBlocks: {},
+    renderBlockOrder: [],
+    openFrames: {},
+    limits: resolveLimits(input.limits),
+    lastRenderBlockIssue: null,
+    chunksReceived: 0,
+    charsStreamed: 0,
+    lastStreamingTs: null,
+    lastPhase: null,
+    lastTool: null,
+    lastWarning: null,
+    lastTransportSeq: 0
+  };
+}
+function asRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function asString2(value) {
+  return typeof value === "string" ? value : null;
+}
+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;
+  const blockId = asString2(data.blockId);
+  const blockIndex = asNumber2(data.blockIndex);
+  const type = asString2(data.type);
+  if (blockId === null || blockIndex === null || type === null) return null;
+  return {
+    blockId,
+    blockIndex,
+    type,
+    status: data.status === "complete" || data.status === "error" ? data.status : "streaming",
+    content: asString2(data.content),
+    data: asRecord2(data.data),
+    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 || !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?.slices ?? {}, [frameIndex]: event.delta },
+    byteLength
+  };
+  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
+    };
+  }
+  delete openFrames[frameId];
+  const serialized = Array.from(
+    { length: frameCount },
+    (_, index) => set.slices[index] ?? ""
+  ).join("");
+  let parsed;
+  try {
+    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
+    );
+  }
+  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.stream_seq <= current.lastTransportSeq) return current;
+  const next = {
+    ...current,
+    chunksReceived: event.chunks_received,
+    charsStreamed: event.chars_streamed,
+    lastStreamingTs: event.ts,
+    lastTransportSeq: event.stream_seq,
+    blockShadowed: current.blockShadowed || Boolean(event.block_shadowed)
+  };
+  switch (event.kind) {
+    case "chunk":
+      return { ...next, answer: current.answer + event.delta };
+    case "reasoning":
+      return { ...next, reasoning: current.reasoning + event.delta };
+    case "phase":
+      return { ...next, lastPhase: event.delta };
+    case "tool":
+      return { ...next, lastTool: event.delta };
+    case "warning":
+      return { ...next, lastWarning: event.delta };
+    case "render_block":
+      return projectRenderFrame(current, event, next);
+    default:
+      return next;
+  }
+}
+
+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;
 exports.projectAgentEvents = projectAgentEvents;
 exports.projectAgentResultForDisplay = projectAgentResultForDisplay;
+exports.projectWorkflowNodeEvent = projectWorkflowNodeEvent;
 exports.readMatrxNdjsonStream = readMatrxNdjsonStream;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map