@ai-matrx/agents 0.35.0 → 0.37.0

package/dist/matrx/index.cjs

@@ -26,6 +26,7 @@ __export(matrx_exports, {
   MATRX_LIVE_STREAM_UNAVAILABLE: () => MATRX_LIVE_STREAM_UNAVAILABLE,
   MATRX_RESUME_CONFLICT: () => MATRX_RESUME_CONFLICT,
   MATRX_RUN_IN_PROGRESS: () => MATRX_RUN_IN_PROGRESS,
+  MATRX_UI_ONLY_BODY_FIELDS: () => MATRX_UI_ONLY_BODY_FIELDS,
   MatrxApiError: () => MatrxApiError,
   MatrxRunError: () => MatrxRunError,
   OrganizationContextError: () => OrganizationContextError,
@@ -41,6 +42,10 @@ __export(matrx_exports, {
   applyOrganizationContextHeader: () => applyOrganizationContextHeader,
   assertOrganizationMatchesOperation: () => assertOrganizationMatchesOperation,
   assertQueryOrganizationMatchesContext: () => assertQueryOrganizationMatchesContext,
+  bareStatusSentence: () => bareStatusSentence,
+  buildMatrxRequestBody: () => buildMatrxRequestBody,
+  buildMatrxRequestUrl: () => buildMatrxRequestUrl,
+  buildSafeRequestLog: () => buildSafeRequestLog,
   cancelAgentRun: () => cancelAgentRun,
   continueAgentConversation: () => continueAgentConversation,
   continueEphemeralConversationStart: () => continueEphemeralConversationStart,
@@ -48,6 +53,7 @@ __export(matrx_exports, {
   createMatrxTransport: () => createMatrxTransport,
   createOrganizationOperation: () => createOrganizationOperation,
   describeBackendFailure: () => describeBackendFailure,
+  executeMatrxCall: () => executeMatrxCall,
   extractMatrxErrorCode: () => extractMatrxErrorCode,
   extractMatrxErrorMessage: () => extractMatrxErrorMessage,
   fetchWithMatrxProtocolFallback: () => fetchWithMatrxProtocolFallback,
@@ -58,6 +64,8 @@ __export(matrx_exports, {
   getRuntimeOperationStatus: () => getRuntimeOperationStatus,
   getRuntimeOperationsByLink: () => getRuntimeOperationsByLink,
   getUserMessage: () => getUserMessage,
+  honestTransportMessage: () => honestTransportMessage,
+  isBareTransportCode: () => isBareTransportCode,
   isCoveredAiPath: () => isCoveredAiPath,
   isGenericUserMessage: () => isGenericUserMessage,
   isJobOutputKind: () => isJobOutputKind,
@@ -77,6 +85,7 @@ __export(matrx_exports, {
   parseCallApiError: () => parseCallApiError,
   parseHttpError: () => parseHttpError,
   parseHttpErrorBody: () => parseHttpErrorBody,
+  parseMatrxNdjsonResponse: () => parseMatrxNdjsonResponse,
   parsePersistedBackendError: () => parsePersistedBackendError,
   parseStreamError: () => parseStreamError,
   providerSessionFailureBody: () => providerSessionFailureBody,
@@ -86,6 +95,7 @@ __export(matrx_exports, {
   readLiveStreamUnavailable: () => readLiveStreamUnavailable,
   readMatrxErrorCode: () => readMatrxErrorCode,
   readMatrxErrorCodeFromMessage: () => readMatrxErrorCodeFromMessage,
+  redactUrlForRequestLog: () => redactUrlForRequestLog,
   rejoinRuntimeOperation: () => rejoinRuntimeOperation,
   reportProviderSessionFailure: () => reportProviderSessionFailure,
   requireOrganizationContext: () => requireOrganizationContext,
@@ -100,6 +110,7 @@ __export(matrx_exports, {
   runWaitTimeoutMessage: () => runWaitTimeoutMessage,
   runtimeOperationRejoinPath: () => runtimeOperationRejoinPath,
   settleRunPickup: () => settleRunPickup,
+  shouldReportMatrxCallError: () => shouldReportMatrxCallError,
   startAgentRun: () => startAgentRun,
   startMandateRun: () => startMandateRun,
   streamErrorText: () => streamErrorText,
@@ -184,1666 +195,1893 @@ function extractMatrxErrorCode(serverDetail) {
 // matrx/client.ts
 var import_data = require("@ai-matrx/data");
 var import_data2 = require("@ai-matrx/data");
+var import_net2 = require("@ai-matrx/data/net");
 
-// matrx/org-context.ts
-var import_uuid = require("@ai-matrx/kit/uuid");
-var OrganizationContextError = class extends Error {
+// matrx/backend-errors.ts
+var BackendApiError = class extends Error {
+  /** Machine-readable error code */
   code;
-  constructor(code, message) {
-    super(message);
-    this.name = "OrganizationContextError";
-    this.code = code;
+  /** Developer-facing detail */
+  detail;
+  /** Safe to display directly in the UI */
+  userMessage;
+  /** Extra info (validation errors, etc.) */
+  details;
+  /** Unique request ID for support/debugging */
+  requestId;
+  /** HTTP status code (if from an HTTP response) */
+  status;
+  constructor(data) {
+    super(data.userMessage);
+    this.name = "BackendApiError";
+    this.code = data.code;
+    this.detail = data.detail;
+    this.userMessage = data.userMessage;
+    this.details = data.details ?? null;
+    this.requestId = data.requestId ?? "";
+    this.status = data.status ?? null;
+  }
+  /** Convert to the wire format for logging */
+  toJSON() {
+    return {
+      error: this.code,
+      message: this.detail,
+      user_message: this.userMessage,
+      details: this.details,
+      request_id: this.requestId
+    };
   }
 };
-function createOrganizationOperation(organizationId) {
-  const organization_id = requireOrganizationContext(organizationId);
-  return Object.freeze({ organization_id });
-}
-function assertOrganizationMatchesOperation(operation, organizationId) {
-  if (operation.organization_id !== requireOrganizationContext(organizationId)) {
-    throw new OrganizationContextError(
-      "organization_context_mismatch",
-      "Organization ID must match the request operation."
-    );
+var StreamTransportError = class extends BackendApiError {
+  /** Always true — reattach and let the server settle the outcome. */
+  resumable = true;
+  constructor(data) {
+    super({
+      code: "stream_transport_lost",
+      detail: data.detail,
+      userMessage: "The connection dropped. Your run is still going on the server \u2014 reconnecting to it now.",
+      details: data.details ?? null,
+      ...data.requestId !== void 0 ? { requestId: data.requestId } : {}
+    });
+    this.name = "StreamTransportError";
   }
-}
-function requireOrganizationContext(selectedOrganizationId, overrideOrganizationId) {
-  const candidate = overrideOrganizationId ?? selectedOrganizationId;
-  if (typeof candidate !== "string" || candidate.trim().length === 0) {
-    throw new OrganizationContextError(
-      "organization_context_required",
-      "Select an organization before sending this request."
-    );
+};
+function isStreamTransportLost(error) {
+  if (error instanceof StreamTransportError) return true;
+  if (error instanceof BackendApiError) {
+    return error.code === "stream_transport_lost";
   }
-  const normalized = candidate.trim();
-  if (!(0, import_uuid.isUuidShape)(normalized)) {
-    throw new OrganizationContextError(
-      "organization_context_invalid",
-      "The selected organization ID is invalid."
-    );
+  if (error && typeof error === "object") {
+    const code = error.code;
+    if (code === "stream_transport_lost") return true;
+    const errorType = error.error_type;
+    if (errorType === "transport_lost") return true;
   }
-  return normalized.toLowerCase();
+  return false;
 }
-function applyOrganizationContextHeader(headers, organizationId) {
-  const normalizedOrganizationId = requireOrganizationContext(organizationId);
-  for (const [name, value] of Object.entries(headers)) {
-    if (name.toLowerCase() === "x-organization-id" && value.trim().toLowerCase() !== normalizedOrganizationId) {
-      throw new OrganizationContextError(
-        "organization_context_mismatch",
-        "X-Organization-Id must match the request context organization."
-      );
+async function parseHttpError(response) {
+  const status = response.status;
+  let body = null;
+  try {
+    body = await response.json();
+  } catch {
+    try {
+      const text = await response.text();
+      return new BackendApiError({
+        code: statusToCode(status),
+        detail: text || `HTTP ${status}`,
+        userMessage: text || `Request failed (${status})`,
+        status
+      });
+    } catch {
+      return new BackendApiError({
+        code: statusToCode(status),
+        detail: `HTTP ${status}`,
+        userMessage: `Request failed (${status})`,
+        status
+      });
     }
   }
-  const withoutOrganizationHeader = Object.fromEntries(
-    Object.entries(headers).filter(
-      ([name]) => name.toLowerCase() !== "x-organization-id"
-    )
-  );
-  return {
-    ...withoutOrganizationHeader,
-    "X-Organization-Id": normalizedOrganizationId
-  };
-}
-function assertQueryOrganizationMatchesContext(queryParams, organizationId) {
-  if (!queryParams || queryParams.organization_id === void 0) return;
-  const queryOrganizationId = requireOrganizationContext(
-    String(queryParams.organization_id)
-  );
-  if (queryOrganizationId !== requireOrganizationContext(organizationId)) {
-    throw new OrganizationContextError(
-      "organization_context_mismatch",
-      "Query organization_id must match the request context organization."
-    );
-  }
+  return parseHttpErrorBody(body, status);
 }
-
-// matrx/protocol.ts
-var import_net = require("@ai-matrx/data/net");
-var MATRX_AI_API_VERSION_DEFAULT = "v2";
-var V2_COVERED_AI_PATH_TEMPLATES = [
-  "/ai/manual",
-  "/ai/chat",
-  "/ai/agents/{agent_id}",
-  "/ai/agent/{agent_id}",
-  // singular alias — behaves identically
-  "/ai/conversations/{conversation_id}",
-  "/ai/conversation/{conversation_id}",
-  // singular alias
-  "/ai/prompts/{prompt_id}",
-  // saved-prompt execution
-  "/ai/mandates/{mandate_key}"
-  // THE MANDATE DOOR — `/v2` sibling exists (routers/v2.py)
-];
-function toV2Path(path) {
-  const withLead = path.startsWith("/") ? path : `/${path}`;
-  if (withLead.startsWith("/api/")) {
-    const rest = withLead.slice("/api".length);
-    return rest.startsWith("/v2/") ? withLead : `/api/v2${rest}`;
+function parseHttpErrorBody(body, status) {
+  if (!body) {
+    return new BackendApiError({
+      code: statusToCode(status),
+      detail: `HTTP ${status}`,
+      userMessage: `Request failed (${status})`,
+      status
+    });
   }
-  return withLead.startsWith("/v2/") ? withLead : `/v2${withLead}`;
-}
-var COVERED_INTERPOLATED_PATH = [
-  /^(?:\/api)?\/ai\/manual$/,
-  /^(?:\/api)?\/ai\/chat$/,
-  /^(?:\/api)?\/ai\/agents\/[^/]+$/,
-  /^(?:\/api)?\/ai\/agent\/[^/]+$/,
-  /^(?:\/api)?\/ai\/conversations\/[^/]+$/,
-  /^(?:\/api)?\/ai\/conversation\/[^/]+$/,
-  /^(?:\/api)?\/ai\/prompts\/[^/]+$/,
-  // `/warm` etc. deliberately don't match
-  /^(?:\/api)?\/ai\/mandates\/[^/]+$/
-  // the mandate door
-];
-function isCoveredAiPath(path) {
-  return COVERED_INTERPOLATED_PATH.some((re) => re.test(path));
-}
-function isV2Path(pathOrUrl) {
-  return /\/v2\/ai\//.test(pathOrUrl);
-}
-function toV1FallbackUrl(url) {
-  return url.replace(/\/v2\/ai\//, "/ai/");
-}
-function applyAiApiVersion(path, version) {
-  if (version !== "v2") return path;
-  return isCoveredAiPath(path) ? toV2Path(path) : path;
-}
-async function fetchWithMatrxProtocolFallback(url, init, opts = {}) {
-  const { onDowngrade, ...fetchOpts } = opts;
-  const logDowngrade = (reason, status2) => {
-    console.warn(
-      `[matrx] ai_v2_downgrade \u2192 retrying on v1. v2=${url} reason=${reason}`
-    );
-    onDowngrade?.({ url, reason, ...status2 !== void 0 ? { status: status2 } : {} });
-  };
-  if (!isV2Path(url)) return (0, import_net.resilientFetch)(url, init, fetchOpts);
-  let result;
-  try {
-    result = await (0, import_net.resilientFetch)(url, init, fetchOpts);
-  } catch (err) {
-    const isAbort = (0, import_net.isNetError)(err) && err.code === "aborted" || err instanceof Error && err.name === "AbortError";
-    if (isAbort) throw err;
-    logDowngrade(String(err));
-    return (0, import_net.resilientFetch)(toV1FallbackUrl(url), init, fetchOpts);
+  if (typeof body.error === "string" && typeof body.user_message === "string") {
+    return new BackendApiError({
+      code: body.error,
+      detail: body.message || `HTTP ${status}`,
+      userMessage: body.user_message,
+      details: body.details ?? null,
+      requestId: typeof body.request_id === "string" ? body.request_id : void 0,
+      status
+    });
   }
-  const status = result.response.status;
-  if (status === 404 || status === 405 || status >= 500) {
-    logDowngrade(`HTTP ${status}`, status);
-    return (0, import_net.resilientFetch)(toV1FallbackUrl(url), init, fetchOpts);
+  if (typeof body.error === "object" && body.error !== null) {
+    const errorObj = body.error;
+    return new BackendApiError({
+      code: errorObj.type || errorObj.error || statusToCode(status),
+      detail: errorObj.message || `HTTP ${status}`,
+      userMessage: errorObj.user_message || errorObj.user_visible_message || errorObj.message || `Request failed (${status})`,
+      details: errorObj.details ?? null,
+      requestId: typeof errorObj.request_id === "string" ? errorObj.request_id : void 0,
+      status
+    });
   }
-  return result;
-}
-function aiVersionPathOverrides(version) {
-  if (version !== "v2") return {};
-  const map = {};
-  for (const template of V2_COVERED_AI_PATH_TEMPLATES) {
-    map[template] = toV2Path(template);
+  if (Array.isArray(body.detail)) {
+    const first = body.detail[0];
+    const firstMsg = first && typeof first.msg === "string" ? first.msg : null;
+    return new BackendApiError({
+      code: statusToCode(status),
+      detail: firstMsg ? `Validation error: ${firstMsg}` : JSON.stringify(body.detail),
+      userMessage: firstMsg || `Request failed (${status})`,
+      details: body.detail,
+      status
+    });
   }
-  return map;
-}
-
-// 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 ((0, import_data.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") };
-}
-var PRODUCTION_CONNECT_TIMEOUT_MS = 15e3;
-function stripContentType(headers) {
-  return Object.fromEntries(
-    Object.entries(headers).filter(
-      ([name]) => name.toLowerCase() !== "content-type"
-    )
-  );
-}
-function createMatrxTransport(options) {
-  const {
-    baseUrl,
-    resolveTarget,
-    credentials,
-    organizationId,
-    aiApiVersion,
-    connectTimeoutMs = PRODUCTION_CONNECT_TIMEOUT_MS,
-    totalTimeoutMs = null,
-    expectedErrorStatuses,
-    diagnostics,
-    source = "matrxTransport"
-  } = options;
-  if (baseUrl === void 0 === (resolveTarget === void 0)) {
-    throw new Error(
-      "createMatrxTransport: provide exactly one of `baseUrl` or `resolveTarget`."
-    );
+  if (typeof body.detail === "object" && body.detail !== null && !Array.isArray(body.detail)) {
+    const d = body.detail;
+    const code = typeof d.code === "string" && d.code || typeof d.error === "string" && d.error || statusToCode(status);
+    const message = typeof d.message === "string" && d.message || typeof d.detail === "string" && d.detail || `HTTP ${status}`;
+    return new BackendApiError({
+      code,
+      detail: message,
+      userMessage: typeof d.user_message === "string" && d.user_message || typeof d.user_visible_message === "string" && d.user_visible_message || message,
+      details: d.details ?? d,
+      requestId: typeof d.request_id === "string" ? d.request_id : void 0,
+      status
+    });
   }
-  const resolve = resolveTarget ?? (() => ({ baseUrl }));
-  const resolveVersion = () => {
-    if (aiApiVersion === void 0) return MATRX_AI_API_VERSION_DEFAULT;
-    return typeof aiApiVersion === "function" ? aiApiVersion() : aiApiVersion;
-  };
-  const resolveOrganizationId = () => {
-    if (organizationId === void 0) return null;
-    const candidate = typeof organizationId === "function" ? organizationId() : organizationId;
-    return requireOrganizationContext(candidate);
-  };
-  return {
-    async fetch(path, init) {
-      const target = resolve();
-      const versionedPath = applyAiApiVersion(path, resolveVersion());
-      const url = `${target.baseUrl}${versionedPath}`;
-      const credentialHeaders = credentials ? (0, import_data2.credentialToHeaders)(await credentials.get()) : {};
-      let headers = {
-        ...init.headers,
-        ...stripContentType(credentialHeaders),
-        ...stripContentType(target.policyHeaders ?? {})
-      };
-      const orgId = resolveOrganizationId();
-      if (orgId !== null) {
-        headers = applyOrganizationContextHeader(headers, orgId);
-      }
-      const info = {
-        url,
-        method: init.method,
-        path,
-        channel: target.channel ?? "default",
-        source
-      };
-      diagnostics?.onRequest?.(info);
-      let response;
-      try {
-        ({ response } = await fetchWithMatrxProtocolFallback(
-          url,
-          {
-            method: init.method,
-            headers,
-            ...init.body !== void 0 ? { body: init.body } : {}
-          },
-          {
-            ...init.signal ? { signal: init.signal } : {},
-            connectTimeoutMs,
-            totalTimeoutMs,
-            throwOnHttpError: false,
-            ...diagnostics?.onProtocolDowngrade ? { onDowngrade: diagnostics.onProtocolDowngrade } : {}
-          }
-        ));
-      } catch (err) {
-        diagnostics?.onError?.(normalizeMatrxError(err), info);
-        throw err;
-      }
-      if (!response.ok && !expectedErrorStatuses?.includes(response.status)) {
-        const serverDetail = await response.clone().json().catch(() => void 0);
-        const code = extractMatrxErrorCode(serverDetail);
-        diagnostics?.onError?.(
-          {
-            type: classifyStatus(response.status),
-            message: extractMatrxErrorMessage(serverDetail) ?? `HTTP ${response.status}`,
-            status: response.status,
-            serverDetail,
-            ...code ? { code } : {}
-          },
-          info
-        );
-      }
-      return response;
-    }
-  };
-}
-
-// 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
-  };
-}
-
-// stream/ndjson.ts
-var DEFAULT_MATRX_NDJSON_READ_AHEAD = 64;
-function isRecord2(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+  return new BackendApiError({
+    code: typeof body.error === "string" ? body.error : statusToCode(status),
+    detail: body.message || body.detail || body.error || `HTTP ${status}`,
+    userMessage: body.user_message || body.user_visible_message || body.message || body.detail || `Request failed (${status})`,
+    details: body.details ?? null,
+    requestId: typeof body.request_id === "string" ? body.request_id : void 0,
+    status
+  });
 }
-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;
-    const streamId = typeof value.stream_id === "string" ? value.stream_id : void 0;
-    return {
-      event: value.event,
-      data: value.data,
-      ...streamId === void 0 ? {} : { stream_id: streamId },
-      ...streamSeq === void 0 ? {} : { stream_seq: streamSeq }
-    };
-  }
-  if (value.e === "c" && typeof value.t === "string") {
-    const streamId = typeof value.stream_id === "string" ? value.stream_id : void 0;
-    const streamSeq = typeof value.stream_seq === "number" && Number.isFinite(value.stream_seq) ? value.stream_seq : void 0;
-    return {
-      event: "chunk",
-      data: { text: value.t },
-      ...streamId === void 0 ? {} : { stream_id: streamId },
-      ...streamSeq === void 0 ? {} : { stream_seq: streamSeq }
-    };
-  }
-  if (value.e === "r" && typeof value.t === "string") {
-    const streamId = typeof value.stream_id === "string" ? value.stream_id : void 0;
-    const streamSeq = typeof value.stream_seq === "number" && Number.isFinite(value.stream_seq) ? value.stream_seq : void 0;
-    return {
-      event: "reasoning_chunk",
-      data: { text: value.t },
-      ...streamId === void 0 ? {} : { stream_id: streamId },
-      ...streamSeq === void 0 ? {} : { stream_seq: streamSeq }
-    };
-  }
-  return null;
+function parseCallApiError(error) {
+  const status = error.status ?? 500;
+  const body = error.serverDetail && typeof error.serverDetail === "object" && !Array.isArray(error.serverDetail) ? error.serverDetail : { message: error.message };
+  return parseHttpErrorBody(body, status);
 }
-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
+function parseStreamError(data) {
+  if (!data || typeof data !== "object") {
+    return new BackendApiError({
+      code: "internal_error",
+      detail: typeof data === "string" ? data : "Unknown streaming error",
+      userMessage: typeof data === "string" ? data : "Something went wrong"
     });
-    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;
   }
+  const obj = data;
+  const details = typeof obj.details === "object" && obj.details !== null ? obj.details : null;
+  return new BackendApiError({
+    code: obj.code || obj.error_type || obj.error || "internal_error",
+    detail: obj.message || "Streaming error",
+    userMessage: obj.user_message || obj.message || "Something went wrong",
+    details,
+    requestId: typeof obj.request_id === "string" ? obj.request_id : typeof details?.request_id === "string" ? details.request_id : void 0
+  });
 }
-
-// matrx/internal.ts
-function encodePathSegment(value) {
-  return encodeURIComponent(value);
+function parsePersistedBackendError(data, requestId = "") {
+  if (!data || typeof data !== "object") return null;
+  const error = data;
+  const failures = Array.isArray(error.failures) ? error.failures : [];
+  const firstSpecific = failures.find(
+    (failure) => typeof failure === "object" && failure !== null && typeof failure.message === "string"
+  );
+  const summary = typeof error.message === "string" ? error.message : "Backend operation failed";
+  const specific = typeof firstSpecific?.message === "string" ? firstSpecific.message : summary;
+  const detail = specific === summary ? summary : `${summary}: ${specific}`;
+  const code = typeof error.type === "string" ? error.type : "internal_error";
+  const userMessage = typeof error.user_message === "string" && error.user_message ? error.user_message : detail;
+  return new BackendApiError({
+    code,
+    detail,
+    userMessage,
+    details: error,
+    requestId
+  });
 }
-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}` : "";
+var GENERIC_MESSAGE_PATTERNS = [
+  /failed unexpectedly/i,
+  /^\s*something went wrong/i,
+  /please try again(\s+later)?\.?\s*$/i,
+  /^\s*request failed\b/i,
+  /^\s*unknown (streaming )?error/i,
+  /^\s*internal server error\.?\s*$/i
+];
+function isGenericUserMessage(message) {
+  const value = (message ?? "").trim();
+  if (!value) return true;
+  return GENERIC_MESSAGE_PATTERNS.some((pattern) => pattern.test(value));
 }
-async function readServerDetail(response) {
+function unwrapUpstreamError(message) {
+  const start = message.indexOf("{");
+  const end = message.lastIndexOf("}");
+  if (start < 0 || end <= start) return null;
+  let parsed;
   try {
-    return await response.json();
+    parsed = JSON.parse(message.slice(start, end + 1));
   } catch {
-    return void 0;
+    return null;
   }
-}
-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) {
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const body = parsed;
+  const inner = typeof body.message === "string" && body.message || typeof body.detail === "string" && body.detail || "";
+  if (!inner) return null;
+  const statusMatch = /\bHTTP (\d{3})\b/.exec(message.slice(0, start));
   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
+    message: inner,
+    code: typeof body.error_type === "string" && body.error_type || typeof body.error === "string" && body.error || null,
+    userMessage: typeof body.user_message === "string" ? body.user_message : null,
+    requestId: typeof body.request_id === "string" ? body.request_id : null,
+    status: statusMatch ? Number(statusMatch[1]) : null
   };
 }
-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."
-    });
+function describeBackendFailure(error) {
+  const chain = [];
+  let code = "internal_error";
+  let requestId = "";
+  let status = null;
+  let userFacing = null;
+  if (error instanceof BackendApiError) {
+    code = error.code;
+    requestId = error.requestId;
+    status = error.status;
+    userFacing = error.userMessage;
+    if (error.detail) chain.push(error.detail);
+    if (error.userMessage && error.userMessage !== error.detail) {
+      chain.push(error.userMessage);
+    }
+  } else if (error instanceof Error) {
+    chain.push(error.message);
+    userFacing = error.message;
+  } else if (typeof error === "string") {
+    chain.push(error);
+    userFacing = error;
+  } else {
+    chain.push("Unknown error");
   }
-  return response;
-}
-
-// 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();
+  for (let cursor = 0; cursor < chain.length && cursor < 12; cursor += 1) {
+    const upstream = unwrapUpstreamError(chain[cursor] ?? "");
+    if (!upstream || chain.includes(upstream.message)) continue;
+    chain.push(upstream.message);
+    if (upstream.code) code = upstream.code;
+    if (upstream.requestId) requestId = upstream.requestId;
+    if (upstream.status !== null) status = upstream.status;
   }
-  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 = "";
+  const specific = [...chain].reverse().find((message) => !isGenericUserMessage(message));
+  const cause = specific ?? chain[0] ?? "Unknown error";
+  const headlineWasGeneric = isGenericUserMessage(userFacing);
   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 };
-    }
+    code,
+    cause,
+    headline: headlineWasGeneric ? cause : userFacing ?? cause,
+    headlineWasGeneric,
+    chain,
+    requestId,
+    status
   };
 }
-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();
+function getUserMessage(error) {
+  if (error instanceof BackendApiError) {
+    return error.userMessage;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  if (typeof error === "object" && error !== null && typeof error.message === "string" && error.message) {
+    return error.message;
   }
+  return "Something went wrong";
 }
-
-// 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;
+function statusToCode(status) {
+  switch (status) {
+    case 401:
+      return "auth_required";
+    case 403:
+      return "admin_required";
+    case 404:
+      return "not_found";
+    case 422:
+      return "validation_error";
+    default:
+      return "internal_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;
+
+// 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;
+    const streamId = typeof value.stream_id === "string" ? value.stream_id : void 0;
+    return {
+      event: value.event,
+      data: value.data,
+      ...streamId === void 0 ? {} : { stream_id: streamId },
+      ...streamSeq === void 0 ? {} : { stream_seq: streamSeq }
+    };
+  }
+  if (value.e === "c" && typeof value.t === "string") {
+    const streamId = typeof value.stream_id === "string" ? value.stream_id : void 0;
+    const streamSeq = typeof value.stream_seq === "number" && Number.isFinite(value.stream_seq) ? value.stream_seq : void 0;
+    return {
+      event: "chunk",
+      data: { text: value.t },
+      ...streamId === void 0 ? {} : { stream_id: streamId },
+      ...streamSeq === void 0 ? {} : { stream_seq: streamSeq }
+    };
   }
-}
-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 {
+  if (value.e === "r" && typeof value.t === "string") {
+    const streamId = typeof value.stream_id === "string" ? value.stream_id : void 0;
+    const streamSeq = typeof value.stream_seq === "number" && Number.isFinite(value.stream_seq) ? value.stream_seq : void 0;
+    return {
+      event: "reasoning_chunk",
+      data: { text: value.t },
+      ...streamId === void 0 ? {} : { stream_id: streamId },
+      ...streamSeq === void 0 ? {} : { stream_seq: streamSeq }
+    };
   }
   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 } : {}
+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 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;
+    const envelope = normalizeMatrxStreamEnvelope(parsed);
+    if (!envelope) {
+      options.onUnknownEnvelope?.(parsed);
+      return null;
     }
-    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;
+    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);
       }
-      if (frame.seq !== null && frame.seq > cursor) cursor = frame.seq;
-      yield { type: "event", event, seq: frame.seq, cursor };
-      continue;
+      return envelopes;
     }
-    yield { type: "liveness", cursor };
+  };
+}
+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 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 attempt2 = new AbortController();
-    const onOuterAbort = () => attempt2.abort();
-    outer?.addEventListener("abort", onOuterAbort, { once: true });
-    let stallTimer = null;
-    const armStall = () => {
-      if (stallTimer !== null) clearTimeout(stallTimer);
-      stallTimer = setTimeout(() => attempt2.abort(), stallTimeoutMs);
-    };
-    try {
-      const items = followRuntimeOperationEvents(transport, executionId, {
-        lastEventSeq: cursor,
-        signal: attempt2.signal,
-        ...options.onMalformedFrame ? { onMalformedFrame: options.onMalformedFrame } : {}
+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;
       });
-      armStall();
-      for await (const item of items) {
-        armStall();
-        failures = 0;
-        cursor = item.cursor;
-        if (item.type === "end") {
-          return { ended: true, status: item.status };
+    }
+    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 (item.type === "event") {
-          options.onEvent(item.event, item.seq);
+      }
+      if (!options.signal?.aborted && !consumerClosed) {
+        for (const envelope of framer.finish()) {
+          if (!await enqueueEvent(envelope)) return;
         }
       }
-      failures += 1;
     } catch (error) {
-      if (outer?.aborted) break;
-      failures += 1;
-      options.onAttemptError?.(error);
+      const aborted = options.signal?.aborted || consumerClosed || error instanceof Error && error.name === "AbortError";
+      if (!aborted) enqueueTerminal({ kind: "error", error });
     } finally {
-      if (stallTimer !== null) clearTimeout(stallTimer);
-      outer?.removeEventListener("abort", onOuterAbort);
+      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;
     }
-    if (!outer?.aborted && failures < reconnectLimit) {
-      await new Promise((r) => setTimeout(r, reconnectDelayMs));
+  } finally {
+    consumerClosed = true;
+    wakeWaitingProducer();
+    wakeWaitingConsumer();
+    options.signal?.removeEventListener("abort", onAbort);
+    if (!readerFinished) {
+      await reader.cancel().catch(() => void 0);
     }
+    await readerPromise;
   }
-  return { ended: false, status: null };
 }
-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 } : {}
+
+// matrx/org-context.ts
+var import_uuid = require("@ai-matrx/kit/uuid");
+var OrganizationContextError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "OrganizationContextError";
+    this.code = code;
+  }
+};
+function createOrganizationOperation(organizationId) {
+  const organization_id = requireOrganizationContext(organizationId);
+  return Object.freeze({ organization_id });
+}
+function assertOrganizationMatchesOperation(operation, organizationId) {
+  if (operation.organization_id !== requireOrganizationContext(organizationId)) {
+    throw new OrganizationContextError(
+      "organization_context_mismatch",
+      "Organization ID must match the request operation."
+    );
+  }
+}
+function requireOrganizationContext(selectedOrganizationId, overrideOrganizationId) {
+  const candidate = overrideOrganizationId ?? selectedOrganizationId;
+  if (typeof candidate !== "string" || candidate.trim().length === 0) {
+    throw new OrganizationContextError(
+      "organization_context_required",
+      "Select an organization before sending this request."
+    );
+  }
+  const normalized = candidate.trim();
+  if (!(0, import_uuid.isUuidShape)(normalized)) {
+    throw new OrganizationContextError(
+      "organization_context_invalid",
+      "The selected organization ID is invalid."
+    );
+  }
+  return normalized.toLowerCase();
+}
+function applyOrganizationContextHeader(headers, organizationId) {
+  const normalizedOrganizationId = requireOrganizationContext(organizationId);
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() === "x-organization-id" && value.trim().toLowerCase() !== normalizedOrganizationId) {
+      throw new OrganizationContextError(
+        "organization_context_mismatch",
+        "X-Organization-Id must match the request context organization."
+      );
     }
+  }
+  const withoutOrganizationHeader = Object.fromEntries(
+    Object.entries(headers).filter(
+      ([name]) => name.toLowerCase() !== "x-organization-id"
+    )
   );
-  return toRunHandle(response, options);
+  return {
+    ...withoutOrganizationHeader,
+    "X-Organization-Id": normalizedOrganizationId
+  };
+}
+function assertQueryOrganizationMatchesContext(queryParams, organizationId) {
+  if (!queryParams || queryParams.organization_id === void 0) return;
+  const queryOrganizationId = requireOrganizationContext(
+    String(queryParams.organization_id)
+  );
+  if (queryOrganizationId !== requireOrganizationContext(organizationId)) {
+    throw new OrganizationContextError(
+      "organization_context_mismatch",
+      "Query organization_id must match the request context organization."
+    );
+  }
 }
 
-// matrx/rejoin.ts
-var MATRX_RUN_IN_PROGRESS = "run_in_progress";
-var MATRX_RESUME_CONFLICT = "resume_conflict";
-var MATRX_LIVE_STREAM_UNAVAILABLE = "live_stream_unavailable";
-function isRecord3(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+// matrx/protocol.ts
+var import_net = require("@ai-matrx/data/net");
+var MATRX_AI_API_VERSION_DEFAULT = "v2";
+var V2_COVERED_AI_PATH_TEMPLATES = [
+  "/ai/manual",
+  "/ai/chat",
+  "/ai/agents/{agent_id}",
+  "/ai/agent/{agent_id}",
+  // singular alias — behaves identically
+  "/ai/conversations/{conversation_id}",
+  "/ai/conversation/{conversation_id}",
+  // singular alias
+  "/ai/prompts/{prompt_id}",
+  // saved-prompt execution
+  "/ai/mandates/{mandate_key}"
+  // THE MANDATE DOOR — `/v2` sibling exists (routers/v2.py)
+];
+function toV2Path(path) {
+  const withLead = path.startsWith("/") ? path : `/${path}`;
+  if (withLead.startsWith("/api/")) {
+    const rest = withLead.slice("/api".length);
+    return rest.startsWith("/v2/") ? withLead : `/api/v2${rest}`;
+  }
+  return withLead.startsWith("/v2/") ? withLead : `/v2${withLead}`;
 }
-function nonBlank(value) {
-  return typeof value === "string" && value.trim() ? value : null;
+var COVERED_INTERPOLATED_PATH = [
+  /^(?:\/api)?\/ai\/manual$/,
+  /^(?:\/api)?\/ai\/chat$/,
+  /^(?:\/api)?\/ai\/agents\/[^/]+$/,
+  /^(?:\/api)?\/ai\/agent\/[^/]+$/,
+  /^(?:\/api)?\/ai\/conversations\/[^/]+$/,
+  /^(?:\/api)?\/ai\/conversation\/[^/]+$/,
+  /^(?:\/api)?\/ai\/prompts\/[^/]+$/,
+  // `/warm` etc. deliberately don't match
+  /^(?:\/api)?\/ai\/mandates\/[^/]+$/
+  // the mandate door
+];
+function isCoveredAiPath(path) {
+  return COVERED_INTERPOLATED_PATH.some((re) => re.test(path));
 }
-function detailCandidates(body) {
-  if (!isRecord3(body)) return [];
-  const out = [];
-  if (isRecord3(body.detail)) out.push(body.detail);
-  if (isRecord3(body.details)) out.push(body.details);
-  out.push(body);
-  return out;
+function isV2Path(pathOrUrl) {
+  return /\/v2\/ai\//.test(pathOrUrl);
 }
-function statusOf(error) {
-  if (!isRecord3(error) && !(error instanceof Error)) return null;
-  const status = error.status;
-  return typeof status === "number" ? status : null;
+function toV1FallbackUrl(url) {
+  return url.replace(/\/v2\/ai\//, "/ai/");
 }
-function bodyOf(error) {
-  if (!isRecord3(error) && !(error instanceof Error)) return void 0;
-  return error.serverDetail;
+function applyAiApiVersion(path, version) {
+  if (version !== "v2") return path;
+  return isCoveredAiPath(path) ? toV2Path(path) : path;
 }
-function readMatrxErrorCode(error) {
-  for (const candidate of detailCandidates(bodyOf(error))) {
-    const code = nonBlank(candidate.code);
-    if (code) return code;
+async function fetchWithMatrxProtocolFallback(url, init, opts = {}) {
+  const { onDowngrade, ...fetchOpts } = opts;
+  const logDowngrade = (reason, status2) => {
+    console.warn(
+      `[matrx] ai_v2_downgrade \u2192 retrying on v1. v2=${url} reason=${reason}`
+    );
+    onDowngrade?.({ url, reason, ...status2 !== void 0 ? { status: status2 } : {} });
+  };
+  if (!isV2Path(url)) return (0, import_net.resilientFetch)(url, init, fetchOpts);
+  let result;
+  try {
+    result = await (0, import_net.resilientFetch)(url, init, fetchOpts);
+  } catch (err) {
+    const isAbort = (0, import_net.isNetError)(err) && err.code === "aborted" || err instanceof Error && err.name === "AbortError";
+    if (isAbort) throw err;
+    logDowngrade(String(err));
+    return (0, import_net.resilientFetch)(toV1FallbackUrl(url), init, fetchOpts);
   }
-  for (const candidate of detailCandidates(bodyOf(error))) {
-    const code = nonBlank(candidate.error);
-    if (code) return code;
+  const status = result.response.status;
+  if (status === 404 || status === 405 || status >= 500) {
+    logDowngrade(`HTTP ${status}`, status);
+    return (0, import_net.resilientFetch)(toV1FallbackUrl(url), init, fetchOpts);
   }
-  return null;
+  return result;
 }
-var PREFIXED_ERROR_CODES = [
-  "resume_conflict",
-  "not_resumable",
-  "outstanding_delegated_calls",
-  "user_request_not_found",
-  "run_in_flight"
-];
-function readMatrxErrorCodeFromMessage(message) {
-  if (typeof message !== "string") return null;
-  for (const code of PREFIXED_ERROR_CODES) {
-    if (message.startsWith(`${code}:`)) return code;
+function aiVersionPathOverrides(version) {
+  if (version !== "v2") return {};
+  const map = {};
+  for (const template of V2_COVERED_AI_PATH_TEMPLATES) {
+    map[template] = toV2Path(template);
   }
-  return null;
+  return map;
 }
-async function readConversationOrganizationId(conversationId, read, onUnreadable) {
-  try {
-    const value = await read(conversationId);
-    if (typeof value === "string" && value.trim()) return value;
-    onUnreadable?.(null);
-  } catch (error) {
-    onUnreadable?.(error instanceof Error ? error.message : String(error));
+
+// matrx/call.ts
+function buildMatrxRequestUrl(baseUrl, pathTemplate, pathParams, queryParams) {
+  let resolvedPath = pathTemplate;
+  if (pathParams) {
+    for (const [key, value] of Object.entries(pathParams)) {
+      resolvedPath = resolvedPath.replace(`{${key}}`, encodeURIComponent(value));
+    }
   }
-  return null;
-}
-function firstString(candidates, key) {
-  for (const candidate of candidates) {
-    const value = nonBlank(candidate[key]);
-    if (value) return value.trim();
+  const fullPath = resolvedPath.startsWith("/api/") ? resolvedPath.slice(4) : resolvedPath;
+  const url = `${baseUrl}${fullPath}`;
+  if (queryParams && Object.keys(queryParams).length > 0) {
+    const qs = new URLSearchParams(
+      Object.fromEntries(
+        Object.entries(queryParams).map(([k, v]) => [k, String(v)])
+      )
+    ).toString();
+    return `${url}?${qs}`;
+  }
+  return url;
+}
+var MATRX_UI_ONLY_BODY_FIELDS = /* @__PURE__ */ new Set([
+  "youtube_videos",
+  "file_urls",
+  "image_urls"
+]);
+function buildMatrxRequestBody(body, scope) {
+  const raw = body ?? {};
+  const base = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (!MATRX_UI_ONLY_BODY_FIELDS.has(key)) base[key] = value;
   }
-  return null;
-}
-function readLiveRunRejoin(error) {
-  if (statusOf(error) !== 409) return null;
-  const candidates = detailCandidates(bodyOf(error));
-  if (candidates.length === 0) return null;
-  const code = readMatrxErrorCode(error);
-  if (code !== MATRX_RUN_IN_PROGRESS) return null;
-  const liveRequestId = firstString(candidates, "live_request_id");
-  const pathFromBody = firstString(candidates, "rejoin_path");
-  const rejoinPath = pathFromBody && pathFromBody.startsWith("/") ? pathFromBody : liveRequestId ? runtimeOperationRejoinPath(liveRequestId) : null;
-  if (!rejoinPath) return null;
-  const root = bodyOf(error);
-  return {
-    liveRequestId,
-    rejoinPath,
-    runId: firstString(candidates, "run_id"),
-    code,
-    body: isRecord3(root) ? root : {}
+  if (base.organization_id === null || typeof base.organization_id === "string" && base.organization_id.trim() === "") {
+    delete base.organization_id;
+  }
+  const bodyOrganizationId = base.organization_id;
+  if (scope.organization_id !== void 0 && bodyOrganizationId !== void 0 && (typeof bodyOrganizationId !== "string" || bodyOrganizationId.trim() !== scope.organization_id)) {
+    throw new OrganizationContextError(
+      "organization_context_mismatch",
+      "Request body organization_id must match the request context organization."
+    );
+  }
+  if (bodyOrganizationId !== void 0 && scope.organization_id !== void 0) {
+    base.organization_id = scope.organization_id;
+  }
+  const scopeFields = {
+    ...scope.organization_id !== void 0 ? { organization_id: scope.organization_id } : {}
   };
+  if (scope.project_id !== void 0) scopeFields.project_id = scope.project_id;
+  if (scope.task_id !== void 0) scopeFields.task_id = scope.task_id;
+  return { ...scopeFields, ...base };
+}
+var BARE_TRANSPORT_CODE = /^\s*(?:HTTP|HTTP\s*Error|Status(?:\s*Code)?)?\s*[:\-]?\s*\d{3}\s*[.:!]?\s*$/i;
+function isBareTransportCode(text) {
+  if (!text) return false;
+  return BARE_TRANSPORT_CODE.test(text);
+}
+function bareStatusSentence(status) {
+  if (status === 401 || status === 403) {
+    return "The server would not let this request through \u2014 your session may have expired, or this account may not have access here. Sign in again, and if it repeats, ask an administrator.";
+  }
+  if (status === 404) {
+    return "The server has nothing at that address. Reload the page; if it repeats, report it \u2014 a client asking for something that no longer exists is a defect, not your mistake.";
+  }
+  if (status === 429) {
+    return "The server is rate-limiting this request. Wait a few seconds and try again.";
+  }
+  if (status >= 500) {
+    return "The server failed while answering this, and sent no explanation. Try again in a moment; if it repeats, report it with the request id above.";
+  }
+  return "The server refused this request and sent no reason with it \u2014 the missing reason is itself a defect worth reporting. Reload the page and try once more; if it repeats, report it with the request id above.";
 }
-function readLiveRunRequestId(error) {
-  return readLiveRunRejoin(error)?.liveRequestId ?? null;
+function honestTransportMessage(raw, status) {
+  if (raw && !isBareTransportCode(raw)) return raw;
+  return bareStatusSentence(status ?? 0);
 }
-function isResumeConflict(error) {
-  return statusOf(error) === 409 && readMatrxErrorCode(error) === MATRX_RESUME_CONFLICT;
+var SENSITIVE_HEADER_NAME = /authorization|cookie|token|api[-_]?key/i;
+function buildSafeRequestLog(headers, body) {
+  const safeHeaders = Object.fromEntries(
+    Object.entries(headers).map(([name, value]) => [
+      name,
+      SENSITIVE_HEADER_NAME.test(name) ? "[REDACTED]" : value
+    ])
+  );
+  const bodyMetadata = Array.isArray(body) ? { type: "array", itemCount: body.length } : body && typeof body === "object" ? { type: "object", keys: Object.keys(body) } : { type: body === null ? "null" : typeof body };
+  return { headers: safeHeaders, body: bodyMetadata };
 }
-function isLiveStreamUnavailable(error) {
-  return statusOf(error) === 409 && readMatrxErrorCode(error) === MATRX_LIVE_STREAM_UNAVAILABLE;
+function redactUrlForRequestLog(url) {
+  try {
+    const parsed = new URL(url);
+    for (const key of parsed.searchParams.keys()) {
+      parsed.searchParams.set(key, "[REDACTED]");
+    }
+    return parsed.toString();
+  } catch {
+    const queryIndex = url.indexOf("?");
+    return queryIndex === -1 ? url : `${url.slice(0, queryIndex)}?[REDACTED]`;
+  }
 }
-function runtimeOperationRejoinPath(requestId) {
-  return `/runtime/operations/${encodePathSegment(requestId)}/rejoin`;
+function shouldReportMatrxCallError(status, expectedErrorStatuses) {
+  return status == null || !expectedErrorStatuses?.includes(status);
 }
-function streamErrorText(eventOrPayload) {
-  if (!isRecord3(eventOrPayload)) return null;
-  const payload = typeof eventOrPayload.event === "string" && isRecord3(eventOrPayload.data) ? eventOrPayload.data : eventOrPayload;
-  return nonBlank(payload.user_message) ?? nonBlank(payload.message);
+function parseMatrxNdjsonResponse(response, signal, hooks = {}) {
+  const ids = {
+    requestId: response.headers.get("X-Request-ID"),
+    conversationId: response.headers.get("X-Conversation-ID")
+  };
+  async function* events() {
+    if (!response.body) {
+      throw new BackendApiError({
+        code: "internal_error",
+        detail: "Response has no body",
+        userMessage: "No response received from server"
+      });
+    }
+    try {
+      for await (const envelope of readMatrxNdjsonStream(response.body, {
+        ...signal ? { signal } : {},
+        ...hooks.onMalformedLine ? { onMalformedLine: hooks.onMalformedLine } : {},
+        ...hooks.onUnknownEnvelope ? { onUnknownEnvelope: hooks.onUnknownEnvelope } : {}
+      })) {
+        hooks.onEvent?.(envelope, ids);
+        yield envelope;
+      }
+    } catch (error) {
+      if (signal?.aborted || error instanceof Error && error.name === "AbortError") {
+        return;
+      }
+      const transportError = error instanceof BackendApiError ? error : new StreamTransportError({
+        detail: error instanceof Error ? error.message : "The response stream ended unexpectedly.",
+        details: error,
+        ...ids.requestId ? { requestId: ids.requestId } : {}
+      });
+      hooks.onTransportError?.(transportError, ids);
+      throw transportError;
+    }
+  }
+  return { events: events(), ...ids };
 }
-async function openMatrxStream(transport, path, options = {}) {
-  const response = await requestStream(transport, path, {
-    method: "POST",
-    ...options.body !== void 0 ? { body: options.body } : {},
-    ...options.signal ? { signal: options.signal } : {}
-  });
-  return toRunHandle(response, options);
+var DEFAULT_CONNECT_TIMEOUT_MS = 15e3;
+var DEFAULT_JSON_TOTAL_TIMEOUT_MS = 3e4;
+async function httpErrorFrom(response) {
+  const serverDetail = await response.json().catch(() => void 0);
+  return {
+    type: response.status >= 400 && response.status < 500 ? "validation_error" : "http_error",
+    message: extractMatrxErrorMessage(serverDetail) ?? bareStatusSentence(response.status),
+    status: response.status,
+    serverDetail
+  };
 }
-function withRunOrganization(transport, organizationId) {
-  const orgId = requireOrganizationContext(organizationId);
+async function executeMatrxCall(request, hooks = {}) {
+  const upper = request.method.toUpperCase();
+  const sendsBody = request.stream || upper !== "GET" && upper !== "HEAD";
+  const { response } = await fetchWithMatrxProtocolFallback(
+    request.url,
+    {
+      method: request.method,
+      headers: request.headers,
+      ...sendsBody ? { body: JSON.stringify(request.body) } : {}
+    },
+    {
+      ...request.signal ? { signal: request.signal } : {},
+      connectTimeoutMs: request.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS,
+      totalTimeoutMs: request.stream ? null : request.totalTimeoutMs === void 0 ? DEFAULT_JSON_TOTAL_TIMEOUT_MS : request.totalTimeoutMs,
+      throwOnHttpError: false,
+      ...hooks.onProtocolDowngrade ? { onDowngrade: hooks.onProtocolDowngrade } : {}
+    }
+  );
+  const requestId = response.headers.get("X-Request-ID");
+  const conversationId = response.headers.get("X-Conversation-ID");
+  const idFields = {
+    ...requestId !== null ? { requestId } : {},
+    ...conversationId !== null ? { conversationId } : {}
+  };
+  if (!response.ok) {
+    const error = await httpErrorFrom(response);
+    if (request.stream) request.onStreamError?.(error);
+    return { ...idFields, error };
+  }
+  if (!request.stream) {
+    const data = response.status === 204 ? void 0 : await response.json();
+    return { data, ...idFields };
+  }
+  if (request.consumeStream) {
+    request.onStreamStart?.(requestId, conversationId);
+    await request.consumeStream(response, { requestId, conversationId });
+    request.onStreamComplete?.(requestId, conversationId);
+    return idFields;
+  }
+  const parse = hooks.parseStream ?? ((res, signal) => parseMatrxNdjsonResponse(res, signal));
+  const parsed = parse(response, request.signal);
+  request.onStreamStart?.(parsed.requestId, parsed.conversationId);
+  for await (const event of parsed.events) {
+    request.onStreamEvent?.(event);
+  }
+  request.onStreamComplete?.(parsed.requestId, parsed.conversationId);
   return {
-    fetch: (path, init) => transport.fetch(path, {
-      ...init,
-      headers: { ...init.headers, "X-Organization-Id": orgId }
-    })
+    ...parsed.requestId !== null ? { requestId: parsed.requestId } : {},
+    ...parsed.conversationId !== null ? { conversationId: parsed.conversationId } : {}
   };
 }
-async function followWorkflowRunEvents(transport, runId, options) {
-  const headers = { Accept: "text/event-stream" };
-  if (options.lastEventId) headers["Last-Event-ID"] = String(options.lastEventId);
-  let response;
-  try {
-    response = await requestStream(
-      transport,
-      `/runs/${encodePathSegment(runId)}/events/stream`,
-      {
-        method: "GET",
-        headers,
-        ...options.signal ? { signal: options.signal } : {}
-      }
+
+// matrx/client.ts
+function classifyStatus(status) {
+  return status >= 400 && status < 500 ? "validation_error" : "http_error";
+}
+function normalizeMatrxError(err) {
+  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 (err instanceof MatrxApiError) {
+    return {
+      type: classifyStatus(err.status),
+      message: honestTransportMessage(err.message, err.status),
+      status: err.status,
+      serverDetail: err.serverDetail,
+      ...err.code ? { code: err.code } : {},
+      name: err.name
+    };
+  }
+  if (err instanceof BackendApiError) {
+    return {
+      type: "network_error",
+      message: honestTransportMessage(
+        err.detail || err.userMessage,
+        err.status ?? void 0
+      ),
+      code: err.code,
+      name: err.name,
+      ...err.status !== null ? { status: err.status } : {},
+      ...err.details !== null ? { serverDetail: err.details } : {}
+    };
+  }
+  if ((0, import_data.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: honestTransportMessage(err.message, status),
+        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: honestTransportMessage(httpMatch[2] ?? err.message, status),
+        status
+      };
+    }
+    if (isBareTransportCode(err.message)) {
+      const status = Number.parseInt(err.message.replace(/\D+/g, ""), 10);
+      return {
+        type: classifyStatus(status),
+        message: bareStatusSentence(status),
+        status
+      };
+    }
+    return { type: "network_error", message: err.message };
+  }
+  return { type: "unknown", message: (0, import_net2.extractErrorMessage)(err) };
+}
+var PRODUCTION_CONNECT_TIMEOUT_MS = 15e3;
+function stripContentType(headers) {
+  return Object.fromEntries(
+    Object.entries(headers).filter(
+      ([name]) => name.toLowerCase() !== "content-type"
+    )
+  );
+}
+function createMatrxTransport(options) {
+  const {
+    baseUrl,
+    resolveTarget,
+    credentials,
+    organizationId,
+    aiApiVersion,
+    connectTimeoutMs = PRODUCTION_CONNECT_TIMEOUT_MS,
+    totalTimeoutMs = null,
+    expectedErrorStatuses,
+    diagnostics,
+    source = "matrxTransport"
+  } = options;
+  if (baseUrl === void 0 === (resolveTarget === void 0)) {
+    throw new Error(
+      "createMatrxTransport: provide exactly one of `baseUrl` or `resolveTarget`."
     );
-  } catch (error) {
-    if (options.signal?.aborted) return { ended: false };
-    throw error;
   }
-  try {
-    for await (const frame of readMatrxSseStream(
-      response.body
-    )) {
-      if (frame.event === "end") return { ended: true };
-      if (frame.data === null) continue;
-      let parsed;
+  const resolve = resolveTarget ?? (() => ({ baseUrl }));
+  const resolveVersion = () => {
+    if (aiApiVersion === void 0) return MATRX_AI_API_VERSION_DEFAULT;
+    return typeof aiApiVersion === "function" ? aiApiVersion() : aiApiVersion;
+  };
+  const resolveOrganizationId = () => {
+    if (organizationId === void 0) return null;
+    const candidate = typeof organizationId === "function" ? organizationId() : organizationId;
+    return requireOrganizationContext(candidate);
+  };
+  return {
+    async fetch(path, init) {
+      const target = resolve();
+      const versionedPath = applyAiApiVersion(path, resolveVersion());
+      const url = `${target.baseUrl}${versionedPath}`;
+      const credentialHeaders = credentials ? (0, import_data2.credentialToHeaders)(await credentials.get()) : {};
+      let headers = {
+        ...init.headers,
+        ...stripContentType(credentialHeaders),
+        ...stripContentType(target.policyHeaders ?? {})
+      };
+      const orgId = resolveOrganizationId();
+      if (orgId !== null) {
+        headers = applyOrganizationContextHeader(headers, orgId);
+      }
+      const info = {
+        url,
+        method: init.method,
+        path,
+        channel: target.channel ?? "default",
+        source
+      };
+      diagnostics?.onRequest?.(info);
+      let response;
       try {
-        parsed = JSON.parse(frame.data);
-      } catch {
-        continue;
+        ({ response } = await fetchWithMatrxProtocolFallback(
+          url,
+          {
+            method: init.method,
+            headers,
+            ...init.body !== void 0 ? { body: init.body } : {}
+          },
+          {
+            ...init.signal ? { signal: init.signal } : {},
+            connectTimeoutMs,
+            totalTimeoutMs,
+            throwOnHttpError: false,
+            ...diagnostics?.onProtocolDowngrade ? { onDowngrade: diagnostics.onProtocolDowngrade } : {}
+          }
+        ));
+      } catch (err) {
+        diagnostics?.onError?.(normalizeMatrxError(err), info);
+        throw err;
       }
-      if (!isRecord3(parsed)) continue;
-      options.onEvent(parsed, parsed.event === "node_stream" ? null : frame.seq);
+      if (!response.ok && !expectedErrorStatuses?.includes(response.status)) {
+        const serverDetail = await response.clone().json().catch(() => void 0);
+        const code = extractMatrxErrorCode(serverDetail);
+        diagnostics?.onError?.(
+          {
+            type: classifyStatus(response.status),
+            message: extractMatrxErrorMessage(serverDetail) ?? `HTTP ${response.status}`,
+            status: response.status,
+            serverDetail,
+            ...code ? { code } : {}
+          },
+          info
+        );
+      }
+      return response;
     }
-  } catch (error) {
-    if (!options.signal?.aborted) throw error;
-  }
-  return { ended: false };
+  };
 }
-async function drain(handle, onEnvelope) {
-  for await (const envelope of handle.events) onEnvelope(envelope);
+
+// 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 };
 }
-async function resumeOrRejoin(transport, resumeCall, options) {
-  const {
-    onEnvelope,
-    organizationId,
-    onRejoin,
-    onOperationEvent,
-    onWorkflowEvent,
-    follow,
-    ...rest
-  } = options;
-  const bound = organizationId ? withRunOrganization(transport, organizationId) : transport;
-  const streamOptions = {
-    ...rest,
-    ...options.signal ? { signal: options.signal } : {}
+function newEphemeralConversationStart(conversationId) {
+  return {
+    conversation_id: conversationId ?? mintMatrxConversationId(),
+    is_new: true,
+    store: false
   };
-  const signalOnly = options.signal ? { signal: options.signal } : {};
-  let rejoin;
-  try {
-    const handle = await resumeCall(bound, streamOptions);
-    await drain(handle, onEnvelope);
-    return { kind: "resumed", requestId: handle.requestId };
-  } catch (error) {
-    const target = readLiveRunRejoin(error);
-    if (!target) {
-      if (error instanceof MatrxApiError && isResumeConflict(error)) {
-        return { kind: "resume_conflict", error };
-      }
-      throw error;
+}
+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));
     }
-    rejoin = target;
   }
-  onRejoin?.(rejoin);
-  let unavailable;
+  const encoded = search.toString();
+  return encoded ? `?${encoded}` : "";
+}
+async function readServerDetail(response) {
   try {
-    const handle = await openMatrxStream(bound, rejoin.rejoinPath, {
-      ...streamOptions,
-      // The rejoin routes take no body model; the reference client posts {}.
-      body: {}
-    });
-    await drain(handle, onEnvelope);
-    return { kind: "rejoined", rejoin };
-  } catch (error) {
-    const read = readLiveStreamUnavailable(error);
-    if (!read) throw error;
-    unavailable = read;
+    return await response.json();
+  } catch {
+    return void 0;
   }
-  return followUnavailableRejoin(bound, rejoin, unavailable, {
-    ...signalOnly,
-    ...onOperationEvent ? { onOperationEvent } : {},
-    ...onWorkflowEvent ? { onWorkflowEvent } : {},
-    ...follow ? { follow } : {}
-  });
 }
-function readLiveStreamUnavailable(error) {
-  if (!isLiveStreamUnavailable(error)) return null;
-  return { runId: firstString(detailCandidates(bodyOf(error)), "run_id") };
+async function throwApiError(path, response) {
+  throw new MatrxApiError({
+    status: response.status,
+    path,
+    serverDetail: await readServerDetail(response)
+  });
 }
-async function followUnavailableRejoin(transport, rejoin, unavailable, options = {}) {
-  const bound = options.organizationId ? withRunOrganization(transport, options.organizationId) : transport;
-  const signalOnly = options.signal ? { signal: options.signal } : {};
-  const runId = unavailable.runId ?? rejoin.runId;
-  if (runId && rejoin.rejoinPath.startsWith("/runtime/operations/")) {
-    const result2 = await followWorkflowRunEvents(bound, runId, {
-      ...signalOnly,
-      onEvent: (event, seq) => options.onWorkflowEvent?.(event, seq)
-    });
-    return { kind: "followed_workflow", rejoin, runId, ended: result2.ended };
-  }
-  const liveRequestId = rejoin.liveRequestId;
-  const statusView = liveRequestId ? await getRuntimeOperationStatus(bound, liveRequestId, signalOnly) : null;
-  const operation = statusView?.operations.find((op) => !op.is_terminal) ?? statusView?.operations[0] ?? null;
-  if (!operation) {
-    return { kind: "followed", rejoin, executionId: null, ended: false, status: null };
-  }
-  if (operation.is_terminal) {
-    return {
-      kind: "followed",
-      rejoin,
-      executionId: operation.execution_id,
-      ended: true,
-      status: operation.status
-    };
-  }
-  const result = await followRuntimeOperationToEnd(bound, operation.execution_id, {
-    ...options.follow,
-    lastEventSeq: operation.last_event_seq,
-    ...signalOnly,
-    onEvent: (event) => options.onOperationEvent?.(event)
+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 {
-    kind: "followed",
-    rejoin,
-    executionId: operation.execution_id,
-    ended: result.ended,
-    status: result.status
+    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 attempt(run) {
-  try {
-    await run();
-    return { reloaded: true };
-  } catch (error) {
-    return { reloaded: false, error };
+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;
 }
-async function settleRunPickup(pickup, options) {
-  switch (pickup.kind) {
-    case "resumed":
-    case "rejoined":
-      return { state: "streamed" };
-    case "resume_conflict":
-      return { state: "retry" };
-    case "followed_workflow":
-    case "followed": {
-      const status = pickup.kind === "followed" ? pickup.status : null;
-      const nothingLive = pickup.kind === "followed" && pickup.executionId === null;
-      if (pickup.ended || nothingLive) {
-        return { state: "settled", status, ...await attempt(options.reloadSavedTurn) };
+
+// 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 {
-        state: "still_running",
-        ...await attempt(options.onStillRunning ?? options.reloadSavedTurn)
-      };
+      return frames;
+    },
+    flush() {
+      const rest = buffer;
+      buffer = "";
+      return { incomplete: rest.length > 0 ? rest : null };
     }
-  }
+  };
 }
-
-// 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);
+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();
+  }
 }
-function startAgentRun(transport, agentId, request, options = {}) {
-  return streamCall(
-    transport,
-    `/ai/agents/${encodePathSegment(agentId)}`,
-    request,
-    options
-  );
+
+// 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;
+  }
 }
-function startMandateRun(transport, mandateKey, request, options = {}) {
-  return streamCall(
-    transport,
-    `/ai/mandates/${encodePathSegment(mandateKey)}`,
-    request,
-    options
+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 continueAgentConversation(transport, conversationId, request, options = {}) {
-  return streamCall(
+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,
-    `/ai/conversations/${encodePathSegment(conversationId)}`,
-    request,
-    options
+    `/runtime/executions/${encodePathSegment(executionId)}/events${query}`,
+    { method: "GET", ...options.signal ? { signal: options.signal } : {} }
   );
 }
-function resumeAgentConversation(transport, conversationId, request = {}, options = {}) {
-  return streamCall(
-    transport,
-    `/ai/conversations/${encodePathSegment(conversationId)}/resume`,
-    request,
-    options
-  );
+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;
 }
-function cancelAgentRun(transport, requestId, options = {}) {
-  const query = buildQuery(
-    options.mode === "interrupt" ? { mode: "interrupt" } : {}
-  );
-  return requestJson(
+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,
-    `/ai/cancel/${encodePathSegment(requestId)}${query}`,
+    `/runtime/executions/${encodePathSegment(executionId)}/events/stream`,
     {
-      method: "POST",
+      method: "GET",
+      headers,
       ...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;
+  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 (envelope.event === "error" && failure === null) {
-      const payload = isRecord4(envelope.data) ? envelope.data : null;
-      failure = new MatrxRunError({
-        message: streamErrorText(payload) ?? "The agent run failed",
-        errorPayload: payload,
-        partialText: text
-      });
+    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;
     }
-    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/provider-failures.ts
-var clip = (value, max) => value.length > max ? value.slice(0, max) : value;
-function providerSessionFailureBody(failure) {
-  const message = failure.message?.trim() || failure.error_type?.trim() || (failure.status_code ? `HTTP ${failure.status_code}` : "provider session failed");
-  const body = {
-    provider: failure.provider,
-    message: clip(message, 4e3)
-  };
-  if (failure.model?.trim()) body.model = clip(failure.model.trim(), 200);
-  if (failure.error_type?.trim()) body.error_type = clip(failure.error_type.trim(), 200);
-  if (typeof failure.status_code === "number" && Number.isInteger(failure.status_code) && failure.status_code >= 100 && failure.status_code <= 599) {
-    body.status_code = failure.status_code;
+    yield { type: "liveness", cursor };
   }
-  return body;
 }
-async function reportProviderSessionFailure(transport, failure, options = {}) {
-  try {
-    return await requestJson(
-      transport,
-      "/broker/provider-failures",
-      {
-        method: "POST",
-        body: providerSessionFailureBody(failure),
-        ...options.signal ? { signal: options.signal } : {}
+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 attempt2 = new AbortController();
+    const onOuterAbort = () => attempt2.abort();
+    outer?.addEventListener("abort", onOuterAbort, { once: true });
+    let stallTimer = null;
+    const armStall = () => {
+      if (stallTimer !== null) clearTimeout(stallTimer);
+      stallTimer = setTimeout(() => attempt2.abort(), stallTimeoutMs);
+    };
+    try {
+      const items = followRuntimeOperationEvents(transport, executionId, {
+        lastEventSeq: cursor,
+        signal: attempt2.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);
+        }
       }
-    );
-  } catch (error) {
-    console.warn(
-      `[provider-failures] could not report a ${failure.provider} session failure`,
-      error
-    );
-    return null;
+      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 };
 }
-
-// matrx/tools.ts
-function submitAgentToolResults(transport, conversationId, results, options = {}) {
-  return requestJson(
+async function rejoinRuntimeOperation(transport, requestId, options = {}) {
+  const response = await requestStream(
     transport,
-    `/ai/conversations/${encodePathSegment(conversationId)}/tool_results`,
+    `/runtime/operations/${encodePathSegment(requestId)}/rejoin`,
     {
       method: "POST",
-      body: {
-        results,
-        ...options.instanceId !== void 0 ? { instance_id: options.instanceId } : {}
-      },
+      // 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);
 }
-function listConversationPendingToolCalls(transport, conversationId, options = {}) {
-  return requestJson(
-    transport,
-    `/ai/conversations/${encodePathSegment(conversationId)}/pending_calls`,
-    {
-      method: "GET",
-      ...options.signal ? { signal: options.signal } : {}
-    }
-  );
+
+// matrx/rejoin.ts
+var MATRX_RUN_IN_PROGRESS = "run_in_progress";
+var MATRX_RESUME_CONFLICT = "resume_conflict";
+var MATRX_LIVE_STREAM_UNAVAILABLE = "live_stream_unavailable";
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-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 } : {}
-    }
-  );
+function nonBlank(value) {
+  return typeof value === "string" && value.trim() ? value : null;
 }
-
-// matrx/backend-errors.ts
-var BackendApiError = class extends Error {
-  /** Machine-readable error code */
-  code;
-  /** Developer-facing detail */
-  detail;
-  /** Safe to display directly in the UI */
-  userMessage;
-  /** Extra info (validation errors, etc.) */
-  details;
-  /** Unique request ID for support/debugging */
-  requestId;
-  /** HTTP status code (if from an HTTP response) */
-  status;
-  constructor(data) {
-    super(data.userMessage);
-    this.name = "BackendApiError";
-    this.code = data.code;
-    this.detail = data.detail;
-    this.userMessage = data.userMessage;
-    this.details = data.details ?? null;
-    this.requestId = data.requestId ?? "";
-    this.status = data.status ?? null;
+function detailCandidates(body) {
+  if (!isRecord3(body)) return [];
+  const out = [];
+  if (isRecord3(body.detail)) out.push(body.detail);
+  if (isRecord3(body.details)) out.push(body.details);
+  out.push(body);
+  return out;
+}
+function statusOf(error) {
+  if (!isRecord3(error) && !(error instanceof Error)) return null;
+  const status = error.status;
+  return typeof status === "number" ? status : null;
+}
+function bodyOf(error) {
+  if (!isRecord3(error) && !(error instanceof Error)) return void 0;
+  return error.serverDetail;
+}
+function readMatrxErrorCode(error) {
+  for (const candidate of detailCandidates(bodyOf(error))) {
+    const code = nonBlank(candidate.code);
+    if (code) return code;
   }
-  /** Convert to the wire format for logging */
-  toJSON() {
-    return {
-      error: this.code,
-      message: this.detail,
-      user_message: this.userMessage,
-      details: this.details,
-      request_id: this.requestId
-    };
+  for (const candidate of detailCandidates(bodyOf(error))) {
+    const code = nonBlank(candidate.error);
+    if (code) return code;
   }
-};
-var StreamTransportError = class extends BackendApiError {
-  /** Always true — reattach and let the server settle the outcome. */
-  resumable = true;
-  constructor(data) {
-    super({
-      code: "stream_transport_lost",
-      detail: data.detail,
-      userMessage: "The connection dropped. Your run is still going on the server \u2014 reconnecting to it now.",
-      details: data.details ?? null,
-      ...data.requestId !== void 0 ? { requestId: data.requestId } : {}
-    });
-    this.name = "StreamTransportError";
+  return null;
+}
+var PREFIXED_ERROR_CODES = [
+  "resume_conflict",
+  "not_resumable",
+  "outstanding_delegated_calls",
+  "user_request_not_found",
+  "run_in_flight"
+];
+function readMatrxErrorCodeFromMessage(message) {
+  if (typeof message !== "string") return null;
+  for (const code of PREFIXED_ERROR_CODES) {
+    if (message.startsWith(`${code}:`)) return code;
   }
-};
-function isStreamTransportLost(error) {
-  if (error instanceof StreamTransportError) return true;
-  if (error instanceof BackendApiError) {
-    return error.code === "stream_transport_lost";
+  return null;
+}
+async function readConversationOrganizationId(conversationId, read, onUnreadable) {
+  try {
+    const value = await read(conversationId);
+    if (typeof value === "string" && value.trim()) return value;
+    onUnreadable?.(null);
+  } catch (error) {
+    onUnreadable?.(error instanceof Error ? error.message : String(error));
   }
-  if (error && typeof error === "object") {
-    const code = error.code;
-    if (code === "stream_transport_lost") return true;
-    const errorType = error.error_type;
-    if (errorType === "transport_lost") return true;
+  return null;
+}
+function firstString(candidates, key) {
+  for (const candidate of candidates) {
+    const value = nonBlank(candidate[key]);
+    if (value) return value.trim();
   }
-  return false;
+  return null;
 }
-async function parseHttpError(response) {
-  const status = response.status;
-  let body = null;
+function readLiveRunRejoin(error) {
+  if (statusOf(error) !== 409) return null;
+  const candidates = detailCandidates(bodyOf(error));
+  if (candidates.length === 0) return null;
+  const code = readMatrxErrorCode(error);
+  if (code !== MATRX_RUN_IN_PROGRESS) return null;
+  const liveRequestId = firstString(candidates, "live_request_id");
+  const pathFromBody = firstString(candidates, "rejoin_path");
+  const rejoinPath = pathFromBody && pathFromBody.startsWith("/") ? pathFromBody : liveRequestId ? runtimeOperationRejoinPath(liveRequestId) : null;
+  if (!rejoinPath) return null;
+  const root = bodyOf(error);
+  return {
+    liveRequestId,
+    rejoinPath,
+    runId: firstString(candidates, "run_id"),
+    code,
+    body: isRecord3(root) ? root : {}
+  };
+}
+function readLiveRunRequestId(error) {
+  return readLiveRunRejoin(error)?.liveRequestId ?? null;
+}
+function isResumeConflict(error) {
+  return statusOf(error) === 409 && readMatrxErrorCode(error) === MATRX_RESUME_CONFLICT;
+}
+function isLiveStreamUnavailable(error) {
+  return statusOf(error) === 409 && readMatrxErrorCode(error) === MATRX_LIVE_STREAM_UNAVAILABLE;
+}
+function runtimeOperationRejoinPath(requestId) {
+  return `/runtime/operations/${encodePathSegment(requestId)}/rejoin`;
+}
+function streamErrorText(eventOrPayload) {
+  if (!isRecord3(eventOrPayload)) return null;
+  const payload = typeof eventOrPayload.event === "string" && isRecord3(eventOrPayload.data) ? eventOrPayload.data : eventOrPayload;
+  return nonBlank(payload.user_message) ?? nonBlank(payload.message);
+}
+async function openMatrxStream(transport, path, options = {}) {
+  const response = await requestStream(transport, path, {
+    method: "POST",
+    ...options.body !== void 0 ? { body: options.body } : {},
+    ...options.signal ? { signal: options.signal } : {}
+  });
+  return toRunHandle(response, options);
+}
+function withRunOrganization(transport, organizationId) {
+  const orgId = requireOrganizationContext(organizationId);
+  return {
+    fetch: (path, init) => transport.fetch(path, {
+      ...init,
+      headers: { ...init.headers, "X-Organization-Id": orgId }
+    })
+  };
+}
+async function followWorkflowRunEvents(transport, runId, options) {
+  const headers = { Accept: "text/event-stream" };
+  if (options.lastEventId) headers["Last-Event-ID"] = String(options.lastEventId);
+  let response;
   try {
-    body = await response.json();
-  } catch {
-    try {
-      const text = await response.text();
-      return new BackendApiError({
-        code: statusToCode(status),
-        detail: text || `HTTP ${status}`,
-        userMessage: text || `Request failed (${status})`,
-        status
-      });
-    } catch {
-      return new BackendApiError({
-        code: statusToCode(status),
-        detail: `HTTP ${status}`,
-        userMessage: `Request failed (${status})`,
-        status
-      });
+    response = await requestStream(
+      transport,
+      `/runs/${encodePathSegment(runId)}/events/stream`,
+      {
+        method: "GET",
+        headers,
+        ...options.signal ? { signal: options.signal } : {}
+      }
+    );
+  } catch (error) {
+    if (options.signal?.aborted) return { ended: false };
+    throw error;
+  }
+  try {
+    for await (const frame of readMatrxSseStream(
+      response.body
+    )) {
+      if (frame.event === "end") return { ended: true };
+      if (frame.data === null) continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(frame.data);
+      } catch {
+        continue;
+      }
+      if (!isRecord3(parsed)) continue;
+      options.onEvent(parsed, parsed.event === "node_stream" ? null : frame.seq);
     }
+  } catch (error) {
+    if (!options.signal?.aborted) throw error;
   }
-  return parseHttpErrorBody(body, status);
+  return { ended: false };
 }
-function parseHttpErrorBody(body, status) {
-  if (!body) {
-    return new BackendApiError({
-      code: statusToCode(status),
-      detail: `HTTP ${status}`,
-      userMessage: `Request failed (${status})`,
-      status
-    });
+async function drain(handle, onEnvelope) {
+  for await (const envelope of handle.events) onEnvelope(envelope);
+}
+async function resumeOrRejoin(transport, resumeCall, options) {
+  const {
+    onEnvelope,
+    organizationId,
+    onRejoin,
+    onOperationEvent,
+    onWorkflowEvent,
+    follow,
+    ...rest
+  } = options;
+  const bound = organizationId ? withRunOrganization(transport, organizationId) : transport;
+  const streamOptions = {
+    ...rest,
+    ...options.signal ? { signal: options.signal } : {}
+  };
+  const signalOnly = options.signal ? { signal: options.signal } : {};
+  let rejoin;
+  try {
+    const handle = await resumeCall(bound, streamOptions);
+    await drain(handle, onEnvelope);
+    return { kind: "resumed", requestId: handle.requestId };
+  } catch (error) {
+    const target = readLiveRunRejoin(error);
+    if (!target) {
+      if (error instanceof MatrxApiError && isResumeConflict(error)) {
+        return { kind: "resume_conflict", error };
+      }
+      throw error;
+    }
+    rejoin = target;
   }
-  if (typeof body.error === "string" && typeof body.user_message === "string") {
-    return new BackendApiError({
-      code: body.error,
-      detail: body.message || `HTTP ${status}`,
-      userMessage: body.user_message,
-      details: body.details ?? null,
-      requestId: typeof body.request_id === "string" ? body.request_id : void 0,
-      status
+  onRejoin?.(rejoin);
+  let unavailable;
+  try {
+    const handle = await openMatrxStream(bound, rejoin.rejoinPath, {
+      ...streamOptions,
+      // The rejoin routes take no body model; the reference client posts {}.
+      body: {}
     });
+    await drain(handle, onEnvelope);
+    return { kind: "rejoined", rejoin };
+  } catch (error) {
+    const read = readLiveStreamUnavailable(error);
+    if (!read) throw error;
+    unavailable = read;
   }
-  if (typeof body.error === "object" && body.error !== null) {
-    const errorObj = body.error;
-    return new BackendApiError({
-      code: errorObj.type || errorObj.error || statusToCode(status),
-      detail: errorObj.message || `HTTP ${status}`,
-      userMessage: errorObj.user_message || errorObj.user_visible_message || errorObj.message || `Request failed (${status})`,
-      details: errorObj.details ?? null,
-      requestId: typeof errorObj.request_id === "string" ? errorObj.request_id : void 0,
-      status
+  return followUnavailableRejoin(bound, rejoin, unavailable, {
+    ...signalOnly,
+    ...onOperationEvent ? { onOperationEvent } : {},
+    ...onWorkflowEvent ? { onWorkflowEvent } : {},
+    ...follow ? { follow } : {}
+  });
+}
+function readLiveStreamUnavailable(error) {
+  if (!isLiveStreamUnavailable(error)) return null;
+  return { runId: firstString(detailCandidates(bodyOf(error)), "run_id") };
+}
+async function followUnavailableRejoin(transport, rejoin, unavailable, options = {}) {
+  const bound = options.organizationId ? withRunOrganization(transport, options.organizationId) : transport;
+  const signalOnly = options.signal ? { signal: options.signal } : {};
+  const runId = unavailable.runId ?? rejoin.runId;
+  if (runId && rejoin.rejoinPath.startsWith("/runtime/operations/")) {
+    const result2 = await followWorkflowRunEvents(bound, runId, {
+      ...signalOnly,
+      onEvent: (event, seq) => options.onWorkflowEvent?.(event, seq)
     });
+    return { kind: "followed_workflow", rejoin, runId, ended: result2.ended };
   }
-  if (Array.isArray(body.detail)) {
-    const first = body.detail[0];
-    const firstMsg = first && typeof first.msg === "string" ? first.msg : null;
-    return new BackendApiError({
-      code: statusToCode(status),
-      detail: firstMsg ? `Validation error: ${firstMsg}` : JSON.stringify(body.detail),
-      userMessage: firstMsg || `Request failed (${status})`,
-      details: body.detail,
-      status
-    });
+  const liveRequestId = rejoin.liveRequestId;
+  const statusView = liveRequestId ? await getRuntimeOperationStatus(bound, liveRequestId, signalOnly) : null;
+  const operation = statusView?.operations.find((op) => !op.is_terminal) ?? statusView?.operations[0] ?? null;
+  if (!operation) {
+    return { kind: "followed", rejoin, executionId: null, ended: false, status: null };
   }
-  if (typeof body.detail === "object" && body.detail !== null && !Array.isArray(body.detail)) {
-    const d = body.detail;
-    const code = typeof d.code === "string" && d.code || typeof d.error === "string" && d.error || statusToCode(status);
-    const message = typeof d.message === "string" && d.message || typeof d.detail === "string" && d.detail || `HTTP ${status}`;
-    return new BackendApiError({
-      code,
-      detail: message,
-      userMessage: typeof d.user_message === "string" && d.user_message || typeof d.user_visible_message === "string" && d.user_visible_message || message,
-      details: d.details ?? d,
-      requestId: typeof d.request_id === "string" ? d.request_id : void 0,
-      status
-    });
+  if (operation.is_terminal) {
+    return {
+      kind: "followed",
+      rejoin,
+      executionId: operation.execution_id,
+      ended: true,
+      status: operation.status
+    };
   }
-  return new BackendApiError({
-    code: typeof body.error === "string" ? body.error : statusToCode(status),
-    detail: body.message || body.detail || body.error || `HTTP ${status}`,
-    userMessage: body.user_message || body.user_visible_message || body.message || body.detail || `Request failed (${status})`,
-    details: body.details ?? null,
-    requestId: typeof body.request_id === "string" ? body.request_id : void 0,
-    status
+  const result = await followRuntimeOperationToEnd(bound, operation.execution_id, {
+    ...options.follow,
+    lastEventSeq: operation.last_event_seq,
+    ...signalOnly,
+    onEvent: (event) => options.onOperationEvent?.(event)
   });
+  return {
+    kind: "followed",
+    rejoin,
+    executionId: operation.execution_id,
+    ended: result.ended,
+    status: result.status
+  };
 }
-function parseCallApiError(error) {
-  const status = error.status ?? 500;
-  const body = error.serverDetail && typeof error.serverDetail === "object" && !Array.isArray(error.serverDetail) ? error.serverDetail : { message: error.message };
-  return parseHttpErrorBody(body, status);
+async function attempt(run) {
+  try {
+    await run();
+    return { reloaded: true };
+  } catch (error) {
+    return { reloaded: false, error };
+  }
 }
-function parseStreamError(data) {
-  if (!data || typeof data !== "object") {
-    return new BackendApiError({
-      code: "internal_error",
-      detail: typeof data === "string" ? data : "Unknown streaming error",
-      userMessage: typeof data === "string" ? data : "Something went wrong"
-    });
+async function settleRunPickup(pickup, options) {
+  switch (pickup.kind) {
+    case "resumed":
+    case "rejoined":
+      return { state: "streamed" };
+    case "resume_conflict":
+      return { state: "retry" };
+    case "followed_workflow":
+    case "followed": {
+      const status = pickup.kind === "followed" ? pickup.status : null;
+      const nothingLive = pickup.kind === "followed" && pickup.executionId === null;
+      if (pickup.ended || nothingLive) {
+        return { state: "settled", status, ...await attempt(options.reloadSavedTurn) };
+      }
+      return {
+        state: "still_running",
+        ...await attempt(options.onStillRunning ?? options.reloadSavedTurn)
+      };
+    }
   }
-  const obj = data;
-  const details = typeof obj.details === "object" && obj.details !== null ? obj.details : null;
-  return new BackendApiError({
-    code: obj.code || obj.error_type || obj.error || "internal_error",
-    detail: obj.message || "Streaming error",
-    userMessage: obj.user_message || obj.message || "Something went wrong",
-    details,
-    requestId: typeof obj.request_id === "string" ? obj.request_id : typeof details?.request_id === "string" ? details.request_id : void 0
+}
+
+// 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 parsePersistedBackendError(data, requestId = "") {
-  if (!data || typeof data !== "object") return null;
-  const error = data;
-  const failures = Array.isArray(error.failures) ? error.failures : [];
-  const firstSpecific = failures.find(
-    (failure) => typeof failure === "object" && failure !== null && typeof failure.message === "string"
+function startAgentRun(transport, agentId, request, options = {}) {
+  return streamCall(
+    transport,
+    `/ai/agents/${encodePathSegment(agentId)}`,
+    request,
+    options
+  );
+}
+function startMandateRun(transport, mandateKey, request, options = {}) {
+  return streamCall(
+    transport,
+    `/ai/mandates/${encodePathSegment(mandateKey)}`,
+    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
   );
-  const summary = typeof error.message === "string" ? error.message : "Backend operation failed";
-  const specific = typeof firstSpecific?.message === "string" ? firstSpecific.message : summary;
-  const detail = specific === summary ? summary : `${summary}: ${specific}`;
-  const code = typeof error.type === "string" ? error.type : "internal_error";
-  const userMessage = typeof error.user_message === "string" && error.user_message ? error.user_message : detail;
-  return new BackendApiError({
-    code,
-    detail,
-    userMessage,
-    details: error,
-    requestId
-  });
 }
-var GENERIC_MESSAGE_PATTERNS = [
-  /failed unexpectedly/i,
-  /^\s*something went wrong/i,
-  /please try again(\s+later)?\.?\s*$/i,
-  /^\s*request failed\b/i,
-  /^\s*unknown (streaming )?error/i,
-  /^\s*internal server error\.?\s*$/i
-];
-function isGenericUserMessage(message) {
-  const value = (message ?? "").trim();
-  if (!value) return true;
-  return GENERIC_MESSAGE_PATTERNS.some((pattern) => pattern.test(value));
+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 } : {}
+    }
+  );
 }
-function unwrapUpstreamError(message) {
-  const start = message.indexOf("{");
-  const end = message.lastIndexOf("}");
-  if (start < 0 || end <= start) return null;
-  let parsed;
-  try {
-    parsed = JSON.parse(message.slice(start, end + 1));
-  } catch {
-    return null;
+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 ?? "";
   }
-  if (typeof parsed !== "object" || parsed === null) return null;
-  const body = parsed;
-  const inner = typeof body.message === "string" && body.message || typeof body.detail === "string" && body.detail || "";
-  if (!inner) return null;
-  const statusMatch = /\bHTTP (\d{3})\b/.exec(message.slice(0, start));
-  return {
-    message: inner,
-    code: typeof body.error_type === "string" && body.error_type || typeof body.error === "string" && body.error || null,
-    userMessage: typeof body.user_message === "string" ? body.user_message : null,
-    requestId: typeof body.request_id === "string" ? body.request_id : null,
-    status: statusMatch ? Number(statusMatch[1]) : null
-  };
+};
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function describeBackendFailure(error) {
-  const chain = [];
-  let code = "internal_error";
-  let requestId = "";
-  let status = null;
-  let userFacing = null;
-  if (error instanceof BackendApiError) {
-    code = error.code;
-    requestId = error.requestId;
-    status = error.status;
-    userFacing = error.userMessage;
-    if (error.detail) chain.push(error.detail);
-    if (error.userMessage && error.userMessage !== error.detail) {
-      chain.push(error.userMessage);
+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: streamErrorText(payload) ?? "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
+      });
     }
-  } else if (error instanceof Error) {
-    chain.push(error.message);
-    userFacing = error.message;
-  } else if (typeof error === "string") {
-    chain.push(error);
-    userFacing = error;
-  } else {
-    chain.push("Unknown error");
   }
-  for (let cursor = 0; cursor < chain.length && cursor < 12; cursor += 1) {
-    const upstream = unwrapUpstreamError(chain[cursor] ?? "");
-    if (!upstream || chain.includes(upstream.message)) continue;
-    chain.push(upstream.message);
-    if (upstream.code) code = upstream.code;
-    if (upstream.requestId) requestId = upstream.requestId;
-    if (upstream.status !== null) status = upstream.status;
+  if (failure) throw failure;
+  if (!text && completion) {
+    const result = completion.result;
+    const output = stringField(result, "output");
+    if (output !== null) text = output;
   }
-  const specific = [...chain].reverse().find((message) => !isGenericUserMessage(message));
-  const cause = specific ?? chain[0] ?? "Unknown error";
-  const headlineWasGeneric = isGenericUserMessage(userFacing);
   return {
-    code,
-    cause,
-    headline: headlineWasGeneric ? cause : userFacing ?? cause,
-    headlineWasGeneric,
-    chain,
-    requestId,
-    status
+    text,
+    requestId: handle.requestId,
+    conversationId: handle.conversationId,
+    completion
   };
 }
-function getUserMessage(error) {
-  if (error instanceof BackendApiError) {
-    return error.userMessage;
-  }
-  if (error instanceof Error) {
-    return error.message;
-  }
-  if (typeof error === "string") {
-    return error;
-  }
-  if (typeof error === "object" && error !== null && typeof error.message === "string" && error.message) {
-    return error.message;
+
+// matrx/provider-failures.ts
+var clip = (value, max) => value.length > max ? value.slice(0, max) : value;
+function providerSessionFailureBody(failure) {
+  const message = failure.message?.trim() || failure.error_type?.trim() || (failure.status_code ? `HTTP ${failure.status_code}` : "provider session failed");
+  const body = {
+    provider: failure.provider,
+    message: clip(message, 4e3)
+  };
+  if (failure.model?.trim()) body.model = clip(failure.model.trim(), 200);
+  if (failure.error_type?.trim()) body.error_type = clip(failure.error_type.trim(), 200);
+  if (typeof failure.status_code === "number" && Number.isInteger(failure.status_code) && failure.status_code >= 100 && failure.status_code <= 599) {
+    body.status_code = failure.status_code;
   }
-  return "Something went wrong";
+  return body;
 }
-function statusToCode(status) {
-  switch (status) {
-    case 401:
-      return "auth_required";
-    case 403:
-      return "admin_required";
-    case 404:
-      return "not_found";
-    case 422:
-      return "validation_error";
-    default:
-      return "internal_error";
+async function reportProviderSessionFailure(transport, failure, options = {}) {
+  try {
+    return await requestJson(
+      transport,
+      "/broker/provider-failures",
+      {
+        method: "POST",
+        body: providerSessionFailureBody(failure),
+        ...options.signal ? { signal: options.signal } : {}
+      }
+    );
+  } catch (error) {
+    console.warn(
+      `[provider-failures] could not report a ${failure.provider} session failure`,
+      error
+    );
+    return null;
   }
 }
 
+// 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 } : {}
+    }
+  );
+}
+
 // matrx/endpoints.ts
 var ENDPOINTS = {
   /** AI endpoints — chat, agents, conversations */