@ai-matrx/agents 0.22.0 → 0.24.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,244 @@ 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 (aidream `services/runtime/FEATURE.md` § "A live run is
+ * REJOINED, never resumed beside itself"; `reconnect.run_in_progress_error`):
+ * - Every resume / retry / continue door asked to resume a run that is STILL
+ *   LIVE answers `409` with, at the ROOT of the error body,
+ *   `{error, code: "run_in_progress", live_request_id, rejoin_path, message,
+ *   …extras}` (extras: `run_id` for workflow / SEO / comparison, `arm_index` /
+ *   `arm`, `analysis_id`). The client follows `rejoin_path` — never a URL it
+ *   builds — because a door outside the spine (SEO collections) answers
+ *   `live_request_id: null` with its own `/seo/collections/{run_id}/rejoin`.
+ * - Chat/conversation resume keeps `code: "resume_conflict"` for older clients
+ *   but ALSO carries `live_request_id` + `rejoin_path` (+
+ *   `details.live_request_id`) when the run is live — then rejoin, never the
+ *   retry loop. A bare `resume_conflict` (no rejoin target) stays host retry.
+ * - The envelope RESERVES `request_id` for the refusing call's own id — the
+ *   live run is read from `live_request_id`, never `request_id` (reading it
+ *   rejoined a request that did not exist: 404, 2026-10-01).
+ * - A rejoin answers `409 live_stream_unavailable` when there is no journal to
+ *   replay (resumed workflow legs, comparison arms). Then: a body naming a
+ *   workflow `run_id` → follow `GET /runs/{run_id}/events/stream` (the workflow
+ *   SSE, which also carries the node_stream media frames); otherwise follow the
+ *   durable lifecycle (`followRuntimeOperationToEnd`).
+ *
+ * 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;
+/** Where to rejoin a live run, read from a resume door's 409. */
+interface MatrxLiveRunRejoin {
+    /** The live request (`GET /runtime/operations/{id}`); null for doors outside the spine (SEO). */
+    liveRequestId: string | null;
+    /** Server-relative path to `POST` for the NDJSON replay-then-follow. Always from the body when present. */
+    rejoinPath: string;
+    /** `run_id` extra (workflow / SEO / comparison), when present. */
+    runId: string | null;
+    /** The refusal's code: `run_in_progress`, or chat's `resume_conflict` carrying a rejoin target. */
+    code: string;
+    /** The refusal body (root of the envelope), for door-specific extras (`arm_index`, `analysis_id`, …). */
+    body: Record<string, unknown>;
+}
+/**
+ * The rejoin target of a live-run refusal: `409` with `code: run_in_progress`,
+ * or chat's `409 resume_conflict` that names a live run. Null for every other
+ * error (a genuine failure is never mistaken for a live run). Reads
+ * `rejoin_path` from the body first; derives the runtime rejoin from
+ * `live_request_id` only when the body names no path. Never reads
+ * `request_id`.
+ */
+declare function readLiveRunRejoin(error: unknown): MatrxLiveRunRejoin | null;
+/**
+ * The request id of a run that is STILL LIVE, read from a resume door's
+ * refusal (`live_request_id` — never the envelope's own `request_id`). Null
+ * for every other error, and for a live refusal outside the spine (SEO) —
+ * follow `readLiveRunRejoin(error).rejoinPath` instead.
+ */
+declare function readLiveRunRequestId(error: unknown): string | null;
+/**
+ * A bare `409 resume_conflict` — another resume holds the claim and NO live
+ * run is named; retry is host policy. (A `resume_conflict` that names a live
+ * run is a rejoin — `readLiveRunRejoin`.)
+ */
+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;
+/**
+ * Follow a workflow run's SSE (`GET /runs/{run_id}/events/stream`) — the
+ * rejoin fallback for workflow legs with no stream journal. Delivers every
+ * parsed event (durable run events with their seq; ephemeral `node_stream`
+ * frames — including `kind: "media"` — with seq null). One connection, no
+ * reconnect policy: resolves `{ended: true}` on the server's `end` frame,
+ * `{ended: false}` when the wire closes or the caller aborts.
+ */
+declare function followWorkflowRunEvents(transport: MatrxTransport, runId: string, options: {
+    onEvent: (event: Record<string, unknown>, seq: number | null) => void;
+    lastEventId?: number | null;
+    signal?: AbortSignal;
+}): Promise<{
+    ended: boolean;
+}>;
+type ResumeOrRejoinOutcome = 
+/** The resume door ran the run; its stream was delivered to `onEnvelope`. */
+{
+    kind: "resumed";
+    requestId: string | null;
+}
+/** The run was live; its stream (from `rejoin_path`) was replayed + followed into `onEnvelope`. */
+ | {
+    kind: "rejoined";
+    rejoin: MatrxLiveRunRejoin;
+}
+/**
+ * The run was live but had no journal to replay; 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";
+    rejoin: MatrxLiveRunRejoin;
+    executionId: string | null;
+    ended: boolean;
+    status: MatrxRuntimeExecutionStatus | null;
+}
+/** No journal, and the run is a workflow: its run SSE was followed into `onWorkflowEvent`. */
+ | {
+    kind: "followed_workflow";
+    rejoin: MatrxLiveRunRejoin;
+    runId: string;
+    ended: boolean;
+}
+/** A bare `409 resume_conflict` (no live run named) — 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 (reset replay-sensitive state). */
+    onRejoin?: (rejoin: MatrxLiveRunRejoin) => void;
+    /** Durable lifecycle events while following (the no-journal fallback). */
+    onOperationEvent?: (event: MatrxRuntimeOperationEvent) => void;
+    /** Workflow run SSE events (the no-journal fallback for a workflow `run_id`). */
+    onWorkflowEvent?: (event: Record<string, unknown>, seq: number | null) => void;
+    /** Tuning for the durable follow (stall / reconnect policy). */
+    follow?: Omit<FollowRuntimeOperationToEndOptions, "onEvent" | "signal" | "lastEventSeq">;
+}
+/**
+ * Resume a run — or, when the server says it is still live, REJOIN it.
+ *
+ * Calls `resumeCall` (the feature's resume door) and pipes its stream into
+ * `onEnvelope`. On a live-run refusal (`run_in_progress`, or chat's
+ * `resume_conflict` naming a live run) it follows the body's `rejoin_path`
+ * into the SAME handler under the same organization; when the rejoin has no
+ * journal (`live_stream_unavailable`) it follows the workflow run SSE (body
+ * names a workflow `run_id`) or the durable lifecycle. Never runs a live run a
+ * second time. A bare `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 +637,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 MatrxLiveRunRejoin, 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, followWorkflowRunEvents, isCoveredAiPath, isLiveStreamUnavailable, isResumeConflict, isV2Path, listConversationPendingToolCalls, listUserPendingToolCalls, normalizeMatrxError, openMatrxStream, providerSessionFailureBody, readLiveRunRejoin, 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,244 @@ 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 (aidream `services/runtime/FEATURE.md` § "A live run is
+ * REJOINED, never resumed beside itself"; `reconnect.run_in_progress_error`):
+ * - Every resume / retry / continue door asked to resume a run that is STILL
+ *   LIVE answers `409` with, at the ROOT of the error body,
+ *   `{error, code: "run_in_progress", live_request_id, rejoin_path, message,
+ *   …extras}` (extras: `run_id` for workflow / SEO / comparison, `arm_index` /
+ *   `arm`, `analysis_id`). The client follows `rejoin_path` — never a URL it
+ *   builds — because a door outside the spine (SEO collections) answers
+ *   `live_request_id: null` with its own `/seo/collections/{run_id}/rejoin`.
+ * - Chat/conversation resume keeps `code: "resume_conflict"` for older clients
+ *   but ALSO carries `live_request_id` + `rejoin_path` (+
+ *   `details.live_request_id`) when the run is live — then rejoin, never the
+ *   retry loop. A bare `resume_conflict` (no rejoin target) stays host retry.
+ * - The envelope RESERVES `request_id` for the refusing call's own id — the
+ *   live run is read from `live_request_id`, never `request_id` (reading it
+ *   rejoined a request that did not exist: 404, 2026-10-01).
+ * - A rejoin answers `409 live_stream_unavailable` when there is no journal to
+ *   replay (resumed workflow legs, comparison arms). Then: a body naming a
+ *   workflow `run_id` → follow `GET /runs/{run_id}/events/stream` (the workflow
+ *   SSE, which also carries the node_stream media frames); otherwise follow the
+ *   durable lifecycle (`followRuntimeOperationToEnd`).
+ *
+ * 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;
+/** Where to rejoin a live run, read from a resume door's 409. */
+interface MatrxLiveRunRejoin {
+    /** The live request (`GET /runtime/operations/{id}`); null for doors outside the spine (SEO). */
+    liveRequestId: string | null;
+    /** Server-relative path to `POST` for the NDJSON replay-then-follow. Always from the body when present. */
+    rejoinPath: string;
+    /** `run_id` extra (workflow / SEO / comparison), when present. */
+    runId: string | null;
+    /** The refusal's code: `run_in_progress`, or chat's `resume_conflict` carrying a rejoin target. */
+    code: string;
+    /** The refusal body (root of the envelope), for door-specific extras (`arm_index`, `analysis_id`, …). */
+    body: Record<string, unknown>;
+}
+/**
+ * The rejoin target of a live-run refusal: `409` with `code: run_in_progress`,
+ * or chat's `409 resume_conflict` that names a live run. Null for every other
+ * error (a genuine failure is never mistaken for a live run). Reads
+ * `rejoin_path` from the body first; derives the runtime rejoin from
+ * `live_request_id` only when the body names no path. Never reads
+ * `request_id`.
+ */
+declare function readLiveRunRejoin(error: unknown): MatrxLiveRunRejoin | null;
+/**
+ * The request id of a run that is STILL LIVE, read from a resume door's
+ * refusal (`live_request_id` — never the envelope's own `request_id`). Null
+ * for every other error, and for a live refusal outside the spine (SEO) —
+ * follow `readLiveRunRejoin(error).rejoinPath` instead.
+ */
+declare function readLiveRunRequestId(error: unknown): string | null;
+/**
+ * A bare `409 resume_conflict` — another resume holds the claim and NO live
+ * run is named; retry is host policy. (A `resume_conflict` that names a live
+ * run is a rejoin — `readLiveRunRejoin`.)
+ */
+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;
+/**
+ * Follow a workflow run's SSE (`GET /runs/{run_id}/events/stream`) — the
+ * rejoin fallback for workflow legs with no stream journal. Delivers every
+ * parsed event (durable run events with their seq; ephemeral `node_stream`
+ * frames — including `kind: "media"` — with seq null). One connection, no
+ * reconnect policy: resolves `{ended: true}` on the server's `end` frame,
+ * `{ended: false}` when the wire closes or the caller aborts.
+ */
+declare function followWorkflowRunEvents(transport: MatrxTransport, runId: string, options: {
+    onEvent: (event: Record<string, unknown>, seq: number | null) => void;
+    lastEventId?: number | null;
+    signal?: AbortSignal;
+}): Promise<{
+    ended: boolean;
+}>;
+type ResumeOrRejoinOutcome = 
+/** The resume door ran the run; its stream was delivered to `onEnvelope`. */
+{
+    kind: "resumed";
+    requestId: string | null;
+}
+/** The run was live; its stream (from `rejoin_path`) was replayed + followed into `onEnvelope`. */
+ | {
+    kind: "rejoined";
+    rejoin: MatrxLiveRunRejoin;
+}
+/**
+ * The run was live but had no journal to replay; 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";
+    rejoin: MatrxLiveRunRejoin;
+    executionId: string | null;
+    ended: boolean;
+    status: MatrxRuntimeExecutionStatus | null;
+}
+/** No journal, and the run is a workflow: its run SSE was followed into `onWorkflowEvent`. */
+ | {
+    kind: "followed_workflow";
+    rejoin: MatrxLiveRunRejoin;
+    runId: string;
+    ended: boolean;
+}
+/** A bare `409 resume_conflict` (no live run named) — 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 (reset replay-sensitive state). */
+    onRejoin?: (rejoin: MatrxLiveRunRejoin) => void;
+    /** Durable lifecycle events while following (the no-journal fallback). */
+    onOperationEvent?: (event: MatrxRuntimeOperationEvent) => void;
+    /** Workflow run SSE events (the no-journal fallback for a workflow `run_id`). */
+    onWorkflowEvent?: (event: Record<string, unknown>, seq: number | null) => void;
+    /** Tuning for the durable follow (stall / reconnect policy). */
+    follow?: Omit<FollowRuntimeOperationToEndOptions, "onEvent" | "signal" | "lastEventSeq">;
+}
+/**
+ * Resume a run — or, when the server says it is still live, REJOIN it.
+ *
+ * Calls `resumeCall` (the feature's resume door) and pipes its stream into
+ * `onEnvelope`. On a live-run refusal (`run_in_progress`, or chat's
+ * `resume_conflict` naming a live run) it follows the body's `rejoin_path`
+ * into the SAME handler under the same organization; when the rejoin has no
+ * journal (`live_stream_unavailable`) it follows the workflow run SSE (body
+ * names a workflow `run_id`) or the durable lifecycle. Never runs a live run a
+ * second time. A bare `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 +637,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 MatrxLiveRunRejoin, 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, followWorkflowRunEvents, isCoveredAiPath, isLiveStreamUnavailable, isResumeConflict, isV2Path, listConversationPendingToolCalls, listUserPendingToolCalls, normalizeMatrxError, openMatrxStream, providerSessionFailureBody, readLiveRunRejoin, readLiveRunRequestId, readMatrxErrorCode, reportProviderSessionFailure, requireOrganizationContext, resumeOrRejoin, runtimeOperationRejoinPath, streamErrorText, submitAgentToolResults, toV1FallbackUrl, toV2Path, withRunOrganization };