@ai-matrx/agents 0.5.1 → 0.6.1

package/dist/matrx/index.cjs

@@ -1,4 +1,65 @@
-'use strict';
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// matrx/index.ts
+var matrx_exports = {};
+__export(matrx_exports, {
+  MATRX_AI_API_VERSION_DEFAULT: () => MATRX_AI_API_VERSION_DEFAULT,
+  MatrxApiError: () => MatrxApiError,
+  MatrxRunError: () => MatrxRunError,
+  OrganizationContextError: () => OrganizationContextError,
+  TERMINAL_MATRX_RUNTIME_STATUSES: () => TERMINAL_MATRX_RUNTIME_STATUSES,
+  V2_COVERED_AI_PATH_TEMPLATES: () => V2_COVERED_AI_PATH_TEMPLATES,
+  applyAiApiVersion: () => applyAiApiVersion,
+  applyOrganizationContextHeader: () => applyOrganizationContextHeader,
+  assertQueryOrganizationMatchesContext: () => assertQueryOrganizationMatchesContext,
+  cancelAgentRun: () => cancelAgentRun,
+  continueAgentConversation: () => continueAgentConversation,
+  continueEphemeralConversationStart: () => continueEphemeralConversationStart,
+  continueStoredConversationStart: () => continueStoredConversationStart,
+  createMatrxTransport: () => createMatrxTransport,
+  extractMatrxErrorCode: () => extractMatrxErrorCode,
+  extractMatrxErrorMessage: () => extractMatrxErrorMessage,
+  fetchWithMatrxProtocolFallback: () => fetchWithMatrxProtocolFallback,
+  followRuntimeOperationEvents: () => followRuntimeOperationEvents,
+  followRuntimeOperationToEnd: () => followRuntimeOperationToEnd,
+  getRuntimeOperationStatus: () => getRuntimeOperationStatus,
+  getRuntimeOperationsByLink: () => getRuntimeOperationsByLink,
+  isCoveredAiPath: () => isCoveredAiPath,
+  isV2Path: () => isV2Path,
+  listConversationPendingToolCalls: () => listConversationPendingToolCalls,
+  listRuntimeOperationEvents: () => listRuntimeOperationEvents,
+  listUserPendingToolCalls: () => listUserPendingToolCalls,
+  mintMatrxConversationId: () => mintMatrxConversationId,
+  newEphemeralConversationStart: () => newEphemeralConversationStart,
+  newStoredConversationStart: () => newStoredConversationStart,
+  normalizeMatrxError: () => normalizeMatrxError,
+  rejoinRuntimeOperation: () => rejoinRuntimeOperation,
+  requireOrganizationContext: () => requireOrganizationContext,
+  resumeAgentConversation: () => resumeAgentConversation,
+  runAgentToCompletion: () => runAgentToCompletion,
+  startAgentRun: () => startAgentRun,
+  submitAgentToolResults: () => submitAgentToolResults,
+  toV1FallbackUrl: () => toV1FallbackUrl,
+  toV2Path: () => toV2Path
+});
+module.exports = __toCommonJS(matrx_exports);
 
 // matrx/transport.ts
 var MatrxApiError = class extends Error {
@@ -69,6 +130,296 @@ function extractMatrxErrorCode(serverDetail) {
   return null;
 }
 
+// matrx/client.ts
+var import_data = require("@ai-matrx/data");
+var import_data2 = require("@ai-matrx/data");
+
+// matrx/org-context.ts
+var OrganizationContextError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "OrganizationContextError";
+    this.code = code;
+  }
+};
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+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 (!UUID_PATTERN.test(normalized)) {
+    throw new OrganizationContextError(
+      "organization_context_invalid",
+      "The selected organization ID is invalid."
+    );
+  }
+  return normalized.toLowerCase();
+}
+function applyOrganizationContextHeader(headers, organizationId) {
+  const normalizedOrganizationId = requireOrganizationContext(organizationId);
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() === "x-organization-id" && value.trim().toLowerCase() !== normalizedOrganizationId) {
+      throw new OrganizationContextError(
+        "organization_context_mismatch",
+        "X-Organization-Id must match the request context organization."
+      );
+    }
+  }
+  const withoutOrganizationHeader = Object.fromEntries(
+    Object.entries(headers).filter(
+      ([name]) => name.toLowerCase() !== "x-organization-id"
+    )
+  );
+  return {
+    ...withoutOrganizationHeader,
+    "X-Organization-Id": normalizedOrganizationId
+  };
+}
+function assertQueryOrganizationMatchesContext(queryParams, organizationId) {
+  if (!queryParams || queryParams.organization_id === void 0) return;
+  const queryOrganizationId = requireOrganizationContext(
+    String(queryParams.organization_id)
+  );
+  if (queryOrganizationId !== requireOrganizationContext(organizationId)) {
+    throw new OrganizationContextError(
+      "organization_context_mismatch",
+      "Query organization_id must match the request context organization."
+    );
+  }
+}
+
+// matrx/protocol.ts
+var import_net = require("@ai-matrx/data/net");
+var MATRX_AI_API_VERSION_DEFAULT = "v2";
+var V2_COVERED_AI_PATH_TEMPLATES = [
+  "/ai/manual",
+  "/ai/chat",
+  "/ai/agents/{agent_id}",
+  "/ai/agent/{agent_id}",
+  // singular alias — behaves identically
+  "/ai/conversations/{conversation_id}",
+  "/ai/conversation/{conversation_id}",
+  // singular alias
+  "/ai/prompts/{prompt_id}",
+  // saved-prompt execution
+  "/ai/mandates/{mandate_key}"
+  // THE MANDATE DOOR — `/v2` sibling exists (routers/v2.py)
+];
+function toV2Path(path) {
+  const withLead = path.startsWith("/") ? path : `/${path}`;
+  if (withLead.startsWith("/api/")) {
+    const rest = withLead.slice("/api".length);
+    return rest.startsWith("/v2/") ? withLead : `/api/v2${rest}`;
+  }
+  return withLead.startsWith("/v2/") ? withLead : `/v2${withLead}`;
+}
+var COVERED_INTERPOLATED_PATH = [
+  /^(?:\/api)?\/ai\/manual$/,
+  /^(?:\/api)?\/ai\/chat$/,
+  /^(?:\/api)?\/ai\/agents\/[^/]+$/,
+  /^(?:\/api)?\/ai\/agent\/[^/]+$/,
+  /^(?:\/api)?\/ai\/conversations\/[^/]+$/,
+  /^(?:\/api)?\/ai\/conversation\/[^/]+$/,
+  /^(?:\/api)?\/ai\/prompts\/[^/]+$/,
+  // `/warm` etc. deliberately don't match
+  /^(?:\/api)?\/ai\/mandates\/[^/]+$/
+  // the mandate door
+];
+function isCoveredAiPath(path) {
+  return COVERED_INTERPOLATED_PATH.some((re) => re.test(path));
+}
+function isV2Path(pathOrUrl) {
+  return /\/v2\/ai\//.test(pathOrUrl);
+}
+function toV1FallbackUrl(url) {
+  return url.replace(/\/v2\/ai\//, "/ai/");
+}
+function applyAiApiVersion(path, version) {
+  if (version !== "v2") return path;
+  return isCoveredAiPath(path) ? toV2Path(path) : path;
+}
+async function fetchWithMatrxProtocolFallback(url, init, opts = {}) {
+  const { onDowngrade, ...fetchOpts } = opts;
+  const logDowngrade = (reason, status2) => {
+    console.warn(
+      `[matrx] ai_v2_downgrade \u2192 retrying on v1. v2=${url} reason=${reason}`
+    );
+    onDowngrade?.({ url, reason, ...status2 !== void 0 ? { status: status2 } : {} });
+  };
+  if (!isV2Path(url)) return (0, import_net.resilientFetch)(url, init, fetchOpts);
+  let result;
+  try {
+    result = await (0, import_net.resilientFetch)(url, init, fetchOpts);
+  } catch (err) {
+    const isAbort = (0, import_net.isNetError)(err) && err.code === "aborted" || err instanceof Error && err.name === "AbortError";
+    if (isAbort) throw err;
+    logDowngrade(String(err));
+    return (0, import_net.resilientFetch)(toV1FallbackUrl(url), init, fetchOpts);
+  }
+  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;
+}
+
+// matrx/client.ts
+function classifyStatus(status) {
+  return status >= 400 && status < 500 ? "validation_error" : "http_error";
+}
+function normalizeMatrxError(err) {
+  if (err instanceof MatrxApiError) {
+    return {
+      type: classifyStatus(err.status),
+      message: err.message,
+      status: err.status,
+      serverDetail: err.serverDetail,
+      ...err.code ? { code: err.code } : {},
+      name: err.name
+    };
+  }
+  if (err instanceof OrganizationContextError) {
+    return {
+      type: "validation_error",
+      message: err.message,
+      code: err.code,
+      name: err.name,
+      ...err.stack !== void 0 ? { stack: err.stack } : {}
+    };
+  }
+  if (err instanceof DOMException && err.name === "AbortError") {
+    return { type: "abort_error", message: "Request was cancelled." };
+  }
+  if ((0, import_data.isNetError)(err)) {
+    if (err.code === "aborted") {
+      return { type: "abort_error", message: err.message };
+    }
+    if (err.code === "http") {
+      const status = err.status ?? 0;
+      return { type: classifyStatus(status), message: err.message, status };
+    }
+    return { type: "network_error", message: err.message };
+  }
+  if (err instanceof Error) {
+    const httpMatch = err.message.match(/HTTP (\d+):\s*(.*)/);
+    if (httpMatch) {
+      const status = parseInt(httpMatch[1], 10);
+      return {
+        type: classifyStatus(status),
+        message: httpMatch[2] ?? err.message,
+        status
+      };
+    }
+    return { type: "network_error", message: err.message };
+  }
+  return { type: "unknown", message: String(err ?? "Unknown error") };
+}
+var PRODUCTION_CONNECT_TIMEOUT_MS = 15e3;
+function stripContentType(headers) {
+  return Object.fromEntries(
+    Object.entries(headers).filter(
+      ([name]) => name.toLowerCase() !== "content-type"
+    )
+  );
+}
+function createMatrxTransport(options) {
+  const {
+    baseUrl,
+    resolveTarget,
+    credentials,
+    organizationId,
+    aiApiVersion,
+    connectTimeoutMs = PRODUCTION_CONNECT_TIMEOUT_MS,
+    totalTimeoutMs = null,
+    expectedErrorStatuses,
+    diagnostics,
+    source = "matrxTransport"
+  } = options;
+  if (baseUrl === void 0 === (resolveTarget === void 0)) {
+    throw new Error(
+      "createMatrxTransport: provide exactly one of `baseUrl` or `resolveTarget`."
+    );
+  }
+  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();
@@ -666,6 +1017,55 @@ async function* followRuntimeOperationEvents(transport, executionId, options = {
     yield { type: "liveness", cursor };
   }
 }
+async function followRuntimeOperationToEnd(transport, executionId, options) {
+  const stallTimeoutMs = options.stallTimeoutMs ?? 45e3;
+  const reconnectLimit = options.reconnectLimit ?? 60;
+  const reconnectDelayMs = options.reconnectDelayMs ?? 2e3;
+  const outer = options.signal;
+  let cursor = options.lastEventSeq ?? 0;
+  let failures = 0;
+  while (!outer?.aborted && failures < reconnectLimit) {
+    const attempt = new AbortController();
+    const onOuterAbort = () => attempt.abort();
+    outer?.addEventListener("abort", onOuterAbort, { once: true });
+    let stallTimer = null;
+    const armStall = () => {
+      if (stallTimer !== null) clearTimeout(stallTimer);
+      stallTimer = setTimeout(() => attempt.abort(), stallTimeoutMs);
+    };
+    try {
+      const items = followRuntimeOperationEvents(transport, executionId, {
+        lastEventSeq: cursor,
+        signal: attempt.signal,
+        ...options.onMalformedFrame ? { onMalformedFrame: options.onMalformedFrame } : {}
+      });
+      armStall();
+      for await (const item of items) {
+        armStall();
+        failures = 0;
+        cursor = item.cursor;
+        if (item.type === "end") {
+          return { ended: true, status: item.status };
+        }
+        if (item.type === "event") {
+          options.onEvent(item.event, item.seq);
+        }
+      }
+      failures += 1;
+    } catch (error) {
+      if (outer?.aborted) break;
+      failures += 1;
+      options.onAttemptError?.(error);
+    } finally {
+      if (stallTimer !== null) clearTimeout(stallTimer);
+      outer?.removeEventListener("abort", onOuterAbort);
+    }
+    if (!outer?.aborted && failures < reconnectLimit) {
+      await new Promise((r) => setTimeout(r, reconnectDelayMs));
+    }
+  }
+  return { ended: false, status: null };
+}
 async function rejoinRuntimeOperation(transport, requestId, options = {}) {
   const response = await requestStream(
     transport,
@@ -719,29 +1119,4 @@ function listUserPendingToolCalls(transport, options = {}) {
     }
   );
 }
-
-exports.MatrxApiError = MatrxApiError;
-exports.MatrxRunError = MatrxRunError;
-exports.TERMINAL_MATRX_RUNTIME_STATUSES = TERMINAL_MATRX_RUNTIME_STATUSES;
-exports.cancelAgentRun = cancelAgentRun;
-exports.continueAgentConversation = continueAgentConversation;
-exports.continueEphemeralConversationStart = continueEphemeralConversationStart;
-exports.continueStoredConversationStart = continueStoredConversationStart;
-exports.extractMatrxErrorCode = extractMatrxErrorCode;
-exports.extractMatrxErrorMessage = extractMatrxErrorMessage;
-exports.followRuntimeOperationEvents = followRuntimeOperationEvents;
-exports.getRuntimeOperationStatus = getRuntimeOperationStatus;
-exports.getRuntimeOperationsByLink = getRuntimeOperationsByLink;
-exports.listConversationPendingToolCalls = listConversationPendingToolCalls;
-exports.listRuntimeOperationEvents = listRuntimeOperationEvents;
-exports.listUserPendingToolCalls = listUserPendingToolCalls;
-exports.mintMatrxConversationId = mintMatrxConversationId;
-exports.newEphemeralConversationStart = newEphemeralConversationStart;
-exports.newStoredConversationStart = newStoredConversationStart;
-exports.rejoinRuntimeOperation = rejoinRuntimeOperation;
-exports.resumeAgentConversation = resumeAgentConversation;
-exports.runAgentToCompletion = runAgentToCompletion;
-exports.startAgentRun = startAgentRun;
-exports.submitAgentToolResults = submitAgentToolResults;
-//# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map