@ai-matrx/agents 0.2.1 → 0.3.0

package/dist/index.js

@@ -1,11 +1,17 @@
 // 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 } };
@@ -15,74 +21,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);
@@ -298,7 +409,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]: {
@@ -355,7 +466,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,
@@ -366,6 +503,8 @@ function createWorkflowNodeProjection(input) {
     renderBlocks: {},
     renderBlockOrder: [],
     openFrames: {},
+    limits: resolveLimits(input.limits),
+    lastRenderBlockIssue: null,
     chunksReceived: 0,
     charsStreamed: 0,
     lastStreamingTs: null,
@@ -384,6 +523,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;
@@ -401,44 +543,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,
@@ -466,6 +703,6 @@ function projectWorkflowNodeEvent(current, event) {
   }
 }
 
-export { createAgentRequestProjection, createWorkflowNodeProjection, normalizeMatrxStreamEnvelope, projectAgentEvent, projectAgentEvents, projectAgentResultForDisplay, projectWorkflowNodeEvent, readMatrxNdjsonStream };
+export { DEFAULT_MATRX_NDJSON_READ_AHEAD, DEFAULT_WORKFLOW_PROJECTION_LIMITS, createAgentRequestProjection, createMatrxNdjsonFramer, createWorkflowNodeProjection, normalizeMatrxStreamEnvelope, projectAgentEvent, projectAgentEvents, projectAgentResultForDisplay, projectWorkflowNodeEvent, readMatrxNdjsonStream };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map