@ai-matrx/api 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,1668 @@
+export { monitorStream } from './chunk-YTEOFGFC.js';
+import { OrganizationContextError, BackendApiError, parseHttpError, MatrxApiError, applyOrganizationContextHeader, extractMatrxErrorCode, extractMatrxErrorMessage, readMatrxNdjsonStream, readMatrxSseStream, requireOrganizationContext, StreamTransportError } from './chunk-UONBYRE4.js';
+export { BackendApiError, CONTRACT_SHA256, DEPLOYMENTS, DOMAINS, MatrxApiError, OrganizationContextError, StreamTransportError, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, createApi, createOrganizationOperation, describeBackendFailure, extractMatrxErrorCode, extractMatrxErrorMessage, getUserMessage, isGenericUserMessage, isStreamTransportLost, openJsonOrStream, openStream, parseCallApiError, parseHttpError, parseHttpErrorBody, parsePersistedBackendError, parseStreamError, requireOrganizationContext, unwrapUpstreamError } from './chunk-UONBYRE4.js';
+import { resilientFetch, isNetError, extractErrorMessage } from './chunk-KIEAFMKB.js';
+export { AbortedError, ConnectTimeoutError, HeartbeatTimeoutError, HttpError, NetError, NetworkError, OfflineError, TotalTimeoutError, extractErrorMessage, isNetError, isTransportFailure, resilientFetch, toNetError, withRetry } from './chunk-KIEAFMKB.js';
+import { credentialToHeaders } from './chunk-AY5N6EA4.js';
+export { API_KEY_PREFIX, MATRX_HEADERS, credentialToHeaders, toCredentialsPort } from './chunk-AY5N6EA4.js';
+import { formatDurationSeconds } from '@ai-matrx/kit/format';
+
+// src/core/protocol.ts
+var MATRX_AI_API_VERSION_DEFAULT = "v2";
+var V2_COVERED_AI_PATH_TEMPLATES = [
+  "/ai/manual",
+  "/ai/chat",
+  "/ai/agents/{agent_id}",
+  "/ai/agent/{agent_id}",
+  // singular alias — behaves identically
+  "/ai/conversations/{conversation_id}",
+  "/ai/conversation/{conversation_id}",
+  // singular alias
+  "/ai/prompts/{prompt_id}",
+  // saved-prompt execution
+  "/ai/mandates/{mandate_key}"
+  // THE MANDATE DOOR — `/v2` sibling exists (routers/v2.py)
+];
+function toV2Path(path) {
+  const withLead = path.startsWith("/") ? path : `/${path}`;
+  if (withLead.startsWith("/api/")) {
+    const rest = withLead.slice("/api".length);
+    return rest.startsWith("/v2/") ? withLead : `/api/v2${rest}`;
+  }
+  return withLead.startsWith("/v2/") ? withLead : `/v2${withLead}`;
+}
+var COVERED_INTERPOLATED_PATH = [
+  /^(?:\/api)?\/ai\/manual$/,
+  /^(?:\/api)?\/ai\/chat$/,
+  /^(?:\/api)?\/ai\/agents\/[^/]+$/,
+  /^(?:\/api)?\/ai\/agent\/[^/]+$/,
+  /^(?:\/api)?\/ai\/conversations\/[^/]+$/,
+  /^(?:\/api)?\/ai\/conversation\/[^/]+$/,
+  /^(?:\/api)?\/ai\/prompts\/[^/]+$/,
+  // `/warm` etc. deliberately don't match
+  /^(?:\/api)?\/ai\/mandates\/[^/]+$/
+  // the mandate door
+];
+function isCoveredAiPath(path) {
+  return COVERED_INTERPOLATED_PATH.some((re) => re.test(path));
+}
+function isV2Path(pathOrUrl) {
+  return /\/v2\/ai\//.test(pathOrUrl);
+}
+function toV1FallbackUrl(url) {
+  return url.replace(/\/v2\/ai\//, "/ai/");
+}
+function applyAiApiVersion(path, version) {
+  if (version !== "v2") return path;
+  return isCoveredAiPath(path) ? toV2Path(path) : path;
+}
+async function fetchWithMatrxProtocolFallback(url, init, opts = {}) {
+  const { onDowngrade, ...fetchOpts } = opts;
+  const logDowngrade = (reason, status2) => {
+    console.warn(
+      `[matrx] ai_v2_downgrade \u2192 retrying on v1. v2=${url} reason=${reason}`
+    );
+    onDowngrade?.({ url, reason, ...status2 !== void 0 ? { status: status2 } : {} });
+  };
+  if (!isV2Path(url)) return resilientFetch(url, init, fetchOpts);
+  let result;
+  try {
+    result = await resilientFetch(url, init, fetchOpts);
+  } catch (err) {
+    const isAbort2 = isNetError(err) && err.code === "aborted" || err instanceof Error && err.name === "AbortError";
+    if (isAbort2) throw err;
+    logDowngrade(String(err));
+    return resilientFetch(toV1FallbackUrl(url), init, fetchOpts);
+  }
+  const status = result.response.status;
+  if (status === 404 || status === 405 || status >= 500) {
+    logDowngrade(`HTTP ${status}`, status);
+    return 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;
+}
+
+// src/core/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) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(queryParams)) {
+      if (value === null || value === void 0) continue;
+      const values = Array.isArray(value) ? value : [value];
+      for (const entry of values) search.append(key, String(entry));
+    }
+    const qs = search.toString();
+    if (qs) return `${url}${url.includes("?") ? "&" : "?"}${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 };
+}
+var BARE_TRANSPORT_CODE = /^\s*(?:HTTP|HTTP\s*Error|Status(?:\s*Code)?)?\s*[:\-]?\s*\d{3}\s*[.:!]?\s*$/i;
+function isBareTransportCode(text) {
+  if (!text) return false;
+  return BARE_TRANSPORT_CODE.test(text);
+}
+function bareStatusSentence(status) {
+  if (status === 401 || status === 403) {
+    return "The server would not let this request through \u2014 your session may have expired, or this account may not have access here. Sign in again, and if it repeats, ask an administrator.";
+  }
+  if (status === 404) {
+    return "The server has nothing at that address. Reload the page; if it repeats, report it \u2014 a client asking for something that no longer exists is a defect, not your mistake.";
+  }
+  if (status === 429) {
+    return "The server is rate-limiting this request. Wait a few seconds and try again.";
+  }
+  if (status >= 500) {
+    return "The server failed while answering this, and sent no explanation. Try again in a moment; if it repeats, report it with the request id above.";
+  }
+  return "The server refused this request and sent no reason with it \u2014 the missing reason is itself a defect worth reporting. Reload the page and try once more; if it repeats, report it with the request id above.";
+}
+function 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 parsed = new URL(url);
+    for (const key of parsed.searchParams.keys()) {
+      parsed.searchParams.set(key, "[REDACTED]");
+    }
+    return parsed.toString();
+  } catch {
+    const queryIndex = url.indexOf("?");
+    return queryIndex === -1 ? url : `${url.slice(0, queryIndex)}?[REDACTED]`;
+  }
+}
+function 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 { events: events(), ...ids };
+}
+var DEFAULT_CONNECT_TIMEOUT_MS = 15e3;
+var DEFAULT_JSON_TOTAL_TIMEOUT_MS = 3e4;
+async function httpErrorFrom(response) {
+  const serverDetail = await response.json().catch(() => void 0);
+  return {
+    type: response.status >= 400 && response.status < 500 ? "validation_error" : "http_error",
+    message: extractMatrxErrorMessage(serverDetail) ?? bareStatusSentence(response.status),
+    status: response.status,
+    serverDetail
+  };
+}
+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 } : {}
+  };
+}
+async function sendMatrxRequest(url, init = {}, options = {}) {
+  const callerSignal = options.signal ?? init.signal ?? void 0;
+  if (options.timeoutMs === void 0) {
+    return fetch(url, { ...init, ...callerSignal ? { signal: callerSignal } : {} });
+  }
+  const controller = new AbortController();
+  const onCallerAbort = () => controller.abort(callerSignal?.reason);
+  if (callerSignal) {
+    if (callerSignal.aborted) controller.abort(callerSignal.reason);
+    else callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+  }
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, options.timeoutMs);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } catch (error) {
+    if (timedOut) {
+      throw new BackendApiError({
+        code: "request_timeout",
+        detail: `${init.method ?? "GET"} ${url} exceeded ${options.timeoutMs}ms`,
+        userMessage: "The request timed out \u2014 please retry.",
+        status: 504
+      });
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    callerSignal?.removeEventListener("abort", onCallerAbort);
+  }
+}
+async function readMatrxJsonResponse(response) {
+  if (!response.ok) throw await parseHttpError(response);
+  if (response.status === 204) return null;
+  return await response.json();
+}
+
+// src/core/client.ts
+function classifyStatus(status) {
+  return status >= 400 && status < 500 ? "validation_error" : "http_error";
+}
+function normalizeMatrxError(err) {
+  if (err instanceof OrganizationContextError) {
+    return {
+      type: "validation_error",
+      message: err.message,
+      code: err.code,
+      name: err.name,
+      ...err.stack !== void 0 ? { stack: err.stack } : {}
+    };
+  }
+  if (err instanceof DOMException && err.name === "AbortError") {
+    return { type: "abort_error", message: "Request was cancelled." };
+  }
+  if (err instanceof MatrxApiError) {
+    return {
+      type: classifyStatus(err.status),
+      message: honestTransportMessage(err.message, err.status),
+      status: err.status,
+      serverDetail: err.serverDetail,
+      ...err.code ? { code: err.code } : {},
+      name: err.name
+    };
+  }
+  if (err instanceof BackendApiError) {
+    return {
+      type: "network_error",
+      message: honestTransportMessage(
+        err.detail || err.userMessage,
+        err.status ?? void 0
+      ),
+      code: err.code,
+      name: err.name,
+      ...err.status !== null ? { status: err.status } : {},
+      ...err.details !== null ? { serverDetail: err.details } : {}
+    };
+  }
+  if (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: extractErrorMessage(err) };
+}
+var PRODUCTION_CONNECT_TIMEOUT_MS = 15e3;
+function stripContentType(headers) {
+  return Object.fromEntries(
+    Object.entries(headers).filter(
+      ([name]) => name.toLowerCase() !== "content-type"
+    )
+  );
+}
+var ORGANIZATION_HEADER = "x-organization-id";
+function readOrganizationHeader(headers) {
+  for (const [name, value] of Object.entries(headers ?? {})) {
+    if (name.toLowerCase() === ORGANIZATION_HEADER && value.trim().length > 0) {
+      return value;
+    }
+  }
+  return null;
+}
+function stripOrganizationHeader(headers) {
+  return Object.fromEntries(
+    Object.entries(headers).filter(
+      ([name]) => name.toLowerCase() !== ORGANIZATION_HEADER
+    )
+  );
+}
+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 = (callOrganizationId) => {
+    if (organizationId === void 0) return null;
+    if (callOrganizationId !== null) return requireOrganizationContext(callOrganizationId);
+    const candidate = typeof organizationId === "function" ? organizationId() : organizationId;
+    return requireOrganizationContext(candidate);
+  };
+  return {
+    async fetch(path, init) {
+      const target = await resolve(init);
+      const callOrganizationId = readOrganizationHeader(init.headers);
+      const versionedPath = applyAiApiVersion(path, resolveVersion());
+      const url = `${target.baseUrl}${versionedPath}`;
+      const credentialHeaders = credentials ? credentialToHeaders(await credentials.get()) : {};
+      const policyHeaders = stripContentType(target.policyHeaders ?? {});
+      let headers = {
+        ...init.headers,
+        ...stripContentType(credentialHeaders),
+        ...callOrganizationId === null ? policyHeaders : stripOrganizationHeader(policyHeaders)
+      };
+      const orgId = resolveOrganizationId(callOrganizationId);
+      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;
+    }
+  };
+}
+
+// src/core/api-target-log.ts
+var SUSPECT_HOST_FRAGMENTS = ["sandbox"];
+function looksSuspect(url) {
+  const lower = url.toLowerCase();
+  return SUSPECT_HOST_FRAGMENTS.some((frag) => lower.includes(frag));
+}
+function logApiTarget(url, context) {
+  const { source, method, channel, activeServer, ...extra } = context;
+  let origin = url;
+  try {
+    origin = new URL(url).origin;
+  } catch {
+  }
+  const suspect = looksSuspect(url);
+  const tag = suspect ? "\u{1F6A8} API TARGET (SANDBOX?)" : "\u{1F4E1} API TARGET";
+  const style = suspect ? "font-weight:bold;color:#fff;background:#c0392b;padding:1px 4px;border-radius:3px;" : "font-weight:bold;color:#fff;background:#16a085;padding:1px 4px;border-radius:3px;";
+  const meta = {
+    origin,
+    fullUrl: url,
+    source
+  };
+  if (method) meta.method = method;
+  if (channel) meta.channel = channel;
+  if (activeServer) meta.activeServer = activeServer;
+  for (const [k, v] of Object.entries(extra)) {
+    if (v !== void 0) meta[k] = v;
+  }
+  const log = suspect ? console.error : console.info;
+  log(
+    `%c${tag}%c ${method ? method + " " : ""}${url}`,
+    style,
+    "color:inherit;",
+    meta
+  );
+}
+
+// src/core/endpoint-path.ts
+function normalizeLeadingSlash(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return "";
+  const withLead = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return withLead.length > 1 && withLead.endsWith("/") ? withLead.slice(0, -1) : withLead;
+}
+function resolveEndpointPath(canonicalPath, config) {
+  if (!config) return canonicalPath;
+  const override = config.pathOverrides?.[canonicalPath];
+  if (override && override.trim()) {
+    return normalizeLeadingSlash(override);
+  }
+  const version = config.apiVersion?.trim();
+  if (version) {
+    const prefix = normalizeLeadingSlash(version);
+    const path = canonicalPath.startsWith("/") ? canonicalPath : `/${canonicalPath}`;
+    return `${prefix}${path}`;
+  }
+  return canonicalPath;
+}
+
+// src/core/desktop-target.ts
+var DESKTOP_NATIVE_CAPABILITY = "desktop-native";
+function applyDesktopTargetToRequestBody(body, targetInstanceId) {
+  if (!targetInstanceId || !isRecord(body)) return;
+  const existingClient = isRecord(body.client) ? body.client : null;
+  const existingState = existingClient && isRecord(existingClient.state) ? existingClient.state : null;
+  const existingDesktopState = existingState && isRecord(existingState[DESKTOP_NATIVE_CAPABILITY]) ? existingState[DESKTOP_NATIVE_CAPABILITY] : null;
+  if (!existingClient || !existingState || !existingDesktopState) return;
+  body.target_instance_id ??= targetInstanceId;
+  existingDesktopState.target_instance_id ??= targetInstanceId;
+}
+function isRecord(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+var RUN_OUTPUT_KINDS = ["text", "image", "video", "audio"];
+var RUN_WAIT_KNOB_FEATURE = "agents.run_wait";
+var RUN_STREAM_LIFETIME_BACKSTOP_MS = 24 * 60 * 60 * 1e3;
+function isJobOutputKind(kind) {
+  return kind !== "text";
+}
+function runOutputKindFromModalities(output) {
+  const set = new Set((output ?? []).map((m) => m.toLowerCase()));
+  if (set.has("video")) return "video";
+  if (set.has("image")) return "image";
+  if (set.has("audio")) return "audio";
+  return "text";
+}
+function runWaitKnobKey(kind) {
+  return `${kind}_seconds`;
+}
+async function resolveRunWaitWith(readKnob, organizationId, userId, kind) {
+  const key = runWaitKnobKey(kind);
+  if (!organizationId) {
+    return { firstResponseMs: RUN_STREAM_LIFETIME_BACKSTOP_MS, seconds: null, kind };
+  }
+  try {
+    const raw = await readKnob(organizationId, userId ?? null, {
+      feature: RUN_WAIT_KNOB_FEATURE,
+      key
+    });
+    const seconds = typeof raw === "number" ? raw : Number(raw);
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+      throw new Error(`it resolves to ${JSON.stringify(raw)}, not a number of seconds`);
+    }
+    return { firstResponseMs: Math.round(seconds * 1e3), seconds, kind };
+  } catch (error) {
+    console.error(
+      `[run-wait] The "${RUN_WAIT_KNOB_FEATURE}.${key}" setting could not be read \u2014 ${error instanceof Error ? error.message : String(error)}. This run waits for the server without a first-response limit (the 24-hour stream backstop) instead of inventing one. Remedy: seed the knob (matrx-frontend migrations/agents_run_wait_knobs.sql) or fix the knob snapshot read.`
+    );
+    return {
+      firstResponseMs: RUN_STREAM_LIFETIME_BACKSTOP_MS,
+      seconds: null,
+      kind
+    };
+  }
+}
+var KIND_NOUN = {
+  text: "a reply",
+  image: "an image",
+  video: "a video",
+  audio: "audio"
+};
+function runJobLabel(kind, modelLabel) {
+  const what = kind === "text" ? "Writing a reply" : `Generating ${KIND_NOUN[kind]}`;
+  return modelLabel ? `${what} with ${modelLabel}` : what;
+}
+function runWaitTimeoutMessage(kind, modelLabel, seconds) {
+  const waited = seconds != null ? (
+    // An exact limit an admin configured, so both tiers: "1 minute 30 seconds".
+    `within ${formatDurationSeconds(seconds, { style: "long", parts: 2, round: "nearest" })}`
+  ) : "in time";
+  const who = modelLabel ? ` (${modelLabel})` : "";
+  return `The server did not start ${kind === "text" ? "answering" : `generating ${KIND_NOUN[kind]}`}${who} ${waited}, so this page stopped waiting. The run may still finish on the server \u2014 open the conversation to check before running it again. An organization admin can lengthen this wait in the organization's configuration settings.`;
+}
+
+// src/core/warm.ts
+var WARM_PATH = "/ai/warm";
+var DEFAULT_COALESCE_MS = 50;
+var DEFAULT_DEDUPE_MS = 6e4;
+var SWEEP_AT = 256;
+var QUEUE_MAX = 64;
+function itemId(item) {
+  return item.id ? `${item.key}:${item.id}` : item.key;
+}
+function createWarmup(options) {
+  const {
+    transport,
+    isSignedIn,
+    scope,
+    organizationId,
+    coalesceMs = DEFAULT_COALESCE_MS,
+    dedupeMs = DEFAULT_DEDUPE_MS,
+    now = Date.now
+  } = options;
+  const sentAt = /* @__PURE__ */ new Map();
+  const inFlight = /* @__PURE__ */ new Set();
+  let queue = [];
+  let queueReason = null;
+  let timer = null;
+  let announcedFailure = false;
+  const listeners = /* @__PURE__ */ new Set();
+  const currentScope = () => {
+    try {
+      if (!isSignedIn()) return "";
+      if (!scope) return "ready";
+      const value = scope();
+      return typeof value === "string" ? value : "";
+    } catch {
+      return "";
+    }
+  };
+  const announce = (detail) => {
+    if (announcedFailure) return;
+    announcedFailure = true;
+    try {
+      console.debug(`[matrx] warm-up not accepted (${detail})`);
+    } catch {
+    }
+  };
+  const schedule = () => {
+    if (timer === null && queue.length > 0) timer = setTimeout(flush, coalesceMs);
+  };
+  function flush() {
+    timer = null;
+    const current = currentScope();
+    if (current === "" || queue.length === 0) return;
+    const reason = queueReason ?? "route";
+    const batch = [];
+    for (const q of queue) {
+      if (q.scope !== "" && q.scope !== current) continue;
+      const key = `${current}|${itemId(q.item)}`;
+      if (inFlight.has(key) || batch.some((b) => itemId(b) === itemId(q.item))) continue;
+      const last = sentAt.get(key);
+      if (last !== void 0 && now() - last < dedupeMs) continue;
+      batch.push(q.item);
+    }
+    queue = [];
+    queueReason = null;
+    if (batch.length === 0) return;
+    const keys = batch.map((i) => `${current}|${itemId(i)}`);
+    keys.forEach((k) => inFlight.add(k));
+    const settle = (ok) => {
+      const t = now();
+      for (const k of keys) {
+        inFlight.delete(k);
+        if (ok) sentAt.set(k, t);
+      }
+    };
+    try {
+      const org = organizationId ? organizationId() : null;
+      void transport.fetch(WARM_PATH, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...org ? { "X-Organization-Id": org } : {}
+        },
+        body: JSON.stringify({ reason, items: batch })
+      }).then(
+        (response) => {
+          settle(response.ok);
+          if (!response.ok) announce(`HTTP ${response.status}`);
+        },
+        (err) => {
+          settle(false);
+          announce(String(err));
+        }
+      );
+    } catch (err) {
+      settle(false);
+      announce(String(err));
+    }
+  }
+  return {
+    currentScope,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    notifyScopeChanged() {
+      try {
+        if (sentAt.size >= SWEEP_AT) {
+          const t = now();
+          for (const [k, at] of sentAt) if (t - at >= dedupeMs) sentAt.delete(k);
+        }
+        const current = currentScope();
+        queue = queue.filter((q) => q.scope === "" || q.scope === current);
+        if (queue.length === 0) queueReason = null;
+        schedule();
+        for (const l of listeners) l();
+      } catch (err) {
+        announce(String(err));
+      }
+    },
+    warm(items, reason) {
+      try {
+        if (items.length === 0) return;
+        const requestScope = currentScope();
+        for (const item of items) {
+          if (queue.length >= QUEUE_MAX) break;
+          if (queue.some((q) => q.scope === requestScope && itemId(q.item) === itemId(item))) continue;
+          queue.push({
+            item: item.id ? { key: item.key, id: item.id } : { key: item.key },
+            scope: requestScope
+          });
+        }
+        queueReason ??= reason;
+        schedule();
+      } catch (err) {
+        announce(String(err));
+      }
+    }
+  };
+}
+var preconnected = /* @__PURE__ */ new Set();
+function preconnectServer(baseUrl) {
+  try {
+    if (!baseUrl || typeof document === "undefined") return;
+    const origin = new URL(baseUrl).origin;
+    if (preconnected.has(origin)) return;
+    preconnected.add(origin);
+    const link = document.createElement("link");
+    link.rel = "preconnect";
+    link.href = origin;
+    link.crossOrigin = "anonymous";
+    document.head.appendChild(link);
+  } catch {
+  }
+}
+function resetPreconnectedForTests() {
+  preconnected.clear();
+}
+
+// src/core/internal.ts
+function encodePathSegment(value) {
+  return encodeURIComponent(value);
+}
+function buildQuery(params) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0) continue;
+    if (Array.isArray(value)) {
+      for (const entry of value) search.append(key, entry);
+    } else {
+      search.append(key, String(value));
+    }
+  }
+  const encoded = search.toString();
+  return encoded ? `?${encoded}` : "";
+}
+async function readServerDetail(response) {
+  try {
+    return await response.json();
+  } catch {
+    return void 0;
+  }
+}
+async function throwApiError(path, response) {
+  throw new MatrxApiError({
+    status: response.status,
+    path,
+    serverDetail: await readServerDetail(response)
+  });
+}
+async function requestJson(transport, path, options) {
+  const hasBody = options.method !== "GET" && options.body !== void 0;
+  const response = await transport.fetch(path, {
+    method: options.method,
+    headers: hasBody ? { "Content-Type": "application/json" } : {},
+    ...hasBody ? { body: JSON.stringify(options.body) } : {},
+    ...options.signal ? { signal: options.signal } : {}
+  });
+  if (!response.ok) return throwApiError(path, response);
+  return await response.json();
+}
+function toRunHandle(response, options) {
+  return {
+    requestId: response.headers.get("X-Request-ID"),
+    conversationId: response.headers.get("X-Conversation-ID"),
+    events: readMatrxNdjsonStream(response.body, {
+      ...options.signal ? { signal: options.signal } : {},
+      ...options.maxReadAhead !== void 0 ? { maxReadAhead: options.maxReadAhead } : {},
+      ...options.onMalformedLine ? { onMalformedLine: options.onMalformedLine } : {},
+      ...options.onUnknownEnvelope ? { onUnknownEnvelope: options.onUnknownEnvelope } : {},
+      ...options.onValidEnvelope ? { onValidEnvelope: options.onValidEnvelope } : {}
+    }),
+    response
+  };
+}
+async function requestStream(transport, path, options) {
+  const hasBody = options.method !== "GET" && options.body !== void 0;
+  const response = await transport.fetch(path, {
+    method: options.method,
+    headers: {
+      ...hasBody ? { "Content-Type": "application/json" } : {},
+      ...options.headers
+    },
+    ...hasBody ? { body: JSON.stringify(options.body) } : {},
+    ...options.signal ? { signal: options.signal } : {}
+  });
+  if (!response.ok) return throwApiError(path, response);
+  if (!response.body) {
+    throw new MatrxApiError({
+      status: response.status,
+      path,
+      serverDetail: { code: "missing_response_body" },
+      message: "The streaming response carried no body."
+    });
+  }
+  return response;
+}
+
+// src/core/conversation.ts
+function mintMatrxConversationId() {
+  return crypto.randomUUID();
+}
+function newStoredConversationStart(conversationId) {
+  return {
+    conversation_id: conversationId ?? mintMatrxConversationId(),
+    is_new: true,
+    store: true
+  };
+}
+function continueStoredConversationStart(conversationId) {
+  return { conversation_id: conversationId, is_new: false, store: true };
+}
+function newEphemeralConversationStart(conversationId) {
+  return {
+    conversation_id: conversationId ?? mintMatrxConversationId(),
+    is_new: true,
+    store: false
+  };
+}
+function continueEphemeralConversationStart(conversationId, priorMessages) {
+  return {
+    conversation_id: conversationId,
+    is_new: false,
+    store: false,
+    prior_messages: priorMessages
+  };
+}
+
+// src/core/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 = {}) {
+  const query = buildQuery(options.executionId ? { execution_id: options.executionId } : {});
+  try {
+    return await requestJson(
+      transport,
+      `/runtime/operations/${encodePathSegment(requestId)}${query}`,
+      { method: "GET", ...options.signal ? { signal: options.signal } : {} }
+    );
+  } catch (error) {
+    if (error instanceof MatrxApiError && error.status === 404) return null;
+    throw error;
+  }
+}
+async function getRuntimeOperationsByLink(transport, linkKind, linkId, options = {}) {
+  const query = buildQuery(
+    options.limit !== void 0 ? { limit: options.limit } : {}
+  );
+  try {
+    return await requestJson(
+      transport,
+      `/runtime/operations/by-link/${encodePathSegment(linkKind)}/${encodePathSegment(linkId)}${query}`,
+      { method: "GET", ...options.signal ? { signal: options.signal } : {} }
+    );
+  } catch (error) {
+    if (error instanceof MatrxApiError && error.status === 404) return null;
+    throw error;
+  }
+}
+function listRuntimeOperationEvents(transport, executionId, options = {}) {
+  const query = buildQuery({
+    ...options.afterSeq !== void 0 ? { after_seq: options.afterSeq } : {},
+    ...options.limit !== void 0 ? { limit: options.limit } : {},
+    ...options.kinds !== void 0 ? { kind: options.kinds } : {}
+  });
+  return requestJson(
+    transport,
+    `/runtime/executions/${encodePathSegment(executionId)}/events${query}`,
+    { method: "GET", ...options.signal ? { signal: options.signal } : {} }
+  );
+}
+function parseEndStatus(data) {
+  if (data === null) return null;
+  try {
+    const parsed = JSON.parse(data);
+    if (typeof parsed === "object" && parsed !== null && typeof parsed.status === "string") {
+      const status = parsed.status;
+      return RUNTIME_STATUSES.has(status) ? status : null;
+    }
+  } catch {
+  }
+  return null;
+}
+async function* followRuntimeOperationEvents(transport, executionId, options = {}) {
+  let cursor = options.lastEventSeq ?? 0;
+  const headers = { Accept: "text/event-stream" };
+  if (cursor > 0) headers["Last-Event-ID"] = String(cursor);
+  const response = await requestStream(
+    transport,
+    `/runtime/executions/${encodePathSegment(executionId)}/events/stream`,
+    {
+      method: "GET",
+      headers,
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+  const frames = readMatrxSseStream(
+    response.body,
+    options.onIncomplete ? { onIncomplete: options.onIncomplete } : {}
+  );
+  for await (const frame of frames) {
+    if (frame.event === "end") {
+      yield { type: "end", status: parseEndStatus(frame.data), cursor };
+      return;
+    }
+    if (frame.event === "execution_event" && frame.data !== null) {
+      let event;
+      try {
+        event = JSON.parse(frame.data);
+      } catch (error) {
+        options.onMalformedFrame?.(frame, error);
+        yield { type: "liveness", cursor };
+        continue;
+      }
+      if (frame.seq !== null && frame.seq > cursor) cursor = frame.seq;
+      yield { type: "event", event, seq: frame.seq, cursor };
+      continue;
+    }
+    yield { type: "liveness", cursor };
+  }
+}
+async function 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));
+    }
+  }
+  return { ended: false, status: null };
+}
+async function rejoinRuntimeOperation(transport, requestId, options = {}) {
+  const response = await requestStream(
+    transport,
+    `/runtime/operations/${encodePathSegment(requestId)}/rejoin`,
+    {
+      method: "POST",
+      // The route takes no body model; the reference client posts an empty
+      // JSON object. Match it so proxies see an ordinary JSON POST.
+      body: {},
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+  return toRunHandle(response, options);
+}
+
+// src/core/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 isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonBlank(value) {
+  return typeof value === "string" && value.trim() ? value : null;
+}
+function detailCandidates(body) {
+  if (!isRecord2(body)) return [];
+  const out = [];
+  if (isRecord2(body.detail)) out.push(body.detail);
+  if (isRecord2(body.details)) out.push(body.details);
+  out.push(body);
+  return out;
+}
+function statusOf(error) {
+  if (!isRecord2(error) && !(error instanceof Error)) return null;
+  const status = error.status;
+  return typeof status === "number" ? status : null;
+}
+function bodyOf(error) {
+  if (!isRecord2(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;
+  }
+  for (const candidate of detailCandidates(bodyOf(error))) {
+    const code = nonBlank(candidate.error);
+    if (code) return code;
+  }
+  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;
+  }
+  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));
+  }
+  return null;
+}
+function firstString(candidates, key) {
+  for (const candidate of candidates) {
+    const value = nonBlank(candidate[key]);
+    if (value) return value.trim();
+  }
+  return null;
+}
+function readLiveRunRejoin(error) {
+  if (statusOf(error) !== 409) return null;
+  const candidates = detailCandidates(bodyOf(error));
+  if (candidates.length === 0) return null;
+  const code = readMatrxErrorCode(error);
+  if (code !== MATRX_RUN_IN_PROGRESS) return null;
+  const liveRequestId = firstString(candidates, "live_request_id");
+  const pathFromBody = firstString(candidates, "rejoin_path");
+  const rejoinPath = pathFromBody && pathFromBody.startsWith("/") ? pathFromBody : liveRequestId ? runtimeOperationRejoinPath(liveRequestId) : null;
+  if (!rejoinPath) return null;
+  const root = bodyOf(error);
+  return {
+    liveRequestId,
+    rejoinPath,
+    runId: firstString(candidates, "run_id"),
+    code,
+    body: isRecord2(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 (!isRecord2(eventOrPayload)) return null;
+  const payload = typeof eventOrPayload.event === "string" && isRecord2(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 {
+    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 (!isRecord2(parsed)) continue;
+      options.onEvent(parsed, parsed.event === "node_stream" ? null : frame.seq);
+    }
+  } catch (error) {
+    if (!options.signal?.aborted) throw error;
+  }
+  return { ended: false };
+}
+async function drain(handle, onEnvelope) {
+  for await (const envelope of handle.events) onEnvelope(envelope);
+}
+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;
+  }
+  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;
+  }
+  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 };
+  }
+  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)
+  });
+  return {
+    kind: "followed",
+    rejoin,
+    executionId: operation.execution_id,
+    ended: result.ended,
+    status: result.status
+  };
+}
+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)
+      };
+    }
+  }
+}
+
+// src/core/follow-server-job.ts
+function readStreamCursor(frame) {
+  if (typeof frame !== "object" || frame === null) return null;
+  const seq = frame.stream_seq;
+  if (typeof seq !== "number" || !Number.isSafeInteger(seq) || seq <= 0) return null;
+  const id = frame.stream_id;
+  return {
+    streamId: typeof id === "string" && id.length > 0 ? id : null,
+    streamSeq: seq
+  };
+}
+var NO_SEGMENT = "";
+function createStreamReplayCursor(options = {}) {
+  const marks = /* @__PURE__ */ new Map();
+  let streamId = null;
+  const seed = () => {
+    marks.clear();
+    streamId = null;
+    const s = options.seed;
+    if (!s) return;
+    for (const [id, seq] of Object.entries(s.marks ?? {})) marks.set(id, seq);
+    streamId = s.streamId ?? null;
+    if (typeof s.lastSeq === "number" && s.lastSeq > 0) {
+      marks.set(streamId ?? NO_SEGMENT, Math.max(s.lastSeq, marks.get(streamId ?? NO_SEGMENT) ?? 0));
+    }
+  };
+  seed();
+  return {
+    admit(frame) {
+      const stamp = readStreamCursor(frame);
+      if (!stamp) return true;
+      const key = stamp.streamId ?? streamId ?? NO_SEGMENT;
+      const known = marks.get(key) ?? (streamId === null ? marks.get(NO_SEGMENT) : void 0) ?? 0;
+      if (stamp.streamSeq <= known) return false;
+      marks.set(key, stamp.streamSeq);
+      if (stamp.streamId !== null) {
+        const changed = streamId !== null && stamp.streamId !== streamId;
+        streamId = stamp.streamId;
+        if (changed) options.onSegmentChange?.(stamp.streamId);
+      }
+      return true;
+    },
+    get streamId() {
+      return streamId;
+    },
+    get lastSeq() {
+      return marks.get(streamId ?? NO_SEGMENT) ?? 0;
+    },
+    get marks() {
+      return Object.fromEntries(marks);
+    },
+    reset() {
+      marks.clear();
+      streamId = null;
+    }
+  };
+}
+function isServerJobSettled(status) {
+  return status === "none" || TERMINAL_MATRX_RUNTIME_STATUSES.has(status);
+}
+var EVENT_STATUS = {
+  created: "pending",
+  started: "running",
+  resumed: "running",
+  paused: "paused",
+  waiting_input: "waiting_input",
+  completed: "completed",
+  failed: "failed",
+  cancelled: "cancelled"
+};
+function pickServerJobOperation(operations) {
+  if (!operations || operations.length === 0) return null;
+  return operations.find((op) => !op.is_terminal) ?? operations[0] ?? null;
+}
+function serverJobRejoinHandle(operation) {
+  if (!operation) return null;
+  return operation.root_request_id || operation.request_id || null;
+}
+function isAbort(error, signal) {
+  if (signal?.aborted) return true;
+  return error instanceof Error && error.name === "AbortError";
+}
+async function followServerJob(transport, options) {
+  const { target, signal } = options;
+  const bound = options.organizationId ? withRunOrganization(transport, options.organizationId) : transport;
+  const cursor = options.cursor ?? createStreamReplayCursor();
+  const signalOnly = signal ? { signal } : {};
+  let operation = null;
+  let status = "connecting";
+  let path = "none";
+  let framesDelivered = 0;
+  let framesSkipped = 0;
+  let standDown = false;
+  const setStatus = (next) => {
+    if (next === status) return;
+    status = next;
+    options.onStatus?.(next, operation);
+  };
+  const currentStatus = () => status;
+  options.onStatus?.("connecting", null);
+  const readByRequestId = async (requestId, executionId) => {
+    const operations = (await getRuntimeOperationStatus(bound, requestId, {
+      ...signalOnly,
+      ...executionId ? { executionId } : {}
+    }))?.operations;
+    return (executionId ? operations?.find((op) => op.execution_id === executionId) : void 0) ?? (executionId ? null : pickServerJobOperation(operations));
+  };
+  const readByLink = async (linkKind, linkId) => (await getRuntimeOperationsByLink(bound, linkKind, linkId, {
+    limit: options.linkLimit ?? 5,
+    ...signalOnly
+  }))?.operations;
+  const identifyOnce = async () => {
+    if ("requestId" in target) return readByRequestId(target.requestId);
+    if (options.identifyLink) {
+      return pickServerJobOperation(
+        await options.identifyLink(target.linkKind, target.linkId, signal)
+      );
+    }
+    const view = await getRuntimeOperationsByLink(bound, target.linkKind, target.linkId, {
+      limit: options.linkLimit ?? 5,
+      ...signalOnly
+    });
+    return pickServerJobOperation(view?.operations);
+  };
+  const identify = () => options.retry ? options.retry(identifyOnce) : identifyOnce();
+  const refresh = async () => {
+    try {
+      let next;
+      const handle = serverJobRejoinHandle(operation);
+      if (!operation || !handle) {
+        next = await identifyOnce();
+      } else {
+        next = await readByRequestId(handle, operation.execution_id);
+        if (!next) {
+          const link = "linkKind" in target ? { kind: target.linkKind, id: target.linkId } : operation.link_kind && operation.link_id ? { kind: operation.link_kind, id: operation.link_id } : null;
+          if (link) {
+            const ops = await readByLink(link.kind, link.id);
+            next = ops?.find((op) => op.execution_id === operation?.execution_id);
+          }
+        }
+      }
+      if (next) {
+        operation = next;
+        setStatus(next.status);
+      }
+    } catch {
+    }
+  };
+  const finish = async () => {
+    const now = currentStatus();
+    const final = now === "connecting" ? "none" : now;
+    const aborted = Boolean(signal?.aborted) || standDown;
+    const settled = !aborted && isServerJobSettled(final);
+    let reloaded = false;
+    let reloadError;
+    if (settled) {
+      try {
+        await options.reloadSavedResult({ status: final, operation });
+        reloaded = true;
+      } catch (error) {
+        reloadError = error;
+      }
+    }
+    return {
+      status: final,
+      settled,
+      aborted,
+      path,
+      requestId: serverJobRejoinHandle(operation) ?? ("requestId" in target ? target.requestId : null),
+      executionId: operation?.execution_id ?? null,
+      error: operation?.error ?? null,
+      framesDelivered,
+      framesSkipped,
+      reloaded,
+      ...reloadError !== void 0 ? { reloadError } : {}
+    };
+  };
+  operation = await identify();
+  if (!operation) {
+    setStatus("none");
+    return finish();
+  }
+  setStatus(operation.status);
+  if (operation.is_terminal) {
+    path = "already_settled";
+    return finish();
+  }
+  let rejoined = false;
+  const rejoinId = serverJobRejoinHandle(operation);
+  if (rejoinId && !operation.waiting_input) {
+    try {
+      if (options.rejoinConsumer) {
+        path = "rejoin";
+        rejoined = true;
+        if (currentStatus() === "pending") setStatus("running");
+        const verdict = await options.rejoinConsumer({ operation, requestId: rejoinId });
+        if (verdict === "stand-down") {
+          standDown = true;
+          return finish();
+        }
+      } else {
+        const handle = await rejoinRuntimeOperation(bound, rejoinId, signalOnly);
+        path = "rejoin";
+        rejoined = true;
+        if (currentStatus() === "pending") setStatus("running");
+        for await (const envelope of handle.events) {
+          if (!cursor.admit(envelope)) {
+            framesSkipped += 1;
+            continue;
+          }
+          framesDelivered += 1;
+          options.onFrame?.(envelope);
+        }
+      }
+    } catch (error) {
+      if (isAbort(error, signal)) return finish();
+      options.onRejoinUnavailable?.(error);
+      rejoined = false;
+    }
+    if (signal?.aborted) return finish();
+    await refresh();
+    if (isServerJobSettled(currentStatus())) return finish();
+    if (rejoined && operation && options.afterRejoin?.(operation) === "handoff") {
+      return finish();
+    }
+  }
+  if (signal?.aborted) return finish();
+  path = rejoined ? "rejoin" : "lifecycle";
+  const live = operation;
+  try {
+    const result = await followRuntimeOperationToEnd(bound, live.execution_id, {
+      ...options.follow,
+      lastEventSeq: live.last_event_seq,
+      ...signalOnly,
+      onEvent: (event) => {
+        options.onOperationEvent?.(event);
+        const next = EVENT_STATUS[event.kind];
+        if (next) setStatus(next);
+      }
+    });
+    if (signal?.aborted) return finish();
+    if (result.ended && result.status) setStatus(result.status);
+  } catch (error) {
+    if (isAbort(error, signal)) return finish();
+  }
+  await refresh();
+  return finish();
+}
+
+// src/core/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 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 } : {}
+      }
+    );
+  } catch (error) {
+    console.warn(
+      `[provider-failures] could not report a ${failure.provider} session failure`,
+      error
+    );
+    return null;
+  }
+}
+
+export { MATRX_AI_API_VERSION_DEFAULT, MATRX_LIVE_STREAM_UNAVAILABLE, MATRX_RESUME_CONFLICT, MATRX_RUN_IN_PROGRESS, MATRX_UI_ONLY_BODY_FIELDS, RUN_OUTPUT_KINDS, RUN_STREAM_LIFETIME_BACKSTOP_MS, RUN_WAIT_KNOB_FEATURE, TERMINAL_MATRX_RUNTIME_STATUSES, V2_COVERED_AI_PATH_TEMPLATES, WARM_PATH, aiVersionPathOverrides, applyAiApiVersion, applyDesktopTargetToRequestBody, bareStatusSentence, buildMatrxRequestBody, buildMatrxRequestUrl, buildQuery, buildSafeRequestLog, continueEphemeralConversationStart, continueStoredConversationStart, createMatrxTransport, createStreamReplayCursor, createWarmup, encodePathSegment, executeMatrxCall, fetchWithMatrxProtocolFallback, followRuntimeOperationEvents, followRuntimeOperationToEnd, followServerJob, followUnavailableRejoin, followWorkflowRunEvents, getRuntimeOperationStatus, getRuntimeOperationsByLink, honestTransportMessage, isBareTransportCode, isCoveredAiPath, isJobOutputKind, isLiveStreamUnavailable, isResumeConflict, isServerJobSettled, isV2Path, listRuntimeOperationEvents, logApiTarget, mintMatrxConversationId, newEphemeralConversationStart, newStoredConversationStart, normalizeMatrxError, openMatrxStream, parseMatrxNdjsonResponse, pickServerJobOperation, preconnectServer, providerSessionFailureBody, readConversationOrganizationId, readLiveRunRejoin, readLiveRunRequestId, readLiveStreamUnavailable, readMatrxErrorCode, readMatrxErrorCodeFromMessage, readMatrxJsonResponse, readStreamCursor, redactUrlForRequestLog, rejoinRuntimeOperation, reportProviderSessionFailure, requestJson, requestStream, resetPreconnectedForTests, resolveEndpointPath, resolveRunWaitWith, resumeOrRejoin, runJobLabel, runOutputKindFromModalities, runWaitKnobKey, runWaitTimeoutMessage, runtimeOperationRejoinPath, sendMatrxRequest, serverJobRejoinHandle, settleRunPickup, shouldReportMatrxCallError, streamErrorText, toRunHandle, toV1FallbackUrl, toV2Path, withRunOrganization };