@ai-matrx/agents 0.5.0 → 0.6.0

package/dist/react/index.js

@@ -0,0 +1,1016 @@
+"use client";
+
+// react/use-agent-run.ts
+import { useCallback, useEffect, useRef, useState } from "react";
+
+// projection/request.ts
+var asRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+var asString = (value) => typeof value === "string" ? value : null;
+var asNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
+function createAgentRequestProjection(input) {
+  return {
+    requestId: input.requestId,
+    conversationId: input.conversationId ?? null,
+    status: "pending",
+    answer: "",
+    reasoning: "",
+    reasoningActive: false,
+    phase: null,
+    phaseHistory: [],
+    operations: {},
+    tools: {},
+    renderBlocks: {},
+    renderBlockOrder: [],
+    completion: null,
+    error: null,
+    lastTransportSeq: 0,
+    eventCount: 0
+  };
+}
+function toolStatus(event) {
+  switch (event) {
+    case "tool_started":
+      return "started";
+    case "tool_step":
+      return "step";
+    case "tool_result_preview":
+      return "preview";
+    case "tool_completed":
+      return "completed";
+    case "tool_error":
+      return "error";
+    case "tool_delegated":
+      return "delegated";
+    default:
+      return "progress";
+  }
+}
+function projectAgentEvent(current, event) {
+  const streamSeq = asNumber(event.stream_seq);
+  if (streamSeq !== null && streamSeq <= current.lastTransportSeq) return current;
+  const data = asRecord(event.data);
+  const next = {
+    ...current,
+    status: current.status === "pending" ? "streaming" : current.status,
+    lastTransportSeq: streamSeq ?? current.lastTransportSeq,
+    eventCount: current.eventCount + 1
+  };
+  switch (event.event) {
+    case "chunk": {
+      const text = asString(data.text);
+      return text === null ? next : { ...next, answer: current.answer + text };
+    }
+    case "reasoning_chunk": {
+      const text = asString(data.text);
+      return text === null ? next : {
+        ...next,
+        reasoning: current.reasoning + text,
+        reasoningActive: true
+      };
+    }
+    case "reasoning":
+      return {
+        ...next,
+        reasoningActive: data.state === "started"
+      };
+    case "phase": {
+      const phase = asString(data.phase);
+      if (phase === null) return next;
+      return {
+        ...next,
+        phase,
+        phaseHistory: [...current.phaseHistory, phase]
+      };
+    }
+    case "init": {
+      const operationId = asString(data.operation_id);
+      const operation = asString(data.operation);
+      if (operationId === null || operation === null) return next;
+      return {
+        ...next,
+        operations: {
+          ...current.operations,
+          [operationId]: {
+            operationId,
+            operation,
+            parentOperationId: asString(data.parent_operation_id),
+            status: "active",
+            metadata: Object.keys(asRecord(data.metadata)).length ? asRecord(data.metadata) : null,
+            result: null
+          }
+        }
+      };
+    }
+    case "completion": {
+      const operationId = asString(data.operation_id);
+      const operation = asString(data.operation);
+      const rawStatus = asString(data.status);
+      const status = rawStatus === "failed" || rawStatus === "cancelled" ? rawStatus : "success";
+      const result = asRecord(data.result);
+      const operations = operationId ? {
+        ...current.operations,
+        [operationId]: {
+          ...current.operations[operationId] ?? {
+            operationId,
+            operation: operation ?? "unknown",
+            parentOperationId: null,
+            metadata: null
+          },
+          status,
+          result
+        }
+      } : current.operations;
+      if (operation === "user_request") {
+        return {
+          ...next,
+          operations,
+          completion: data,
+          status: status === "success" ? "complete" : status === "cancelled" ? "cancelled" : "error"
+        };
+      }
+      return { ...next, operations };
+    }
+    case "tool_event": {
+      const callId = asString(data.call_id);
+      const toolName = asString(data.tool_name);
+      const lifecycle = asString(data.event);
+      if (callId === null || toolName === null || lifecycle === null) return next;
+      const status = toolStatus(lifecycle);
+      return {
+        ...next,
+        status: status === "delegated" ? "awaiting-tools" : status === "completed" || status === "error" ? "streaming" : next.status,
+        tools: {
+          ...current.tools,
+          [callId]: {
+            callId,
+            toolName,
+            status,
+            message: asString(data.message),
+            data: Object.keys(asRecord(data.data)).length ? asRecord(data.data) : null
+          }
+        }
+      };
+    }
+    case "render_block": {
+      const blockId = asString(data.blockId);
+      const blockIndex = asNumber(data.blockIndex);
+      const type = asString(data.type);
+      if (blockId === null || blockIndex === null || type === null) return next;
+      const alreadyKnown = Object.hasOwn(current.renderBlocks, blockId);
+      return {
+        ...next,
+        renderBlocks: {
+          ...current.renderBlocks,
+          [blockId]: {
+            blockId,
+            blockIndex,
+            type,
+            status: data.status === "complete" || data.status === "error" ? data.status : "streaming",
+            content: asString(data.content),
+            data: Object.keys(asRecord(data.data)).length ? asRecord(data.data) : null,
+            metadata: Object.keys(asRecord(data.metadata)).length ? asRecord(data.metadata) : null
+          }
+        },
+        renderBlockOrder: alreadyKnown ? current.renderBlockOrder : [...current.renderBlockOrder, blockId]
+      };
+    }
+    case "error":
+      return { ...next, status: "error", error: data };
+    case "end":
+      return {
+        ...next,
+        status: current.status === "error" || current.status === "cancelled" ? current.status : "complete",
+        reasoningActive: false
+      };
+    case "data": {
+      const conversationId = data.type === "conversation_id" ? asString(data.conversation_id) : null;
+      return conversationId === null ? next : { ...next, conversationId };
+    }
+    default:
+      return next;
+  }
+}
+
+// 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 isRecord(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 (!isRecord(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 (!isRecord(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 (isRecord(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) => isRecord(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 (!isRecord(serverDetail)) return null;
+  const topLevel = nonBlankString(serverDetail.code);
+  if (topLevel) return topLevel;
+  const detail = serverDetail.detail;
+  if (isRecord(detail)) {
+    const nested = nonBlankString(detail.code);
+    if (nested) return nested;
+  }
+  return null;
+}
+
+// matrx/client.ts
+import { isNetError } from "@ai-matrx/data";
+import { credentialToHeaders } from "@ai-matrx/data";
+
+// matrx/org-context.ts
+var OrganizationContextError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "OrganizationContextError";
+    this.code = code;
+  }
+};
+
+// matrx/client.ts
+function classifyStatus(status) {
+  return status >= 400 && status < 500 ? "validation_error" : "http_error";
+}
+function normalizeMatrxError(err) {
+  if (err instanceof MatrxApiError) {
+    return {
+      type: classifyStatus(err.status),
+      message: err.message,
+      status: err.status,
+      serverDetail: err.serverDetail,
+      ...err.code ? { code: err.code } : {},
+      name: err.name
+    };
+  }
+  if (err instanceof OrganizationContextError) {
+    return {
+      type: "validation_error",
+      message: err.message,
+      code: err.code,
+      name: err.name,
+      ...err.stack !== void 0 ? { stack: err.stack } : {}
+    };
+  }
+  if (err instanceof DOMException && err.name === "AbortError") {
+    return { type: "abort_error", message: "Request was cancelled." };
+  }
+  if (isNetError(err)) {
+    if (err.code === "aborted") {
+      return { type: "abort_error", message: err.message };
+    }
+    if (err.code === "http") {
+      const status = err.status ?? 0;
+      return { type: classifyStatus(status), message: err.message, status };
+    }
+    return { type: "network_error", message: err.message };
+  }
+  if (err instanceof Error) {
+    const httpMatch = err.message.match(/HTTP (\d+):\s*(.*)/);
+    if (httpMatch) {
+      const status = parseInt(httpMatch[1], 10);
+      return {
+        type: classifyStatus(status),
+        message: httpMatch[2] ?? err.message,
+        status
+      };
+    }
+    return { type: "network_error", message: err.message };
+  }
+  return { type: "unknown", message: String(err ?? "Unknown error") };
+}
+
+// stream/ndjson.ts
+var DEFAULT_MATRX_NDJSON_READ_AHEAD = 64;
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeMatrxStreamEnvelope(value) {
+  if (!isRecord2(value)) return null;
+  if (typeof value.event === "string") {
+    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 } };
+  }
+  if (value.e === "r" && typeof value.t === "string") {
+    return { event: "reasoning_chunk", data: { text: value.t } };
+  }
+  return null;
+}
+function createMatrxNdjsonFramer(options = {}) {
+  const decoder = new TextDecoder();
+  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 null;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch (error) {
+      options.onMalformedLine?.({
+        line: trimmed,
+        error,
+        lineNumber: currentLineNumber,
+        atCompletion
+      });
+      return null;
+    }
+    const envelope = normalizeMatrxStreamEnvelope(parsed);
+    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 () => {
+    try {
+      while (!options.signal?.aborted && !consumerClosed) {
+        if (!await waitForReadCapacity()) return;
+        const { value, done } = await reader.read();
+        if (done) break;
+        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;
+        }
+      }
+    } catch (error) {
+      const aborted = options.signal?.aborted || consumerClosed || error instanceof Error && error.name === "AbortError";
+      if (!aborted) enqueueTerminal({ kind: "error", error });
+    } finally {
+      readerFinished = true;
+      reader.releaseLock();
+      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);
+    }
+    await readerPromise;
+  }
+}
+
+// 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 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 } : {}
+    }
+  );
+}
+
+// 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();
+  }
+}
+
+// matrx/operations.ts
+var RUNTIME_STATUSES = /* @__PURE__ */ new Set([
+  "pending",
+  "running",
+  "paused",
+  "waiting_input",
+  "completed",
+  "failed",
+  "cancelled"
+]);
+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 followRuntimeOperationToEnd(transport, executionId, options) {
+  const stallTimeoutMs = options.stallTimeoutMs ?? 45e3;
+  const reconnectLimit = options.reconnectLimit ?? 60;
+  const reconnectDelayMs = options.reconnectDelayMs ?? 2e3;
+  const outer = options.signal;
+  let cursor = options.lastEventSeq ?? 0;
+  let failures = 0;
+  while (!outer?.aborted && failures < reconnectLimit) {
+    const attempt = new AbortController();
+    const onOuterAbort = () => attempt.abort();
+    outer?.addEventListener("abort", onOuterAbort, { once: true });
+    let stallTimer = null;
+    const armStall = () => {
+      if (stallTimer !== null) clearTimeout(stallTimer);
+      stallTimer = setTimeout(() => attempt.abort(), stallTimeoutMs);
+    };
+    try {
+      const items = followRuntimeOperationEvents(transport, executionId, {
+        lastEventSeq: cursor,
+        signal: attempt.signal,
+        ...options.onMalformedFrame ? { onMalformedFrame: options.onMalformedFrame } : {}
+      });
+      armStall();
+      for await (const item of items) {
+        armStall();
+        failures = 0;
+        cursor = item.cursor;
+        if (item.type === "end") {
+          return { ended: true, status: item.status };
+        }
+        if (item.type === "event") {
+          options.onEvent(item.event, item.seq);
+        }
+      }
+      failures += 1;
+    } catch (error) {
+      if (outer?.aborted) break;
+      failures += 1;
+      options.onAttemptError?.(error);
+    } finally {
+      if (stallTimer !== null) clearTimeout(stallTimer);
+      outer?.removeEventListener("abort", onOuterAbort);
+    }
+    if (!outer?.aborted && failures < reconnectLimit) {
+      await new Promise((r) => setTimeout(r, reconnectDelayMs));
+    }
+  }
+  return { ended: false, status: null };
+}
+
+// react/use-agent-run.ts
+function useAgentRun(options) {
+  const [phase, setPhase] = useState("idle");
+  const [projection, setProjection] = useState(
+    null
+  );
+  const [error, setError] = useState(null);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const runSeqRef = useRef(0);
+  const controllerRef = useRef(null);
+  const requestIdRef = useRef(null);
+  const transportRef = useRef(null);
+  const abort = useCallback(() => {
+    controllerRef.current?.abort();
+  }, []);
+  useEffect(() => () => controllerRef.current?.abort(), []);
+  const runStream = useCallback(
+    async (open, seedConversationId) => {
+      const seq = ++runSeqRef.current;
+      const isCurrent = () => runSeqRef.current === seq;
+      controllerRef.current?.abort();
+      const controller = new AbortController();
+      controllerRef.current = controller;
+      requestIdRef.current = null;
+      const opts = optionsRef.current;
+      const transport = typeof opts.transport === "function" ? opts.transport() : opts.transport;
+      transportRef.current = transport;
+      setPhase("starting");
+      setError(null);
+      setProjection(null);
+      try {
+        const handle = await open(transport, {
+          ...opts.streamOptions,
+          signal: controller.signal
+        });
+        requestIdRef.current = handle.requestId;
+        let current = createAgentRequestProjection({
+          requestId: handle.requestId ?? crypto.randomUUID(),
+          conversationId: handle.conversationId ?? seedConversationId
+        });
+        if (isCurrent()) {
+          setPhase("streaming");
+          setProjection(current);
+        }
+        for await (const envelope of handle.events) {
+          current = projectAgentEvent(current, envelope);
+          if (isCurrent()) {
+            setProjection(current);
+            optionsRef.current.onProjection?.(current);
+          }
+        }
+        if (isCurrent()) {
+          setPhase(
+            current.status === "error" ? "error" : current.status === "cancelled" ? "cancelled" : "complete"
+          );
+          if (current.status === "error") {
+            const failure = {
+              type: "unknown",
+              message: typeof current.error?.user_message === "string" && current.error.user_message || typeof current.error?.message === "string" && current.error.message || "The agent run failed",
+              serverDetail: current.error
+            };
+            setError(failure);
+            optionsRef.current.onError?.(failure);
+          }
+        }
+        return current;
+      } catch (err) {
+        const failure = normalizeMatrxError(err);
+        if (isCurrent()) {
+          setPhase(failure.type === "abort_error" ? "cancelled" : "error");
+          if (failure.type !== "abort_error") {
+            setError(failure);
+            optionsRef.current.onError?.(failure);
+          }
+        }
+        throw err;
+      }
+    },
+    []
+  );
+  const start = useCallback(
+    (agentId, request) => runStream(
+      (transport, callOptions) => startAgentRun(transport, agentId, request, callOptions),
+      request.conversation_id
+    ),
+    [runStream]
+  );
+  const continueConversation = useCallback(
+    (conversationId, request) => runStream(
+      (transport, callOptions) => continueAgentConversation(
+        transport,
+        conversationId,
+        request,
+        callOptions
+      ),
+      conversationId
+    ),
+    [runStream]
+  );
+  const cancel = useCallback(
+    async (mode = "cancel") => {
+      const requestId = requestIdRef.current;
+      const transport = transportRef.current;
+      if (!requestId || !transport) return null;
+      return cancelAgentRun(transport, requestId, { mode });
+    },
+    []
+  );
+  const reset = useCallback(() => {
+    runSeqRef.current += 1;
+    controllerRef.current?.abort();
+    controllerRef.current = null;
+    requestIdRef.current = null;
+    setPhase("idle");
+    setProjection(null);
+    setError(null);
+  }, []);
+  return {
+    phase,
+    projection,
+    requestId: projection?.requestId ?? null,
+    conversationId: projection?.conversationId ?? null,
+    error,
+    start,
+    continueConversation,
+    cancel,
+    abort,
+    reset
+  };
+}
+
+// react/use-follow-runtime-operation.ts
+import { useCallback as useCallback2, useEffect as useEffect2, useRef as useRef2, useState as useState2 } from "react";
+function useFollowRuntimeOperation(options) {
+  const [following, setFollowing] = useState2(false);
+  const [ended, setEnded] = useState2(false);
+  const [status, setStatus] = useState2(
+    null
+  );
+  const optionsRef = useRef2(options);
+  optionsRef.current = options;
+  const { executionId, enabled = true } = options;
+  const active = enabled && !!executionId;
+  const follow = useCallback2(
+    (id, signal, isCurrent) => {
+      const opts = optionsRef.current;
+      const transport = typeof opts.transport === "function" ? opts.transport() : opts.transport;
+      return followRuntimeOperationToEnd(transport, id, {
+        signal,
+        ...opts.lastEventSeq !== void 0 ? { lastEventSeq: opts.lastEventSeq } : {},
+        ...opts.stallTimeoutMs !== void 0 ? { stallTimeoutMs: opts.stallTimeoutMs } : {},
+        ...opts.reconnectLimit !== void 0 ? { reconnectLimit: opts.reconnectLimit } : {},
+        ...opts.reconnectDelayMs !== void 0 ? { reconnectDelayMs: opts.reconnectDelayMs } : {},
+        onEvent: (event, seq) => {
+          if (isCurrent()) optionsRef.current.onEvent?.(event, seq);
+        }
+      });
+    },
+    []
+  );
+  useEffect2(() => {
+    if (!active || !executionId) return;
+    let current = true;
+    const controller = new AbortController();
+    setFollowing(true);
+    setEnded(false);
+    setStatus(null);
+    void follow(executionId, controller.signal, () => current).then((result) => {
+      if (!current) return;
+      setFollowing(false);
+      setEnded(result.ended);
+      setStatus(result.status);
+      optionsRef.current.onSettled?.(result);
+    }).catch(() => {
+      if (!current) return;
+      setFollowing(false);
+      optionsRef.current.onSettled?.({ ended: false, status: null });
+    });
+    return () => {
+      current = false;
+      controller.abort();
+      setFollowing(false);
+    };
+  }, [active, executionId, follow]);
+  return { following, ended, status };
+}
+export {
+  useAgentRun,
+  useFollowRuntimeOperation
+};
+//# sourceMappingURL=index.js.map