@ai-matrx/api 0.1.28 → 0.1.29

package/CHANGELOG.md

@@ -2,13 +2,35 @@
 
 ### Unreleased
 
+- **Warm-up retries transient failures.** `createWarmup` re-sends a batch that failed with a network error or 408/425/429/5xx (not 501) after 2s, 8s and 30s while the scope is unchanged — a server rollover is exactly when a warm-up matters. New option `retryDelaysMs` (its length is the budget; `[]` disables). Refusals never retry. Consumer action: none.
 - **Removed** the deprecated aliases `ENDPOINTS.ai.chat` (use `ENDPOINTS.ai.manual`) and `ENDPOINTS.utilities.pdfExtractText` (use `ENDPOINTS.pdf.extractText`); no importer existed. Added `FEATURE.md`. Consumer action: none.
 
-## 0.1.28
+## 0.1.29
 
 UNVERIFIED: this release has no Unreleased entry and the source comparison could not be made (the caller supplied no source comparison). Whether source changed is unknown; consumer action is unknown.
 Check the package's gitHead on npm against this version's gitHead: `git diff <previous gitHead> <this gitHead> -- apps/shared/api/src`.
 
+## 0.1.28
+
+SOURCE CHANGED WITH NO RELEASE NOTE. This release shipped source changes that nobody described in an Unreleased entry,
+so they may include breaking API changes. Consumer action is UNKNOWN: read the diff before upgrading.
+Diff: `git diff 3702c2122e 6638270587 -- apps/shared/api/src`
+
+Changed shipped source files (31):
+- `apps/shared/api/src/deployments.generated.ts`
+- `apps/shared/api/src/generated/account.ts`
+- `apps/shared/api/src/generated/agents.ts`
+- `apps/shared/api/src/generated/ai.ts`
+- `apps/shared/api/src/generated/apps.ts`
+- `apps/shared/api/src/generated/architecture.ts`
+- `apps/shared/api/src/generated/audio.ts`
+- `apps/shared/api/src/generated/chat.ts`
+- `apps/shared/api/src/generated/code.ts`
+- `apps/shared/api/src/generated/commerce.ts`
+- `apps/shared/api/src/generated/communications.ts`
+- `apps/shared/api/src/generated/computer.ts`
+- ...and 19 more
+
 ## 0.1.27
 
 Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 967a33b7f1 3702c2122e -- apps/shared/api/src`

package/dist/index.cjs

@@ -532,6 +532,10 @@ function runWaitTimeoutMessage(kind, modelLabel, seconds) {
 var WARM_PATH = "/ai/warm";
 var DEFAULT_COALESCE_MS = 50;
 var DEFAULT_DEDUPE_MS = 6e4;
+var DEFAULT_RETRY_DELAYS_MS = [2e3, 8e3, 3e4];
+function isTransientStatus(status) {
+  return status === 408 || status === 425 || status === 429 || status >= 500 && status !== 501;
+}
 var SWEEP_AT = 256;
 var QUEUE_MAX = 64;
 function itemId(item) {
@@ -545,6 +549,7 @@ function createWarmup(options) {
     organizationId,
     coalesceMs = DEFAULT_COALESCE_MS,
     dedupeMs = DEFAULT_DEDUPE_MS,
+    retryDelaysMs = DEFAULT_RETRY_DELAYS_MS,
     now = Date.now
   } = options;
   const sentAt = /* @__PURE__ */ new Map();
@@ -594,6 +599,9 @@ function createWarmup(options) {
     if (batch.length === 0) return;
     const keys = batch.map((i) => `${current}|${itemId(i)}`);
     keys.forEach((k) => inFlight.add(k));
+    send(batch, keys, reason, current, 0);
+  }
+  function send(batch, keys, reason, sendScope, attempt2) {
     const settle = (ok) => {
       const t = now();
       for (const k of keys) {
@@ -601,6 +609,21 @@ function createWarmup(options) {
         if (ok) sentAt.set(k, t);
       }
     };
+    const failed = (transient, detail) => {
+      const delay = retryDelaysMs[attempt2];
+      if (transient && delay !== void 0) {
+        setTimeout(() => {
+          if (currentScope() !== sendScope) {
+            settle(false);
+            return;
+          }
+          send(batch, keys, reason, sendScope, attempt2 + 1);
+        }, delay);
+        return;
+      }
+      settle(false);
+      announce(attempt2 > 0 ? `${detail} after ${attempt2 + 1} attempts` : detail);
+    };
     try {
       const org = organizationId ? organizationId() : null;
       void transport.fetch(WARM_PATH, {
@@ -612,12 +635,11 @@ function createWarmup(options) {
         body: JSON.stringify({ reason, items: batch })
       }).then(
         (response) => {
-          settle(response.ok);
-          if (!response.ok) announce(`HTTP ${response.status}`);
+          if (response.ok) settle(true);
+          else failed(isTransientStatus(response.status), `HTTP ${response.status}`);
         },
         (err) => {
-          settle(false);
-          announce(String(err));
+          failed(true, String(err));
         }
       );
     } catch (err) {
@@ -1574,9 +1596,9 @@ async function reportProviderSessionUsage(transport, usage, options = {}) {
     return "retry";
   }
 }
-var DEFAULT_RETRY_DELAYS_MS = [1e3, 4e3, 15e3, 6e4, 18e4];
+var DEFAULT_RETRY_DELAYS_MS2 = [1e3, 4e3, 15e3, 6e4, 18e4];
 function createProviderUsageReporter(options) {
-  const delays = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+  const delays = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS2;
   const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
   const seen = /* @__PURE__ */ new Set();
   const inflight = /* @__PURE__ */ new Set();

package/dist/index.d.cts

@@ -837,6 +837,12 @@ declare function runWaitTimeoutMessage(kind: RunOutputKind, modelLabel: string |
  * out → nothing is sent. Until the server endpoint exists the call answers 404
  * and the primitive stays silent (one `console.debug`, once).
  *
+ * TRANSIENT FAILURES ARE RETRIED. A server rollover (a release every ~30 min)
+ * answers `Failed to fetch` or a 502/503/504 for a few seconds — exactly when a
+ * warm-up matters most, because the new server's caches are cold. A batch that
+ * fails that way goes again after `retryDelaysMs` (default 2s, 8s, 30s) while
+ * the scope is unchanged; a refusal (4xx other than 408/425/429) never retries.
+ *
  * Auth, base URL and `X-Organization-Id` are the injected `MatrxTransport`'s
  * job, exactly as for every other call in this package.
  */
@@ -874,6 +880,11 @@ interface CreateWarmupOptions {
     coalesceMs?: number;
     /** Per-scope per-item dedupe window after a 2xx. Default 60_000ms. */
     dedupeMs?: number;
+    /**
+     * Delay before each retry of a batch that failed transiently (network error,
+     * 408/425/429/5xx); its length is the retry budget. Default 2s, 8s, 30s.
+     */
+    retryDelaysMs?: readonly number[];
     /** Clock, for tests. Default `Date.now`. */
     now?: () => number;
 }

package/dist/index.d.ts

@@ -837,6 +837,12 @@ declare function runWaitTimeoutMessage(kind: RunOutputKind, modelLabel: string |
  * out → nothing is sent. Until the server endpoint exists the call answers 404
  * and the primitive stays silent (one `console.debug`, once).
  *
+ * TRANSIENT FAILURES ARE RETRIED. A server rollover (a release every ~30 min)
+ * answers `Failed to fetch` or a 502/503/504 for a few seconds — exactly when a
+ * warm-up matters most, because the new server's caches are cold. A batch that
+ * fails that way goes again after `retryDelaysMs` (default 2s, 8s, 30s) while
+ * the scope is unchanged; a refusal (4xx other than 408/425/429) never retries.
+ *
  * Auth, base URL and `X-Organization-Id` are the injected `MatrxTransport`'s
  * job, exactly as for every other call in this package.
  */
@@ -874,6 +880,11 @@ interface CreateWarmupOptions {
     coalesceMs?: number;
     /** Per-scope per-item dedupe window after a 2xx. Default 60_000ms. */
     dedupeMs?: number;
+    /**
+     * Delay before each retry of a batch that failed transiently (network error,
+     * 408/425/429/5xx); its length is the retry budget. Default 2s, 8s, 30s.
+     */
+    retryDelaysMs?: readonly number[];
     /** Clock, for tests. Default `Date.now`. */
     now?: () => number;
 }

package/dist/index.js

@@ -532,6 +532,10 @@ function runWaitTimeoutMessage(kind, modelLabel, seconds) {
 var WARM_PATH = "/ai/warm";
 var DEFAULT_COALESCE_MS = 50;
 var DEFAULT_DEDUPE_MS = 6e4;
+var DEFAULT_RETRY_DELAYS_MS = [2e3, 8e3, 3e4];
+function isTransientStatus(status) {
+  return status === 408 || status === 425 || status === 429 || status >= 500 && status !== 501;
+}
 var SWEEP_AT = 256;
 var QUEUE_MAX = 64;
 function itemId(item) {
@@ -545,6 +549,7 @@ function createWarmup(options) {
     organizationId,
     coalesceMs = DEFAULT_COALESCE_MS,
     dedupeMs = DEFAULT_DEDUPE_MS,
+    retryDelaysMs = DEFAULT_RETRY_DELAYS_MS,
     now = Date.now
   } = options;
   const sentAt = /* @__PURE__ */ new Map();
@@ -594,6 +599,9 @@ function createWarmup(options) {
     if (batch.length === 0) return;
     const keys = batch.map((i) => `${current}|${itemId(i)}`);
     keys.forEach((k) => inFlight.add(k));
+    send(batch, keys, reason, current, 0);
+  }
+  function send(batch, keys, reason, sendScope, attempt2) {
     const settle = (ok) => {
       const t = now();
       for (const k of keys) {
@@ -601,6 +609,21 @@ function createWarmup(options) {
         if (ok) sentAt.set(k, t);
       }
     };
+    const failed = (transient, detail) => {
+      const delay = retryDelaysMs[attempt2];
+      if (transient && delay !== void 0) {
+        setTimeout(() => {
+          if (currentScope() !== sendScope) {
+            settle(false);
+            return;
+          }
+          send(batch, keys, reason, sendScope, attempt2 + 1);
+        }, delay);
+        return;
+      }
+      settle(false);
+      announce(attempt2 > 0 ? `${detail} after ${attempt2 + 1} attempts` : detail);
+    };
     try {
       const org = organizationId ? organizationId() : null;
       void transport.fetch(WARM_PATH, {
@@ -612,12 +635,11 @@ function createWarmup(options) {
         body: JSON.stringify({ reason, items: batch })
       }).then(
         (response) => {
-          settle(response.ok);
-          if (!response.ok) announce(`HTTP ${response.status}`);
+          if (response.ok) settle(true);
+          else failed(isTransientStatus(response.status), `HTTP ${response.status}`);
         },
         (err) => {
-          settle(false);
-          announce(String(err));
+          failed(true, String(err));
         }
       );
     } catch (err) {
@@ -1574,9 +1596,9 @@ async function reportProviderSessionUsage(transport, usage, options = {}) {
     return "retry";
   }
 }
-var DEFAULT_RETRY_DELAYS_MS = [1e3, 4e3, 15e3, 6e4, 18e4];
+var DEFAULT_RETRY_DELAYS_MS2 = [1e3, 4e3, 15e3, 6e4, 18e4];
 function createProviderUsageReporter(options) {
-  const delays = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+  const delays = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS2;
   const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
   const seen = /* @__PURE__ */ new Set();
   const inflight = /* @__PURE__ */ new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/api",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "description": "The one way every app talks to every AI Matrx server: generated from the server contract, split by domain so an app loads only the requests it calls. Transport, five credential kinds, organization binding, streams, job follow. No screens, app state or database code.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -439,5 +439,5 @@
     "check:sections": "node scripts/section-probe.mjs \"$PWD\"",
     "verify:tarball": "node scripts/verify-tarball.mjs"
   },
-  "gitHead": "663827058712d4e48f1c98d95b8efbdafd0667bd"
+  "gitHead": "fab8a30b0b60555c3314c6116dd8d4a7a29473fd"
 }