@ai-matrx/agents 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 0.6.0 — 2026-08-30
+
+- **The production transport moved IN** (C22 — the hard parts live in the
+  package; hosts inject only identity). `@ai-matrx/agents/matrx` now ships
+  `createMatrxTransport({ baseUrl | resolveTarget, credentials, organizationId? })`
+  with everything else defaulted to the proven production values:
+  - connect timeout 15s / total UNCAPPED (stream-safe) over
+    `@ai-matrx/data/net`'s `resilientFetch` — `@ai-matrx/data` is now an
+    ordinary dependency (sanctioned sibling dep, C23/X3);
+  - the AI API protocol-version policy (`applyAiApiVersion`, default v2, the
+    scoped covered-surface allowlist) + the loud v2 → v1 transport fallback
+    (`fetchWithMatrxProtocolFallback`) — a caller abort is never logged as a
+    downgrade;
+  - credentials read FRESH per call through `@ai-matrx/data`'s
+    `CredentialsPort` / `credentialToHeaders` (token refresh mid-run picked
+    up); resolver policy headers supported for dynamic channels;
+  - the fail-closed `X-Organization-Id` kernel
+    (`requireOrganizationContext` / `applyOrganizationContextHeader` /
+    `assertQueryOrganizationMatchesContext`, moved verbatim from
+    matrx-frontend `lib/api/organization-context.ts`) — configured lanes
+    refuse before the wire, conversation lanes send org in the body only;
+  - the ONE error classification: `normalizeMatrxError` → `MatrxCallError`
+    (structurally compatible with matrx-frontend's `ApiCallError`);
+  - a typed diagnostics seam (`onRequest` / `onError` /
+    `onProtocolDowngrade`) with `expectedErrorStatuses` suppression;
+  - policy/credential `Content-Type` is stripped defensively — the wire owns
+    it (a policy Content-Type merged over a GET SSE call corrupts the wire).
+- **The reconnect policy moved IN**: `followRuntimeOperationToEnd` — the full
+  production replay-then-follow loop (45s stall watchdog, 60 × 2s reconnect
+  budget reset by ANY parsed frame, durable `Last-Event-ID` cursor across
+  attempts), previously hand-rolled in matrx-frontend
+  `features/agents/runtime-reconnect/api.ts`. Fix over the ported original
+  (recorded per C22): the stall watchdog now also covers the connect phase,
+  so a hanging connect can no longer wedge an attempt forever.
+- **New `/react` entry** (client-stamped): `useAgentRun`
+  (start / continue / cancel + streamed state as the parity-proven
+  `AgentRequestProjection`) and `useFollowRuntimeOperation` (the reconnect
+  follower as a hook, production knobs typed). `react >= 18` is an optional
+  peer needed only by this entry.
+
+## 0.5.1 — 2026-08-29
+
+- Clarified the package boundary in the published README: `@ai-matrx/agents`
+  talks to the fully assembled AI Dream brain, while
+  `@ai-matrx/agent-engine` runs a brain the embedder assembles locally.
+
 ## 0.5.0 — 2026-08-29
 
 - Added `@ai-matrx/agents/matrx` — the Matrx API client: run an agent

package/README.md

@@ -5,6 +5,10 @@ standardizes the stream wire, pure request/workflow projection, and safe
 Creator-facing result boundaries without importing React, Redux, Next.js, or
 application code.
 
+**This package talks to the fully assembled AI Dream brain. It does not run the
+provider/tool loop locally; use `@ai-matrx/agent-engine` when you need to run a
+brain you assemble with your own providers, tools, persistence, and memory.**
+
 ## Install
 
 ```bash
@@ -83,25 +87,24 @@ rejected or malformed blocks are observable through `lastRenderBlockIssue`.
 
 ## Run an agent end-to-end (`./matrx`)
 
-The `@ai-matrx/agents/matrx` subpath is the Matrx API client. You inject ONE
-fetch-shaped transport — base URL, credentials (user JWT, guest fingerprint,
-or API key), the org header, and retry policy are yours; the package owns the
-wire semantics (paths, bodies, streaming headers, the `Last-Event-ID` cursor):
+The `@ai-matrx/agents/matrx` subpath is the Matrx API client. Build the
+PRODUCTION transport from identity alone — everything else (connect/total
+timeout policy, the v2 → v1 protocol fallback, fresh-per-call credential
+headers, the fail-closed org header, error classification, diagnostics
+hooks) ships in the package with the proven production defaults:
 
 ```ts
 import {
+  createMatrxTransport,
   newEphemeralConversationStart,
   runAgentToCompletion,
-  type MatrxTransport,
 } from "@ai-matrx/agents/matrx";
 
-const transport: MatrxTransport = {
-  fetch: (path, init) =>
-    fetch(`https://server.app.matrxserver.com${path}`, {
-      ...init,
-      headers: { ...init.headers, Authorization: `Bearer ${token}` },
-    }),
-};
+const transport = createMatrxTransport({
+  baseUrl: "https://server.app.matrxserver.com",
+  credentials: { get: async () => ({ kind: "api_key", apiKey }) }, // CredentialsPort (@ai-matrx/data)
+  organizationId: orgId, // omit for conversation-lane calls (org rides the body)
+});
 
 const run = await runAgentToCompletion(transport, agentId, {
   ...newEphemeralConversationStart(),
@@ -110,20 +113,46 @@ const run = await runAgentToCompletion(transport, agentId, {
 }, { onChunk: (text) => render(text) });
 ```
 
+Hosts with dynamic routing pass `resolveTarget` (fresh per call: base URL,
+extra policy headers, channel label) instead of `baseUrl`, and can wire the
+typed `diagnostics` seam (`onRequest` / `onError` / `onProtocolDowngrade`)
+into their telemetry. `MatrxTransport` remains a plain fetch-shaped port, so
+a fully custom transport still plugs in.
+
 Lower-level pieces: `startAgentRun` / `continueAgentConversation` /
 `resumeAgentConversation` return a `MatrxRunHandle` (`X-Request-ID` and
 `X-Conversation-ID` before any event, plus the normalized envelope stream);
 `cancelAgentRun` stops a run by its server request id;
 `getRuntimeOperationStatus` / `listRuntimeOperationEvents` /
 `followRuntimeOperationEvents` / `rejoinRuntimeOperation` are the reconnect
-ladder; `submitAgentToolResults` + pending-call discovery drive delegated
+ladder — and `followRuntimeOperationToEnd` is the full production reconnect
+policy over them (stall watchdog, bounded retry budget, durable
+`Last-Event-ID` cursor, all knobs typed and defaulted);
+`submitAgentToolResults` + pending-call discovery drive delegated
 client tools (watch `continuation_needed` → `resumeAgentConversation`).
 
+## React hooks (`./react`)
+
+Client-only bindings over the same transport:
+
+```tsx
+import { useAgentRun } from "@ai-matrx/agents/react";
+
+const { phase, projection, start, cancel } = useAgentRun({ transport });
+// projection is the parity-proven AgentRequestProjection: answer, reasoning,
+// phases, operations, tools, render blocks, completion, error.
+```
+
+`useFollowRuntimeOperation({ transport, executionId, onEvent })` is the
+reconnect follower as a hook — production stall/retry/cursor policy built in.
+
 ## Runtime support
 
-The package is framework-free ESM targeting modern browsers, browser-based
-desktop shells, extensions, Next.js client or server modules, and Node 20+.
-It has no runtime dependencies and performs no work at import time.
+The package targets modern browsers, browser-based desktop shells,
+extensions, Next.js client or server modules, and Node 20+. Its one runtime
+dependency is `@ai-matrx/data` (the shared net-resilience + credentials
+layer); `react >= 18` is an optional peer needed only by `./react`. No entry
+point performs work at import time.
 
 ## Development
 

package/dist/index.cjs

@@ -1,4 +1,79 @@
-'use strict';
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_MATRX_NDJSON_READ_AHEAD: () => DEFAULT_MATRX_NDJSON_READ_AHEAD,
+  DEFAULT_WORKFLOW_PROJECTION_LIMITS: () => DEFAULT_WORKFLOW_PROJECTION_LIMITS,
+  MATRX_AI_API_VERSION_DEFAULT: () => MATRX_AI_API_VERSION_DEFAULT,
+  MatrxApiError: () => MatrxApiError,
+  MatrxRunError: () => MatrxRunError,
+  OrganizationContextError: () => OrganizationContextError,
+  TERMINAL_MATRX_RUNTIME_STATUSES: () => TERMINAL_MATRX_RUNTIME_STATUSES,
+  V2_COVERED_AI_PATH_TEMPLATES: () => V2_COVERED_AI_PATH_TEMPLATES,
+  applyAiApiVersion: () => applyAiApiVersion,
+  applyOrganizationContextHeader: () => applyOrganizationContextHeader,
+  assertQueryOrganizationMatchesContext: () => assertQueryOrganizationMatchesContext,
+  cancelAgentRun: () => cancelAgentRun,
+  continueAgentConversation: () => continueAgentConversation,
+  continueEphemeralConversationStart: () => continueEphemeralConversationStart,
+  continueStoredConversationStart: () => continueStoredConversationStart,
+  createAgentRequestProjection: () => createAgentRequestProjection,
+  createMatrxNdjsonFramer: () => createMatrxNdjsonFramer,
+  createMatrxSseFramer: () => createMatrxSseFramer,
+  createMatrxTransport: () => createMatrxTransport,
+  createWorkflowNodeProjection: () => createWorkflowNodeProjection,
+  extractMatrxErrorCode: () => extractMatrxErrorCode,
+  extractMatrxErrorMessage: () => extractMatrxErrorMessage,
+  fetchWithMatrxProtocolFallback: () => fetchWithMatrxProtocolFallback,
+  followRuntimeOperationEvents: () => followRuntimeOperationEvents,
+  followRuntimeOperationToEnd: () => followRuntimeOperationToEnd,
+  getRuntimeOperationStatus: () => getRuntimeOperationStatus,
+  getRuntimeOperationsByLink: () => getRuntimeOperationsByLink,
+  isCoveredAiPath: () => isCoveredAiPath,
+  isV2Path: () => isV2Path,
+  listConversationPendingToolCalls: () => listConversationPendingToolCalls,
+  listRuntimeOperationEvents: () => listRuntimeOperationEvents,
+  listUserPendingToolCalls: () => listUserPendingToolCalls,
+  mintMatrxConversationId: () => mintMatrxConversationId,
+  newEphemeralConversationStart: () => newEphemeralConversationStart,
+  newStoredConversationStart: () => newStoredConversationStart,
+  normalizeMatrxError: () => normalizeMatrxError,
+  normalizeMatrxStreamEnvelope: () => normalizeMatrxStreamEnvelope,
+  parseMatrxSseFrame: () => parseMatrxSseFrame,
+  projectAgentEvent: () => projectAgentEvent,
+  projectAgentEvents: () => projectAgentEvents,
+  projectAgentResultForDisplay: () => projectAgentResultForDisplay,
+  projectWorkflowNodeEvent: () => projectWorkflowNodeEvent,
+  readMatrxNdjsonStream: () => readMatrxNdjsonStream,
+  readMatrxSseStream: () => readMatrxSseStream,
+  rejoinRuntimeOperation: () => rejoinRuntimeOperation,
+  requireOrganizationContext: () => requireOrganizationContext,
+  resumeAgentConversation: () => resumeAgentConversation,
+  runAgentToCompletion: () => runAgentToCompletion,
+  startAgentRun: () => startAgentRun,
+  submitAgentToolResults: () => submitAgentToolResults,
+  toV1FallbackUrl: () => toV1FallbackUrl,
+  toV2Path: () => toV2Path
+});
+module.exports = __toCommonJS(index_exports);
 
 // stream/ndjson.ts
 var DEFAULT_MATRX_NDJSON_READ_AHEAD = 64;
@@ -836,6 +911,296 @@ function extractMatrxErrorCode(serverDetail) {
   return null;
 }
 
+// matrx/client.ts
+var import_data = require("@ai-matrx/data");
+var import_data2 = require("@ai-matrx/data");
+
+// matrx/org-context.ts
+var OrganizationContextError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "OrganizationContextError";
+    this.code = code;
+  }
+};
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function requireOrganizationContext(selectedOrganizationId, overrideOrganizationId) {
+  const candidate = overrideOrganizationId ?? selectedOrganizationId;
+  if (typeof candidate !== "string" || candidate.trim().length === 0) {
+    throw new OrganizationContextError(
+      "organization_context_required",
+      "Select an organization before sending this request."
+    );
+  }
+  const normalized = candidate.trim();
+  if (!UUID_PATTERN.test(normalized)) {
+    throw new OrganizationContextError(
+      "organization_context_invalid",
+      "The selected organization ID is invalid."
+    );
+  }
+  return normalized.toLowerCase();
+}
+function applyOrganizationContextHeader(headers, organizationId) {
+  const normalizedOrganizationId = requireOrganizationContext(organizationId);
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() === "x-organization-id" && value.trim().toLowerCase() !== normalizedOrganizationId) {
+      throw new OrganizationContextError(
+        "organization_context_mismatch",
+        "X-Organization-Id must match the request context organization."
+      );
+    }
+  }
+  const withoutOrganizationHeader = Object.fromEntries(
+    Object.entries(headers).filter(
+      ([name]) => name.toLowerCase() !== "x-organization-id"
+    )
+  );
+  return {
+    ...withoutOrganizationHeader,
+    "X-Organization-Id": normalizedOrganizationId
+  };
+}
+function assertQueryOrganizationMatchesContext(queryParams, organizationId) {
+  if (!queryParams || queryParams.organization_id === void 0) return;
+  const queryOrganizationId = requireOrganizationContext(
+    String(queryParams.organization_id)
+  );
+  if (queryOrganizationId !== requireOrganizationContext(organizationId)) {
+    throw new OrganizationContextError(
+      "organization_context_mismatch",
+      "Query organization_id must match the request context organization."
+    );
+  }
+}
+
+// matrx/protocol.ts
+var import_net = require("@ai-matrx/data/net");
+var MATRX_AI_API_VERSION_DEFAULT = "v2";
+var V2_COVERED_AI_PATH_TEMPLATES = [
+  "/ai/manual",
+  "/ai/chat",
+  "/ai/agents/{agent_id}",
+  "/ai/agent/{agent_id}",
+  // singular alias — behaves identically
+  "/ai/conversations/{conversation_id}",
+  "/ai/conversation/{conversation_id}",
+  // singular alias
+  "/ai/prompts/{prompt_id}",
+  // saved-prompt execution
+  "/ai/mandates/{mandate_key}"
+  // THE MANDATE DOOR — `/v2` sibling exists (routers/v2.py)
+];
+function toV2Path(path) {
+  const withLead = path.startsWith("/") ? path : `/${path}`;
+  if (withLead.startsWith("/api/")) {
+    const rest = withLead.slice("/api".length);
+    return rest.startsWith("/v2/") ? withLead : `/api/v2${rest}`;
+  }
+  return withLead.startsWith("/v2/") ? withLead : `/v2${withLead}`;
+}
+var COVERED_INTERPOLATED_PATH = [
+  /^(?:\/api)?\/ai\/manual$/,
+  /^(?:\/api)?\/ai\/chat$/,
+  /^(?:\/api)?\/ai\/agents\/[^/]+$/,
+  /^(?:\/api)?\/ai\/agent\/[^/]+$/,
+  /^(?:\/api)?\/ai\/conversations\/[^/]+$/,
+  /^(?:\/api)?\/ai\/conversation\/[^/]+$/,
+  /^(?:\/api)?\/ai\/prompts\/[^/]+$/,
+  // `/warm` etc. deliberately don't match
+  /^(?:\/api)?\/ai\/mandates\/[^/]+$/
+  // the mandate door
+];
+function isCoveredAiPath(path) {
+  return COVERED_INTERPOLATED_PATH.some((re) => re.test(path));
+}
+function isV2Path(pathOrUrl) {
+  return /\/v2\/ai\//.test(pathOrUrl);
+}
+function toV1FallbackUrl(url) {
+  return url.replace(/\/v2\/ai\//, "/ai/");
+}
+function applyAiApiVersion(path, version) {
+  if (version !== "v2") return path;
+  return isCoveredAiPath(path) ? toV2Path(path) : path;
+}
+async function fetchWithMatrxProtocolFallback(url, init, opts = {}) {
+  const { onDowngrade, ...fetchOpts } = opts;
+  const logDowngrade = (reason, status2) => {
+    console.warn(
+      `[matrx] ai_v2_downgrade \u2192 retrying on v1. v2=${url} reason=${reason}`
+    );
+    onDowngrade?.({ url, reason, ...status2 !== void 0 ? { status: status2 } : {} });
+  };
+  if (!isV2Path(url)) return (0, import_net.resilientFetch)(url, init, fetchOpts);
+  let result;
+  try {
+    result = await (0, import_net.resilientFetch)(url, init, fetchOpts);
+  } catch (err) {
+    const isAbort = (0, import_net.isNetError)(err) && err.code === "aborted" || err instanceof Error && err.name === "AbortError";
+    if (isAbort) throw err;
+    logDowngrade(String(err));
+    return (0, import_net.resilientFetch)(toV1FallbackUrl(url), init, fetchOpts);
+  }
+  const status = result.response.status;
+  if (status === 404 || status === 405 || status >= 500) {
+    logDowngrade(`HTTP ${status}`, status);
+    return (0, import_net.resilientFetch)(toV1FallbackUrl(url), init, fetchOpts);
+  }
+  return result;
+}
+
+// matrx/client.ts
+function classifyStatus(status) {
+  return status >= 400 && status < 500 ? "validation_error" : "http_error";
+}
+function normalizeMatrxError(err) {
+  if (err instanceof MatrxApiError) {
+    return {
+      type: classifyStatus(err.status),
+      message: err.message,
+      status: err.status,
+      serverDetail: err.serverDetail,
+      ...err.code ? { code: err.code } : {},
+      name: err.name
+    };
+  }
+  if (err instanceof OrganizationContextError) {
+    return {
+      type: "validation_error",
+      message: err.message,
+      code: err.code,
+      name: err.name,
+      ...err.stack !== void 0 ? { stack: err.stack } : {}
+    };
+  }
+  if (err instanceof DOMException && err.name === "AbortError") {
+    return { type: "abort_error", message: "Request was cancelled." };
+  }
+  if ((0, import_data.isNetError)(err)) {
+    if (err.code === "aborted") {
+      return { type: "abort_error", message: err.message };
+    }
+    if (err.code === "http") {
+      const status = err.status ?? 0;
+      return { type: classifyStatus(status), message: err.message, status };
+    }
+    return { type: "network_error", message: err.message };
+  }
+  if (err instanceof Error) {
+    const httpMatch = err.message.match(/HTTP (\d+):\s*(.*)/);
+    if (httpMatch) {
+      const status = parseInt(httpMatch[1], 10);
+      return {
+        type: classifyStatus(status),
+        message: httpMatch[2] ?? err.message,
+        status
+      };
+    }
+    return { type: "network_error", message: err.message };
+  }
+  return { type: "unknown", message: String(err ?? "Unknown error") };
+}
+var PRODUCTION_CONNECT_TIMEOUT_MS = 15e3;
+function stripContentType(headers) {
+  return Object.fromEntries(
+    Object.entries(headers).filter(
+      ([name]) => name.toLowerCase() !== "content-type"
+    )
+  );
+}
+function createMatrxTransport(options) {
+  const {
+    baseUrl,
+    resolveTarget,
+    credentials,
+    organizationId,
+    aiApiVersion,
+    connectTimeoutMs = PRODUCTION_CONNECT_TIMEOUT_MS,
+    totalTimeoutMs = null,
+    expectedErrorStatuses,
+    diagnostics,
+    source = "matrxTransport"
+  } = options;
+  if (baseUrl === void 0 === (resolveTarget === void 0)) {
+    throw new Error(
+      "createMatrxTransport: provide exactly one of `baseUrl` or `resolveTarget`."
+    );
+  }
+  const resolve = resolveTarget ?? (() => ({ baseUrl }));
+  const resolveVersion = () => {
+    if (aiApiVersion === void 0) return MATRX_AI_API_VERSION_DEFAULT;
+    return typeof aiApiVersion === "function" ? aiApiVersion() : aiApiVersion;
+  };
+  const resolveOrganizationId = () => {
+    if (organizationId === void 0) return null;
+    const candidate = typeof organizationId === "function" ? organizationId() : organizationId;
+    return requireOrganizationContext(candidate);
+  };
+  return {
+    async fetch(path, init) {
+      const target = resolve();
+      const versionedPath = applyAiApiVersion(path, resolveVersion());
+      const url = `${target.baseUrl}${versionedPath}`;
+      const credentialHeaders = credentials ? (0, import_data2.credentialToHeaders)(await credentials.get()) : {};
+      let headers = {
+        ...init.headers,
+        ...stripContentType(credentialHeaders),
+        ...stripContentType(target.policyHeaders ?? {})
+      };
+      const orgId = resolveOrganizationId();
+      if (orgId !== null) {
+        headers = applyOrganizationContextHeader(headers, orgId);
+      }
+      const info = {
+        url,
+        method: init.method,
+        path,
+        channel: target.channel ?? "default",
+        source
+      };
+      diagnostics?.onRequest?.(info);
+      let response;
+      try {
+        ({ response } = await fetchWithMatrxProtocolFallback(
+          url,
+          {
+            method: init.method,
+            headers,
+            ...init.body !== void 0 ? { body: init.body } : {}
+          },
+          {
+            ...init.signal ? { signal: init.signal } : {},
+            connectTimeoutMs,
+            totalTimeoutMs,
+            throwOnHttpError: false,
+            ...diagnostics?.onProtocolDowngrade ? { onDowngrade: diagnostics.onProtocolDowngrade } : {}
+          }
+        ));
+      } catch (err) {
+        diagnostics?.onError?.(normalizeMatrxError(err), info);
+        throw err;
+      }
+      if (!response.ok && !expectedErrorStatuses?.includes(response.status)) {
+        const serverDetail = await response.clone().json().catch(() => void 0);
+        const code = extractMatrxErrorCode(serverDetail);
+        diagnostics?.onError?.(
+          {
+            type: classifyStatus(response.status),
+            message: extractMatrxErrorMessage(serverDetail) ?? `HTTP ${response.status}`,
+            status: response.status,
+            serverDetail,
+            ...code ? { code } : {}
+          },
+          info
+        );
+      }
+      return response;
+    }
+  };
+}
+
 // matrx/conversation.ts
 function mintMatrxConversationId() {
   return crypto.randomUUID();
@@ -1167,6 +1532,55 @@ async function* followRuntimeOperationEvents(transport, executionId, options = {
     yield { type: "liveness", cursor };
   }
 }
+async function followRuntimeOperationToEnd(transport, executionId, options) {
+  const stallTimeoutMs = options.stallTimeoutMs ?? 45e3;
+  const reconnectLimit = options.reconnectLimit ?? 60;
+  const reconnectDelayMs = options.reconnectDelayMs ?? 2e3;
+  const outer = options.signal;
+  let cursor = options.lastEventSeq ?? 0;
+  let failures = 0;
+  while (!outer?.aborted && failures < reconnectLimit) {
+    const attempt = new AbortController();
+    const onOuterAbort = () => attempt.abort();
+    outer?.addEventListener("abort", onOuterAbort, { once: true });
+    let stallTimer = null;
+    const armStall = () => {
+      if (stallTimer !== null) clearTimeout(stallTimer);
+      stallTimer = setTimeout(() => attempt.abort(), stallTimeoutMs);
+    };
+    try {
+      const items = followRuntimeOperationEvents(transport, executionId, {
+        lastEventSeq: cursor,
+        signal: attempt.signal,
+        ...options.onMalformedFrame ? { onMalformedFrame: options.onMalformedFrame } : {}
+      });
+      armStall();
+      for await (const item of items) {
+        armStall();
+        failures = 0;
+        cursor = item.cursor;
+        if (item.type === "end") {
+          return { ended: true, status: item.status };
+        }
+        if (item.type === "event") {
+          options.onEvent(item.event, item.seq);
+        }
+      }
+      failures += 1;
+    } catch (error) {
+      if (outer?.aborted) break;
+      failures += 1;
+      options.onAttemptError?.(error);
+    } finally {
+      if (stallTimer !== null) clearTimeout(stallTimer);
+      outer?.removeEventListener("abort", onOuterAbort);
+    }
+    if (!outer?.aborted && failures < reconnectLimit) {
+      await new Promise((r) => setTimeout(r, reconnectDelayMs));
+    }
+  }
+  return { ended: false, status: null };
+}
 async function rejoinRuntimeOperation(transport, requestId, options = {}) {
   const response = await requestStream(
     transport,
@@ -1220,43 +1634,4 @@ function listUserPendingToolCalls(transport, options = {}) {
     }
   );
 }
-
-exports.DEFAULT_MATRX_NDJSON_READ_AHEAD = DEFAULT_MATRX_NDJSON_READ_AHEAD;
-exports.DEFAULT_WORKFLOW_PROJECTION_LIMITS = DEFAULT_WORKFLOW_PROJECTION_LIMITS;
-exports.MatrxApiError = MatrxApiError;
-exports.MatrxRunError = MatrxRunError;
-exports.TERMINAL_MATRX_RUNTIME_STATUSES = TERMINAL_MATRX_RUNTIME_STATUSES;
-exports.cancelAgentRun = cancelAgentRun;
-exports.continueAgentConversation = continueAgentConversation;
-exports.continueEphemeralConversationStart = continueEphemeralConversationStart;
-exports.continueStoredConversationStart = continueStoredConversationStart;
-exports.createAgentRequestProjection = createAgentRequestProjection;
-exports.createMatrxNdjsonFramer = createMatrxNdjsonFramer;
-exports.createMatrxSseFramer = createMatrxSseFramer;
-exports.createWorkflowNodeProjection = createWorkflowNodeProjection;
-exports.extractMatrxErrorCode = extractMatrxErrorCode;
-exports.extractMatrxErrorMessage = extractMatrxErrorMessage;
-exports.followRuntimeOperationEvents = followRuntimeOperationEvents;
-exports.getRuntimeOperationStatus = getRuntimeOperationStatus;
-exports.getRuntimeOperationsByLink = getRuntimeOperationsByLink;
-exports.listConversationPendingToolCalls = listConversationPendingToolCalls;
-exports.listRuntimeOperationEvents = listRuntimeOperationEvents;
-exports.listUserPendingToolCalls = listUserPendingToolCalls;
-exports.mintMatrxConversationId = mintMatrxConversationId;
-exports.newEphemeralConversationStart = newEphemeralConversationStart;
-exports.newStoredConversationStart = newStoredConversationStart;
-exports.normalizeMatrxStreamEnvelope = normalizeMatrxStreamEnvelope;
-exports.parseMatrxSseFrame = parseMatrxSseFrame;
-exports.projectAgentEvent = projectAgentEvent;
-exports.projectAgentEvents = projectAgentEvents;
-exports.projectAgentResultForDisplay = projectAgentResultForDisplay;
-exports.projectWorkflowNodeEvent = projectWorkflowNodeEvent;
-exports.readMatrxNdjsonStream = readMatrxNdjsonStream;
-exports.readMatrxSseStream = readMatrxSseStream;
-exports.rejoinRuntimeOperation = rejoinRuntimeOperation;
-exports.resumeAgentConversation = resumeAgentConversation;
-exports.runAgentToCompletion = runAgentToCompletion;
-exports.startAgentRun = startAgentRun;
-exports.submitAgentToolResults = submitAgentToolResults;
-//# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map