@ai-matrx/agents 0.21.45 → 0.23.0

package/dist/matrx/index.d.cts

@@ -1,8 +1,8 @@
-import { B as MatrxTransport, m as MatrxJsonValue, l as MatrxJsonObject } from '../operations--f5ko9Su.cjs';
-export { F as FollowRuntimeOperationOptions, a as FollowRuntimeOperationToEndOptions, b as FollowRuntimeOperationToEndResult, M as MatrxAgentStartRequest, c as MatrxApiError, d as MatrxCancelResponse, e as MatrxChatMessage, f as MatrxCompletedRun, g as MatrxContextAnchor, h as MatrxConversationContinueRequest, i as MatrxConversationResumeRequest, j as MatrxConversationStart, k as MatrxEphemeralConversation, n as MatrxMandateStartRequest, o as MatrxOperationEventsPage, p as MatrxOperationFollowEvent, q as MatrxOperationStatusResponse, r as MatrxOperationsByLinkResponse, s as MatrxRequestScope, t as MatrxRunError, u as MatrxRunHandle, v as MatrxRuntimeExecutionStatus, w as MatrxRuntimeOperationEvent, x as MatrxRuntimeOperationView, y as MatrxStoredConversationContinue, z as MatrxStoredConversationCreate, A as MatrxStreamCallOptions, C as MatrxTransportRequest, D as MatrxTurnFields, R as RunAgentToCompletionOptions, T as TERMINAL_MATRX_RUNTIME_STATUSES, E as cancelAgentRun, G as continueAgentConversation, H as continueEphemeralConversationStart, I as continueStoredConversationStart, J as extractMatrxErrorCode, K as extractMatrxErrorMessage, L as followRuntimeOperationEvents, N as followRuntimeOperationToEnd, O as getRuntimeOperationStatus, P as getRuntimeOperationsByLink, Q as listRuntimeOperationEvents, S as mintMatrxConversationId, U as newEphemeralConversationStart, V as newStoredConversationStart, W as rejoinRuntimeOperation, X as resumeAgentConversation, Y as runAgentToCompletion, Z as startAgentRun, _ as startMandateRun } from '../operations--f5ko9Su.cjs';
+import { B as MatrxTransport, A as MatrxStreamCallOptions, w as MatrxRuntimeOperationEvent, a as FollowRuntimeOperationToEndOptions, v as MatrxRuntimeExecutionStatus, c as MatrxApiError, u as MatrxRunHandle, m as MatrxJsonValue, l as MatrxJsonObject } from '../operations--f5ko9Su.cjs';
+export { F as FollowRuntimeOperationOptions, b as FollowRuntimeOperationToEndResult, M as MatrxAgentStartRequest, d as MatrxCancelResponse, e as MatrxChatMessage, f as MatrxCompletedRun, g as MatrxContextAnchor, h as MatrxConversationContinueRequest, i as MatrxConversationResumeRequest, j as MatrxConversationStart, k as MatrxEphemeralConversation, n as MatrxMandateStartRequest, o as MatrxOperationEventsPage, p as MatrxOperationFollowEvent, q as MatrxOperationStatusResponse, r as MatrxOperationsByLinkResponse, s as MatrxRequestScope, t as MatrxRunError, x as MatrxRuntimeOperationView, y as MatrxStoredConversationContinue, z as MatrxStoredConversationCreate, C as MatrxTransportRequest, D as MatrxTurnFields, R as RunAgentToCompletionOptions, T as TERMINAL_MATRX_RUNTIME_STATUSES, E as cancelAgentRun, G as continueAgentConversation, H as continueEphemeralConversationStart, I as continueStoredConversationStart, J as extractMatrxErrorCode, K as extractMatrxErrorMessage, L as followRuntimeOperationEvents, N as followRuntimeOperationToEnd, O as getRuntimeOperationStatus, P as getRuntimeOperationsByLink, Q as listRuntimeOperationEvents, S as mintMatrxConversationId, U as newEphemeralConversationStart, V as newStoredConversationStart, W as rejoinRuntimeOperation, X as resumeAgentConversation, Y as runAgentToCompletion, Z as startAgentRun, _ as startMandateRun } from '../operations--f5ko9Su.cjs';
 import { CredentialsPort } from '@ai-matrx/data';
 import { ResilientFetchOptions } from '@ai-matrx/data/net';
-import '../stream/ndjson.cjs';
+import { MatrxStreamEnvelope } from '../stream/ndjson.cjs';
 import '../stream/sse.cjs';
 
 /**
@@ -307,6 +307,187 @@ declare function applyOrganizationContextHeader(headers: Record<string, string>,
  */
 declare function assertQueryOrganizationMatchesContext(queryParams: Record<string, string | number | boolean> | undefined, organizationId: string): void;
 
+/**
+ * Resume-or-rejoin — the ONE client behavior for "pick a run back up".
+ *
+ * Server truth (verified against aidream source):
+ * - A resume door asked to resume a run that is STILL RUNNING answers
+ *   `409` with `code: "run_in_progress"` and `live_request_id`
+ *   (`aidream/api/routers/podcast_generator.py` `resume_podcast_endpoint`;
+ *   other doors adopt the same contract). The platform error envelope
+ *   (`aidream/api/errors.py`) hoists the detail's non-reserved keys to the top
+ *   level and RESERVES `request_id` for the API call's own id — so the live
+ *   run's id is read from `live_request_id`, never `request_id` (reading
+ *   `request_id` rejoined a request that did not exist: 404, 2026-10-01).
+ * - The client then follows `POST /runtime/operations/{live_request_id}/rejoin`
+ *   (NDJSON replay-then-follow). That answers `409 live_stream_unavailable`
+ *   when the live journal is gone — the durable lifecycle stream
+ *   (`followRuntimeOperationToEnd`) is the fallback.
+ * - Conversations answer `409 resume_conflict` (retryable: the suspending run
+ *   has not persisted yet, or a duplicate lost the claim). Retrying is host
+ *   policy — this module reports it as an outcome, never retries itself.
+ *
+ * Resume and rejoin are work on an EXISTING run, so they carry THAT run's
+ * organization (`organizationId`), never whatever the session has selected.
+ */
+
+declare const MATRX_RUN_IN_PROGRESS = "run_in_progress";
+declare const MATRX_RESUME_CONFLICT = "resume_conflict";
+declare const MATRX_LIVE_STREAM_UNAVAILABLE = "live_stream_unavailable";
+/**
+ * Any error carrying an HTTP status and the parsed server body —
+ * `MatrxApiError`, matrx-frontend's `ApiCallError`, or a host's own shape.
+ */
+interface MatrxHttpErrorLike {
+    status?: unknown;
+    serverDetail?: unknown;
+}
+/**
+ * The machine code of a Matrx HTTP error: `code` (or the envelope's hoisted
+ * `error`) from `detail`, `details`, or the top level. Null when absent.
+ */
+declare function readMatrxErrorCode(error: unknown): string | null;
+/**
+ * The request id of a run that is STILL RUNNING, read from a resume door's
+ * `409 run_in_progress` refusal. Null for every other error, so a genuine
+ * failure is never mistaken for a live run. Reads `live_request_id` only —
+ * the envelope's `request_id` is the refusing API call's own id.
+ */
+declare function readLiveRunRequestId(error: unknown): string | null;
+/** `409 resume_conflict` — another resume holds the run claim; retry is host policy. */
+declare function isResumeConflict(error: unknown): boolean;
+/** `409 live_stream_unavailable` — the rejoin journal is gone; follow the durable lifecycle instead. */
+declare function isLiveStreamUnavailable(error: unknown): boolean;
+/**
+ * The server-relative rejoin path — for hosts whose stream pipeline takes a
+ * URL instead of a transport (prepend the resolved base URL).
+ */
+declare function runtimeOperationRejoinPath(requestId: string): string;
+/**
+ * The text to show for a stream `error` event: the server's `user_message`
+ * first (it is written for the person — e.g. "OpenAI refused this request:
+ * the platform's OpenAI account is out of credit."), then `message`. Accepts
+ * the `{event, data}` envelope or its `data` payload. Null when neither is
+ * present — the host supplies its own fallback; it must never REPLACE a
+ * message the server sent.
+ */
+declare function streamErrorText(eventOrPayload: unknown): string | null;
+/**
+ * Open any Matrx NDJSON stream by path (`POST`, optional JSON body) — for
+ * feature doors outside the agent lifecycle (`/podcast/resume/{run_id}`, …)
+ * so their streams ride the same transport and wire kernel as every run.
+ */
+declare function openMatrxStream(transport: MatrxTransport, path: string, options?: MatrxStreamCallOptions & {
+    body?: unknown;
+}): Promise<MatrxRunHandle>;
+/**
+ * Bind a run's organization onto every call as `X-Organization-Id`. Host
+ * policy headers still merge on top; the package's own `createMatrxTransport`
+ * refuses a disagreeing org (`organization_context_mismatch`) rather than
+ * silently swapping it, so a host must not force the SESSION org onto a
+ * resume/rejoin transport.
+ */
+declare function withRunOrganization(transport: MatrxTransport, organizationId: string): MatrxTransport;
+type ResumeOrRejoinOutcome = 
+/** The resume door ran the run; its stream was delivered to `onEnvelope`. */
+{
+    kind: "resumed";
+    requestId: string | null;
+}
+/** The run was still live; its original stream was replayed + followed into `onEnvelope`. */
+ | {
+    kind: "rejoined";
+    liveRequestId: string;
+}
+/**
+ * The run was still live but its stream could not be replayed; the durable
+ * lifecycle was followed instead. Re-query the feature's record for the
+ * result. `ended: false` = the follow gave up (or no operation was found).
+ */
+ | {
+    kind: "followed";
+    liveRequestId: string;
+    executionId: string | null;
+    ended: boolean;
+    status: MatrxRuntimeExecutionStatus | null;
+}
+/** `409 resume_conflict` — retry with the host's backoff policy. */
+ | {
+    kind: "resume_conflict";
+    error: MatrxApiError;
+};
+interface ResumeOrRejoinOptions extends Omit<MatrxStreamCallOptions, "signal"> {
+    /** Every NDJSON envelope — from the resume stream OR the rejoined stream. */
+    onEnvelope: (envelope: MatrxStreamEnvelope) => void;
+    /** THE RUN'S organization (from its durable record) — bound on every call. */
+    organizationId?: string | null;
+    signal?: AbortSignal;
+    /** Fired the moment a live run is detected, before the rejoin opens. */
+    onRejoin?: (liveRequestId: string) => void;
+    /** Durable lifecycle events while following (the no-replay fallback). */
+    onOperationEvent?: (event: MatrxRuntimeOperationEvent) => void;
+    /** Tuning for the fallback follow (stall / reconnect policy). */
+    follow?: Omit<FollowRuntimeOperationToEndOptions, "onEvent" | "signal" | "lastEventSeq">;
+}
+/**
+ * Resume a run — or, when the server says it is still running, REJOIN it.
+ *
+ * Calls `resumeCall` (the feature's resume door) and pipes its stream into
+ * `onEnvelope`. On `409 run_in_progress` it follows
+ * `POST /runtime/operations/{live_request_id}/rejoin` into the SAME handler
+ * under the same organization; when replay is unavailable it follows the
+ * durable lifecycle to its end. Never runs a live run a second time.
+ * `resume_conflict` comes back as an outcome; any other error is thrown.
+ */
+declare function resumeOrRejoin(transport: MatrxTransport, resumeCall: (transport: MatrxTransport, options: MatrxStreamCallOptions) => Promise<MatrxRunHandle>, options: ResumeOrRejoinOptions): Promise<ResumeOrRejoinOutcome>;
+
+/**
+ * Browser-held provider sessions report their failures through the server.
+ *
+ * Realtime voice (OpenAI / xAI) and Cartesia TTS run browser → provider
+ * directly on an ephemeral token from the token broker, so a provider refusal
+ * (e.g. the platform's account is out of credit) never touches the server —
+ * the operator would never hear of it, and the person would see raw provider
+ * text. Every client calls `reportProviderSessionFailure` from the session's
+ * error handler and shows the returned `user_message`.
+ *
+ * Server truth: `POST /broker/provider-failures`
+ * (`aidream/api/routers/token_broker.py`; body `ProviderSessionFailureReport`
+ * in `aidream/services/token_broker/models.py` — `extra="forbid"`, allow-listed
+ * providers, bounded text; identity and organization come from the session).
+ */
+
+/** The providers whose sessions a browser holds directly (server allow-list). */
+type MatrxClientSessionProvider = "openai" | "xai" | "cartesia";
+interface ProviderSessionFailure {
+    provider: MatrxClientSessionProvider;
+    model?: string | null;
+    /** HTTP status the provider answered, when the failure was an HTTP answer. */
+    status_code?: number | null;
+    /** The provider's own error type/code (`insufficient_quota`, …). */
+    error_type?: string | null;
+    /** The provider's text, verbatim — classified server-side, never shown. */
+    message: string;
+}
+/** `ProviderSessionFailureVerdict` — what to show, and whether reconnecting can help. */
+interface ProviderSessionFailureVerdict {
+    error_type: string;
+    retryable: boolean;
+    /** The sentence to show the person (never the provider's raw text). */
+    user_message: string;
+}
+/** The body the server accepts — bounded exactly as its model bounds it. */
+declare function providerSessionFailureBody(failure: ProviderSessionFailure): Record<string, string | number>;
+/**
+ * Report a browser-held provider session failure and get the sentence to
+ * show. Resolves null (and warns) when the report itself could not be made —
+ * the caller then shows its own fallback; it never throws from an error
+ * handler.
+ */
+declare function reportProviderSessionFailure(transport: MatrxTransport, failure: ProviderSessionFailure, options?: {
+    signal?: AbortSignal;
+}): Promise<ProviderSessionFailureVerdict | null>;
+
 /**
  * Delegated client tools — submit results and discover pending calls.
  *
@@ -399,4 +580,4 @@ declare function listUserPendingToolCalls(transport: MatrxTransport, options?: {
     signal?: AbortSignal;
 }): Promise<MatrxPendingCallSummary[]>;
 
-export { type CreateMatrxTransportOptions, MATRX_AI_API_VERSION_DEFAULT, type MatrxAiApiVersion, type MatrxCallError, type MatrxClientToolResult, MatrxJsonObject, MatrxJsonValue, type MatrxPendingCallSummary, type MatrxProtocolDowngrade, type MatrxProtocolFallbackOptions, type MatrxRequestInfo, type MatrxToolResultsResponse, MatrxTransport, type MatrxTransportDiagnostics, type MatrxTransportTarget, OrganizationContextError, type OrganizationContextErrorCode, type OrganizationOperation, V2_COVERED_AI_PATH_TEMPLATES, applyAiApiVersion, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, createMatrxTransport, createOrganizationOperation, fetchWithMatrxProtocolFallback, isCoveredAiPath, isV2Path, listConversationPendingToolCalls, listUserPendingToolCalls, normalizeMatrxError, requireOrganizationContext, submitAgentToolResults, toV1FallbackUrl, toV2Path };
+export { type CreateMatrxTransportOptions, FollowRuntimeOperationToEndOptions, 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 MatrxHttpErrorLike, MatrxJsonObject, MatrxJsonValue, type MatrxPendingCallSummary, type MatrxProtocolDowngrade, type MatrxProtocolFallbackOptions, type MatrxRequestInfo, MatrxRunHandle, MatrxRuntimeExecutionStatus, MatrxRuntimeOperationEvent, MatrxStreamCallOptions, type MatrxToolResultsResponse, MatrxTransport, type MatrxTransportDiagnostics, type MatrxTransportTarget, OrganizationContextError, type OrganizationContextErrorCode, type OrganizationOperation, type ProviderSessionFailure, type ProviderSessionFailureVerdict, type ResumeOrRejoinOptions, type ResumeOrRejoinOutcome, V2_COVERED_AI_PATH_TEMPLATES, applyAiApiVersion, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, createMatrxTransport, createOrganizationOperation, fetchWithMatrxProtocolFallback, isCoveredAiPath, isLiveStreamUnavailable, isResumeConflict, isV2Path, listConversationPendingToolCalls, listUserPendingToolCalls, normalizeMatrxError, openMatrxStream, providerSessionFailureBody, readLiveRunRequestId, readMatrxErrorCode, reportProviderSessionFailure, requireOrganizationContext, resumeOrRejoin, runtimeOperationRejoinPath, streamErrorText, submitAgentToolResults, toV1FallbackUrl, toV2Path, withRunOrganization };

package/dist/matrx/index.d.ts

@@ -1,8 +1,8 @@
-import { B as MatrxTransport, m as MatrxJsonValue, l as MatrxJsonObject } from '../operations-Dp4ut-ac.js';
-export { F as FollowRuntimeOperationOptions, a as FollowRuntimeOperationToEndOptions, b as FollowRuntimeOperationToEndResult, M as MatrxAgentStartRequest, c as MatrxApiError, d as MatrxCancelResponse, e as MatrxChatMessage, f as MatrxCompletedRun, g as MatrxContextAnchor, h as MatrxConversationContinueRequest, i as MatrxConversationResumeRequest, j as MatrxConversationStart, k as MatrxEphemeralConversation, n as MatrxMandateStartRequest, o as MatrxOperationEventsPage, p as MatrxOperationFollowEvent, q as MatrxOperationStatusResponse, r as MatrxOperationsByLinkResponse, s as MatrxRequestScope, t as MatrxRunError, u as MatrxRunHandle, v as MatrxRuntimeExecutionStatus, w as MatrxRuntimeOperationEvent, x as MatrxRuntimeOperationView, y as MatrxStoredConversationContinue, z as MatrxStoredConversationCreate, A as MatrxStreamCallOptions, C as MatrxTransportRequest, D as MatrxTurnFields, R as RunAgentToCompletionOptions, T as TERMINAL_MATRX_RUNTIME_STATUSES, E as cancelAgentRun, G as continueAgentConversation, H as continueEphemeralConversationStart, I as continueStoredConversationStart, J as extractMatrxErrorCode, K as extractMatrxErrorMessage, L as followRuntimeOperationEvents, N as followRuntimeOperationToEnd, O as getRuntimeOperationStatus, P as getRuntimeOperationsByLink, Q as listRuntimeOperationEvents, S as mintMatrxConversationId, U as newEphemeralConversationStart, V as newStoredConversationStart, W as rejoinRuntimeOperation, X as resumeAgentConversation, Y as runAgentToCompletion, Z as startAgentRun, _ as startMandateRun } from '../operations-Dp4ut-ac.js';
+import { B as MatrxTransport, A as MatrxStreamCallOptions, w as MatrxRuntimeOperationEvent, a as FollowRuntimeOperationToEndOptions, v as MatrxRuntimeExecutionStatus, c as MatrxApiError, u as MatrxRunHandle, m as MatrxJsonValue, l as MatrxJsonObject } from '../operations-Dp4ut-ac.js';
+export { F as FollowRuntimeOperationOptions, b as FollowRuntimeOperationToEndResult, M as MatrxAgentStartRequest, d as MatrxCancelResponse, e as MatrxChatMessage, f as MatrxCompletedRun, g as MatrxContextAnchor, h as MatrxConversationContinueRequest, i as MatrxConversationResumeRequest, j as MatrxConversationStart, k as MatrxEphemeralConversation, n as MatrxMandateStartRequest, o as MatrxOperationEventsPage, p as MatrxOperationFollowEvent, q as MatrxOperationStatusResponse, r as MatrxOperationsByLinkResponse, s as MatrxRequestScope, t as MatrxRunError, x as MatrxRuntimeOperationView, y as MatrxStoredConversationContinue, z as MatrxStoredConversationCreate, C as MatrxTransportRequest, D as MatrxTurnFields, R as RunAgentToCompletionOptions, T as TERMINAL_MATRX_RUNTIME_STATUSES, E as cancelAgentRun, G as continueAgentConversation, H as continueEphemeralConversationStart, I as continueStoredConversationStart, J as extractMatrxErrorCode, K as extractMatrxErrorMessage, L as followRuntimeOperationEvents, N as followRuntimeOperationToEnd, O as getRuntimeOperationStatus, P as getRuntimeOperationsByLink, Q as listRuntimeOperationEvents, S as mintMatrxConversationId, U as newEphemeralConversationStart, V as newStoredConversationStart, W as rejoinRuntimeOperation, X as resumeAgentConversation, Y as runAgentToCompletion, Z as startAgentRun, _ as startMandateRun } from '../operations-Dp4ut-ac.js';
 import { CredentialsPort } from '@ai-matrx/data';
 import { ResilientFetchOptions } from '@ai-matrx/data/net';
-import '../stream/ndjson.js';
+import { MatrxStreamEnvelope } from '../stream/ndjson.js';
 import '../stream/sse.js';
 
 /**
@@ -307,6 +307,187 @@ declare function applyOrganizationContextHeader(headers: Record<string, string>,
  */
 declare function assertQueryOrganizationMatchesContext(queryParams: Record<string, string | number | boolean> | undefined, organizationId: string): void;
 
+/**
+ * Resume-or-rejoin — the ONE client behavior for "pick a run back up".
+ *
+ * Server truth (verified against aidream source):
+ * - A resume door asked to resume a run that is STILL RUNNING answers
+ *   `409` with `code: "run_in_progress"` and `live_request_id`
+ *   (`aidream/api/routers/podcast_generator.py` `resume_podcast_endpoint`;
+ *   other doors adopt the same contract). The platform error envelope
+ *   (`aidream/api/errors.py`) hoists the detail's non-reserved keys to the top
+ *   level and RESERVES `request_id` for the API call's own id — so the live
+ *   run's id is read from `live_request_id`, never `request_id` (reading
+ *   `request_id` rejoined a request that did not exist: 404, 2026-10-01).
+ * - The client then follows `POST /runtime/operations/{live_request_id}/rejoin`
+ *   (NDJSON replay-then-follow). That answers `409 live_stream_unavailable`
+ *   when the live journal is gone — the durable lifecycle stream
+ *   (`followRuntimeOperationToEnd`) is the fallback.
+ * - Conversations answer `409 resume_conflict` (retryable: the suspending run
+ *   has not persisted yet, or a duplicate lost the claim). Retrying is host
+ *   policy — this module reports it as an outcome, never retries itself.
+ *
+ * Resume and rejoin are work on an EXISTING run, so they carry THAT run's
+ * organization (`organizationId`), never whatever the session has selected.
+ */
+
+declare const MATRX_RUN_IN_PROGRESS = "run_in_progress";
+declare const MATRX_RESUME_CONFLICT = "resume_conflict";
+declare const MATRX_LIVE_STREAM_UNAVAILABLE = "live_stream_unavailable";
+/**
+ * Any error carrying an HTTP status and the parsed server body —
+ * `MatrxApiError`, matrx-frontend's `ApiCallError`, or a host's own shape.
+ */
+interface MatrxHttpErrorLike {
+    status?: unknown;
+    serverDetail?: unknown;
+}
+/**
+ * The machine code of a Matrx HTTP error: `code` (or the envelope's hoisted
+ * `error`) from `detail`, `details`, or the top level. Null when absent.
+ */
+declare function readMatrxErrorCode(error: unknown): string | null;
+/**
+ * The request id of a run that is STILL RUNNING, read from a resume door's
+ * `409 run_in_progress` refusal. Null for every other error, so a genuine
+ * failure is never mistaken for a live run. Reads `live_request_id` only —
+ * the envelope's `request_id` is the refusing API call's own id.
+ */
+declare function readLiveRunRequestId(error: unknown): string | null;
+/** `409 resume_conflict` — another resume holds the run claim; retry is host policy. */
+declare function isResumeConflict(error: unknown): boolean;
+/** `409 live_stream_unavailable` — the rejoin journal is gone; follow the durable lifecycle instead. */
+declare function isLiveStreamUnavailable(error: unknown): boolean;
+/**
+ * The server-relative rejoin path — for hosts whose stream pipeline takes a
+ * URL instead of a transport (prepend the resolved base URL).
+ */
+declare function runtimeOperationRejoinPath(requestId: string): string;
+/**
+ * The text to show for a stream `error` event: the server's `user_message`
+ * first (it is written for the person — e.g. "OpenAI refused this request:
+ * the platform's OpenAI account is out of credit."), then `message`. Accepts
+ * the `{event, data}` envelope or its `data` payload. Null when neither is
+ * present — the host supplies its own fallback; it must never REPLACE a
+ * message the server sent.
+ */
+declare function streamErrorText(eventOrPayload: unknown): string | null;
+/**
+ * Open any Matrx NDJSON stream by path (`POST`, optional JSON body) — for
+ * feature doors outside the agent lifecycle (`/podcast/resume/{run_id}`, …)
+ * so their streams ride the same transport and wire kernel as every run.
+ */
+declare function openMatrxStream(transport: MatrxTransport, path: string, options?: MatrxStreamCallOptions & {
+    body?: unknown;
+}): Promise<MatrxRunHandle>;
+/**
+ * Bind a run's organization onto every call as `X-Organization-Id`. Host
+ * policy headers still merge on top; the package's own `createMatrxTransport`
+ * refuses a disagreeing org (`organization_context_mismatch`) rather than
+ * silently swapping it, so a host must not force the SESSION org onto a
+ * resume/rejoin transport.
+ */
+declare function withRunOrganization(transport: MatrxTransport, organizationId: string): MatrxTransport;
+type ResumeOrRejoinOutcome = 
+/** The resume door ran the run; its stream was delivered to `onEnvelope`. */
+{
+    kind: "resumed";
+    requestId: string | null;
+}
+/** The run was still live; its original stream was replayed + followed into `onEnvelope`. */
+ | {
+    kind: "rejoined";
+    liveRequestId: string;
+}
+/**
+ * The run was still live but its stream could not be replayed; the durable
+ * lifecycle was followed instead. Re-query the feature's record for the
+ * result. `ended: false` = the follow gave up (or no operation was found).
+ */
+ | {
+    kind: "followed";
+    liveRequestId: string;
+    executionId: string | null;
+    ended: boolean;
+    status: MatrxRuntimeExecutionStatus | null;
+}
+/** `409 resume_conflict` — retry with the host's backoff policy. */
+ | {
+    kind: "resume_conflict";
+    error: MatrxApiError;
+};
+interface ResumeOrRejoinOptions extends Omit<MatrxStreamCallOptions, "signal"> {
+    /** Every NDJSON envelope — from the resume stream OR the rejoined stream. */
+    onEnvelope: (envelope: MatrxStreamEnvelope) => void;
+    /** THE RUN'S organization (from its durable record) — bound on every call. */
+    organizationId?: string | null;
+    signal?: AbortSignal;
+    /** Fired the moment a live run is detected, before the rejoin opens. */
+    onRejoin?: (liveRequestId: string) => void;
+    /** Durable lifecycle events while following (the no-replay fallback). */
+    onOperationEvent?: (event: MatrxRuntimeOperationEvent) => void;
+    /** Tuning for the fallback follow (stall / reconnect policy). */
+    follow?: Omit<FollowRuntimeOperationToEndOptions, "onEvent" | "signal" | "lastEventSeq">;
+}
+/**
+ * Resume a run — or, when the server says it is still running, REJOIN it.
+ *
+ * Calls `resumeCall` (the feature's resume door) and pipes its stream into
+ * `onEnvelope`. On `409 run_in_progress` it follows
+ * `POST /runtime/operations/{live_request_id}/rejoin` into the SAME handler
+ * under the same organization; when replay is unavailable it follows the
+ * durable lifecycle to its end. Never runs a live run a second time.
+ * `resume_conflict` comes back as an outcome; any other error is thrown.
+ */
+declare function resumeOrRejoin(transport: MatrxTransport, resumeCall: (transport: MatrxTransport, options: MatrxStreamCallOptions) => Promise<MatrxRunHandle>, options: ResumeOrRejoinOptions): Promise<ResumeOrRejoinOutcome>;
+
+/**
+ * Browser-held provider sessions report their failures through the server.
+ *
+ * Realtime voice (OpenAI / xAI) and Cartesia TTS run browser → provider
+ * directly on an ephemeral token from the token broker, so a provider refusal
+ * (e.g. the platform's account is out of credit) never touches the server —
+ * the operator would never hear of it, and the person would see raw provider
+ * text. Every client calls `reportProviderSessionFailure` from the session's
+ * error handler and shows the returned `user_message`.
+ *
+ * Server truth: `POST /broker/provider-failures`
+ * (`aidream/api/routers/token_broker.py`; body `ProviderSessionFailureReport`
+ * in `aidream/services/token_broker/models.py` — `extra="forbid"`, allow-listed
+ * providers, bounded text; identity and organization come from the session).
+ */
+
+/** The providers whose sessions a browser holds directly (server allow-list). */
+type MatrxClientSessionProvider = "openai" | "xai" | "cartesia";
+interface ProviderSessionFailure {
+    provider: MatrxClientSessionProvider;
+    model?: string | null;
+    /** HTTP status the provider answered, when the failure was an HTTP answer. */
+    status_code?: number | null;
+    /** The provider's own error type/code (`insufficient_quota`, …). */
+    error_type?: string | null;
+    /** The provider's text, verbatim — classified server-side, never shown. */
+    message: string;
+}
+/** `ProviderSessionFailureVerdict` — what to show, and whether reconnecting can help. */
+interface ProviderSessionFailureVerdict {
+    error_type: string;
+    retryable: boolean;
+    /** The sentence to show the person (never the provider's raw text). */
+    user_message: string;
+}
+/** The body the server accepts — bounded exactly as its model bounds it. */
+declare function providerSessionFailureBody(failure: ProviderSessionFailure): Record<string, string | number>;
+/**
+ * Report a browser-held provider session failure and get the sentence to
+ * show. Resolves null (and warns) when the report itself could not be made —
+ * the caller then shows its own fallback; it never throws from an error
+ * handler.
+ */
+declare function reportProviderSessionFailure(transport: MatrxTransport, failure: ProviderSessionFailure, options?: {
+    signal?: AbortSignal;
+}): Promise<ProviderSessionFailureVerdict | null>;
+
 /**
  * Delegated client tools — submit results and discover pending calls.
  *
@@ -399,4 +580,4 @@ declare function listUserPendingToolCalls(transport: MatrxTransport, options?: {
     signal?: AbortSignal;
 }): Promise<MatrxPendingCallSummary[]>;
 
-export { type CreateMatrxTransportOptions, MATRX_AI_API_VERSION_DEFAULT, type MatrxAiApiVersion, type MatrxCallError, type MatrxClientToolResult, MatrxJsonObject, MatrxJsonValue, type MatrxPendingCallSummary, type MatrxProtocolDowngrade, type MatrxProtocolFallbackOptions, type MatrxRequestInfo, type MatrxToolResultsResponse, MatrxTransport, type MatrxTransportDiagnostics, type MatrxTransportTarget, OrganizationContextError, type OrganizationContextErrorCode, type OrganizationOperation, V2_COVERED_AI_PATH_TEMPLATES, applyAiApiVersion, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, createMatrxTransport, createOrganizationOperation, fetchWithMatrxProtocolFallback, isCoveredAiPath, isV2Path, listConversationPendingToolCalls, listUserPendingToolCalls, normalizeMatrxError, requireOrganizationContext, submitAgentToolResults, toV1FallbackUrl, toV2Path };
+export { type CreateMatrxTransportOptions, FollowRuntimeOperationToEndOptions, 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 MatrxHttpErrorLike, MatrxJsonObject, MatrxJsonValue, type MatrxPendingCallSummary, type MatrxProtocolDowngrade, type MatrxProtocolFallbackOptions, type MatrxRequestInfo, MatrxRunHandle, MatrxRuntimeExecutionStatus, MatrxRuntimeOperationEvent, MatrxStreamCallOptions, type MatrxToolResultsResponse, MatrxTransport, type MatrxTransportDiagnostics, type MatrxTransportTarget, OrganizationContextError, type OrganizationContextErrorCode, type OrganizationOperation, type ProviderSessionFailure, type ProviderSessionFailureVerdict, type ResumeOrRejoinOptions, type ResumeOrRejoinOutcome, V2_COVERED_AI_PATH_TEMPLATES, applyAiApiVersion, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, createMatrxTransport, createOrganizationOperation, fetchWithMatrxProtocolFallback, isCoveredAiPath, isLiveStreamUnavailable, isResumeConflict, isV2Path, listConversationPendingToolCalls, listUserPendingToolCalls, normalizeMatrxError, openMatrxStream, providerSessionFailureBody, readLiveRunRequestId, readMatrxErrorCode, reportProviderSessionFailure, requireOrganizationContext, resumeOrRejoin, runtimeOperationRejoinPath, streamErrorText, submitAgentToolResults, toV1FallbackUrl, toV2Path, withRunOrganization };