@ai-matrx/agents 0.35.0 → 0.37.0

package/dist/index.cjs

@@ -31,6 +31,7 @@ __export(index_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,
@@ -48,6 +49,10 @@ __export(index_exports, {
   applyOrganizationContextHeader: () => applyOrganizationContextHeader,
   assertOrganizationMatchesOperation: () => assertOrganizationMatchesOperation,
   assertQueryOrganizationMatchesContext: () => assertQueryOrganizationMatchesContext,
+  bareStatusSentence: () => bareStatusSentence,
+  buildMatrxRequestBody: () => buildMatrxRequestBody,
+  buildMatrxRequestUrl: () => buildMatrxRequestUrl,
+  buildSafeRequestLog: () => buildSafeRequestLog,
   cancelAgentRun: () => cancelAgentRun,
   continueAgentConversation: () => continueAgentConversation,
   continueEphemeralConversationStart: () => continueEphemeralConversationStart,
@@ -60,6 +65,7 @@ __export(index_exports, {
   createWorkflowNodeProjection: () => createWorkflowNodeProjection,
   deriveRunInputs: () => deriveRunInputs,
   describeBackendFailure: () => describeBackendFailure,
+  executeMatrxCall: () => executeMatrxCall,
   extractMatrxErrorCode: () => extractMatrxErrorCode,
   extractMatrxErrorMessage: () => extractMatrxErrorMessage,
   fetchWithMatrxProtocolFallback: () => fetchWithMatrxProtocolFallback,
@@ -70,7 +76,9 @@ __export(index_exports, {
   getRuntimeOperationStatus: () => getRuntimeOperationStatus,
   getRuntimeOperationsByLink: () => getRuntimeOperationsByLink,
   getUserMessage: () => getUserMessage,
+  honestTransportMessage: () => honestTransportMessage,
   imageRoleVerdict: () => imageRoleVerdict,
+  isBareTransportCode: () => isBareTransportCode,
   isControlVariable: () => isControlVariable,
   isCoveredAiPath: () => isCoveredAiPath,
   isGenericUserMessage: () => isGenericUserMessage,
@@ -97,6 +105,7 @@ __export(index_exports, {
   parseCallApiError: () => parseCallApiError,
   parseHttpError: () => parseHttpError,
   parseHttpErrorBody: () => parseHttpErrorBody,
+  parseMatrxNdjsonResponse: () => parseMatrxNdjsonResponse,
   parseMatrxSseFrame: () => parseMatrxSseFrame,
   parsePersistedBackendError: () => parsePersistedBackendError,
   parseStreamError: () => parseStreamError,
@@ -115,6 +124,7 @@ __export(index_exports, {
   readMatrxErrorCodeFromMessage: () => readMatrxErrorCodeFromMessage,
   readMatrxNdjsonStream: () => readMatrxNdjsonStream,
   readMatrxSseStream: () => readMatrxSseStream,
+  redactUrlForRequestLog: () => redactUrlForRequestLog,
   referenceRoleCaption: () => referenceRoleCaption,
   rejoinRuntimeOperation: () => rejoinRuntimeOperation,
   reportProviderSessionFailure: () => reportProviderSessionFailure,
@@ -132,6 +142,7 @@ __export(index_exports, {
   runWaitTimeoutMessage: () => runWaitTimeoutMessage,
   runtimeOperationRejoinPath: () => runtimeOperationRejoinPath,
   settleRunPickup: () => settleRunPickup,
+  shouldReportMatrxCallError: () => shouldReportMatrxCallError,
   startAgentRun: () => startAgentRun,
   startMandateRun: () => startMandateRun,
   streamErrorText: () => streamErrorText,
@@ -1009,1384 +1020,1611 @@ 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;
-  }
-};
-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."
-    );
+  /** 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;
   }
-  const normalized = candidate.trim();
-  if (!(0, import_uuid.isUuidShape)(normalized)) {
-    throw new OrganizationContextError(
-      "organization_context_invalid",
-      "The selected organization ID is invalid."
-    );
+  /** 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
+    };
   }
-  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."
-      );
-    }
+};
+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";
   }
-  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."
-    );
+};
+function isStreamTransportLost(error) {
+  if (error instanceof StreamTransportError) return true;
+  if (error instanceof BackendApiError) {
+    return error.code === "stream_transport_lost";
   }
-}
-
-// 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}`;
+  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 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;
+  return false;
 }
-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;
+async function parseHttpError(response) {
+  const status = response.status;
+  let body = null;
   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);
-  }
-  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 result;
-}
-function aiVersionPathOverrides(version) {
-  if (version !== "v2") return {};
-  const map = {};
-  for (const template of V2_COVERED_AI_PATH_TEMPLATES) {
-    map[template] = toV2Path(template);
+    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
+      });
+    }
   }
-  return map;
-}
-
-// matrx/client.ts
-function classifyStatus(status) {
-  return status >= 400 && status < 500 ? "validation_error" : "http_error";
+  return parseHttpErrorBody(body, status);
 }
-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
-    };
+function parseHttpErrorBody(body, status) {
+  if (!body) {
+    return new BackendApiError({
+      code: statusToCode(status),
+      detail: `HTTP ${status}`,
+      userMessage: `Request failed (${status})`,
+      status
+    });
   }
-  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 (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
+    });
   }
-  if (err instanceof DOMException && err.name === "AbortError") {
-    return { type: "abort_error", message: "Request was cancelled." };
+  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
+    });
   }
-  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 (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
+    });
   }
-  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 };
+  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
+    });
   }
-  return { type: "unknown", message: String(err ?? "Unknown error") };
+  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
+  });
 }
-var PRODUCTION_CONNECT_TIMEOUT_MS = 15e3;
-function stripContentType(headers) {
-  return Object.fromEntries(
-    Object.entries(headers).filter(
-      ([name]) => name.toLowerCase() !== "content-type"
-    )
-  );
+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 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`."
-    );
+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"
+    });
   }
-  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
-  };
+  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
+  });
 }
-function continueStoredConversationStart(conversationId) {
-  return { conversation_id: conversationId, is_new: false, store: true };
+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 newEphemeralConversationStart(conversationId) {
-  return {
-    conversation_id: conversationId ?? mintMatrxConversationId(),
-    is_new: true,
-    store: false
-  };
+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 continueEphemeralConversationStart(conversationId, priorMessages) {
+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;
+  }
+  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 {
-    conversation_id: conversationId,
-    is_new: false,
-    store: false,
-    prior_messages: priorMessages
+    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
   };
 }
-
-// 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));
+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");
   }
-  const encoded = search.toString();
-  return encoded ? `?${encoded}` : "";
-}
-async function readServerDetail(response) {
-  try {
-    return await response.json();
-  } catch {
-    return void 0;
+  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;
   }
-}
-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) {
+  const specific = [...chain].reverse().find((message) => !isGenericUserMessage(message));
+  const cause = specific ?? chain[0] ?? "Unknown error";
+  const headlineWasGeneric = isGenericUserMessage(userFacing);
   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
+    code,
+    cause,
+    headline: headlineWasGeneric ? cause : userFacing ?? cause,
+    headlineWasGeneric,
+    chain,
+    requestId,
+    status
   };
 }
-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 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";
+}
+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";
   }
-  return response;
 }
 
-// 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 } : {} }
+// 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."
     );
-  } catch (error) {
-    if (error instanceof MatrxApiError && error.status === 404) return null;
-    throw error;
   }
 }
-async function getRuntimeOperationsByLink(transport, linkKind, linkId, options = {}) {
-  const query = buildQuery(
-    options.limit !== void 0 ? { limit: options.limit } : {}
-  );
-  try {
-    return await requestJson(
-      transport,
-      `/runtime/operations/by-link/${encodePathSegment(linkKind)}/${encodePathSegment(linkId)}${query}`,
-      { method: "GET", ...options.signal ? { signal: options.signal } : {} }
+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."
     );
-  } catch (error) {
-    if (error instanceof MatrxApiError && error.status === 404) return null;
-    throw error;
   }
+  return normalized.toLowerCase();
 }
-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;
+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."
+      );
     }
-  } catch {
   }
-  return null;
-}
-async function* followRuntimeOperationEvents(transport, executionId, options = {}) {
-  let cursor = options.lastEventSeq ?? 0;
-  const headers = { Accept: "text/event-stream" };
-  if (cursor > 0) headers["Last-Event-ID"] = String(cursor);
-  const response = await requestStream(
-    transport,
-    `/runtime/executions/${encodePathSegment(executionId)}/events/stream`,
-    {
-      method: "GET",
-      headers,
-      ...options.signal ? { signal: options.signal } : {}
-    }
+  const withoutOrganizationHeader = Object.fromEntries(
+    Object.entries(headers).filter(
+      ([name]) => name.toLowerCase() !== "x-organization-id"
+    )
   );
-  const frames = readMatrxSseStream(
-    response.body,
-    options.onIncomplete ? { onIncomplete: options.onIncomplete } : {}
+  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)
   );
-  for await (const frame of frames) {
-    if (frame.event === "end") {
-      yield { type: "end", status: parseEndStatus(frame.data), cursor };
-      return;
-    }
-    if (frame.event === "execution_event" && frame.data !== null) {
-      let event;
-      try {
-        event = JSON.parse(frame.data);
-      } catch (error) {
-        options.onMalformedFrame?.(frame, error);
-        yield { type: "liveness", cursor };
-        continue;
-      }
-      if (frame.seq !== null && frame.seq > cursor) cursor = frame.seq;
-      yield { type: "event", event, seq: frame.seq, cursor };
-      continue;
-    }
-    yield { type: "liveness", cursor };
+  if (queryOrganizationId !== requireOrganizationContext(organizationId)) {
+    throw new OrganizationContextError(
+      "organization_context_mismatch",
+      "Query organization_id must match the request context organization."
+    );
   }
 }
-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);
-        }
-      }
-      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));
-    }
+
+// 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 { ended: false, status: null };
+  return withLead.startsWith("/v2/") ? withLead : `/v2${withLead}`;
 }
-async function rejoinRuntimeOperation(transport, requestId, options = {}) {
-  const response = await requestStream(
-    transport,
-    `/runtime/operations/${encodePathSegment(requestId)}/rejoin`,
-    {
-      method: "POST",
-      // The route takes no body model; the reference client posts an empty
-      // JSON object. Match it so proxies see an ordinary JSON POST.
-      body: {},
-      ...options.signal ? { signal: options.signal } : {}
-    }
-  );
-  return toRunHandle(response, options);
+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));
 }
-
-// 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 isRecord4(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+function isV2Path(pathOrUrl) {
+  return /\/v2\/ai\//.test(pathOrUrl);
 }
-function nonBlank(value) {
-  return typeof value === "string" && value.trim() ? value : null;
+function toV1FallbackUrl(url) {
+  return url.replace(/\/v2\/ai\//, "/ai/");
 }
-function detailCandidates(body) {
-  if (!isRecord4(body)) return [];
-  const out = [];
-  if (isRecord4(body.detail)) out.push(body.detail);
-  if (isRecord4(body.details)) out.push(body.details);
-  out.push(body);
-  return out;
+function applyAiApiVersion(path, version) {
+  if (version !== "v2") return path;
+  return isCoveredAiPath(path) ? toV2Path(path) : path;
 }
-function statusOf(error) {
-  if (!isRecord4(error) && !(error instanceof Error)) return null;
-  const status = error.status;
-  return typeof status === "number" ? status : null;
+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);
+  }
+  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 result;
+}
+function aiVersionPathOverrides(version) {
+  if (version !== "v2") return {};
+  const map = {};
+  for (const template of V2_COVERED_AI_PATH_TEMPLATES) {
+    map[template] = toV2Path(template);
+  }
+  return map;
+}
+
+// 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));
+    }
+  }
+  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;
+  }
+  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 };
 }
-function bodyOf(error) {
-  if (!isRecord4(error) && !(error instanceof Error)) return void 0;
-  return error.serverDetail;
+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 readMatrxErrorCode(error) {
-  for (const candidate of detailCandidates(bodyOf(error))) {
-    const code = nonBlank(candidate.code);
-    if (code) return code;
+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.";
   }
-  for (const candidate of detailCandidates(bodyOf(error))) {
-    const code = nonBlank(candidate.error);
-    if (code) return code;
+  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.";
   }
-  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;
+  if (status === 429) {
+    return "The server is rate-limiting this request. Wait a few seconds and try again.";
   }
-  return null;
+  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.";
 }
-async function readConversationOrganizationId(conversationId, read, onUnreadable) {
+function honestTransportMessage(raw, status) {
+  if (raw && !isBareTransportCode(raw)) return raw;
+  return bareStatusSentence(status ?? 0);
+}
+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 redactUrlForRequestLog(url) {
   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));
+    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]`;
   }
-  return null;
 }
-function firstString(candidates, key) {
-  for (const candidate of candidates) {
-    const value = nonBlank(candidate[key]);
-    if (value) return value.trim();
+function shouldReportMatrxCallError(status, expectedErrorStatuses) {
+  return status == null || !expectedErrorStatuses?.includes(status);
+}
+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 null;
+  return { events: events(), ...ids };
 }
-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);
+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 {
-    liveRequestId,
-    rejoinPath,
-    runId: firstString(candidates, "run_id"),
-    code,
-    body: isRecord4(root) ? root : {}
+    type: response.status >= 400 && response.status < 500 ? "validation_error" : "http_error",
+    message: extractMatrxErrorMessage(serverDetail) ?? bareStatusSentence(response.status),
+    status: response.status,
+    serverDetail
   };
 }
-function readLiveRunRequestId(error) {
-  return readLiveRunRejoin(error)?.liveRequestId ?? null;
-}
-function isResumeConflict(error) {
-  return statusOf(error) === 409 && readMatrxErrorCode(error) === MATRX_RESUME_CONFLICT;
+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 {
+    ...parsed.requestId !== null ? { requestId: parsed.requestId } : {},
+    ...parsed.conversationId !== null ? { conversationId: parsed.conversationId } : {}
+  };
 }
-function isLiveStreamUnavailable(error) {
-  return statusOf(error) === 409 && readMatrxErrorCode(error) === MATRX_LIVE_STREAM_UNAVAILABLE;
+
+// matrx/client.ts
+function classifyStatus(status) {
+  return status >= 400 && status < 500 ? "validation_error" : "http_error";
 }
-function runtimeOperationRejoinPath(requestId) {
-  return `/runtime/operations/${encodePathSegment(requestId)}/rejoin`;
+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) };
 }
-function streamErrorText(eventOrPayload) {
-  if (!isRecord4(eventOrPayload)) return null;
-  const payload = typeof eventOrPayload.event === "string" && isRecord4(eventOrPayload.data) ? eventOrPayload.data : eventOrPayload;
-  return nonBlank(payload.user_message) ?? nonBlank(payload.message);
+var PRODUCTION_CONNECT_TIMEOUT_MS = 15e3;
+function stripContentType(headers) {
+  return Object.fromEntries(
+    Object.entries(headers).filter(
+      ([name]) => name.toLowerCase() !== "content-type"
+    )
+  );
 }
-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 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`."
+    );
+  }
+  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;
+    }
+  };
 }
-function withRunOrganization(transport, organizationId) {
-  const orgId = requireOrganizationContext(organizationId);
+
+// matrx/conversation.ts
+function mintMatrxConversationId() {
+  return crypto.randomUUID();
+}
+function newStoredConversationStart(conversationId) {
   return {
-    fetch: (path, init) => transport.fetch(path, {
-      ...init,
-      headers: { ...init.headers, "X-Organization-Id": orgId }
-    })
+    conversation_id: conversationId ?? mintMatrxConversationId(),
+    is_new: true,
+    store: true
   };
 }
-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 } : {}
-      }
-    );
-  } 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 (!isRecord4(parsed)) continue;
-      options.onEvent(parsed, parsed.event === "node_stream" ? null : frame.seq);
-    }
-  } catch (error) {
-    if (!options.signal?.aborted) throw error;
-  }
-  return { ended: false };
+function continueStoredConversationStart(conversationId) {
+  return { conversation_id: conversationId, is_new: false, store: true };
 }
-async function drain(handle, onEnvelope) {
-  for await (const envelope of handle.events) onEnvelope(envelope);
+function newEphemeralConversationStart(conversationId) {
+  return {
+    conversation_id: conversationId ?? mintMatrxConversationId(),
+    is_new: true,
+    store: false
+  };
 }
-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 continueEphemeralConversationStart(conversationId, priorMessages) {
+  return {
+    conversation_id: conversationId,
+    is_new: false,
+    store: false,
+    prior_messages: priorMessages
   };
-  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;
+}
+
+// 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 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)
-      };
-    }
-  }
-}
-
-// 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 },
+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 } : {}
   });
-  return toRunHandle(response, options);
+  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;
 }
-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 isRecord5(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function stringField(value, key) {
-  if (!isRecord5(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 = isRecord5(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" || !isRecord5(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 = isRecord5(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 isRecord4(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 (!isRecord4(body)) return [];
+  const out = [];
+  if (isRecord4(body.detail)) out.push(body.detail);
+  if (isRecord4(body.details)) out.push(body.details);
+  out.push(body);
+  return out;
+}
+function statusOf(error) {
+  if (!isRecord4(error) && !(error instanceof Error)) return null;
+  const status = error.status;
+  return typeof status === "number" ? status : null;
+}
+function bodyOf(error) {
+  if (!isRecord4(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: isRecord4(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 (!isRecord4(eventOrPayload)) return null;
+  const payload = typeof eventOrPayload.event === "string" && isRecord4(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 (!isRecord4(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 isRecord5(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 (!isRecord5(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 = isRecord5(envelope.data) ? envelope.data : null;
+      failure = new MatrxRunError({
+        message: streamErrorText(payload) ?? "The agent run failed",
+        errorPayload: payload,
+        partialText: text
+      });
+      continue;
+    }
+    if (envelope.event !== "completion" || !isRecord5(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 = isRecord5(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 */