@ai-matrx/agents 0.22.0 → 0.24.0

package/dist/matrx/index.cjs

@@ -21,6 +21,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var matrx_exports = {};
 __export(matrx_exports, {
   MATRX_AI_API_VERSION_DEFAULT: () => MATRX_AI_API_VERSION_DEFAULT,
+  MATRX_LIVE_STREAM_UNAVAILABLE: () => MATRX_LIVE_STREAM_UNAVAILABLE,
+  MATRX_RESUME_CONFLICT: () => MATRX_RESUME_CONFLICT,
+  MATRX_RUN_IN_PROGRESS: () => MATRX_RUN_IN_PROGRESS,
   MatrxApiError: () => MatrxApiError,
   MatrxRunError: () => MatrxRunError,
   OrganizationContextError: () => OrganizationContextError,
@@ -41,9 +44,12 @@ __export(matrx_exports, {
   fetchWithMatrxProtocolFallback: () => fetchWithMatrxProtocolFallback,
   followRuntimeOperationEvents: () => followRuntimeOperationEvents,
   followRuntimeOperationToEnd: () => followRuntimeOperationToEnd,
+  followWorkflowRunEvents: () => followWorkflowRunEvents,
   getRuntimeOperationStatus: () => getRuntimeOperationStatus,
   getRuntimeOperationsByLink: () => getRuntimeOperationsByLink,
   isCoveredAiPath: () => isCoveredAiPath,
+  isLiveStreamUnavailable: () => isLiveStreamUnavailable,
+  isResumeConflict: () => isResumeConflict,
   isV2Path: () => isV2Path,
   listConversationPendingToolCalls: () => listConversationPendingToolCalls,
   listRuntimeOperationEvents: () => listRuntimeOperationEvents,
@@ -52,15 +58,25 @@ __export(matrx_exports, {
   newEphemeralConversationStart: () => newEphemeralConversationStart,
   newStoredConversationStart: () => newStoredConversationStart,
   normalizeMatrxError: () => normalizeMatrxError,
+  openMatrxStream: () => openMatrxStream,
+  providerSessionFailureBody: () => providerSessionFailureBody,
+  readLiveRunRejoin: () => readLiveRunRejoin,
+  readLiveRunRequestId: () => readLiveRunRequestId,
+  readMatrxErrorCode: () => readMatrxErrorCode,
   rejoinRuntimeOperation: () => rejoinRuntimeOperation,
+  reportProviderSessionFailure: () => reportProviderSessionFailure,
   requireOrganizationContext: () => requireOrganizationContext,
   resumeAgentConversation: () => resumeAgentConversation,
+  resumeOrRejoin: () => resumeOrRejoin,
   runAgentToCompletion: () => runAgentToCompletion,
+  runtimeOperationRejoinPath: () => runtimeOperationRejoinPath,
   startAgentRun: () => startAgentRun,
   startMandateRun: () => startMandateRun,
+  streamErrorText: () => streamErrorText,
   submitAgentToolResults: () => submitAgentToolResults,
   toV1FallbackUrl: () => toV1FallbackUrl,
-  toV2Path: () => toV2Path
+  toV2Path: () => toV2Path,
+  withRunOrganization: () => withRunOrganization
 });
 module.exports = __toCommonJS(matrx_exports);
 
@@ -764,136 +780,6 @@ async function requestStream(transport, path, options) {
   return response;
 }
 
-// matrx/run.ts
-async function streamCall(transport, path, body, options) {
-  const response = await requestStream(transport, path, {
-    method: "POST",
-    // This client IS the streaming path — `stream: true` always, last so a
-    // caller-supplied value can never flip the response off NDJSON.
-    body: { ...body, stream: true },
-    ...options.signal ? { signal: options.signal } : {}
-  });
-  return toRunHandle(response, options);
-}
-function startAgentRun(transport, agentId, request, options = {}) {
-  return streamCall(
-    transport,
-    `/ai/agents/${encodePathSegment(agentId)}`,
-    request,
-    options
-  );
-}
-function 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
-  );
-}
-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 } : {}
-    }
-  );
-}
-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 isRecord3(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function stringField(value, key) {
-  if (!isRecord3(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 = isRecord3(envelope.data) ? envelope.data : null;
-      failure = new MatrxRunError({
-        message: stringField(payload, "user_message") ?? stringField(payload, "message") ?? "The agent run failed",
-        errorPayload: payload,
-        partialText: text
-      });
-      continue;
-    }
-    if (envelope.event !== "completion" || !isRecord3(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 = isRecord3(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
-  };
-}
-
 // stream/sse.ts
 var FRAME_SEPARATOR = /\r\n\r\n|\n\n|\r\r/;
 var LINE_SEPARATOR = /\r\n|\n|\r/;
@@ -1120,6 +1006,393 @@ async function rejoinRuntimeOperation(transport, requestId, options = {}) {
   return toRunHandle(response, options);
 }
 
+// matrx/rejoin.ts
+var MATRX_RUN_IN_PROGRESS = "run_in_progress";
+var MATRX_RESUME_CONFLICT = "resume_conflict";
+var MATRX_LIVE_STREAM_UNAVAILABLE = "live_stream_unavailable";
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonBlank(value) {
+  return typeof value === "string" && value.trim() ? value : null;
+}
+function detailCandidates(body) {
+  if (!isRecord3(body)) return [];
+  const out = [];
+  if (isRecord3(body.detail)) out.push(body.detail);
+  if (isRecord3(body.details)) out.push(body.details);
+  out.push(body);
+  return out;
+}
+function statusOf(error) {
+  if (!isRecord3(error) && !(error instanceof Error)) return null;
+  const status = error.status;
+  return typeof status === "number" ? status : null;
+}
+function bodyOf(error) {
+  if (!isRecord3(error) && !(error instanceof Error)) return void 0;
+  return error.serverDetail;
+}
+function readMatrxErrorCode(error) {
+  for (const candidate of detailCandidates(bodyOf(error))) {
+    const code = nonBlank(candidate.code);
+    if (code) return code;
+  }
+  for (const candidate of detailCandidates(bodyOf(error))) {
+    const code = nonBlank(candidate.error);
+    if (code) return code;
+  }
+  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 && code !== MATRX_RESUME_CONFLICT) return null;
+  const liveRequestId = firstString(candidates, "live_request_id");
+  const pathFromBody = firstString(candidates, "rejoin_path");
+  const rejoinPath = pathFromBody && pathFromBody.startsWith("/") ? pathFromBody : liveRequestId ? runtimeOperationRejoinPath(liveRequestId) : null;
+  if (!rejoinPath) return null;
+  const root = bodyOf(error);
+  return {
+    liveRequestId,
+    rejoinPath,
+    runId: firstString(candidates, "run_id"),
+    code,
+    body: isRecord3(root) ? root : {}
+  };
+}
+function readLiveRunRequestId(error) {
+  return readLiveRunRejoin(error)?.liveRequestId ?? null;
+}
+function isResumeConflict(error) {
+  return statusOf(error) === 409 && readMatrxErrorCode(error) === MATRX_RESUME_CONFLICT && readLiveRunRejoin(error) === null;
+}
+function isLiveStreamUnavailable(error) {
+  return statusOf(error) === 409 && readMatrxErrorCode(error) === MATRX_LIVE_STREAM_UNAVAILABLE;
+}
+function runtimeOperationRejoinPath(requestId) {
+  return `/runtime/operations/${encodePathSegment(requestId)}/rejoin`;
+}
+function streamErrorText(eventOrPayload) {
+  if (!isRecord3(eventOrPayload)) return null;
+  const payload = typeof eventOrPayload.event === "string" && isRecord3(eventOrPayload.data) ? eventOrPayload.data : eventOrPayload;
+  return nonBlank(payload.user_message) ?? nonBlank(payload.message);
+}
+async function openMatrxStream(transport, path, options = {}) {
+  const response = await requestStream(transport, path, {
+    method: "POST",
+    ...options.body !== void 0 ? { body: options.body } : {},
+    ...options.signal ? { signal: options.signal } : {}
+  });
+  return toRunHandle(response, options);
+}
+function withRunOrganization(transport, organizationId) {
+  const orgId = requireOrganizationContext(organizationId);
+  return {
+    fetch: (path, init) => transport.fetch(path, {
+      ...init,
+      headers: { ...init.headers, "X-Organization-Id": orgId }
+    })
+  };
+}
+async function followWorkflowRunEvents(transport, runId, options) {
+  const headers = { Accept: "text/event-stream" };
+  if (options.lastEventId) headers["Last-Event-ID"] = String(options.lastEventId);
+  let response;
+  try {
+    response = await requestStream(
+      transport,
+      `/runs/${encodePathSegment(runId)}/events/stream`,
+      {
+        method: "GET",
+        headers,
+        ...options.signal ? { signal: options.signal } : {}
+      }
+    );
+  } catch (error) {
+    if (options.signal?.aborted) return { ended: false };
+    throw error;
+  }
+  try {
+    for await (const frame of readMatrxSseStream(
+      response.body
+    )) {
+      if (frame.event === "end") return { ended: true };
+      if (frame.data === null) continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(frame.data);
+      } catch {
+        continue;
+      }
+      if (!isRecord3(parsed)) continue;
+      options.onEvent(parsed, parsed.event === "node_stream" ? null : frame.seq);
+    }
+  } catch (error) {
+    if (!options.signal?.aborted) throw error;
+  }
+  return { 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 unavailableBody;
+  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) {
+    if (!isLiveStreamUnavailable(error)) throw error;
+    unavailableBody = bodyOf(error);
+  }
+  const runId = firstString(detailCandidates(unavailableBody), "run_id") ?? rejoin.runId;
+  if (runId && rejoin.rejoinPath.startsWith("/runtime/operations/")) {
+    const result2 = await followWorkflowRunEvents(bound, runId, {
+      ...signalOnly,
+      onEvent: (event, seq) => 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, {
+    ...follow,
+    lastEventSeq: operation.last_event_seq,
+    ...signalOnly,
+    onEvent: (event) => onOperationEvent?.(event)
+  });
+  return {
+    kind: "followed",
+    rejoin,
+    executionId: operation.execution_id,
+    ended: result.ended,
+    status: result.status
+  };
+}
+
+// matrx/run.ts
+async function streamCall(transport, path, body, options) {
+  const response = await requestStream(transport, path, {
+    method: "POST",
+    // This client IS the streaming path — `stream: true` always, last so a
+    // caller-supplied value can never flip the response off NDJSON.
+    body: { ...body, stream: true },
+    ...options.signal ? { signal: options.signal } : {}
+  });
+  return toRunHandle(response, options);
+}
+function startAgentRun(transport, agentId, request, options = {}) {
+  return streamCall(
+    transport,
+    `/ai/agents/${encodePathSegment(agentId)}`,
+    request,
+    options
+  );
+}
+function 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
+  );
+}
+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 } : {}
+    }
+  );
+}
+var MatrxRunError = class extends Error {
+  name = "MatrxRunError";
+  /** The verbatim `error` event payload, when one fired. */
+  errorPayload;
+  /** The `user_request` completion status (`"failed"` | `"cancelled"`), when that was the trigger. */
+  completionStatus;
+  /** Text streamed before the failure — partial content never vanishes. */
+  partialText;
+  constructor(args) {
+    super(args.message);
+    this.errorPayload = args.errorPayload ?? null;
+    this.completionStatus = args.completionStatus ?? null;
+    this.partialText = args.partialText ?? "";
+  }
+};
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringField(value, key) {
+  if (!isRecord4(value)) return null;
+  const field = value[key];
+  return typeof field === "string" && field ? field : null;
+}
+async function runAgentToCompletion(transport, agentId, request, options = {}) {
+  const handle = await startAgentRun(transport, agentId, request, options);
+  let text = "";
+  let completion = null;
+  let failure = null;
+  for await (const envelope of handle.events) {
+    options.onEvent?.(envelope);
+    if (envelope.event === "chunk") {
+      const chunk = stringField(envelope.data, "text");
+      if (chunk !== null) {
+        text += chunk;
+        options.onChunk?.(text);
+      }
+      continue;
+    }
+    if (envelope.event === "error" && failure === null) {
+      const payload = isRecord4(envelope.data) ? envelope.data : null;
+      failure = new MatrxRunError({
+        message: streamErrorText(payload) ?? "The agent run failed",
+        errorPayload: payload,
+        partialText: text
+      });
+      continue;
+    }
+    if (envelope.event !== "completion" || !isRecord4(envelope.data)) continue;
+    if (envelope.data.operation !== "user_request") continue;
+    completion = envelope.data;
+    const status = envelope.data.status;
+    if ((status === "failed" || status === "cancelled") && failure === null) {
+      const result = isRecord4(envelope.data.result) ? envelope.data.result : null;
+      failure = new MatrxRunError({
+        message: stringField(result, "error") ?? stringField(result, "user_message") ?? `The agent run ${status}`,
+        completionStatus: status,
+        partialText: text
+      });
+    }
+  }
+  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;
+  }
+  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;
+  }
+}
+
 // matrx/tools.ts
 function submitAgentToolResults(transport, conversationId, results, options = {}) {
   return requestJson(