@ai-matrx/agents 0.2.1 → 0.5.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);
@@ -91,6 +202,68 @@ async function* readMatrxNdjsonStream(body, options = {}) {
   }
 }
 
+// stream/sse.ts
+var FRAME_SEPARATOR = /\r\n\r\n|\n\n|\r\r/;
+var LINE_SEPARATOR = /\r\n|\n|\r/;
+function parseMatrxSseFrame(frame) {
+  let event = "message";
+  let id = null;
+  const dataLines = [];
+  let sawData = false;
+  for (const line of frame.split(LINE_SEPARATOR)) {
+    if (line.startsWith(":")) continue;
+    if (line.startsWith("event:")) event = line.slice(6).trim();
+    else if (line.startsWith("data:")) {
+      sawData = true;
+      dataLines.push(line.slice(5).replace(/^ /, ""));
+    } else if (line.startsWith("id:")) id = line.slice(3).trim();
+  }
+  const seqCandidate = id !== null && id !== "" ? Number(id) : NaN;
+  const seq = Number.isSafeInteger(seqCandidate) && seqCandidate >= 0 ? seqCandidate : null;
+  return { event, id, seq, data: sawData ? dataLines.join("\n") : null };
+}
+function createMatrxSseFramer() {
+  let buffer = "";
+  return {
+    push(chunk) {
+      buffer += chunk;
+      const frames = [];
+      for (; ; ) {
+        const sep = FRAME_SEPARATOR.exec(buffer);
+        if (sep === null) break;
+        const frame = buffer.slice(0, sep.index);
+        buffer = buffer.slice(sep.index + sep[0].length);
+        frames.push(parseMatrxSseFrame(frame));
+      }
+      return frames;
+    },
+    flush() {
+      const rest = buffer;
+      buffer = "";
+      return { incomplete: rest.length > 0 ? rest : null };
+    }
+  };
+}
+async function* readMatrxSseStream(stream, options = {}) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  const framer = createMatrxSseFramer();
+  try {
+    for (; ; ) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      const frames = framer.push(decoder.decode(value, { stream: true }));
+      for (const frame of frames) yield frame;
+    }
+    const tail = framer.push(decoder.decode());
+    for (const frame of tail) yield frame;
+    const { incomplete } = framer.flush();
+    if (incomplete !== null) options.onIncomplete?.(incomplete);
+  } finally {
+    reader.releaseLock();
+  }
+}
+
 // presentation/result.ts
 var PRIVATE_REASONING_TYPES = /* @__PURE__ */ new Set([
   "thinking",
@@ -298,7 +471,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 +528,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 +565,8 @@ function createWorkflowNodeProjection(input) {
     renderBlocks: {},
     renderBlockOrder: [],
     openFrames: {},
+    limits: resolveLimits(input.limits),
+    lastRenderBlockIssue: null,
     chunksReceived: 0,
     charsStreamed: 0,
     lastStreamingTs: null,
@@ -384,6 +585,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 +605,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 +765,460 @@ function projectWorkflowNodeEvent(current, event) {
   }
 }
 
-export { createAgentRequestProjection, createWorkflowNodeProjection, normalizeMatrxStreamEnvelope, projectAgentEvent, projectAgentEvents, projectAgentResultForDisplay, projectWorkflowNodeEvent, readMatrxNdjsonStream };
+// matrx/transport.ts
+var MatrxApiError = class extends Error {
+  name = "MatrxApiError";
+  /** HTTP status of the failed response. */
+  status;
+  /** Machine code from the server body (`code`, or `detail.code`), when present. */
+  code;
+  /** The parsed server error body, verbatim (undefined when unparsable). */
+  serverDetail;
+  /** The request path the failure came from (server-relative). */
+  path;
+  constructor(args) {
+    super(
+      args.message ?? extractMatrxErrorMessage(args.serverDetail) ?? `HTTP ${args.status}`
+    );
+    this.status = args.status;
+    this.path = args.path;
+    this.serverDetail = args.serverDetail;
+    this.code = extractMatrxErrorCode(args.serverDetail);
+  }
+};
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonBlankString(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function extractMatrxErrorMessage(serverDetail) {
+  if (!isRecord3(serverDetail)) return void 0;
+  const userMessage = nonBlankString(serverDetail.user_message);
+  if (userMessage) return userMessage;
+  const message = nonBlankString(serverDetail.message);
+  if (message) return message;
+  if (Array.isArray(serverDetail.details)) {
+    const messages = serverDetail.details.map((entry) => {
+      if (!isRecord3(entry)) return void 0;
+      const detailMessage = nonBlankString(entry.message);
+      if (!detailMessage) return void 0;
+      const field = nonBlankString(entry.field);
+      return field ? `${field}: ${detailMessage}` : detailMessage;
+    }).filter((m) => typeof m === "string");
+    if (messages.length > 0) return messages.join("; ");
+  }
+  const detail = serverDetail.detail;
+  if (isRecord3(detail)) {
+    const detailMessage = nonBlankString(detail.message) ?? nonBlankString(detail.user_message);
+    if (detailMessage) return detailMessage;
+  }
+  if (typeof detail === "string" && detail.trim()) return detail;
+  if (Array.isArray(detail)) {
+    const messages = detail.map(
+      (entry) => isRecord3(entry) ? nonBlankString(entry.msg) : void 0
+    ).filter((m) => typeof m === "string");
+    if (messages.length > 0) return messages.join("; ");
+  }
+  return void 0;
+}
+function extractMatrxErrorCode(serverDetail) {
+  if (!isRecord3(serverDetail)) return null;
+  const topLevel = nonBlankString(serverDetail.code);
+  if (topLevel) return topLevel;
+  const detail = serverDetail.detail;
+  if (isRecord3(detail)) {
+    const nested = nonBlankString(detail.code);
+    if (nested) return nested;
+  }
+  return null;
+}
+
+// matrx/conversation.ts
+function mintMatrxConversationId() {
+  return crypto.randomUUID();
+}
+function newStoredConversationStart(conversationId) {
+  return {
+    conversation_id: conversationId ?? mintMatrxConversationId(),
+    is_new: true,
+    store: true
+  };
+}
+function continueStoredConversationStart(conversationId) {
+  return { conversation_id: conversationId, is_new: false, store: true };
+}
+function newEphemeralConversationStart(conversationId) {
+  return {
+    conversation_id: conversationId ?? mintMatrxConversationId(),
+    is_new: true,
+    store: false
+  };
+}
+function continueEphemeralConversationStart(conversationId, priorMessages) {
+  return {
+    conversation_id: conversationId,
+    is_new: false,
+    store: false,
+    prior_messages: priorMessages
+  };
+}
+
+// matrx/internal.ts
+function encodePathSegment(value) {
+  return encodeURIComponent(value);
+}
+function buildQuery(params) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0) continue;
+    if (Array.isArray(value)) {
+      for (const entry of value) search.append(key, entry);
+    } else {
+      search.append(key, String(value));
+    }
+  }
+  const encoded = search.toString();
+  return encoded ? `?${encoded}` : "";
+}
+async function readServerDetail(response) {
+  try {
+    return await response.json();
+  } catch {
+    return void 0;
+  }
+}
+async function throwApiError(path, response) {
+  throw new MatrxApiError({
+    status: response.status,
+    path,
+    serverDetail: await readServerDetail(response)
+  });
+}
+async function requestJson(transport, path, options) {
+  const hasBody = options.method !== "GET" && options.body !== void 0;
+  const response = await transport.fetch(path, {
+    method: options.method,
+    headers: hasBody ? { "Content-Type": "application/json" } : {},
+    ...hasBody ? { body: JSON.stringify(options.body) } : {},
+    ...options.signal ? { signal: options.signal } : {}
+  });
+  if (!response.ok) return throwApiError(path, response);
+  return await response.json();
+}
+function toRunHandle(response, options) {
+  return {
+    requestId: response.headers.get("X-Request-ID"),
+    conversationId: response.headers.get("X-Conversation-ID"),
+    events: readMatrxNdjsonStream(response.body, {
+      ...options.signal ? { signal: options.signal } : {},
+      ...options.maxReadAhead !== void 0 ? { maxReadAhead: options.maxReadAhead } : {},
+      ...options.onMalformedLine ? { onMalformedLine: options.onMalformedLine } : {},
+      ...options.onUnknownEnvelope ? { onUnknownEnvelope: options.onUnknownEnvelope } : {},
+      ...options.onValidEnvelope ? { onValidEnvelope: options.onValidEnvelope } : {}
+    }),
+    response
+  };
+}
+async function requestStream(transport, path, options) {
+  const hasBody = options.method !== "GET" && options.body !== void 0;
+  const response = await transport.fetch(path, {
+    method: options.method,
+    headers: {
+      ...hasBody ? { "Content-Type": "application/json" } : {},
+      ...options.headers
+    },
+    ...hasBody ? { body: JSON.stringify(options.body) } : {},
+    ...options.signal ? { signal: options.signal } : {}
+  });
+  if (!response.ok) return throwApiError(path, response);
+  if (!response.body) {
+    throw new MatrxApiError({
+      status: response.status,
+      path,
+      serverDetail: { code: "missing_response_body" },
+      message: "The streaming response carried no body."
+    });
+  }
+  return response;
+}
+
+// matrx/run.ts
+async function streamCall(transport, path, body, options) {
+  const response = await requestStream(transport, path, {
+    method: "POST",
+    // This client IS the streaming path — `stream: true` always, last so a
+    // caller-supplied value can never flip the response off NDJSON.
+    body: { ...body, stream: true },
+    ...options.signal ? { signal: options.signal } : {}
+  });
+  return toRunHandle(response, options);
+}
+function startAgentRun(transport, agentId, request, options = {}) {
+  return streamCall(
+    transport,
+    `/ai/agents/${encodePathSegment(agentId)}`,
+    request,
+    options
+  );
+}
+function continueAgentConversation(transport, conversationId, request, options = {}) {
+  return streamCall(
+    transport,
+    `/ai/conversations/${encodePathSegment(conversationId)}`,
+    request,
+    options
+  );
+}
+function resumeAgentConversation(transport, conversationId, request = {}, options = {}) {
+  return streamCall(
+    transport,
+    `/ai/conversations/${encodePathSegment(conversationId)}/resume`,
+    request,
+    options
+  );
+}
+function cancelAgentRun(transport, requestId, options = {}) {
+  const query = buildQuery(
+    options.mode === "interrupt" ? { mode: "interrupt" } : {}
+  );
+  return requestJson(
+    transport,
+    `/ai/cancel/${encodePathSegment(requestId)}${query}`,
+    {
+      method: "POST",
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+}
+var MatrxRunError = class extends Error {
+  name = "MatrxRunError";
+  /** The verbatim `error` event payload, when one fired. */
+  errorPayload;
+  /** The `user_request` completion status (`"failed"` | `"cancelled"`), when that was the trigger. */
+  completionStatus;
+  /** Text streamed before the failure — partial content never vanishes. */
+  partialText;
+  constructor(args) {
+    super(args.message);
+    this.errorPayload = args.errorPayload ?? null;
+    this.completionStatus = args.completionStatus ?? null;
+    this.partialText = args.partialText ?? "";
+  }
+};
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringField(value, key) {
+  if (!isRecord4(value)) return null;
+  const field = value[key];
+  return typeof field === "string" && field ? field : null;
+}
+async function runAgentToCompletion(transport, agentId, request, options = {}) {
+  const handle = await startAgentRun(transport, agentId, request, options);
+  let text = "";
+  let completion = null;
+  let failure = null;
+  for await (const envelope of handle.events) {
+    options.onEvent?.(envelope);
+    if (envelope.event === "chunk") {
+      const chunk = stringField(envelope.data, "text");
+      if (chunk !== null) {
+        text += chunk;
+        options.onChunk?.(text);
+      }
+      continue;
+    }
+    if (envelope.event === "error" && failure === null) {
+      const payload = isRecord4(envelope.data) ? envelope.data : null;
+      failure = new MatrxRunError({
+        message: stringField(payload, "user_message") ?? stringField(payload, "message") ?? "The agent run failed",
+        errorPayload: payload,
+        partialText: text
+      });
+      continue;
+    }
+    if (envelope.event !== "completion" || !isRecord4(envelope.data)) continue;
+    if (envelope.data.operation !== "user_request") continue;
+    completion = envelope.data;
+    const status = envelope.data.status;
+    if ((status === "failed" || status === "cancelled") && failure === null) {
+      const result = isRecord4(envelope.data.result) ? envelope.data.result : null;
+      failure = new MatrxRunError({
+        message: stringField(result, "error") ?? stringField(result, "user_message") ?? `The agent run ${status}`,
+        completionStatus: status,
+        partialText: text
+      });
+    }
+  }
+  if (failure) throw failure;
+  if (!text && completion) {
+    const result = completion.result;
+    const output = stringField(result, "output");
+    if (output !== null) text = output;
+  }
+  return {
+    text,
+    requestId: handle.requestId,
+    conversationId: handle.conversationId,
+    completion
+  };
+}
+
+// matrx/operations.ts
+var TERMINAL_MATRX_RUNTIME_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+var RUNTIME_STATUSES = /* @__PURE__ */ new Set([
+  "pending",
+  "running",
+  "paused",
+  "waiting_input",
+  "completed",
+  "failed",
+  "cancelled"
+]);
+async function getRuntimeOperationStatus(transport, requestId, options = {}) {
+  try {
+    return await requestJson(
+      transport,
+      `/runtime/operations/${encodePathSegment(requestId)}`,
+      { method: "GET", ...options.signal ? { signal: options.signal } : {} }
+    );
+  } catch (error) {
+    if (error instanceof MatrxApiError && error.status === 404) return null;
+    throw error;
+  }
+}
+async function getRuntimeOperationsByLink(transport, linkKind, linkId, options = {}) {
+  const query = buildQuery(
+    options.limit !== void 0 ? { limit: options.limit } : {}
+  );
+  try {
+    return await requestJson(
+      transport,
+      `/runtime/operations/by-link/${encodePathSegment(linkKind)}/${encodePathSegment(linkId)}${query}`,
+      { method: "GET", ...options.signal ? { signal: options.signal } : {} }
+    );
+  } catch (error) {
+    if (error instanceof MatrxApiError && error.status === 404) return null;
+    throw error;
+  }
+}
+function listRuntimeOperationEvents(transport, executionId, options = {}) {
+  const query = buildQuery({
+    ...options.afterSeq !== void 0 ? { after_seq: options.afterSeq } : {},
+    ...options.limit !== void 0 ? { limit: options.limit } : {},
+    ...options.kinds !== void 0 ? { kind: options.kinds } : {}
+  });
+  return requestJson(
+    transport,
+    `/runtime/executions/${encodePathSegment(executionId)}/events${query}`,
+    { method: "GET", ...options.signal ? { signal: options.signal } : {} }
+  );
+}
+function parseEndStatus(data) {
+  if (data === null) return null;
+  try {
+    const parsed = JSON.parse(data);
+    if (typeof parsed === "object" && parsed !== null && typeof parsed.status === "string") {
+      const status = parsed.status;
+      return RUNTIME_STATUSES.has(status) ? status : null;
+    }
+  } catch {
+  }
+  return null;
+}
+async function* followRuntimeOperationEvents(transport, executionId, options = {}) {
+  let cursor = options.lastEventSeq ?? 0;
+  const headers = { Accept: "text/event-stream" };
+  if (cursor > 0) headers["Last-Event-ID"] = String(cursor);
+  const response = await requestStream(
+    transport,
+    `/runtime/executions/${encodePathSegment(executionId)}/events/stream`,
+    {
+      method: "GET",
+      headers,
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+  const frames = readMatrxSseStream(
+    response.body,
+    options.onIncomplete ? { onIncomplete: options.onIncomplete } : {}
+  );
+  for await (const frame of frames) {
+    if (frame.event === "end") {
+      yield { type: "end", status: parseEndStatus(frame.data), cursor };
+      return;
+    }
+    if (frame.event === "execution_event" && frame.data !== null) {
+      let event;
+      try {
+        event = JSON.parse(frame.data);
+      } catch (error) {
+        options.onMalformedFrame?.(frame, error);
+        yield { type: "liveness", cursor };
+        continue;
+      }
+      if (frame.seq !== null && frame.seq > cursor) cursor = frame.seq;
+      yield { type: "event", event, seq: frame.seq, cursor };
+      continue;
+    }
+    yield { type: "liveness", cursor };
+  }
+}
+async function rejoinRuntimeOperation(transport, requestId, options = {}) {
+  const response = await requestStream(
+    transport,
+    `/runtime/operations/${encodePathSegment(requestId)}/rejoin`,
+    {
+      method: "POST",
+      // The route takes no body model; the reference client posts an empty
+      // JSON object. Match it so proxies see an ordinary JSON POST.
+      body: {},
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+  return toRunHandle(response, options);
+}
+
+// matrx/tools.ts
+function submitAgentToolResults(transport, conversationId, results, options = {}) {
+  return requestJson(
+    transport,
+    `/ai/conversations/${encodePathSegment(conversationId)}/tool_results`,
+    {
+      method: "POST",
+      body: {
+        results,
+        ...options.instanceId !== void 0 ? { instance_id: options.instanceId } : {}
+      },
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+}
+function listConversationPendingToolCalls(transport, conversationId, options = {}) {
+  return requestJson(
+    transport,
+    `/ai/conversations/${encodePathSegment(conversationId)}/pending_calls`,
+    {
+      method: "GET",
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+}
+function listUserPendingToolCalls(transport, options = {}) {
+  const query = buildQuery(
+    options.instanceId !== void 0 ? { instance_id: options.instanceId } : {}
+  );
+  return requestJson(
+    transport,
+    `/ai/user/pending_calls${query}`,
+    {
+      method: "GET",
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+}
+
+export { DEFAULT_MATRX_NDJSON_READ_AHEAD, DEFAULT_WORKFLOW_PROJECTION_LIMITS, MatrxApiError, MatrxRunError, TERMINAL_MATRX_RUNTIME_STATUSES, cancelAgentRun, continueAgentConversation, continueEphemeralConversationStart, continueStoredConversationStart, createAgentRequestProjection, createMatrxNdjsonFramer, createMatrxSseFramer, createWorkflowNodeProjection, extractMatrxErrorCode, extractMatrxErrorMessage, followRuntimeOperationEvents, getRuntimeOperationStatus, getRuntimeOperationsByLink, listConversationPendingToolCalls, listRuntimeOperationEvents, listUserPendingToolCalls, mintMatrxConversationId, newEphemeralConversationStart, newStoredConversationStart, normalizeMatrxStreamEnvelope, parseMatrxSseFrame, projectAgentEvent, projectAgentEvents, projectAgentResultForDisplay, projectWorkflowNodeEvent, readMatrxNdjsonStream, readMatrxSseStream, rejoinRuntimeOperation, resumeAgentConversation, runAgentToCompletion, startAgentRun, submitAgentToolResults };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map