@ai-matrx/agents 0.24.1 → 0.25.0

package/dist/matrx/index.d.cts

@@ -1,4 +1,4 @@
-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';
+import { B as MatrxTransport, w as MatrxRuntimeOperationEvent, a as FollowRuntimeOperationToEndOptions, v as MatrxRuntimeExecutionStatus, c as MatrxApiError, A as MatrxStreamCallOptions, 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';
@@ -319,10 +319,12 @@ declare function assertQueryOrganizationMatchesContext(queryParams: Record<strin
  *   `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.
+ * - Chat/conversation resume answers `code: "resume_conflict"` — even when the
+ *   body ALSO names `live_request_id` + `rejoin_path` — and it is ALWAYS host
+ *   retry, never a rejoin: the claim holder is usually the turn that is still
+ *   SUSPENDING, and rejoining it replays that turn from frame one (duplicate
+ *   text) while the person's continuation never runs. Only
+ *   `code: run_in_progress` rejoins.
  * - 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).
@@ -360,15 +362,16 @@ interface MatrxLiveRunRejoin {
     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. */
+    /** The refusal's code — always `run_in_progress` (chat's `resume_conflict` is retried, never rejoined). */
     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
+ * The rejoin target of a live-run refusal: `409` with `code: run_in_progress`.
+ * Null for every other error — a genuine failure is never mistaken for a live
+ * run, and chat's `resume_conflict` is never a rejoin even when its body names
+ * one (the host retries the resume so the continuation runs). 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`.
@@ -382,9 +385,9 @@ declare function readLiveRunRejoin(error: unknown): MatrxLiveRunRejoin | null;
  */
 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`.)
+ * `409 resume_conflict` — another run holds the conversation's claim (usually
+ * the turn still suspending); retry the resume with the host's backoff so the
+ * continuation runs. Never a rejoin, even when the body names a live run.
  */
 declare function isResumeConflict(error: unknown): boolean;
 /** `409 live_stream_unavailable` — the rejoin journal is gone; follow the durable lifecycle instead. */
@@ -464,7 +467,7 @@ type ResumeOrRejoinOutcome =
     runId: string;
     ended: boolean;
 }
-/** A bare `409 resume_conflict` (no live run named) — retry with the host's backoff policy. */
+/** `409 resume_conflict` (named live run or not) — retry with the host's backoff policy. */
  | {
     kind: "resume_conflict";
     error: MatrxApiError;
@@ -488,15 +491,106 @@ interface ResumeOrRejoinOptions extends Omit<MatrxStreamCallOptions, "signal"> {
  * 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`
+ * `onEnvelope`. On a live-run refusal (`run_in_progress`) 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
+ * second time. Every `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>;
+/** What a `409 live_stream_unavailable` rejoin answer names: a workflow `run_id`, when it has one. */
+interface MatrxLiveStreamUnavailable {
+    runId: string | null;
+}
+/**
+ * Read a rejoin's `409 live_stream_unavailable` (the journal is gone). Null
+ * for every other error. For hosts that open the rejoin stream themselves —
+ * hand the result to `followUnavailableRejoin`.
+ */
+declare function readLiveStreamUnavailable(error: unknown): MatrxLiveStreamUnavailable | null;
+type MatrxFollowedOutcome = Extract<ResumeOrRejoinOutcome, {
+    kind: "followed" | "followed_workflow";
+}>;
+interface FollowUnavailableRejoinOptions {
+    /** THE RUN'S organization; omit when `transport` is already bound to it. */
+    organizationId?: string | null;
+    signal?: AbortSignal;
+    onOperationEvent?: (event: MatrxRuntimeOperationEvent) => void;
+    onWorkflowEvent?: (event: Record<string, unknown>, seq: number | null) => void;
+    follow?: Omit<FollowRuntimeOperationToEndOptions, "onEvent" | "signal" | "lastEventSeq">;
+}
+/**
+ * The no-journal fallback of a rejoin — the SAME branch `resumeOrRejoin`
+ * takes, exported for hosts whose rejoin stream rides their own wire (the
+ * extension's offscreen fetch, the desktop's request loop). A workflow
+ * `run_id` (from the unavailable body, else the refusal) on a runtime rejoin
+ * → follow the workflow run SSE; otherwise read the live operation and
+ * follow it to its end. Settle the result with `settleRunPickup`.
+ */
+declare function followUnavailableRejoin(transport: MatrxTransport, rejoin: MatrxLiveRunRejoin, unavailable: MatrxLiveStreamUnavailable, options?: FollowUnavailableRejoinOptions): Promise<MatrxFollowedOutcome>;
+/**
+ * The parts of a pick-up result `settleRunPickup` reads — every
+ * `ResumeOrRejoinOutcome` is one, and so is a host's own follow result.
+ */
+type MatrxRunPickup = {
+    kind: "resumed" | "rejoined";
+} | {
+    kind: "resume_conflict";
+} | {
+    kind: "followed";
+    executionId: string | null;
+    ended: boolean;
+    status: MatrxRuntimeExecutionStatus | null;
+} | {
+    kind: "followed_workflow";
+    ended: boolean;
+};
+type MatrxRunPickupSettlement = 
+/** The turn arrived on a stream the host already rendered — nothing to reload. */
+{
+    state: "streamed";
+}
+/** Bare `resume_conflict` — retry with the host's backoff. */
+ | {
+    state: "retry";
+}
+/**
+ * The run is over (or no live operation remains): the SAVED turn was
+ * reloaded — that is the answer to show, never an empty bubble and never a
+ * failure the run did not have. `status` null = unknown (workflow / none
+ * found); `reloaded: false` = the reload itself threw (`error`).
+ */
+ | {
+    state: "settled";
+    status: MatrxRuntimeExecutionStatus | null;
+    reloaded: boolean;
+    error?: unknown;
+}
+/** The follow gave up while the run may still be live; `onStillRunning` (default: reload what is saved) ran. */
+ | {
+    state: "still_running";
+    reloaded: boolean;
+    error?: unknown;
+};
+interface SettleRunPickupOptions {
+    /** Re-read the feature's saved record (the conversation's messages) into the screen. */
+    reloadSavedTurn: () => Promise<void> | void;
+    /**
+     * The follow gave up on a run that may still be live. Default: reload what
+     * is saved now. A host with its own patient recovery (the web app's
+     * dropped-stream poll) passes it here instead.
+     */
+    onStillRunning?: () => Promise<void> | void;
+}
+/**
+ * THE one mapping from a pick-up result to what the screen does, shared by
+ * every chat client so a live run that cannot replay ends the same way
+ * everywhere: streamed → done; bare conflict → retry; followed to its end
+ * (or nothing live left to follow) → reload the saved turn and report the
+ * run's real status; follow gave up → still running (never "failed").
+ */
+declare function settleRunPickup(pickup: MatrxRunPickup, options: SettleRunPickupOptions): Promise<MatrxRunPickupSettlement>;
 
 /**
  * Browser-held provider sessions report their failures through the server.
@@ -637,4 +731,4 @@ declare function listUserPendingToolCalls(transport: MatrxTransport, options?: {
     signal?: AbortSignal;
 }): Promise<MatrxPendingCallSummary[]>;
 
-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 };
+export { type CreateMatrxTransportOptions, 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, type ResumeOrRejoinOptions, type ResumeOrRejoinOutcome, type SettleRunPickupOptions, V2_COVERED_AI_PATH_TEMPLATES, applyAiApiVersion, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, createMatrxTransport, createOrganizationOperation, fetchWithMatrxProtocolFallback, followUnavailableRejoin, followWorkflowRunEvents, isCoveredAiPath, isLiveStreamUnavailable, isResumeConflict, isV2Path, listConversationPendingToolCalls, listUserPendingToolCalls, normalizeMatrxError, openMatrxStream, providerSessionFailureBody, readLiveRunRejoin, readLiveRunRequestId, readLiveStreamUnavailable, readMatrxErrorCode, reportProviderSessionFailure, requireOrganizationContext, resumeOrRejoin, runtimeOperationRejoinPath, settleRunPickup, streamErrorText, submitAgentToolResults, toV1FallbackUrl, toV2Path, withRunOrganization };

package/dist/matrx/index.d.ts

@@ -1,4 +1,4 @@
-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';
+import { B as MatrxTransport, w as MatrxRuntimeOperationEvent, a as FollowRuntimeOperationToEndOptions, v as MatrxRuntimeExecutionStatus, c as MatrxApiError, A as MatrxStreamCallOptions, 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';
@@ -319,10 +319,12 @@ declare function assertQueryOrganizationMatchesContext(queryParams: Record<strin
  *   `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.
+ * - Chat/conversation resume answers `code: "resume_conflict"` — even when the
+ *   body ALSO names `live_request_id` + `rejoin_path` — and it is ALWAYS host
+ *   retry, never a rejoin: the claim holder is usually the turn that is still
+ *   SUSPENDING, and rejoining it replays that turn from frame one (duplicate
+ *   text) while the person's continuation never runs. Only
+ *   `code: run_in_progress` rejoins.
  * - 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).
@@ -360,15 +362,16 @@ interface MatrxLiveRunRejoin {
     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. */
+    /** The refusal's code — always `run_in_progress` (chat's `resume_conflict` is retried, never rejoined). */
     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
+ * The rejoin target of a live-run refusal: `409` with `code: run_in_progress`.
+ * Null for every other error — a genuine failure is never mistaken for a live
+ * run, and chat's `resume_conflict` is never a rejoin even when its body names
+ * one (the host retries the resume so the continuation runs). 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`.
@@ -382,9 +385,9 @@ declare function readLiveRunRejoin(error: unknown): MatrxLiveRunRejoin | null;
  */
 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`.)
+ * `409 resume_conflict` — another run holds the conversation's claim (usually
+ * the turn still suspending); retry the resume with the host's backoff so the
+ * continuation runs. Never a rejoin, even when the body names a live run.
  */
 declare function isResumeConflict(error: unknown): boolean;
 /** `409 live_stream_unavailable` — the rejoin journal is gone; follow the durable lifecycle instead. */
@@ -464,7 +467,7 @@ type ResumeOrRejoinOutcome =
     runId: string;
     ended: boolean;
 }
-/** A bare `409 resume_conflict` (no live run named) — retry with the host's backoff policy. */
+/** `409 resume_conflict` (named live run or not) — retry with the host's backoff policy. */
  | {
     kind: "resume_conflict";
     error: MatrxApiError;
@@ -488,15 +491,106 @@ interface ResumeOrRejoinOptions extends Omit<MatrxStreamCallOptions, "signal"> {
  * 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`
+ * `onEnvelope`. On a live-run refusal (`run_in_progress`) 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
+ * second time. Every `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>;
+/** What a `409 live_stream_unavailable` rejoin answer names: a workflow `run_id`, when it has one. */
+interface MatrxLiveStreamUnavailable {
+    runId: string | null;
+}
+/**
+ * Read a rejoin's `409 live_stream_unavailable` (the journal is gone). Null
+ * for every other error. For hosts that open the rejoin stream themselves —
+ * hand the result to `followUnavailableRejoin`.
+ */
+declare function readLiveStreamUnavailable(error: unknown): MatrxLiveStreamUnavailable | null;
+type MatrxFollowedOutcome = Extract<ResumeOrRejoinOutcome, {
+    kind: "followed" | "followed_workflow";
+}>;
+interface FollowUnavailableRejoinOptions {
+    /** THE RUN'S organization; omit when `transport` is already bound to it. */
+    organizationId?: string | null;
+    signal?: AbortSignal;
+    onOperationEvent?: (event: MatrxRuntimeOperationEvent) => void;
+    onWorkflowEvent?: (event: Record<string, unknown>, seq: number | null) => void;
+    follow?: Omit<FollowRuntimeOperationToEndOptions, "onEvent" | "signal" | "lastEventSeq">;
+}
+/**
+ * The no-journal fallback of a rejoin — the SAME branch `resumeOrRejoin`
+ * takes, exported for hosts whose rejoin stream rides their own wire (the
+ * extension's offscreen fetch, the desktop's request loop). A workflow
+ * `run_id` (from the unavailable body, else the refusal) on a runtime rejoin
+ * → follow the workflow run SSE; otherwise read the live operation and
+ * follow it to its end. Settle the result with `settleRunPickup`.
+ */
+declare function followUnavailableRejoin(transport: MatrxTransport, rejoin: MatrxLiveRunRejoin, unavailable: MatrxLiveStreamUnavailable, options?: FollowUnavailableRejoinOptions): Promise<MatrxFollowedOutcome>;
+/**
+ * The parts of a pick-up result `settleRunPickup` reads — every
+ * `ResumeOrRejoinOutcome` is one, and so is a host's own follow result.
+ */
+type MatrxRunPickup = {
+    kind: "resumed" | "rejoined";
+} | {
+    kind: "resume_conflict";
+} | {
+    kind: "followed";
+    executionId: string | null;
+    ended: boolean;
+    status: MatrxRuntimeExecutionStatus | null;
+} | {
+    kind: "followed_workflow";
+    ended: boolean;
+};
+type MatrxRunPickupSettlement = 
+/** The turn arrived on a stream the host already rendered — nothing to reload. */
+{
+    state: "streamed";
+}
+/** Bare `resume_conflict` — retry with the host's backoff. */
+ | {
+    state: "retry";
+}
+/**
+ * The run is over (or no live operation remains): the SAVED turn was
+ * reloaded — that is the answer to show, never an empty bubble and never a
+ * failure the run did not have. `status` null = unknown (workflow / none
+ * found); `reloaded: false` = the reload itself threw (`error`).
+ */
+ | {
+    state: "settled";
+    status: MatrxRuntimeExecutionStatus | null;
+    reloaded: boolean;
+    error?: unknown;
+}
+/** The follow gave up while the run may still be live; `onStillRunning` (default: reload what is saved) ran. */
+ | {
+    state: "still_running";
+    reloaded: boolean;
+    error?: unknown;
+};
+interface SettleRunPickupOptions {
+    /** Re-read the feature's saved record (the conversation's messages) into the screen. */
+    reloadSavedTurn: () => Promise<void> | void;
+    /**
+     * The follow gave up on a run that may still be live. Default: reload what
+     * is saved now. A host with its own patient recovery (the web app's
+     * dropped-stream poll) passes it here instead.
+     */
+    onStillRunning?: () => Promise<void> | void;
+}
+/**
+ * THE one mapping from a pick-up result to what the screen does, shared by
+ * every chat client so a live run that cannot replay ends the same way
+ * everywhere: streamed → done; bare conflict → retry; followed to its end
+ * (or nothing live left to follow) → reload the saved turn and report the
+ * run's real status; follow gave up → still running (never "failed").
+ */
+declare function settleRunPickup(pickup: MatrxRunPickup, options: SettleRunPickupOptions): Promise<MatrxRunPickupSettlement>;
 
 /**
  * Browser-held provider sessions report their failures through the server.
@@ -637,4 +731,4 @@ declare function listUserPendingToolCalls(transport: MatrxTransport, options?: {
     signal?: AbortSignal;
 }): Promise<MatrxPendingCallSummary[]>;
 
-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 };
+export { type CreateMatrxTransportOptions, 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, type ResumeOrRejoinOptions, type ResumeOrRejoinOutcome, type SettleRunPickupOptions, V2_COVERED_AI_PATH_TEMPLATES, applyAiApiVersion, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, createMatrxTransport, createOrganizationOperation, fetchWithMatrxProtocolFallback, followUnavailableRejoin, followWorkflowRunEvents, isCoveredAiPath, isLiveStreamUnavailable, isResumeConflict, isV2Path, listConversationPendingToolCalls, listUserPendingToolCalls, normalizeMatrxError, openMatrxStream, providerSessionFailureBody, readLiveRunRejoin, readLiveRunRequestId, readLiveStreamUnavailable, readMatrxErrorCode, reportProviderSessionFailure, requireOrganizationContext, resumeOrRejoin, runtimeOperationRejoinPath, settleRunPickup, streamErrorText, submitAgentToolResults, toV1FallbackUrl, toV2Path, withRunOrganization };

package/dist/matrx/index.js

@@ -871,18 +871,18 @@ async function followRuntimeOperationToEnd(transport, executionId, options) {
   let cursor = options.lastEventSeq ?? 0;
   let failures = 0;
   while (!outer?.aborted && failures < reconnectLimit) {
-    const attempt = new AbortController();
-    const onOuterAbort = () => attempt.abort();
+    const attempt2 = new AbortController();
+    const onOuterAbort = () => attempt2.abort();
     outer?.addEventListener("abort", onOuterAbort, { once: true });
     let stallTimer = null;
     const armStall = () => {
       if (stallTimer !== null) clearTimeout(stallTimer);
-      stallTimer = setTimeout(() => attempt.abort(), stallTimeoutMs);
+      stallTimer = setTimeout(() => attempt2.abort(), stallTimeoutMs);
     };
     try {
       const items = followRuntimeOperationEvents(transport, executionId, {
         lastEventSeq: cursor,
-        signal: attempt.signal,
+        signal: attempt2.signal,
         ...options.onMalformedFrame ? { onMalformedFrame: options.onMalformedFrame } : {}
       });
       armStall();
@@ -977,7 +977,7 @@ function readLiveRunRejoin(error) {
   const candidates = detailCandidates(bodyOf(error));
   if (candidates.length === 0) return null;
   const code = readMatrxErrorCode(error);
-  if (code !== MATRX_RUN_IN_PROGRESS && code !== MATRX_RESUME_CONFLICT) return null;
+  if (code !== MATRX_RUN_IN_PROGRESS) return null;
   const liveRequestId = firstString(candidates, "live_request_id");
   const pathFromBody = firstString(candidates, "rejoin_path");
   const rejoinPath = pathFromBody && pathFromBody.startsWith("/") ? pathFromBody : liveRequestId ? runtimeOperationRejoinPath(liveRequestId) : null;
@@ -995,7 +995,7 @@ function readLiveRunRequestId(error) {
   return readLiveRunRejoin(error)?.liveRequestId ?? null;
 }
 function isResumeConflict(error) {
-  return statusOf(error) === 409 && readMatrxErrorCode(error) === MATRX_RESUME_CONFLICT && readLiveRunRejoin(error) === null;
+  return statusOf(error) === 409 && readMatrxErrorCode(error) === MATRX_RESUME_CONFLICT;
 }
 function isLiveStreamUnavailable(error) {
   return statusOf(error) === 409 && readMatrxErrorCode(error) === MATRX_LIVE_STREAM_UNAVAILABLE;
@@ -1098,7 +1098,7 @@ async function resumeOrRejoin(transport, resumeCall, options) {
     rejoin = target;
   }
   onRejoin?.(rejoin);
-  let unavailableBody;
+  let unavailable;
   try {
     const handle = await openMatrxStream(bound, rejoin.rejoinPath, {
       ...streamOptions,
@@ -1108,14 +1108,29 @@ async function resumeOrRejoin(transport, resumeCall, options) {
     await drain(handle, onEnvelope);
     return { kind: "rejoined", rejoin };
   } catch (error) {
-    if (!isLiveStreamUnavailable(error)) throw error;
-    unavailableBody = bodyOf(error);
+    const read = readLiveStreamUnavailable(error);
+    if (!read) throw error;
+    unavailable = read;
   }
-  const runId = firstString(detailCandidates(unavailableBody), "run_id") ?? rejoin.runId;
+  return followUnavailableRejoin(bound, rejoin, unavailable, {
+    ...signalOnly,
+    ...onOperationEvent ? { onOperationEvent } : {},
+    ...onWorkflowEvent ? { onWorkflowEvent } : {},
+    ...follow ? { follow } : {}
+  });
+}
+function readLiveStreamUnavailable(error) {
+  if (!isLiveStreamUnavailable(error)) return null;
+  return { runId: firstString(detailCandidates(bodyOf(error)), "run_id") };
+}
+async function followUnavailableRejoin(transport, rejoin, unavailable, options = {}) {
+  const bound = options.organizationId ? withRunOrganization(transport, options.organizationId) : transport;
+  const signalOnly = options.signal ? { signal: options.signal } : {};
+  const runId = unavailable.runId ?? rejoin.runId;
   if (runId && rejoin.rejoinPath.startsWith("/runtime/operations/")) {
     const result2 = await followWorkflowRunEvents(bound, runId, {
       ...signalOnly,
-      onEvent: (event, seq) => onWorkflowEvent?.(event, seq)
+      onEvent: (event, seq) => options.onWorkflowEvent?.(event, seq)
     });
     return { kind: "followed_workflow", rejoin, runId, ended: result2.ended };
   }
@@ -1135,10 +1150,10 @@ async function resumeOrRejoin(transport, resumeCall, options) {
     };
   }
   const result = await followRuntimeOperationToEnd(bound, operation.execution_id, {
-    ...follow,
+    ...options.follow,
     lastEventSeq: operation.last_event_seq,
     ...signalOnly,
-    onEvent: (event) => onOperationEvent?.(event)
+    onEvent: (event) => options.onOperationEvent?.(event)
   });
   return {
     kind: "followed",
@@ -1148,6 +1163,35 @@ async function resumeOrRejoin(transport, resumeCall, options) {
     status: result.status
   };
 }
+async function attempt(run) {
+  try {
+    await run();
+    return { reloaded: true };
+  } catch (error) {
+    return { reloaded: false, error };
+  }
+}
+async function settleRunPickup(pickup, options) {
+  switch (pickup.kind) {
+    case "resumed":
+    case "rejoined":
+      return { state: "streamed" };
+    case "resume_conflict":
+      return { state: "retry" };
+    case "followed_workflow":
+    case "followed": {
+      const status = pickup.kind === "followed" ? pickup.status : null;
+      const nothingLive = pickup.kind === "followed" && pickup.executionId === null;
+      if (pickup.ended || nothingLive) {
+        return { state: "settled", status, ...await attempt(options.reloadSavedTurn) };
+      }
+      return {
+        state: "still_running",
+        ...await attempt(options.onStillRunning ?? options.reloadSavedTurn)
+      };
+    }
+  }
+}
 
 // matrx/run.ts
 async function streamCall(transport, path, body, options) {
@@ -1377,6 +1421,7 @@ export {
   fetchWithMatrxProtocolFallback,
   followRuntimeOperationEvents,
   followRuntimeOperationToEnd,
+  followUnavailableRejoin,
   followWorkflowRunEvents,
   getRuntimeOperationStatus,
   getRuntimeOperationsByLink,
@@ -1395,6 +1440,7 @@ export {
   providerSessionFailureBody,
   readLiveRunRejoin,
   readLiveRunRequestId,
+  readLiveStreamUnavailable,
   readMatrxErrorCode,
   rejoinRuntimeOperation,
   reportProviderSessionFailure,
@@ -1403,6 +1449,7 @@ export {
   resumeOrRejoin,
   runAgentToCompletion,
   runtimeOperationRejoinPath,
+  settleRunPickup,
   startAgentRun,
   startMandateRun,
   streamErrorText,