@ai-matrx/agents 0.36.0 → 0.37.1

package/dist/matrx/index.d.ts

@@ -2,10 +2,10 @@ import { M as MatrxTransport, a as MatrxApiError } from '../transport-CxD0fL8p.j
 export { b as MatrxTransportRequest, e as extractMatrxErrorCode, c as extractMatrxErrorMessage } from '../transport-CxD0fL8p.js';
 import { CredentialsPort } from '@ai-matrx/data';
 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 { MatrxStreamEnvelope } from '../stream/ndjson.js';
-import { M as MandateKey, D as DynamicMandateKey } from '../keys.generated-DCtN66RS.js';
+import { M as MandateKey, D as DynamicMandateKey } from '../keys.generated-DL-5LCNz.js';
 import '../stream/sse.js';
 
 /**
@@ -175,11 +175,21 @@ interface MatrxCallError {
     name?: string;
     /** Original exception stack. */
     stack?: string;
+    /** JSON-safe dump of the original thrown value. */
+    raw?: unknown;
 }
 /**
- * Classify any failure thrown by a package client call — `MatrxApiError`,
- * a `NetError` from the resilience layer, an org-context refusal, an abort —
- * into the `MatrxCallError` envelope. Never throws.
+ * Classify any failure thrown by a Matrx client call — `MatrxApiError`, a
+ * typed `BackendApiError` / `StreamTransportError`, a `NetError` from the
+ * resilience layer, an org-context refusal, an abort — into the
+ * `MatrxCallError` envelope. Never throws.
+ *
+ * Every message is laundered through `honestTransportMessage`: a bare status
+ * line ("HTTP 400") never reaches a person — the status rides `status`.
+ * A `BackendApiError` keeps its machine `code` (a dropped socket stays
+ * `stream_transport_lost`, so a surface reattaches instead of dead-ending)
+ * and its structured `details` ride `serverDetail` (the organization-hold
+ * body carries the caller's membership choices there).
  */
 declare function normalizeMatrxError(err: unknown): MatrxCallError;
 /**
@@ -273,6 +283,366 @@ interface CreateMatrxTransportOptions {
  */
 declare function createMatrxTransport(options: CreateMatrxTransportOptions): MatrxTransport;
 
+/**
+ * `@ai-matrx/agents/matrx` — the AI Matrx server's error model, as every
+ * client reads it: `BackendApiError` (the server's `APIError` body),
+ * `StreamTransportError` (the socket died mid-run; the run may still finish
+ * and is reattachable), parsing of HTTP / stream / persisted errors, and the
+ * ONE sentence a person sees (`getUserMessage`, `describeBackendFailure`).
+ *
+ * Moved from matrx-frontend `lib/api/errors.ts` (chat-package independence
+ * P9); the app re-exports it from here. Pure: no host, no window, no env.
+ */
+/**
+ * Standardized error shape returned by all backend endpoints.
+ * Matches the Python `APIError` Pydantic model.
+ */
+interface BackendApiErrorData {
+    /** Machine-readable error code (e.g. "auth_required", "validation_error") */
+    error: string;
+    /** Developer-facing detail for debugging */
+    message: string;
+    /** Safe to display directly in the UI */
+    user_message: string;
+    /** Extra info (validation errors, etc.) */
+    details: unknown | null;
+    /** Unique request ID for support/debugging */
+    request_id: string;
+}
+/** Common backend error codes */
+type BackendErrorCode = "auth_required" | "token_required" | "admin_required" | "validation_error" | "not_found" | "internal_error" | "agent_error"
+/** The stream socket died mid-run; the server run may still be completing
+ *  and is reattachable. See `StreamTransportError`. */
+ | "stream_transport_lost" | (string & {});
+/**
+ * Typed error thrown by all backend API operations.
+ * Contains structured fields matching the Python APIError model.
+ *
+ * Usage:
+ * ```typescript
+ * try {
+ *   await client.post(ENDPOINTS.ai.agentStart(agentId), body);
+ * } catch (err) {
+ *   if (err instanceof BackendApiError) {
+ *     // Show err.userMessage to the user
+ *     // Log err.requestId for debugging
+ *     // Check err.code for programmatic handling
+ *   }
+ * }
+ * ```
+ */
+declare class BackendApiError extends Error {
+    /** Machine-readable error code */
+    readonly code: BackendErrorCode;
+    /** Developer-facing detail */
+    readonly detail: string;
+    /** Safe to display directly in the UI */
+    readonly userMessage: string;
+    /** Extra info (validation errors, etc.) */
+    readonly details: unknown | null;
+    /** Unique request ID for support/debugging */
+    readonly requestId: string;
+    /** HTTP status code (if from an HTTP response) */
+    readonly status: number | null;
+    constructor(data: {
+        code: BackendErrorCode;
+        detail: string;
+        userMessage: string;
+        details?: unknown | null;
+        requestId?: string | undefined;
+        status?: number | null | undefined;
+    });
+    /** Convert to the wire format for logging */
+    toJSON(): BackendApiErrorData;
+}
+/**
+ * The socket carrying a live NDJSON stream broke mid-run.
+ *
+ * THE DISTINCTION THIS EXISTS TO MAKE: a backend that blows up mid-stream does
+ * NOT break the socket — it emits a typed `error` event and closes the body
+ * cleanly. So an exception escaping the body reader means the *transport* died,
+ * not the run. And aidream streams run `detach_on_disconnect=True`: the server
+ * keeps executing and persisting the turn after our connection goes away.
+ *
+ * The client therefore cannot decide locally whether the answer is lost — it
+ * must ASK THE SERVER. That is what `resumable` means here: "reattach by
+ * requestId / conversationId / durable run id and let server truth settle it",
+ * never "this succeeded". A server that genuinely died reports `failed` on
+ * reattach and the honest record replaces the optimistic copy.
+ *
+ * Consumers: `run-ai-stream.ts` (chat → `reconnectServerOperation`) and
+ * `adopt-foreign-stream.ts` (pipeline runs → the surface's own rejoin).
+ */
+declare class StreamTransportError extends BackendApiError {
+    /** Always true — reattach and let the server settle the outcome. */
+    readonly resumable: true;
+    constructor(data: {
+        detail: string;
+        details?: unknown | null;
+        requestId?: string;
+    });
+}
+/**
+ * True when a failure is a dropped transport rather than a failed run. Use this
+ * instead of `instanceof` at boundaries that re-wrap errors (thunk rejections,
+ * `callApi` result errors), where the class identity is lost but the code
+ * survives.
+ */
+declare function isStreamTransportLost(error: unknown): boolean;
+/**
+ * Parse a non-OK HTTP response into a BackendApiError.
+ *
+ * Handles the standardized backend shape and falls back gracefully
+ * when the response isn't JSON or uses a legacy format.
+ */
+declare function parseHttpError(response: Response): Promise<BackendApiError>;
+/**
+ * Parse an already-decoded JSON error body into a BackendApiError.
+ *
+ * Exported because XHR callers (upload/download progress paths) have the
+ * parsed body in hand and MUST NOT hand-roll a shallower read: a private
+ * copy in `python-client.ts` looked only at top-level `error`/`message`, so
+ * FastAPI's `{"detail": {...}}` envelope — what every matrx-files 500 uses —
+ * degraded to the useless `code: "internal", detail: "HTTP 500"`. That is
+ * exactly how an upload failure with a real server-side cause reached the
+ * user as `Upload failed (500)` and nothing else. One parser, every transport.
+ */
+declare function parseHttpErrorBody(body: Record<string, unknown> | null, status: number): BackendApiError;
+/**
+ * Adapt callApi's result-style error into the same canonical error used by
+ * direct fetch and streaming consumers.
+ *
+ * callApi intentionally returns errors instead of throwing them, but its
+ * `serverDetail` contains the complete FastAPI body. Sending only
+ * `error.message` to a feature discards that body and turns a precise
+ * configuration failure into "HTTP 422". This adapter keeps one parser and
+ * one human-facing explanation path across both client styles.
+ */
+declare function parseCallApiError(error: {
+    message: string;
+    status?: number;
+    serverDetail?: unknown;
+}): BackendApiError;
+/**
+ * Parse streaming error event data into a BackendApiError.
+ *
+ * Handles both new format (`user_message`) and legacy (`user_visible_message`).
+ */
+declare function parseStreamError(data: unknown): BackendApiError;
+/**
+ * Restore the canonical error shape from a durable backend run row.
+ *
+ * Provider ledgers often keep an aggregate summary plus a more specific first
+ * child failure. Prefer that child so a page refresh does not turn a precise
+ * streamed failure back into "1 request failed".
+ */
+declare function parsePersistedBackendError(data: unknown, requestId?: string): BackendApiError | null;
+/** True when a message tells the reader nothing about what actually broke. */
+declare function isGenericUserMessage(message: string | null | undefined): boolean;
+interface UpstreamErrorPayload {
+    message: string;
+    code: string | null;
+    userMessage: string | null;
+    requestId: string | null;
+    status: number | null;
+}
+/**
+ * Recover an upstream service's structured error that a downstream service
+ * stringified into its own message.
+ *
+ * Real example (scraper wrapping aidream):
+ *   `aidream could not resolve GSC credential 7223…: HTTP 409 {"error":"conflict",
+ *    "message":"Google connection 7223… has no vault credential — it needs
+ *    re-authentication","user_message":"Something went wrong…","request_id":"9002…"}`
+ *
+ * Without this, the only actionable sentence on the whole hop is invisible.
+ */
+declare function unwrapUpstreamError(message: string): UpstreamErrorPayload | null;
+interface BackendFailureExplanation {
+    /** Machine code from the deepest layer that classified the failure. */
+    code: string;
+    /** The most specific human-readable cause available — never a template. */
+    cause: string;
+    /** What to headline in the UI: the cause when the server was generic. */
+    headline: string;
+    /** True when every user-facing message the server sent was a template. */
+    headlineWasGeneric: boolean;
+    /** Message chain, outermost (closest service) first. */
+    chain: string[];
+    /** Deepest request id available, for cross-service log correlation. */
+    requestId: string;
+    status: number | null;
+}
+/**
+ * THE anti-secrecy primitive: turn any thrown backend/stream failure into the
+ * most specific explanation the payload can support — unwrapping every nested
+ * upstream error and refusing to let a templated `user_message` be the answer.
+ *
+ * Every surface that reports a backend failure to a human should headline
+ * `explanation.headline` and always keep `cause` + `requestId` reachable.
+ */
+declare function describeBackendFailure(error: unknown): BackendFailureExplanation;
+/**
+ * Extract a user-visible message from any error object.
+ * Utility for components that just need the display string.
+ */
+declare function getUserMessage(error: unknown): string;
+
+/**
+ * `@ai-matrx/agents/matrx` — THE request pipeline every typed Matrx server call
+ * rides (chat package independence P9b). One implementation for every client:
+ * matrx-frontend's `lib/api` `callApi` and the chat package's bare-host default
+ * both build on it, and supply only their host facts — where the server is,
+ * which credential and organization ride, and where diagnostics go.
+ *
+ * What lives here (pure, no host/window/env read):
+ *
+ * - `buildMatrxRequestUrl` — path params, the legacy `/api` strip, the query;
+ * - `buildMatrxRequestBody` — scope injection (`organization_id` /
+ *   `project_id` / `task_id`), the UI-only field strip, and the fail-closed
+ *   body-vs-context organization check;
+ * - `bareStatusSentence` / `isBareTransportCode` / `honestTransportMessage` —
+ *   a bare status code is never a sentence at a person;
+ * - `parseMatrxNdjsonResponse` — a response body as typed envelopes, a broken
+ *   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`;
+ * - `buildSafeRequestLog` / `redactUrlForRequestLog` /
+ *   `shouldReportMatrxCallError` — the log and capture policy.
+ *
+ * The error envelope (`MatrxCallError`) and its ONE classifier
+ * (`normalizeMatrxError`) live in `./client`.
+ */
+
+type MatrxHttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+/**
+ * Every context dimension a call may carry. `organization_id`, `project_id`
+ * and `task_id` are injected into the body; `user_id` rides the credential and
+ * `conversation_id` the path or an explicit body field — never injected.
+ */
+interface MatrxCallScope {
+    user_id?: string;
+    organization_id?: string;
+    project_id?: string;
+    task_id?: string;
+    conversation_id?: string;
+}
+interface MatrxCallResult<T = unknown> {
+    /** Parsed JSON response body (non-streaming calls only). */
+    data?: T;
+    /** Server-assigned request id (response header). */
+    requestId?: string;
+    /** Server-assigned conversation id (response header). */
+    conversationId?: string;
+    /** Set when the call failed with an HTTP error response. */
+    error?: MatrxCallError;
+}
+type MatrxQueryParams = Record<string, string | number | boolean>;
+/**
+ * The full URL for one call: `{param}` segments substituted (encoded), the
+ * legacy `/api` prefix stripped (server routes no longer live under it), and
+ * the query appended.
+ */
+declare function buildMatrxRequestUrl(baseUrl: string, pathTemplate: string, pathParams?: Record<string, string>, queryParams?: MatrxQueryParams): string;
+/**
+ * Client capability flags that must never reach the server — the server's
+ * request schemas reject them.
+ */
+declare const MATRX_UI_ONLY_BODY_FIELDS: ReadonlySet<string>;
+/**
+ * The final request body: UI-only fields stripped, scope fields injected.
+ *
+ * A caller's `organization_id: null` (or blank) means "I have none of my own",
+ * never "send this for a different organization" — it is dropped and the
+ * scope's organization injected. A real value that disagrees with the scope
+ * is refused (`organization_context_mismatch`). With no scope organization
+ * (the org-less guest lane, an org-free read) nothing is injected for it.
+ * Other scope fields keep caller-wins behaviour.
+ */
+declare function buildMatrxRequestBody(body: unknown, scope: MatrxCallScope): Record<string, unknown>;
+/** True when a candidate sentence is really just the status line wearing words. */
+declare function isBareTransportCode(text: string | null | undefined): boolean;
+/**
+ * A BARE STATUS CODE IS NEVER A SENTENCE. What a person reads when the server
+ * answered an error with no readable message. The status itself rides
+ * `error.status`, which is what code branches on — this is only the words.
+ */
+declare function bareStatusSentence(status: number): string;
+/** `raw` unless it is empty or only a status line; then the status sentence. */
+declare function honestTransportMessage(raw: string, status: number | undefined): string;
+/** Request metadata safe to log: secret headers redacted, the body as its shape only. */
+declare function buildSafeRequestLog(headers: Record<string, string>, body: unknown): {
+    headers: Record<string, string>;
+    body: Record<string, unknown>;
+};
+/** The URL with every query value redacted. */
+declare function redactUrlForRequestLog(url: string): string;
+/** False only for an HTTP status the call site declared an expected outcome. */
+declare function shouldReportMatrxCallError(status: number | null | undefined, expectedErrorStatuses: readonly number[] | undefined): boolean;
+interface MatrxStreamIds {
+    requestId: string | null;
+    conversationId: string | null;
+}
+interface MatrxStreamParse<E = MatrxStreamEnvelope> extends MatrxStreamIds {
+    events: AsyncGenerator<E, void, undefined>;
+}
+interface ParseMatrxNdjsonResponseHooks {
+    /** Every envelope, before the consumer sees it. */
+    onEvent?: (event: MatrxStreamEnvelope, ids: MatrxStreamIds) => void;
+    /** A broken body reader, already classified, before it is thrown. */
+    onTransportError?: (error: BackendApiError, ids: MatrxStreamIds) => void;
+    onMalformedLine?: (issue: MatrxNdjsonIssue) => void;
+    onUnknownEnvelope?: (value: unknown) => void;
+}
+/**
+ * A Matrx NDJSON response as typed envelopes. The ids come from headers, so
+ * they are available before any event. A body that breaks mid-run is a
+ * TRANSPORT loss (the run may still finish server-side and is reattachable) —
+ * thrown as `StreamTransportError`, never a failed run; an abort ends quietly.
+ */
+declare function parseMatrxNdjsonResponse(response: Response, signal?: AbortSignal, hooks?: ParseMatrxNdjsonResponseHooks): MatrxStreamParse;
+interface ExecuteMatrxCallRequest<E = MatrxStreamEnvelope> {
+    /** The final URL (`buildMatrxRequestUrl`). */
+    url: string;
+    method: string;
+    /** Every header the host binds (credential, organization, Content-Type). */
+    headers: Record<string, string>;
+    /** The assembled body (`buildMatrxRequestBody`); never sent on GET/HEAD. */
+    body: unknown;
+    /** NDJSON streaming call. */
+    stream?: boolean;
+    signal?: AbortSignal;
+    /** Time to response headers. Default 15_000. */
+    connectTimeoutMs?: number;
+    /** Whole-request cap for JSON calls. Default 30_000; `null` uncaps. Streams are uncapped. */
+    totalTimeoutMs?: number | null;
+    /** Fires when headers arrive, before any event. */
+    onStreamStart?: (requestId: string | null, conversationId: string | null) => void;
+    onStreamEvent?: (event: E) => void;
+    /**
+     * Take ownership of the body instead of the executor draining it (a body is
+     * consumed once). `onStreamEvent` is then not called; start / complete /
+     * error still fire.
+     */
+    consumeStream?: (response: Response, ids: MatrxStreamIds) => Promise<void>;
+    onStreamComplete?: (requestId: string | null, conversationId: string | null) => void;
+    /** Fires for an HTTP error response on a stream (thrown failures are the caller's). */
+    onStreamError?: (error: MatrxCallError) => void;
+}
+interface ExecuteMatrxCallHooks<E = MatrxStreamEnvelope> {
+    /** Every v2 → v1 protocol downgrade. */
+    onProtocolDowngrade?: (downgrade: MatrxProtocolDowngrade) => void;
+    /** The host's stream parser (default `parseMatrxNdjsonResponse`). */
+    parseStream?: (response: Response, signal?: AbortSignal) => MatrxStreamParse<E>;
+}
+/**
+ * Execute one call over the v2 → v1 protocol fallback. An HTTP error
+ * response resolves as `{ error }`; a thrown failure (network, timeout,
+ * abort, a broken stream) propagates — the caller normalizes it with
+ * `normalizeMatrxError` and decides what to capture.
+ */
+declare function executeMatrxCall<T = unknown, E = MatrxStreamEnvelope>(request: ExecuteMatrxCallRequest<E>, hooks?: ExecuteMatrxCallHooks<E>): Promise<MatrxCallResult<T>>;
+
 /**
  * The fail-closed organization-context kernel — ONE implementation for every
  * Matrx client transport (moved in from matrx-frontend
@@ -758,211 +1128,6 @@ declare function listUserPendingToolCalls(transport: MatrxTransport, options?: {
     signal?: AbortSignal;
 }): Promise<MatrxPendingCallSummary[]>;
 
-/**
- * `@ai-matrx/agents/matrx` — the AI Matrx server's error model, as every
- * client reads it: `BackendApiError` (the server's `APIError` body),
- * `StreamTransportError` (the socket died mid-run; the run may still finish
- * and is reattachable), parsing of HTTP / stream / persisted errors, and the
- * ONE sentence a person sees (`getUserMessage`, `describeBackendFailure`).
- *
- * Moved from matrx-frontend `lib/api/errors.ts` (chat-package independence
- * P9); the app re-exports it from here. Pure: no host, no window, no env.
- */
-/**
- * Standardized error shape returned by all backend endpoints.
- * Matches the Python `APIError` Pydantic model.
- */
-interface BackendApiErrorData {
-    /** Machine-readable error code (e.g. "auth_required", "validation_error") */
-    error: string;
-    /** Developer-facing detail for debugging */
-    message: string;
-    /** Safe to display directly in the UI */
-    user_message: string;
-    /** Extra info (validation errors, etc.) */
-    details: unknown | null;
-    /** Unique request ID for support/debugging */
-    request_id: string;
-}
-/** Common backend error codes */
-type BackendErrorCode = "auth_required" | "token_required" | "admin_required" | "validation_error" | "not_found" | "internal_error" | "agent_error"
-/** The stream socket died mid-run; the server run may still be completing
- *  and is reattachable. See `StreamTransportError`. */
- | "stream_transport_lost" | (string & {});
-/**
- * Typed error thrown by all backend API operations.
- * Contains structured fields matching the Python APIError model.
- *
- * Usage:
- * ```typescript
- * try {
- *   await client.post(ENDPOINTS.ai.agentStart(agentId), body);
- * } catch (err) {
- *   if (err instanceof BackendApiError) {
- *     // Show err.userMessage to the user
- *     // Log err.requestId for debugging
- *     // Check err.code for programmatic handling
- *   }
- * }
- * ```
- */
-declare class BackendApiError extends Error {
-    /** Machine-readable error code */
-    readonly code: BackendErrorCode;
-    /** Developer-facing detail */
-    readonly detail: string;
-    /** Safe to display directly in the UI */
-    readonly userMessage: string;
-    /** Extra info (validation errors, etc.) */
-    readonly details: unknown | null;
-    /** Unique request ID for support/debugging */
-    readonly requestId: string;
-    /** HTTP status code (if from an HTTP response) */
-    readonly status: number | null;
-    constructor(data: {
-        code: BackendErrorCode;
-        detail: string;
-        userMessage: string;
-        details?: unknown | null;
-        requestId?: string | undefined;
-        status?: number | null | undefined;
-    });
-    /** Convert to the wire format for logging */
-    toJSON(): BackendApiErrorData;
-}
-/**
- * The socket carrying a live NDJSON stream broke mid-run.
- *
- * THE DISTINCTION THIS EXISTS TO MAKE: a backend that blows up mid-stream does
- * NOT break the socket — it emits a typed `error` event and closes the body
- * cleanly. So an exception escaping the body reader means the *transport* died,
- * not the run. And aidream streams run `detach_on_disconnect=True`: the server
- * keeps executing and persisting the turn after our connection goes away.
- *
- * The client therefore cannot decide locally whether the answer is lost — it
- * must ASK THE SERVER. That is what `resumable` means here: "reattach by
- * requestId / conversationId / durable run id and let server truth settle it",
- * never "this succeeded". A server that genuinely died reports `failed` on
- * reattach and the honest record replaces the optimistic copy.
- *
- * Consumers: `run-ai-stream.ts` (chat → `reconnectServerOperation`) and
- * `adopt-foreign-stream.ts` (pipeline runs → the surface's own rejoin).
- */
-declare class StreamTransportError extends BackendApiError {
-    /** Always true — reattach and let the server settle the outcome. */
-    readonly resumable: true;
-    constructor(data: {
-        detail: string;
-        details?: unknown | null;
-        requestId?: string;
-    });
-}
-/**
- * True when a failure is a dropped transport rather than a failed run. Use this
- * instead of `instanceof` at boundaries that re-wrap errors (thunk rejections,
- * `callApi` result errors), where the class identity is lost but the code
- * survives.
- */
-declare function isStreamTransportLost(error: unknown): boolean;
-/**
- * Parse a non-OK HTTP response into a BackendApiError.
- *
- * Handles the standardized backend shape and falls back gracefully
- * when the response isn't JSON or uses a legacy format.
- */
-declare function parseHttpError(response: Response): Promise<BackendApiError>;
-/**
- * Parse an already-decoded JSON error body into a BackendApiError.
- *
- * Exported because XHR callers (upload/download progress paths) have the
- * parsed body in hand and MUST NOT hand-roll a shallower read: a private
- * copy in `python-client.ts` looked only at top-level `error`/`message`, so
- * FastAPI's `{"detail": {...}}` envelope — what every matrx-files 500 uses —
- * degraded to the useless `code: "internal", detail: "HTTP 500"`. That is
- * exactly how an upload failure with a real server-side cause reached the
- * user as `Upload failed (500)` and nothing else. One parser, every transport.
- */
-declare function parseHttpErrorBody(body: Record<string, unknown> | null, status: number): BackendApiError;
-/**
- * Adapt callApi's result-style error into the same canonical error used by
- * direct fetch and streaming consumers.
- *
- * callApi intentionally returns errors instead of throwing them, but its
- * `serverDetail` contains the complete FastAPI body. Sending only
- * `error.message` to a feature discards that body and turns a precise
- * configuration failure into "HTTP 422". This adapter keeps one parser and
- * one human-facing explanation path across both client styles.
- */
-declare function parseCallApiError(error: {
-    message: string;
-    status?: number;
-    serverDetail?: unknown;
-}): BackendApiError;
-/**
- * Parse streaming error event data into a BackendApiError.
- *
- * Handles both new format (`user_message`) and legacy (`user_visible_message`).
- */
-declare function parseStreamError(data: unknown): BackendApiError;
-/**
- * Restore the canonical error shape from a durable backend run row.
- *
- * Provider ledgers often keep an aggregate summary plus a more specific first
- * child failure. Prefer that child so a page refresh does not turn a precise
- * streamed failure back into "1 request failed".
- */
-declare function parsePersistedBackendError(data: unknown, requestId?: string): BackendApiError | null;
-/** True when a message tells the reader nothing about what actually broke. */
-declare function isGenericUserMessage(message: string | null | undefined): boolean;
-interface UpstreamErrorPayload {
-    message: string;
-    code: string | null;
-    userMessage: string | null;
-    requestId: string | null;
-    status: number | null;
-}
-/**
- * Recover an upstream service's structured error that a downstream service
- * stringified into its own message.
- *
- * Real example (scraper wrapping aidream):
- *   `aidream could not resolve GSC credential 7223…: HTTP 409 {"error":"conflict",
- *    "message":"Google connection 7223… has no vault credential — it needs
- *    re-authentication","user_message":"Something went wrong…","request_id":"9002…"}`
- *
- * Without this, the only actionable sentence on the whole hop is invisible.
- */
-declare function unwrapUpstreamError(message: string): UpstreamErrorPayload | null;
-interface BackendFailureExplanation {
-    /** Machine code from the deepest layer that classified the failure. */
-    code: string;
-    /** The most specific human-readable cause available — never a template. */
-    cause: string;
-    /** What to headline in the UI: the cause when the server was generic. */
-    headline: string;
-    /** True when every user-facing message the server sent was a template. */
-    headlineWasGeneric: boolean;
-    /** Message chain, outermost (closest service) first. */
-    chain: string[];
-    /** Deepest request id available, for cross-service log correlation. */
-    requestId: string;
-    status: number | null;
-}
-/**
- * THE anti-secrecy primitive: turn any thrown backend/stream failure into the
- * most specific explanation the payload can support — unwrapping every nested
- * upstream error and refusing to let a templated `user_message` be the answer.
- *
- * Every surface that reports a backend failure to a human should headline
- * `explanation.headline` and always keep `cause` + `requestId` reachable.
- */
-declare function describeBackendFailure(error: unknown): BackendFailureExplanation;
-/**
- * Extract a user-visible message from any error object.
- * Utility for components that just need the display string.
- */
-declare function getUserMessage(error: unknown): string;
-
 /**
  * `@ai-matrx/agents/matrx` — every AI Matrx server endpoint path, by feature
  * area (matching the server's router structure). Paths only, rooted at the
@@ -1664,4 +1829,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, FollowRuntimeOperationToEndOptions, type FollowUnavailableRejoinOptions, MATRX_AI_API_VERSION_DEFAULT, MATRX_LIVE_STREAM_UNAVAILABLE, MATRX_RESUME_CONFLICT, MATRX_RUN_IN_PROGRESS, type MatrxAiApiVersion, MatrxApiError, type MatrxCallError, type MatrxClientSessionProvider, type MatrxClientToolResult, type MatrxFollowedOutcome, type MatrxHttpErrorLike, MatrxJsonObject, MatrxJsonValue, type MatrxLiveRunRejoin, type MatrxLiveStreamUnavailable, type MatrxPendingCallSummary, type MatrxProtocolDowngrade, type MatrxProtocolFallbackOptions, type MatrxRequestInfo, MatrxRunHandle, type MatrxRunPickup, type MatrxRunPickupSettlement, MatrxRuntimeExecutionStatus, MatrxRuntimeOperationEvent, MatrxStreamCallOptions, type MatrxToolResultsResponse, MatrxTransport, type MatrxTransportDiagnostics, type MatrxTransportTarget, OrganizationContextError, type OrganizationContextErrorCode, type OrganizationOperation, 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, createMatrxTransport, createOrganizationOperation, describeBackendFailure, fetchWithMatrxProtocolFallback, followUnavailableRejoin, followWorkflowRunEvents, getUserMessage, isCoveredAiPath, isGenericUserMessage, isJobOutputKind, isLiveStreamUnavailable, isResumeConflict, isStreamTransportLost, isV2Path, listConversationPendingToolCalls, listUserPendingToolCalls, logApiTarget, normalizeMatrxError, openMatrxStream, parseCallApiError, parseHttpError, parseHttpErrorBody, parsePersistedBackendError, parseStreamError, providerSessionFailureBody, readConversationOrganizationId, readLiveRunRejoin, readLiveRunRequestId, readLiveStreamUnavailable, readMatrxErrorCode, readMatrxErrorCodeFromMessage, reportProviderSessionFailure, requireOrganizationContext, resolveEndpointPath, resolveRunWaitWith, resumeOrRejoin, runJobLabel, runOutputKindFromModalities, runWaitKnobKey, runWaitTimeoutMessage, runtimeOperationRejoinPath, settleRunPickup, 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 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 };