@ai-matrx/agents 0.23.0 → 0.24.1

package/dist/matrx/index.d.cts

@@ -310,22 +310,27 @@ declare function assertQueryOrganizationMatchesContext(queryParams: Record<strin
 /**
  * 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.
+ * 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.
@@ -347,14 +352,40 @@ interface MatrxHttpErrorLike {
  * `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 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.
+ * 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;
-/** `409 resume_conflict` — another resume holds the run claim; retry is host policy. */
+/**
+ * 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;
@@ -388,30 +419,52 @@ declare function openMatrxStream(transport: MatrxTransport, path: string, option
  * 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 still live; its original stream was replayed + followed into `onEnvelope`. */
+/** The run was live; its stream (from `rejoin_path`) was replayed + followed into `onEnvelope`. */
  | {
     kind: "rejoined";
-    liveRequestId: string;
+    rejoin: MatrxLiveRunRejoin;
 }
 /**
- * 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).
+ * 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";
-    liveRequestId: string;
+    rejoin: MatrxLiveRunRejoin;
     executionId: string | null;
     ended: boolean;
     status: MatrxRuntimeExecutionStatus | null;
 }
-/** `409 resume_conflict` — retry with the host's backoff policy. */
+/** 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;
@@ -422,22 +475,26 @@ interface ResumeOrRejoinOptions extends Omit<MatrxStreamCallOptions, "signal"> {
     /** 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). */
+    /** 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;
-    /** Tuning for the fallback follow (stall / reconnect policy). */
+    /** 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 running, REJOIN it.
+ * 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 `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.
+ * `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>;
 
@@ -580,4 +637,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 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 };
+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

@@ -310,22 +310,27 @@ declare function assertQueryOrganizationMatchesContext(queryParams: Record<strin
 /**
  * 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.
+ * 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.
@@ -347,14 +352,40 @@ interface MatrxHttpErrorLike {
  * `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 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.
+ * 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;
-/** `409 resume_conflict` — another resume holds the run claim; retry is host policy. */
+/**
+ * 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;
@@ -388,30 +419,52 @@ declare function openMatrxStream(transport: MatrxTransport, path: string, option
  * 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 still live; its original stream was replayed + followed into `onEnvelope`. */
+/** The run was live; its stream (from `rejoin_path`) was replayed + followed into `onEnvelope`. */
  | {
     kind: "rejoined";
-    liveRequestId: string;
+    rejoin: MatrxLiveRunRejoin;
 }
 /**
- * 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).
+ * 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";
-    liveRequestId: string;
+    rejoin: MatrxLiveRunRejoin;
     executionId: string | null;
     ended: boolean;
     status: MatrxRuntimeExecutionStatus | null;
 }
-/** `409 resume_conflict` — retry with the host's backoff policy. */
+/** 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;
@@ -422,22 +475,26 @@ interface ResumeOrRejoinOptions extends Omit<MatrxStreamCallOptions, "signal"> {
     /** 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). */
+    /** 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;
-    /** Tuning for the fallback follow (stall / reconnect policy). */
+    /** 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 running, REJOIN it.
+ * 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 `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.
+ * `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>;
 
@@ -580,4 +637,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 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 };
+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.js

@@ -965,17 +965,37 @@ function readMatrxErrorCode(error) {
   }
   return null;
 }
-function readLiveRunRequestId(error) {
-  if (statusOf(error) !== 409) return null;
-  for (const candidate of detailCandidates(bodyOf(error))) {
-    if (candidate.code !== MATRX_RUN_IN_PROGRESS) continue;
-    const live = nonBlank(candidate.live_request_id);
-    if (live) return live.trim();
+function firstString(candidates, key) {
+  for (const candidate of candidates) {
+    const value = nonBlank(candidate[key]);
+    if (value) return value.trim();
   }
   return null;
 }
+function readLiveRunRejoin(error) {
+  if (statusOf(error) !== 409) return null;
+  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;
+  const liveRequestId = firstString(candidates, "live_request_id");
+  const pathFromBody = firstString(candidates, "rejoin_path");
+  const rejoinPath = pathFromBody && pathFromBody.startsWith("/") ? pathFromBody : liveRequestId ? runtimeOperationRejoinPath(liveRequestId) : null;
+  if (!rejoinPath) return null;
+  const root = bodyOf(error);
+  return {
+    liveRequestId,
+    rejoinPath,
+    runId: firstString(candidates, "run_id"),
+    code,
+    body: isRecord3(root) ? root : {}
+  };
+}
+function readLiveRunRequestId(error) {
+  return readLiveRunRejoin(error)?.liveRequestId ?? null;
+}
 function isResumeConflict(error) {
-  return statusOf(error) === 409 && readMatrxErrorCode(error) === MATRX_RESUME_CONFLICT;
+  return statusOf(error) === 409 && readMatrxErrorCode(error) === MATRX_RESUME_CONFLICT && readLiveRunRejoin(error) === null;
 }
 function isLiveStreamUnavailable(error) {
   return statusOf(error) === 409 && readMatrxErrorCode(error) === MATRX_LIVE_STREAM_UNAVAILABLE;
@@ -1005,54 +1025,110 @@ function withRunOrganization(transport, organizationId) {
     })
   };
 }
+async function followWorkflowRunEvents(transport, runId, options) {
+  const headers = { Accept: "text/event-stream" };
+  if (options.lastEventId) headers["Last-Event-ID"] = String(options.lastEventId);
+  let response;
+  try {
+    response = await requestStream(
+      transport,
+      `/runs/${encodePathSegment(runId)}/events/stream`,
+      {
+        method: "GET",
+        headers,
+        ...options.signal ? { signal: options.signal } : {}
+      }
+    );
+  } catch (error) {
+    if (options.signal?.aborted) return { ended: false };
+    throw error;
+  }
+  try {
+    for await (const frame of readMatrxSseStream(
+      response.body
+    )) {
+      if (frame.event === "end") return { ended: true };
+      if (frame.data === null) continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(frame.data);
+      } catch {
+        continue;
+      }
+      if (!isRecord3(parsed)) continue;
+      options.onEvent(parsed, parsed.event === "node_stream" ? null : frame.seq);
+    }
+  } catch (error) {
+    if (!options.signal?.aborted) throw error;
+  }
+  return { ended: false };
+}
 async function drain(handle, onEnvelope) {
   for await (const envelope of handle.events) onEnvelope(envelope);
 }
 async function resumeOrRejoin(transport, resumeCall, options) {
-  const { onEnvelope, organizationId, onRejoin, onOperationEvent, follow, ...rest } = options;
+  const {
+    onEnvelope,
+    organizationId,
+    onRejoin,
+    onOperationEvent,
+    onWorkflowEvent,
+    follow,
+    ...rest
+  } = options;
   const bound = organizationId ? withRunOrganization(transport, organizationId) : transport;
   const streamOptions = {
     ...rest,
     ...options.signal ? { signal: options.signal } : {}
   };
-  let liveRequestId;
+  const signalOnly = options.signal ? { signal: options.signal } : {};
+  let rejoin;
   try {
     const handle = await resumeCall(bound, streamOptions);
     await drain(handle, onEnvelope);
     return { kind: "resumed", requestId: handle.requestId };
   } catch (error) {
-    if (error instanceof MatrxApiError && isResumeConflict(error)) {
-      return { kind: "resume_conflict", error };
+    const target = readLiveRunRejoin(error);
+    if (!target) {
+      if (error instanceof MatrxApiError && isResumeConflict(error)) {
+        return { kind: "resume_conflict", error };
+      }
+      throw error;
     }
-    const live = readLiveRunRequestId(error);
-    if (!live) throw error;
-    liveRequestId = live;
+    rejoin = target;
   }
-  onRejoin?.(liveRequestId);
+  onRejoin?.(rejoin);
+  let unavailableBody;
   try {
-    const handle = await rejoinRuntimeOperation(bound, liveRequestId, streamOptions);
+    const handle = await openMatrxStream(bound, rejoin.rejoinPath, {
+      ...streamOptions,
+      // The rejoin routes take no body model; the reference client posts {}.
+      body: {}
+    });
     await drain(handle, onEnvelope);
-    return { kind: "rejoined", liveRequestId };
+    return { kind: "rejoined", rejoin };
   } catch (error) {
     if (!isLiveStreamUnavailable(error)) throw error;
+    unavailableBody = bodyOf(error);
   }
-  const statusView = await getRuntimeOperationStatus(bound, liveRequestId, {
-    ...options.signal ? { signal: options.signal } : {}
-  });
+  const runId = firstString(detailCandidates(unavailableBody), "run_id") ?? rejoin.runId;
+  if (runId && rejoin.rejoinPath.startsWith("/runtime/operations/")) {
+    const result2 = await followWorkflowRunEvents(bound, runId, {
+      ...signalOnly,
+      onEvent: (event, seq) => onWorkflowEvent?.(event, seq)
+    });
+    return { kind: "followed_workflow", rejoin, runId, ended: result2.ended };
+  }
+  const liveRequestId = rejoin.liveRequestId;
+  const statusView = liveRequestId ? await getRuntimeOperationStatus(bound, liveRequestId, signalOnly) : null;
   const operation = statusView?.operations.find((op) => !op.is_terminal) ?? statusView?.operations[0] ?? null;
   if (!operation) {
-    return {
-      kind: "followed",
-      liveRequestId,
-      executionId: null,
-      ended: false,
-      status: null
-    };
+    return { kind: "followed", rejoin, executionId: null, ended: false, status: null };
   }
   if (operation.is_terminal) {
     return {
       kind: "followed",
-      liveRequestId,
+      rejoin,
       executionId: operation.execution_id,
       ended: true,
       status: operation.status
@@ -1061,12 +1137,12 @@ async function resumeOrRejoin(transport, resumeCall, options) {
   const result = await followRuntimeOperationToEnd(bound, operation.execution_id, {
     ...follow,
     lastEventSeq: operation.last_event_seq,
-    ...options.signal ? { signal: options.signal } : {},
+    ...signalOnly,
     onEvent: (event) => onOperationEvent?.(event)
   });
   return {
     kind: "followed",
-    liveRequestId,
+    rejoin,
     executionId: operation.execution_id,
     ended: result.ended,
     status: result.status
@@ -1301,6 +1377,7 @@ export {
   fetchWithMatrxProtocolFallback,
   followRuntimeOperationEvents,
   followRuntimeOperationToEnd,
+  followWorkflowRunEvents,
   getRuntimeOperationStatus,
   getRuntimeOperationsByLink,
   isCoveredAiPath,
@@ -1316,6 +1393,7 @@ export {
   normalizeMatrxError,
   openMatrxStream,
   providerSessionFailureBody,
+  readLiveRunRejoin,
   readLiveRunRequestId,
   readMatrxErrorCode,
   rejoinRuntimeOperation,