@cadraos/sdk 0.3.12 → 0.3.14-p46.0

package/dist/chat/index.cjs

@@ -447,7 +447,8 @@ var SSEClient = class {
           "Authorization": this.config.authHeader,
           "X-Org-Id": String(this.config.orgId),
           "Accept": "text/event-stream",
-          "Cache-Control": "no-cache"
+          "Cache-Control": "no-cache",
+          ...this.config.lastEventId ? { "Last-Event-ID": this.config.lastEventId } : {}
         },
         signal: this.abortController.signal
       });
@@ -673,13 +674,167 @@ function normalizeUrl(url) {
   return url;
 }
 
+// src/streaming/poll-policy.ts
+var UNNAMED_RATE_LIMIT_WAIT_MS = 6e4;
+function asDict(value) {
+  return typeof value === "object" && value !== null ? value : null;
+}
+var RATE_LIMIT_CODES = /* @__PURE__ */ new Set([
+  "rate_limit_error",
+  "rate_limited",
+  "rate_limit_exceeded",
+  "too_many_requests"
+]);
+function isRateLimited(error) {
+  if (typeof error === "string") return /\b429\b/.test(error);
+  const err = asDict(error);
+  if (!err) return false;
+  for (const key of ["status", "statusCode", "httpStatus", "code"]) {
+    if (err[key] === 429 || err[key] === "429") return true;
+  }
+  const response = asDict(err.response);
+  if (response && (response.status === 429 || response.statusCode === 429)) return true;
+  if (typeof err.code === "string" && RATE_LIMIT_CODES.has(err.code.toLowerCase())) return true;
+  if (err.name === "RateLimitError") return true;
+  const message = typeof err.message === "string" ? err.message : "";
+  return /\b429\b/.test(message) || /rate[\s_-]?limit/i.test(message) || /too many requests/i.test(message);
+}
+function readHeader(bag, name) {
+  if (bag === null || bag === void 0) return null;
+  const getter = bag.get;
+  if (typeof getter === "function") {
+    try {
+      const value = getter.call(bag, name);
+      if (value !== null && value !== void 0) return String(value);
+    } catch {
+    }
+  }
+  const dict = asDict(bag);
+  if (!dict) return null;
+  const wanted = name.toLowerCase();
+  for (const [key, value] of Object.entries(dict)) {
+    if (key.toLowerCase() === wanted && value !== null && value !== void 0) {
+      return String(value);
+    }
+  }
+  return null;
+}
+function parseRetryAfter(raw, now) {
+  if (raw === null || raw === void 0) return null;
+  if (typeof raw === "number") {
+    return Number.isFinite(raw) && raw >= 0 ? raw * 1e3 : null;
+  }
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  if (trimmed === "") return null;
+  if (/^\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed) * 1e3;
+  const at = Date.parse(trimmed);
+  return Number.isNaN(at) ? null : Math.max(0, at - now);
+}
+function parseResetAt(raw, now) {
+  if (raw === null || raw === void 0) return null;
+  const numeric = typeof raw === "number" ? raw : typeof raw === "string" && /^\d+(\.\d+)?$/.test(raw.trim()) ? Number(raw.trim()) : null;
+  if (numeric !== null) {
+    if (!Number.isFinite(numeric) || numeric < 0) return null;
+    if (numeric > 1e11) return Math.max(0, numeric - now);
+    if (numeric > 1e9) return Math.max(0, numeric * 1e3 - now);
+    return numeric * 1e3;
+  }
+  if (typeof raw !== "string") return null;
+  const at = Date.parse(raw.trim());
+  return Number.isNaN(at) ? null : Math.max(0, at - now);
+}
+function getRetryAfterMs(error, now = Date.now()) {
+  const err = asDict(error);
+  if (!err) return null;
+  const details = asDict(err.details);
+  const response = asDict(err.response);
+  const body = asDict(err.body) ?? asDict(response?.data);
+  const bodyError = asDict(body?.error);
+  const bodyDetails = asDict(bodyError?.details) ?? asDict(body?.details);
+  for (const source of [err, details, bodyDetails]) {
+    const ms = source?.retryAfterMs;
+    if (typeof ms === "number" && Number.isFinite(ms) && ms >= 0) return ms;
+  }
+  for (const source of [err, details, bodyDetails, bodyError]) {
+    const parsed = parseRetryAfter(source?.retryAfter, now);
+    if (parsed !== null) return parsed;
+  }
+  const headerBags = [err.headers, response?.headers, details?.headers, body?.headers];
+  for (const bag of headerBags) {
+    const parsed = parseRetryAfter(readHeader(bag, "retry-after"), now);
+    if (parsed !== null) return parsed;
+  }
+  for (const source of [details, bodyDetails, err]) {
+    for (const key of ["resetAt", "reset", "rateLimitReset"]) {
+      const parsed = parseResetAt(source?.[key], now);
+      if (parsed !== null) return parsed;
+    }
+  }
+  for (const bag of headerBags) {
+    for (const header of ["x-ratelimit-reset", "ratelimit-reset"]) {
+      const parsed = parseResetAt(readHeader(bag, header), now);
+      if (parsed !== null) return parsed;
+    }
+  }
+  return null;
+}
+function getHttpStatus(error) {
+  const err = asDict(error);
+  if (!err) return null;
+  for (const key of ["status", "statusCode", "httpStatus"]) {
+    const value = err[key];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+    if (typeof value === "string" && /^\d{3}$/.test(value)) return Number(value);
+  }
+  const response = asDict(err.response);
+  for (const key of ["status", "statusCode"]) {
+    const value = response?.[key];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return null;
+}
+function isTerminalClientError(error) {
+  const status = getHttpStatus(error);
+  if (status === null) return false;
+  return status >= 400 && status < 500 && status !== 429 && status !== 408;
+}
+var FAILURE_GROWTH_FACTOR = 2;
+var IDLE_GROWTH_FACTOR = 1.5;
+function nextFailureDelayMs(currentMs, maxMs) {
+  return Math.min(Math.max(currentMs, 1) * FAILURE_GROWTH_FACTOR, maxMs);
+}
+function nextIdleDelayMs(currentMs, maxMs) {
+  return Math.min(Math.ceil(Math.max(currentMs, 1) * IDLE_GROWTH_FACTOR), maxMs);
+}
+function applyJitter(delayMs, ratio, random = Math.random) {
+  if (ratio <= 0) return delayMs;
+  return Math.round(delayMs * (1 + random() * ratio));
+}
+
 // src/streaming/stream-controller.ts
 var DEFAULT_STREAMING_CONFIG = {
   maxReconnectAttempts: 5,
   reconnectBaseDelayMs: 1e3,
   reconnectMaxDelayMs: 1e4,
+  // NOTE (unchanged, deliberately): this watchdog force-disconnects a HEALTHY
+  // SSE connection after 30s of silence and routes it through the same
+  // handleConnectionError path as a real transport failure. Ordinary LLM
+  // latency exceeds 30s routinely, so it fires against working streams — that
+  // is what drives sessions into the polling fallback in the first place. The
+  // fix is a server-side SSE heartbeat, not a bigger number here; raising this
+  // is a guess against a moving target. Everything below only bounds what the
+  // fallback costs once it has been entered.
   activityTimeoutMs: 3e4,
-  pollingIntervalMs: 2e3
+  pollingIntervalMs: 5e3,
+  pollingMaxIntervalMs: 3e4,
+  pollingMaxConsecutiveFailures: 10,
+  pollingMaxConsecutiveRateLimits: 3,
+  pollingMaxConsecutiveClientErrors: 3,
+  pollingMaxDurationMs: 18e5,
+  pollingMaxRetryAfterMs: 3e5,
+  pollingJitterRatio: 0.1,
+  sseRetryIntervalMs: 6e4
 };
 var DEFAULT_POLLING_ENABLED = true;
 var ExecutionStreamControllerImpl = class {
@@ -692,9 +847,24 @@ var ExecutionStreamControllerImpl = class {
   seenEventIds = /* @__PURE__ */ new Set();
   _lastEventId = null;
   activityTimeoutId = null;
-  pollingIntervalId = null;
   finalExecution = null;
   finalError = null;
+  // --- Fallback polling state ---
+  // A self-rescheduling timeout, not setInterval: the delay has to change
+  // between ticks (that is what backoff IS), and a timeout chain also cannot
+  // stack overlapping requests the way a fixed interval does when the API is
+  // slow to answer.
+  pollTimeoutId = null;
+  pollDelayMs = 0;
+  pollConsecutiveFailures = 0;
+  pollConsecutiveRateLimits = 0;
+  pollConsecutiveClientErrors = 0;
+  /** When the loop last observed anything new — the clock the give-up bound runs on. */
+  pollLastProgressAt = 0;
+  pollInFlight = false;
+  lastPolledStatus = null;
+  sseRetryTimeoutId = null;
+  sseRetryInFlight = false;
   // Event callbacks
   listeners = {
     log: [],
@@ -723,6 +893,39 @@ var ExecutionStreamControllerImpl = class {
     this.config = { ...DEFAULT_STREAMING_CONFIG, ...options.config };
     this.pollingEnabled = options.pollingEnabled ?? DEFAULT_POLLING_ENABLED;
   }
+  // Resolved fallback-poll settings. Read through `??` rather than off the
+  // spread config so an explicit `undefined` in a caller's partial config still
+  // lands on the default instead of NaN-ing the arithmetic.
+  get pollBaseIntervalMs() {
+    return this.config.pollingIntervalMs ?? DEFAULT_STREAMING_CONFIG.pollingIntervalMs;
+  }
+  get pollMaxIntervalMs() {
+    return Math.max(
+      this.config.pollingMaxIntervalMs ?? DEFAULT_STREAMING_CONFIG.pollingMaxIntervalMs,
+      this.pollBaseIntervalMs
+    );
+  }
+  get pollMaxConsecutiveFailures() {
+    return this.config.pollingMaxConsecutiveFailures ?? DEFAULT_STREAMING_CONFIG.pollingMaxConsecutiveFailures;
+  }
+  get pollMaxConsecutiveRateLimits() {
+    return this.config.pollingMaxConsecutiveRateLimits ?? DEFAULT_STREAMING_CONFIG.pollingMaxConsecutiveRateLimits;
+  }
+  get pollMaxConsecutiveClientErrors() {
+    return this.config.pollingMaxConsecutiveClientErrors ?? DEFAULT_STREAMING_CONFIG.pollingMaxConsecutiveClientErrors;
+  }
+  get pollMaxDurationMs() {
+    return this.config.pollingMaxDurationMs ?? DEFAULT_STREAMING_CONFIG.pollingMaxDurationMs;
+  }
+  get pollMaxRetryAfterMs() {
+    return this.config.pollingMaxRetryAfterMs ?? DEFAULT_STREAMING_CONFIG.pollingMaxRetryAfterMs;
+  }
+  get pollJitterRatio() {
+    return this.config.pollingJitterRatio ?? DEFAULT_STREAMING_CONFIG.pollingJitterRatio;
+  }
+  get sseRetryIntervalMs() {
+    return this.config.sseRetryIntervalMs ?? DEFAULT_STREAMING_CONFIG.sseRetryIntervalMs;
+  }
   /**
    * Get the last event ID (for resume support)
    */
@@ -813,28 +1016,45 @@ var ExecutionStreamControllerImpl = class {
     console.log("[SDK:StreamController] executionId:", this.options.executionId);
     console.log("[SDK:StreamController] orgId:", this.options.orgId);
     console.log("[SDK:StreamController] apiKey:", authToken ? `${authToken.substring(0, 20)}...` : "MISSING");
-    this.sseClient = new SSEClient({
+    if (this.sseClient) {
+      this.sseClient.disconnect();
+      this.sseClient = null;
+    }
+    const client = new SSEClient({
       url,
       authHeader: `Bearer ${authToken}`,
       orgId: this.options.orgId,
       fetch: this.options.fetch,
-      onEvent: (event) => this.handleEvent(event),
+      // Resume from where this session left off. On a first connect this is
+      // null and the header is omitted.
+      lastEventId: this._lastEventId,
+      onEvent: (event) => {
+        if (this.sseClient !== client) return;
+        this.handleEvent(event);
+      },
       onError: (error) => {
+        if (this.sseClient !== client) return;
         console.error("[SDK:StreamController] SSE error:", error);
         this.handleConnectionError(error);
       },
       onConnectionChange: (connected) => {
+        if (this.sseClient !== client) return;
         console.log("[SDK:StreamController] SSE connection change:", connected);
         if (connected) {
           this.status = "connected";
           this.reconnectAttempts = 0;
+          this.stopPolling();
           this.resetActivityTimeout();
         }
-        this.emit("connectionChange", { connected, usingFallback: false });
+        this.emit("connectionChange", {
+          connected,
+          usingFallback: this.status === "fallback_polling"
+        });
       }
     });
+    this.sseClient = client;
     try {
-      await this.sseClient.connect();
+      await client.connect();
       console.log("[SDK:StreamController] SSE connect() completed");
     } catch (error) {
       console.error("[SDK:StreamController] SSE connect() threw:", error);
@@ -1073,6 +1293,7 @@ var ExecutionStreamControllerImpl = class {
   handleComplete(data) {
     this.status = "closed";
     this.stopActivityTimeout();
+    this.stopPolling();
     const sessionId = data.sessionId ?? this.options.sessionId;
     const execution = {
       uuid: this.options.executionId,
@@ -1099,6 +1320,7 @@ var ExecutionStreamControllerImpl = class {
   handleError(error) {
     this.status = "closed";
     this.stopActivityTimeout();
+    this.stopPolling();
     this.finalError = error;
     this.emit("error", error);
     if (this.waitReject) {
@@ -1125,6 +1347,10 @@ var ExecutionStreamControllerImpl = class {
       this.handleError({ error: msg, errorCode: "stream_unrecoverable" });
       return;
     }
+    if (this.status === "fallback_polling") {
+      this.startPolling();
+      return;
+    }
     if (this.reconnectAttempts < this.config.maxReconnectAttempts) {
       this.status = "reconnecting";
       this.reconnectAttempts++;
@@ -1194,41 +1420,215 @@ var ExecutionStreamControllerImpl = class {
     }
   }
   /**
-   * Start polling fallback
+   * Start polling fallback.
+   *
+   * Idempotent — calling it while a loop is already running is a no-op, so no
+   * path can end up with two loops racing the same execution.
    */
   startPolling() {
-    this.pollingIntervalId = setInterval(async () => {
-      try {
-        const execution = await this.options.getExecution(this.options.executionId);
-        for (const log of execution.logs) {
-          if (!this.seenEventIds.has(log.uuid)) {
-            this.seenEventIds.add(log.uuid);
-            this.emit("log", log);
-          }
-        }
-        if (execution.status === "completed") {
-          this.stopPolling();
-          this.handleComplete(execution);
-        } else if (execution.status === "failed" || execution.status === "cancelled") {
-          this.stopPolling();
-          this.handleError({
-            error: execution.error ?? `Execution ${execution.status}`,
-            errorCode: execution.status
-          });
+    if (this.pollTimeoutId !== null || this.pollInFlight) {
+      return;
+    }
+    this.pollLastProgressAt = Date.now();
+    this.pollDelayMs = this.pollBaseIntervalMs;
+    this.pollConsecutiveFailures = 0;
+    this.pollConsecutiveRateLimits = 0;
+    this.pollConsecutiveClientErrors = 0;
+    this.lastPolledStatus = null;
+    this.stopActivityTimeout();
+    this.scheduleSSERetry();
+    this.schedulePoll(this.pollDelayMs);
+  }
+  /**
+   * Queue the next poll tick.
+   */
+  schedulePoll(delayMs) {
+    if (this.status !== "fallback_polling") {
+      return;
+    }
+    this.pollTimeoutId = setTimeout(() => {
+      this.pollTimeoutId = null;
+      void this.runPoll();
+    }, Math.max(0, Math.round(delayMs)));
+  }
+  /**
+   * One poll tick: fetch state, emit what is new, then decide how long to wait
+   * before the next one — or whether there should be a next one at all.
+   */
+  async runPoll() {
+    if (this.status !== "fallback_polling") {
+      return;
+    }
+    if (Date.now() - this.pollLastProgressAt >= this.pollMaxDurationMs) {
+      this.failPolling(
+        `Streaming fallback gave up: no execution progress for ${Math.round(this.pollMaxDurationMs / 1e3)}s`,
+        "polling_timeout"
+      );
+      return;
+    }
+    this.pollInFlight = true;
+    try {
+      const execution = await this.options.getExecution(this.options.executionId);
+      this.pollConsecutiveFailures = 0;
+      this.pollConsecutiveRateLimits = 0;
+      this.pollConsecutiveClientErrors = 0;
+      let sawNewInfo = false;
+      for (const log of execution.logs ?? []) {
+        if (!this.seenEventIds.has(log.uuid)) {
+          this.seenEventIds.add(log.uuid);
+          this.emit("log", log);
+          sawNewInfo = true;
         }
-      } catch (error) {
-        console.error("Polling error:", error);
       }
-    }, this.config.pollingIntervalMs);
+      if (execution.status !== this.lastPolledStatus) {
+        this.lastPolledStatus = execution.status;
+        sawNewInfo = true;
+      }
+      if (sawNewInfo) {
+        this.pollLastProgressAt = Date.now();
+      }
+      if (execution.status === "completed") {
+        this.stopPolling();
+        this.handleComplete(execution);
+        return;
+      }
+      if (execution.status === "failed" || execution.status === "cancelled") {
+        this.stopPolling();
+        this.handleError({
+          error: execution.error ?? `Execution ${execution.status}`,
+          errorCode: execution.status
+        });
+        return;
+      }
+      this.pollDelayMs = sawNewInfo ? this.pollBaseIntervalMs : nextIdleDelayMs(this.pollDelayMs, this.pollMaxIntervalMs);
+    } catch (error) {
+      if (!this.handlePollError(error)) {
+        return;
+      }
+    } finally {
+      this.pollInFlight = false;
+    }
+    this.schedulePoll(applyJitter(this.pollDelayMs, this.pollJitterRatio));
+  }
+  /**
+   * Apply backpressure for a failed poll.
+   *
+   * @returns `true` to keep polling (with `pollDelayMs` updated), `false` when
+   * the loop has been terminated.
+   */
+  handlePollError(error) {
+    const retryAfterMs = getRetryAfterMs(error);
+    const rateLimited = isRateLimited(error) || retryAfterMs !== null;
+    if (rateLimited) {
+      this.pollConsecutiveRateLimits++;
+      console.warn(
+        "[SDK:StreamController] Poll rate-limited",
+        retryAfterMs !== null ? `(server asked for ${Math.round(retryAfterMs / 1e3)}s)` : "(no reset named)"
+      );
+      if (retryAfterMs !== null && retryAfterMs > this.pollMaxRetryAfterMs) {
+        this.failPolling(
+          `Rate limited: the API asked for ${Math.round(retryAfterMs / 1e3)}s, longer than this stream will wait`,
+          "rate_limited"
+        );
+        return false;
+      }
+      if (this.pollConsecutiveRateLimits >= this.pollMaxConsecutiveRateLimits) {
+        this.failPolling(
+          "Rate limited by the API; stopped the streaming fallback rather than keep spending the key quota",
+          "rate_limited"
+        );
+        return false;
+      }
+      this.pollDelayMs = Math.max(retryAfterMs ?? UNNAMED_RATE_LIMIT_WAIT_MS, this.pollDelayMs);
+      return true;
+    }
+    if (isTerminalClientError(error)) {
+      this.pollConsecutiveClientErrors++;
+      const status = getHttpStatus(error);
+      console.warn(
+        `[SDK:StreamController] Poll got HTTP ${status} (${this.pollConsecutiveClientErrors}/${this.pollMaxConsecutiveClientErrors})`
+      );
+      if (this.pollConsecutiveClientErrors >= this.pollMaxConsecutiveClientErrors) {
+        this.failPolling(
+          `Execution status endpoint returned HTTP ${status} ${this.pollConsecutiveClientErrors} times \u2014 cannot track this run`,
+          "polling_unrecoverable"
+        );
+        return false;
+      }
+      this.pollDelayMs = nextFailureDelayMs(this.pollDelayMs, this.pollMaxIntervalMs);
+      return true;
+    }
+    this.pollConsecutiveFailures++;
+    console.warn(
+      `[SDK:StreamController] Poll failed (${this.pollConsecutiveFailures}/${this.pollMaxConsecutiveFailures}):`,
+      error
+    );
+    if (this.pollConsecutiveFailures >= this.pollMaxConsecutiveFailures) {
+      this.failPolling(
+        `Streaming fallback failed ${this.pollConsecutiveFailures} times in a row`,
+        "polling_failed"
+      );
+      return false;
+    }
+    this.pollDelayMs = nextFailureDelayMs(this.pollDelayMs, this.pollMaxIntervalMs);
+    return true;
+  }
+  /**
+   * Terminate the fallback loop and surface the reason.
+   */
+  failPolling(error, errorCode) {
+    this.stopPolling();
+    this.handleError({ error, errorCode });
   }
   /**
-   * Stop polling
+   * Stop polling, including the periodic SSE re-attempt that belongs to it.
    */
   stopPolling() {
-    if (this.pollingIntervalId) {
-      clearInterval(this.pollingIntervalId);
-      this.pollingIntervalId = null;
+    if (this.pollTimeoutId !== null) {
+      clearTimeout(this.pollTimeoutId);
+      this.pollTimeoutId = null;
+    }
+    if (this.sseRetryTimeoutId !== null) {
+      clearTimeout(this.sseRetryTimeoutId);
+      this.sseRetryTimeoutId = null;
+    }
+  }
+  /**
+   * Queue the next attempt to get the real stream back.
+   */
+  scheduleSSERetry() {
+    if (this.sseRetryTimeoutId !== null || this.status !== "fallback_polling") {
+      return;
+    }
+    this.sseRetryTimeoutId = setTimeout(() => {
+      this.sseRetryTimeoutId = null;
+      this.attemptSSERecovery();
+    }, this.sseRetryIntervalMs);
+  }
+  /**
+   * Re-attempt SSE from inside the fallback, so a transient outage costs the
+   * session a few polls rather than its stream for the lifetime of the tab.
+   *
+   * Success is NOT observed here: `SSEClient.connect()` resolves when the
+   * stream ENDS, not when it opens. The open is observed by
+   * `onConnectionChange(true)`, which flips status and stops this loop. The
+   * promise below only tells us the attempt is over so the next one can be
+   * queued.
+   */
+  attemptSSERecovery() {
+    if (this.status !== "fallback_polling") {
+      return;
+    }
+    if (this.sseRetryInFlight) {
+      this.scheduleSSERetry();
+      return;
     }
+    this.sseRetryInFlight = true;
+    void this.connectSSE().catch(() => {
+    }).finally(() => {
+      this.sseRetryInFlight = false;
+      this.scheduleSSERetry();
+    });
   }
   /**
    * Reset activity timeout
@@ -1360,12 +1760,23 @@ async function collectImagesFromStream(stream, options = {}) {
   });
 }
 
+// src/utils/api-paths.ts
+var API_V1 = "/api/v1";
+var EXECUTION_PATH = `${API_V1}/executions`;
+function executionPath(executionId) {
+  return `${EXECUTION_PATH}/${executionId}`;
+}
+function executionCancelPath(executionId) {
+  return `${EXECUTION_PATH}/${executionId}/cancel`;
+}
+
 // src/resources/agents.ts
 var AgentsAPI = class extends BaseResourceAPI {
   constructor(http, getStreamConfig) {
     super(http, "/api/v1/agents");
     this.getStreamConfig = getStreamConfig;
   }
+  getStreamConfig;
   // ===== LIST Operations =====
   /**
    * List all agents in the organization
@@ -1622,7 +2033,7 @@ var AgentsAPI = class extends BaseResourceAPI {
    * ```
    */
   async getExecution(executionId) {
-    return this.http.get(`/executions/${executionId}`);
+    return this.http.get(executionPath(executionId));
   }
   // ===== EDIT Operations =====
   /**
@@ -1677,7 +2088,7 @@ var AgentsAPI = class extends BaseResourceAPI {
    */
   async cancelExecution(executionId) {
     return this.http.post(
-      `/executions/${executionId}/cancel`,
+      executionCancelPath(executionId),
       void 0,
       { skipRetry: true }
     );
@@ -2178,6 +2589,7 @@ var ArtifactsAPI = class extends BaseResourceAPI {
     }
     return this.http.request({
       method: "POST",
+      // KNOWN BROKEN — same missing `/api/v1` prefix as listArtifacts above.
       path: `/executions/${executionId}/artifacts`,
       body: formData,
       headers: {
@@ -2271,6 +2683,7 @@ var SessionsAPI = class extends BaseResourceAPI {
     super(http, "/api/v1/sessions");
     this.getStreamConfig = getStreamConfig;
   }
+  getStreamConfig;
   // ===== LIST Operations =====
   /**
    * List all sessions in the organization
@@ -2450,7 +2863,7 @@ var SessionsAPI = class extends BaseResourceAPI {
    * Get execution result
    */
   async getExecution(executionId) {
-    return this.http.get(`/executions/${executionId}`);
+    return this.http.get(executionPath(executionId));
   }
   // ===== EDIT Operations =====
   /**
@@ -2590,6 +3003,7 @@ var KanbanAPI = class extends BaseResourceAPI {
     super(http, "/api/v1/kanban");
     this.getStreamConfig = getStreamConfig;
   }
+  getStreamConfig;
   // ===== BOARD =====
   /**
    * Get the current org's board (lanes in declared order). Auto-provisions
@@ -2724,7 +3138,7 @@ var KanbanAPI = class extends BaseResourceAPI {
    * @returns Execution details.
    */
   async getCardRun(executionId) {
-    return this.http.get(`/api/v1/agents/executions/${executionId}`);
+    return this.http.get(executionPath(executionId));
   }
   /**
    * Create a stream controller for a card's run, keyed on the card's
@@ -2791,6 +3205,7 @@ var RemoteAgentsAPI = class extends BaseResourceAPI {
     super(http, "/api/v1/remote-agents");
     this.getStreamConfig = getStreamConfig;
   }
+  getStreamConfig;
   /**
    * List all remote agents in the organization
    *
@@ -2924,7 +3339,7 @@ var RemoteAgentsAPI = class extends BaseResourceAPI {
       apiKey: config.apiKey,
       tokenProvider: config.tokenProvider,
       orgId: config.orgId,
-      getExecution: (id) => this.http.get(`/executions/${id}`)
+      getExecution: (id) => this.http.get(executionPath(id))
     });
     return controller;
   }
@@ -4005,6 +4420,13 @@ function initialState() {
 
 // src/chat/hooks/useAgentChat.ts
 var __DEV__ = typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
+var LEGACY_POLL_BASE_INTERVAL_MS = 5e3;
+var LEGACY_POLL_MAX_INTERVAL_MS = 3e4;
+var LEGACY_POLL_MAX_FAILURES = 10;
+var LEGACY_POLL_MAX_RATE_LIMITS = 3;
+var LEGACY_POLL_MAX_IDLE_MS = 18e5;
+var LEGACY_POLL_MAX_RETRY_AFTER_MS = 3e5;
+var LEGACY_POLL_JITTER_RATIO = 0.1;
 var SILENT_TOOL_NAMES = /* @__PURE__ */ new Set([
   "check_delegations"
 ]);
@@ -4592,12 +5014,17 @@ function useAgentChat(options) {
       }
     }
   });
-  const pollingIntervalRef = react.useRef(null);
+  const pollingTimeoutRef = react.useRef(null);
   const pollingExecutionIdRef = react.useRef(null);
+  const pollDelayRef = react.useRef(0);
+  const pollFailuresRef = react.useRef(0);
+  const pollRateLimitsRef = react.useRef(0);
+  const pollLastProgressRef = react.useRef(0);
+  const pollLastStatusRef = react.useRef(null);
   const stopPolling = react.useCallback(() => {
-    if (pollingIntervalRef.current) {
-      clearInterval(pollingIntervalRef.current);
-      pollingIntervalRef.current = null;
+    if (pollingTimeoutRef.current) {
+      clearTimeout(pollingTimeoutRef.current);
+      pollingTimeoutRef.current = null;
     }
     pollingExecutionIdRef.current = null;
   }, []);
@@ -4605,26 +5032,77 @@ function useAgentChat(options) {
     if (pollingExecutionIdRef.current === executionId) return;
     stopPolling();
     pollingExecutionIdRef.current = executionId;
+    const baseDelayMs = pollingInterval ?? LEGACY_POLL_BASE_INTERVAL_MS;
+    pollDelayRef.current = baseDelayMs;
+    pollFailuresRef.current = 0;
+    pollRateLimitsRef.current = 0;
+    pollLastProgressRef.current = Date.now();
+    pollLastStatusRef.current = null;
     if (__DEV__) console.log("[useAgentChat] Starting polling fallback for:", executionId);
+    const schedule = (delayMs) => {
+      if (pollingExecutionIdRef.current !== executionId) return;
+      pollingTimeoutRef.current = setTimeout(() => {
+        pollingTimeoutRef.current = null;
+        void poll();
+      }, Math.max(0, Math.round(delayMs)));
+    };
+    const giveUp = (message) => {
+      if (__DEV__) console.warn("[useAgentChat] Polling gave up:", message);
+      stopPolling();
+      handleError(message);
+    };
     const poll = async () => {
       if (pollingExecutionIdRef.current !== executionId) return;
+      if (Date.now() - pollLastProgressRef.current >= LEGACY_POLL_MAX_IDLE_MS) {
+        giveUp("Lost the live connection and stopped receiving updates for this run");
+        return;
+      }
       try {
         const execution = await adapter.getExecution(executionId);
+        pollFailuresRef.current = 0;
+        pollRateLimitsRef.current = 0;
+        if (execution.status !== pollLastStatusRef.current) {
+          pollLastStatusRef.current = execution.status;
+          pollLastProgressRef.current = Date.now();
+          pollDelayRef.current = baseDelayMs;
+        } else {
+          pollDelayRef.current = nextIdleDelayMs(pollDelayRef.current, LEGACY_POLL_MAX_INTERVAL_MS);
+        }
         if (execution.status === "completed") {
           if (__DEV__) console.log("[useAgentChat] Polling: execution completed");
           stopPolling();
           handleComplete(execution.result || void 0);
-        } else if (execution.status === "failed") {
+          return;
+        }
+        if (execution.status === "failed") {
           if (__DEV__) console.log("[useAgentChat] Polling: execution failed");
           stopPolling();
           handleError(execution.error || "Execution failed");
+          return;
         }
       } catch (err) {
-        if (__DEV__) console.warn("[useAgentChat] Polling error (will retry):", err);
+        const retryAfterMs = getRetryAfterMs(err);
+        if (isRateLimited(err) || retryAfterMs !== null) {
+          pollRateLimitsRef.current++;
+          const resetTooFarOut = retryAfterMs !== null && retryAfterMs > LEGACY_POLL_MAX_RETRY_AFTER_MS;
+          if (resetTooFarOut || pollRateLimitsRef.current >= LEGACY_POLL_MAX_RATE_LIMITS) {
+            giveUp("Rate limited by the API \u2014 stopped polling for updates on this run");
+            return;
+          }
+          pollDelayRef.current = Math.max(retryAfterMs ?? UNNAMED_RATE_LIMIT_WAIT_MS, pollDelayRef.current);
+        } else {
+          pollFailuresRef.current++;
+          if (__DEV__) console.warn("[useAgentChat] Polling error (will retry):", err);
+          if (pollFailuresRef.current >= LEGACY_POLL_MAX_FAILURES) {
+            giveUp("Lost connection to the agent \u2014 stopped polling for updates on this run");
+            return;
+          }
+          pollDelayRef.current = nextFailureDelayMs(pollDelayRef.current, LEGACY_POLL_MAX_INTERVAL_MS);
+        }
       }
+      schedule(applyJitter(pollDelayRef.current, LEGACY_POLL_JITTER_RATIO));
     };
-    poll();
-    pollingIntervalRef.current = setInterval(poll, pollingInterval ?? 2e3);
+    void poll();
   }, [adapter, stopPolling, handleComplete, handleError, pollingInterval]);
   react.useEffect(() => {
     if (!useStreamController && isUsingFallback && currentExecutionId && isLoading && pollingEnabled !== false) {