@ai-matrx/agents 0.37.0 → 0.38.1

package/dist/matrx/index.d.cts

@@ -5,7 +5,7 @@ import { ResilientFetchOptions } from '@ai-matrx/data/net';
 import { MatrxStreamEnvelope, MatrxNdjsonIssue } from '../stream/ndjson.cjs';
 import { v as MatrxRuntimeOperationEvent, a as FollowRuntimeOperationToEndOptions, u as MatrxRuntimeExecutionStatus, z as MatrxStreamCallOptions, t as MatrxRunHandle, l as MatrxJsonValue, k as MatrxJsonObject } from '../operations-C9QvBH_2.cjs';
 export { F as FollowRuntimeOperationOptions, b as FollowRuntimeOperationToEndResult, M as MatrxAgentStartRequest, c as MatrxCancelResponse, d as MatrxChatMessage, e as MatrxCompletedRun, f as MatrxContextAnchor, g as MatrxConversationContinueRequest, h as MatrxConversationResumeRequest, i as MatrxConversationStart, j as MatrxEphemeralConversation, m as MatrxMandateStartRequest, n as MatrxOperationEventsPage, o as MatrxOperationFollowEvent, p as MatrxOperationStatusResponse, q as MatrxOperationsByLinkResponse, r as MatrxRequestScope, s as MatrxRunError, w as MatrxRuntimeOperationView, x as MatrxStoredConversationContinue, y as MatrxStoredConversationCreate, A as MatrxTurnFields, R as RunAgentToCompletionOptions, T as TERMINAL_MATRX_RUNTIME_STATUSES, B as cancelAgentRun, C as continueAgentConversation, D as continueEphemeralConversationStart, E as continueStoredConversationStart, G as followRuntimeOperationEvents, H as followRuntimeOperationToEnd, I as getRuntimeOperationStatus, J as getRuntimeOperationsByLink, K as listRuntimeOperationEvents, L as mintMatrxConversationId, N as newEphemeralConversationStart, O as newStoredConversationStart, P as rejoinRuntimeOperation, Q as resumeAgentConversation, S as runAgentToCompletion, U as startAgentRun, V as startMandateRun } from '../operations-C9QvBH_2.cjs';
-import { M as MandateKey, D as DynamicMandateKey } from '../keys.generated-klzs6I1T.cjs';
+import { M as MandateKey, D as DynamicMandateKey } from '../keys.generated-DNRbtHNx.cjs';
 import '../stream/sse.cjs';
 
 /**
@@ -507,6 +507,10 @@ declare function getUserMessage(error: unknown): string;
  *   body reader classified as a resumable `StreamTransportError`;
  * - `executeMatrxCall` — the JSON or NDJSON execution over the v2 → v1
  *   protocol fallback, with the stream callbacks and `consumeStream`;
+ * - `sendMatrxRequest` / `readMatrxJsonResponse` — the raw-`Response` lane
+ *   for a host's imperative client (multipart bodies, byte downloads,
+ *   response-aware callers): one deadline, a caller abort kept as itself, and
+ *   the ONE HTTP error parser;
  * - `buildSafeRequestLog` / `redactUrlForRequestLog` /
  *   `shouldReportMatrxCallError` — the log and capture policy.
  *
@@ -537,7 +541,12 @@ interface MatrxCallResult<T = unknown> {
     /** Set when the call failed with an HTTP error response. */
     error?: MatrxCallError;
 }
-type MatrxQueryParams = Record<string, string | number | boolean>;
+type MatrxQueryScalar = string | number | boolean;
+/**
+ * Query values: a scalar is sent as itself, an array repeats the key (the
+ * FastAPI repeatable-parameter convention), `null` / `undefined` are omitted.
+ */
+type MatrxQueryParams = Record<string, MatrxQueryScalar | readonly MatrxQueryScalar[] | null | undefined>;
 /**
  * The full URL for one call: `{param}` segments substituted (encoded), the
  * legacy `/api` prefix stripped (server routes no longer live under it), and
@@ -642,6 +651,29 @@ interface ExecuteMatrxCallHooks<E = MatrxStreamEnvelope> {
  * `normalizeMatrxError` and decides what to capture.
  */
 declare function executeMatrxCall<T = unknown, E = MatrxStreamEnvelope>(request: ExecuteMatrxCallRequest<E>, hooks?: ExecuteMatrxCallHooks<E>): Promise<MatrxCallResult<T>>;
+interface SendMatrxRequestOptions {
+    /** Caller cancellation; an abort propagates as the caller's own AbortError. */
+    signal?: AbortSignal;
+    /**
+     * Deadline (ms) from send to response headers. On expiry the call rejects
+     * with a `BackendApiError` coded `request_timeout` (status 504) — never a
+     * fake caller cancellation. Omit for no deadline.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Send one request and resolve with the raw `Response`, whatever its status.
+ * The lane for an imperative host client whose bodies are not JSON (a
+ * `FormData` upload), whose answers are bytes, or which reads the response
+ * itself. A caller abort and a network failure propagate unchanged; only this
+ * call's own deadline is classified (`request_timeout`).
+ */
+declare function sendMatrxRequest(url: string, init?: RequestInit, options?: SendMatrxRequestOptions): Promise<Response>;
+/**
+ * A response's JSON body, or the ONE classified `BackendApiError`
+ * (`parseHttpError`) for a non-2xx answer. A 204 resolves `null`.
+ */
+declare function readMatrxJsonResponse<T>(response: Response): Promise<T>;
 
 /**
  * The fail-closed organization-context kernel — ONE implementation for every
@@ -1829,4 +1861,4 @@ interface WarmAgentOptions extends WarmOptions {
  */
 declare function warmAgent(agentId: string, { baseUrl, isVersion, onError }: WarmAgentOptions): void;
 
-export { type ApiTargetLogContext, BackendApiError, type BackendApiErrorData, type BackendErrorCode, type BackendFailureExplanation, type CreateMatrxTransportOptions, ENDPOINTS, type EndpointOverrideConfig, type ExecuteMatrxCallHooks, type ExecuteMatrxCallRequest, FollowRuntimeOperationToEndOptions, type FollowUnavailableRejoinOptions, MATRX_AI_API_VERSION_DEFAULT, MATRX_LIVE_STREAM_UNAVAILABLE, MATRX_RESUME_CONFLICT, MATRX_RUN_IN_PROGRESS, MATRX_UI_ONLY_BODY_FIELDS, type MatrxAiApiVersion, MatrxApiError, type MatrxCallError, type MatrxCallResult, type MatrxCallScope, type MatrxClientSessionProvider, type MatrxClientToolResult, type MatrxFollowedOutcome, type MatrxHttpErrorLike, type MatrxHttpMethod, MatrxJsonObject, MatrxJsonValue, type MatrxLiveRunRejoin, type MatrxLiveStreamUnavailable, type MatrxPendingCallSummary, type MatrxProtocolDowngrade, type MatrxProtocolFallbackOptions, type MatrxQueryParams, type MatrxRequestInfo, MatrxRunHandle, type MatrxRunPickup, type MatrxRunPickupSettlement, MatrxRuntimeExecutionStatus, MatrxRuntimeOperationEvent, MatrxStreamCallOptions, type MatrxStreamIds, type MatrxStreamParse, type MatrxToolResultsResponse, MatrxTransport, type MatrxTransportDiagnostics, type MatrxTransportTarget, OrganizationContextError, type OrganizationContextErrorCode, type OrganizationOperation, type ParseMatrxNdjsonResponseHooks, type ProviderSessionFailure, type ProviderSessionFailureVerdict, RUN_OUTPUT_KINDS, RUN_STREAM_LIFETIME_BACKSTOP_MS, RUN_WAIT_KNOB_FEATURE, type ResumeOrRejoinOptions, type ResumeOrRejoinOutcome, type RunOutputKind, type RunWait, type RunWaitKnobReader, type SettleRunPickupOptions, StreamTransportError, type UpstreamErrorPayload, V2_COVERED_AI_PATH_TEMPLATES, aiVersionPathOverrides, applyAiApiVersion, applyDesktopTargetToRequestBody, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, bareStatusSentence, buildMatrxRequestBody, buildMatrxRequestUrl, buildSafeRequestLog, createMatrxTransport, createOrganizationOperation, describeBackendFailure, executeMatrxCall, fetchWithMatrxProtocolFallback, followUnavailableRejoin, followWorkflowRunEvents, getUserMessage, honestTransportMessage, isBareTransportCode, isCoveredAiPath, isGenericUserMessage, isJobOutputKind, isLiveStreamUnavailable, isResumeConflict, isStreamTransportLost, isV2Path, listConversationPendingToolCalls, listUserPendingToolCalls, logApiTarget, normalizeMatrxError, openMatrxStream, parseCallApiError, parseHttpError, parseHttpErrorBody, parseMatrxNdjsonResponse, parsePersistedBackendError, parseStreamError, providerSessionFailureBody, readConversationOrganizationId, readLiveRunRejoin, readLiveRunRequestId, readLiveStreamUnavailable, readMatrxErrorCode, readMatrxErrorCodeFromMessage, redactUrlForRequestLog, reportProviderSessionFailure, requireOrganizationContext, resolveEndpointPath, resolveRunWaitWith, resumeOrRejoin, runJobLabel, runOutputKindFromModalities, runWaitKnobKey, runWaitTimeoutMessage, runtimeOperationRejoinPath, settleRunPickup, shouldReportMatrxCallError, streamErrorText, submitAgentToolResults, toV1FallbackUrl, toV2Path, unwrapUpstreamError, warmAgent, withRunOrganization };
+export { type ApiTargetLogContext, BackendApiError, type BackendApiErrorData, type BackendErrorCode, type BackendFailureExplanation, type CreateMatrxTransportOptions, ENDPOINTS, type EndpointOverrideConfig, type ExecuteMatrxCallHooks, type ExecuteMatrxCallRequest, FollowRuntimeOperationToEndOptions, type FollowUnavailableRejoinOptions, MATRX_AI_API_VERSION_DEFAULT, MATRX_LIVE_STREAM_UNAVAILABLE, MATRX_RESUME_CONFLICT, MATRX_RUN_IN_PROGRESS, MATRX_UI_ONLY_BODY_FIELDS, type MatrxAiApiVersion, MatrxApiError, type MatrxCallError, type MatrxCallResult, type MatrxCallScope, type MatrxClientSessionProvider, type MatrxClientToolResult, type MatrxFollowedOutcome, type MatrxHttpErrorLike, type MatrxHttpMethod, MatrxJsonObject, MatrxJsonValue, type MatrxLiveRunRejoin, type MatrxLiveStreamUnavailable, type MatrxPendingCallSummary, type MatrxProtocolDowngrade, type MatrxProtocolFallbackOptions, type MatrxQueryParams, type MatrxRequestInfo, MatrxRunHandle, type MatrxRunPickup, type MatrxRunPickupSettlement, MatrxRuntimeExecutionStatus, MatrxRuntimeOperationEvent, MatrxStreamCallOptions, type MatrxStreamIds, type MatrxStreamParse, type MatrxToolResultsResponse, MatrxTransport, type MatrxTransportDiagnostics, type MatrxTransportTarget, OrganizationContextError, type OrganizationContextErrorCode, type OrganizationOperation, type ParseMatrxNdjsonResponseHooks, type ProviderSessionFailure, type ProviderSessionFailureVerdict, RUN_OUTPUT_KINDS, RUN_STREAM_LIFETIME_BACKSTOP_MS, RUN_WAIT_KNOB_FEATURE, type ResumeOrRejoinOptions, type ResumeOrRejoinOutcome, type RunOutputKind, type RunWait, type RunWaitKnobReader, type SendMatrxRequestOptions, type SettleRunPickupOptions, StreamTransportError, type UpstreamErrorPayload, V2_COVERED_AI_PATH_TEMPLATES, aiVersionPathOverrides, applyAiApiVersion, applyDesktopTargetToRequestBody, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, bareStatusSentence, buildMatrxRequestBody, buildMatrxRequestUrl, buildSafeRequestLog, createMatrxTransport, createOrganizationOperation, describeBackendFailure, executeMatrxCall, fetchWithMatrxProtocolFallback, followUnavailableRejoin, followWorkflowRunEvents, getUserMessage, honestTransportMessage, isBareTransportCode, isCoveredAiPath, isGenericUserMessage, isJobOutputKind, isLiveStreamUnavailable, isResumeConflict, isStreamTransportLost, isV2Path, listConversationPendingToolCalls, listUserPendingToolCalls, logApiTarget, normalizeMatrxError, openMatrxStream, parseCallApiError, parseHttpError, parseHttpErrorBody, parseMatrxNdjsonResponse, parsePersistedBackendError, parseStreamError, providerSessionFailureBody, readConversationOrganizationId, readLiveRunRejoin, readLiveRunRequestId, readLiveStreamUnavailable, readMatrxErrorCode, readMatrxErrorCodeFromMessage, readMatrxJsonResponse, redactUrlForRequestLog, reportProviderSessionFailure, requireOrganizationContext, resolveEndpointPath, resolveRunWaitWith, resumeOrRejoin, runJobLabel, runOutputKindFromModalities, runWaitKnobKey, runWaitTimeoutMessage, runtimeOperationRejoinPath, sendMatrxRequest, settleRunPickup, shouldReportMatrxCallError, streamErrorText, submitAgentToolResults, toV1FallbackUrl, toV2Path, unwrapUpstreamError, warmAgent, withRunOrganization };

package/dist/matrx/index.d.ts

@@ -5,7 +5,7 @@ import { ResilientFetchOptions } from '@ai-matrx/data/net';
 import { MatrxStreamEnvelope, MatrxNdjsonIssue } from '../stream/ndjson.js';
 import { v as MatrxRuntimeOperationEvent, a as FollowRuntimeOperationToEndOptions, u as MatrxRuntimeExecutionStatus, z as MatrxStreamCallOptions, t as MatrxRunHandle, l as MatrxJsonValue, k as MatrxJsonObject } from '../operations-C3iHFcnt.js';
 export { F as FollowRuntimeOperationOptions, b as FollowRuntimeOperationToEndResult, M as MatrxAgentStartRequest, c as MatrxCancelResponse, d as MatrxChatMessage, e as MatrxCompletedRun, f as MatrxContextAnchor, g as MatrxConversationContinueRequest, h as MatrxConversationResumeRequest, i as MatrxConversationStart, j as MatrxEphemeralConversation, m as MatrxMandateStartRequest, n as MatrxOperationEventsPage, o as MatrxOperationFollowEvent, p as MatrxOperationStatusResponse, q as MatrxOperationsByLinkResponse, r as MatrxRequestScope, s as MatrxRunError, w as MatrxRuntimeOperationView, x as MatrxStoredConversationContinue, y as MatrxStoredConversationCreate, A as MatrxTurnFields, R as RunAgentToCompletionOptions, T as TERMINAL_MATRX_RUNTIME_STATUSES, B as cancelAgentRun, C as continueAgentConversation, D as continueEphemeralConversationStart, E as continueStoredConversationStart, G as followRuntimeOperationEvents, H as followRuntimeOperationToEnd, I as getRuntimeOperationStatus, J as getRuntimeOperationsByLink, K as listRuntimeOperationEvents, L as mintMatrxConversationId, N as newEphemeralConversationStart, O as newStoredConversationStart, P as rejoinRuntimeOperation, Q as resumeAgentConversation, S as runAgentToCompletion, U as startAgentRun, V as startMandateRun } from '../operations-C3iHFcnt.js';
-import { M as MandateKey, D as DynamicMandateKey } from '../keys.generated-klzs6I1T.js';
+import { M as MandateKey, D as DynamicMandateKey } from '../keys.generated-DNRbtHNx.js';
 import '../stream/sse.js';
 
 /**
@@ -507,6 +507,10 @@ declare function getUserMessage(error: unknown): string;
  *   body reader classified as a resumable `StreamTransportError`;
  * - `executeMatrxCall` — the JSON or NDJSON execution over the v2 → v1
  *   protocol fallback, with the stream callbacks and `consumeStream`;
+ * - `sendMatrxRequest` / `readMatrxJsonResponse` — the raw-`Response` lane
+ *   for a host's imperative client (multipart bodies, byte downloads,
+ *   response-aware callers): one deadline, a caller abort kept as itself, and
+ *   the ONE HTTP error parser;
  * - `buildSafeRequestLog` / `redactUrlForRequestLog` /
  *   `shouldReportMatrxCallError` — the log and capture policy.
  *
@@ -537,7 +541,12 @@ interface MatrxCallResult<T = unknown> {
     /** Set when the call failed with an HTTP error response. */
     error?: MatrxCallError;
 }
-type MatrxQueryParams = Record<string, string | number | boolean>;
+type MatrxQueryScalar = string | number | boolean;
+/**
+ * Query values: a scalar is sent as itself, an array repeats the key (the
+ * FastAPI repeatable-parameter convention), `null` / `undefined` are omitted.
+ */
+type MatrxQueryParams = Record<string, MatrxQueryScalar | readonly MatrxQueryScalar[] | null | undefined>;
 /**
  * The full URL for one call: `{param}` segments substituted (encoded), the
  * legacy `/api` prefix stripped (server routes no longer live under it), and
@@ -642,6 +651,29 @@ interface ExecuteMatrxCallHooks<E = MatrxStreamEnvelope> {
  * `normalizeMatrxError` and decides what to capture.
  */
 declare function executeMatrxCall<T = unknown, E = MatrxStreamEnvelope>(request: ExecuteMatrxCallRequest<E>, hooks?: ExecuteMatrxCallHooks<E>): Promise<MatrxCallResult<T>>;
+interface SendMatrxRequestOptions {
+    /** Caller cancellation; an abort propagates as the caller's own AbortError. */
+    signal?: AbortSignal;
+    /**
+     * Deadline (ms) from send to response headers. On expiry the call rejects
+     * with a `BackendApiError` coded `request_timeout` (status 504) — never a
+     * fake caller cancellation. Omit for no deadline.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Send one request and resolve with the raw `Response`, whatever its status.
+ * The lane for an imperative host client whose bodies are not JSON (a
+ * `FormData` upload), whose answers are bytes, or which reads the response
+ * itself. A caller abort and a network failure propagate unchanged; only this
+ * call's own deadline is classified (`request_timeout`).
+ */
+declare function sendMatrxRequest(url: string, init?: RequestInit, options?: SendMatrxRequestOptions): Promise<Response>;
+/**
+ * A response's JSON body, or the ONE classified `BackendApiError`
+ * (`parseHttpError`) for a non-2xx answer. A 204 resolves `null`.
+ */
+declare function readMatrxJsonResponse<T>(response: Response): Promise<T>;
 
 /**
  * The fail-closed organization-context kernel — ONE implementation for every
@@ -1829,4 +1861,4 @@ interface WarmAgentOptions extends WarmOptions {
  */
 declare function warmAgent(agentId: string, { baseUrl, isVersion, onError }: WarmAgentOptions): void;
 
-export { type ApiTargetLogContext, BackendApiError, type BackendApiErrorData, type BackendErrorCode, type BackendFailureExplanation, type CreateMatrxTransportOptions, ENDPOINTS, type EndpointOverrideConfig, type ExecuteMatrxCallHooks, type ExecuteMatrxCallRequest, FollowRuntimeOperationToEndOptions, type FollowUnavailableRejoinOptions, MATRX_AI_API_VERSION_DEFAULT, MATRX_LIVE_STREAM_UNAVAILABLE, MATRX_RESUME_CONFLICT, MATRX_RUN_IN_PROGRESS, MATRX_UI_ONLY_BODY_FIELDS, type MatrxAiApiVersion, MatrxApiError, type MatrxCallError, type MatrxCallResult, type MatrxCallScope, type MatrxClientSessionProvider, type MatrxClientToolResult, type MatrxFollowedOutcome, type MatrxHttpErrorLike, type MatrxHttpMethod, MatrxJsonObject, MatrxJsonValue, type MatrxLiveRunRejoin, type MatrxLiveStreamUnavailable, type MatrxPendingCallSummary, type MatrxProtocolDowngrade, type MatrxProtocolFallbackOptions, type MatrxQueryParams, type MatrxRequestInfo, MatrxRunHandle, type MatrxRunPickup, type MatrxRunPickupSettlement, MatrxRuntimeExecutionStatus, MatrxRuntimeOperationEvent, MatrxStreamCallOptions, type MatrxStreamIds, type MatrxStreamParse, type MatrxToolResultsResponse, MatrxTransport, type MatrxTransportDiagnostics, type MatrxTransportTarget, OrganizationContextError, type OrganizationContextErrorCode, type OrganizationOperation, type ParseMatrxNdjsonResponseHooks, type ProviderSessionFailure, type ProviderSessionFailureVerdict, RUN_OUTPUT_KINDS, RUN_STREAM_LIFETIME_BACKSTOP_MS, RUN_WAIT_KNOB_FEATURE, type ResumeOrRejoinOptions, type ResumeOrRejoinOutcome, type RunOutputKind, type RunWait, type RunWaitKnobReader, type SettleRunPickupOptions, StreamTransportError, type UpstreamErrorPayload, V2_COVERED_AI_PATH_TEMPLATES, aiVersionPathOverrides, applyAiApiVersion, applyDesktopTargetToRequestBody, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, bareStatusSentence, buildMatrxRequestBody, buildMatrxRequestUrl, buildSafeRequestLog, createMatrxTransport, createOrganizationOperation, describeBackendFailure, executeMatrxCall, fetchWithMatrxProtocolFallback, followUnavailableRejoin, followWorkflowRunEvents, getUserMessage, honestTransportMessage, isBareTransportCode, isCoveredAiPath, isGenericUserMessage, isJobOutputKind, isLiveStreamUnavailable, isResumeConflict, isStreamTransportLost, isV2Path, listConversationPendingToolCalls, listUserPendingToolCalls, logApiTarget, normalizeMatrxError, openMatrxStream, parseCallApiError, parseHttpError, parseHttpErrorBody, parseMatrxNdjsonResponse, parsePersistedBackendError, parseStreamError, providerSessionFailureBody, readConversationOrganizationId, readLiveRunRejoin, readLiveRunRequestId, readLiveStreamUnavailable, readMatrxErrorCode, readMatrxErrorCodeFromMessage, redactUrlForRequestLog, reportProviderSessionFailure, requireOrganizationContext, resolveEndpointPath, resolveRunWaitWith, resumeOrRejoin, runJobLabel, runOutputKindFromModalities, runWaitKnobKey, runWaitTimeoutMessage, runtimeOperationRejoinPath, settleRunPickup, shouldReportMatrxCallError, streamErrorText, submitAgentToolResults, toV1FallbackUrl, toV2Path, unwrapUpstreamError, warmAgent, withRunOrganization };
+export { type ApiTargetLogContext, BackendApiError, type BackendApiErrorData, type BackendErrorCode, type BackendFailureExplanation, type CreateMatrxTransportOptions, ENDPOINTS, type EndpointOverrideConfig, type ExecuteMatrxCallHooks, type ExecuteMatrxCallRequest, FollowRuntimeOperationToEndOptions, type FollowUnavailableRejoinOptions, MATRX_AI_API_VERSION_DEFAULT, MATRX_LIVE_STREAM_UNAVAILABLE, MATRX_RESUME_CONFLICT, MATRX_RUN_IN_PROGRESS, MATRX_UI_ONLY_BODY_FIELDS, type MatrxAiApiVersion, MatrxApiError, type MatrxCallError, type MatrxCallResult, type MatrxCallScope, type MatrxClientSessionProvider, type MatrxClientToolResult, type MatrxFollowedOutcome, type MatrxHttpErrorLike, type MatrxHttpMethod, MatrxJsonObject, MatrxJsonValue, type MatrxLiveRunRejoin, type MatrxLiveStreamUnavailable, type MatrxPendingCallSummary, type MatrxProtocolDowngrade, type MatrxProtocolFallbackOptions, type MatrxQueryParams, type MatrxRequestInfo, MatrxRunHandle, type MatrxRunPickup, type MatrxRunPickupSettlement, MatrxRuntimeExecutionStatus, MatrxRuntimeOperationEvent, MatrxStreamCallOptions, type MatrxStreamIds, type MatrxStreamParse, type MatrxToolResultsResponse, MatrxTransport, type MatrxTransportDiagnostics, type MatrxTransportTarget, OrganizationContextError, type OrganizationContextErrorCode, type OrganizationOperation, type ParseMatrxNdjsonResponseHooks, type ProviderSessionFailure, type ProviderSessionFailureVerdict, RUN_OUTPUT_KINDS, RUN_STREAM_LIFETIME_BACKSTOP_MS, RUN_WAIT_KNOB_FEATURE, type ResumeOrRejoinOptions, type ResumeOrRejoinOutcome, type RunOutputKind, type RunWait, type RunWaitKnobReader, type SendMatrxRequestOptions, type SettleRunPickupOptions, StreamTransportError, type UpstreamErrorPayload, V2_COVERED_AI_PATH_TEMPLATES, aiVersionPathOverrides, applyAiApiVersion, applyDesktopTargetToRequestBody, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, bareStatusSentence, buildMatrxRequestBody, buildMatrxRequestUrl, buildSafeRequestLog, createMatrxTransport, createOrganizationOperation, describeBackendFailure, executeMatrxCall, fetchWithMatrxProtocolFallback, followUnavailableRejoin, followWorkflowRunEvents, getUserMessage, honestTransportMessage, isBareTransportCode, isCoveredAiPath, isGenericUserMessage, isJobOutputKind, isLiveStreamUnavailable, isResumeConflict, isStreamTransportLost, isV2Path, listConversationPendingToolCalls, listUserPendingToolCalls, logApiTarget, normalizeMatrxError, openMatrxStream, parseCallApiError, parseHttpError, parseHttpErrorBody, parseMatrxNdjsonResponse, parsePersistedBackendError, parseStreamError, providerSessionFailureBody, readConversationOrganizationId, readLiveRunRejoin, readLiveRunRequestId, readLiveStreamUnavailable, readMatrxErrorCode, readMatrxErrorCodeFromMessage, readMatrxJsonResponse, redactUrlForRequestLog, reportProviderSessionFailure, requireOrganizationContext, resolveEndpointPath, resolveRunWaitWith, resumeOrRejoin, runJobLabel, runOutputKindFromModalities, runWaitKnobKey, runWaitTimeoutMessage, runtimeOperationRejoinPath, sendMatrxRequest, settleRunPickup, shouldReportMatrxCallError, streamErrorText, submitAgentToolResults, toV1FallbackUrl, toV2Path, unwrapUpstreamError, warmAgent, withRunOrganization };

package/dist/matrx/index.js

@@ -765,13 +765,15 @@ function buildMatrxRequestUrl(baseUrl, pathTemplate, pathParams, queryParams) {
   }
   const fullPath = resolvedPath.startsWith("/api/") ? resolvedPath.slice(4) : resolvedPath;
   const url = `${baseUrl}${fullPath}`;
-  if (queryParams && Object.keys(queryParams).length > 0) {
-    const qs = new URLSearchParams(
-      Object.fromEntries(
-        Object.entries(queryParams).map(([k, v]) => [k, String(v)])
-      )
-    ).toString();
-    return `${url}?${qs}`;
+  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;
 }
@@ -955,6 +957,44 @@ async function executeMatrxCall(request, hooks = {}) {
     ...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();
+}
 
 // matrx/client.ts
 function classifyStatus(status) {
@@ -2659,6 +2699,7 @@ export {
   readLiveStreamUnavailable,
   readMatrxErrorCode,
   readMatrxErrorCodeFromMessage,
+  readMatrxJsonResponse,
   redactUrlForRequestLog,
   rejoinRuntimeOperation,
   reportProviderSessionFailure,
@@ -2673,6 +2714,7 @@ export {
   runWaitKnobKey,
   runWaitTimeoutMessage,
   runtimeOperationRejoinPath,
+  sendMatrxRequest,
   settleRunPickup,
   shouldReportMatrxCallError,
   startAgentRun,