@aexhq/sdk 0.28.0 → 0.28.1

package/dist/_contracts/event-stream-client.d.ts

@@ -9,6 +9,14 @@
  * reconnects (no gap, no duplicate). It stops on a terminal event, on abort,
  * or when the caller breaks the iterator.
  *
+ * A silently half-open socket (no close/error, no frames) is the dangerous
+ * case: the read loop would block forever and MISS a terminal that was already
+ * persisted server-side. So the client sends a tiny keep-alive ping the
+ * coordinator auto-responds to (hibernation-safe, no DO wake) and runs an idle
+ * watchdog: if no frame arrives within {@link CoordinatorStreamOptions.idleTimeoutMs},
+ * the socket is treated as dead and reconnected — resume-from-cursor then
+ * replays the terminal.
+ *
  * Filtering and projection are the client's concern (the wire carries the
  * whole run): compose {@link filterStream} with the envelope guards, and
  * {@link mapStream} with {@link toAGUI}, on top of this stream.
@@ -23,6 +31,8 @@ export interface WebSocketLike {
     addEventListener(type: "open" | "message" | "close" | "error", listener: (ev: {
         data?: unknown;
     }) => void): void;
+    /** Send a keep-alive ping. Optional: a transport without it just relies on real events to reset the watchdog. */
+    send?(data: string): void;
 }
 export type WebSocketFactory = (url: string) => WebSocketLike;
 export interface CoordinatorStreamOptions {
@@ -47,6 +57,20 @@ export interface CoordinatorStreamOptions {
      * once a subsequent `getRun` is guaranteed terminal.
      */
     readonly isTerminal?: (event: AexEvent) => boolean;
+    /**
+     * Half-open watchdog window. If no frame (a real event OR a keep-alive pong)
+     * arrives within this many ms, the socket is treated as dead and reconnected
+     * (resume from cursor). Default 45s. Set 0 to disable.
+     */
+    readonly idleTimeoutMs?: number;
+    /**
+     * Client keep-alive ping cadence. The client sends {@link COORDINATOR_PING},
+     * which the coordinator auto-responds to WITHOUT waking the durable object, so
+     * a legitimately quiet run keeps the socket measurably alive and does not trip
+     * the watchdog. Default 15s. Set 0 to disable (then only real events reset the
+     * watchdog → quiet runs may reconnect).
+     */
+    readonly pingIntervalMs?: number;
 }
 export declare function streamCoordinatorEvents(opts: CoordinatorStreamOptions): AsyncGenerator<AexEvent, void, void>;
 /** Async-iterable filter — keep only events matching the predicate. */

package/dist/_contracts/event-stream-client.js

@@ -9,6 +9,14 @@
  * reconnects (no gap, no duplicate). It stops on a terminal event, on abort,
  * or when the caller breaks the iterator.
  *
+ * A silently half-open socket (no close/error, no frames) is the dangerous
+ * case: the read loop would block forever and MISS a terminal that was already
+ * persisted server-side. So the client sends a tiny keep-alive ping the
+ * coordinator auto-responds to (hibernation-safe, no DO wake) and runs an idle
+ * watchdog: if no frame arrives within {@link CoordinatorStreamOptions.idleTimeoutMs},
+ * the socket is treated as dead and reconnected — resume-from-cursor then
+ * replays the terminal.
+ *
  * Filtering and projection are the client's concern (the wire carries the
  * whole run): compose {@link filterStream} with the envelope guards, and
  * {@link mapStream} with {@link toAGUI}, on top of this stream.
@@ -17,11 +25,23 @@
  * (Bun and Node 22+ ship it; no dependency) and tests drive a fake.
  */
 const isTerminalType = (e) => e.type === "RUN_FINISHED" || e.type === "RUN_ERROR";
+/**
+ * Keep-alive ping the client sends; the coordinator answers it via
+ * `setWebSocketAutoResponse` without waking the DO. Must stay byte-identical to
+ * the coordinator's pair (aex-platform `packages/shared/src/event-stream-client.ts`).
+ */
+const COORDINATOR_PING = "aex:ping";
+/** Default half-open watchdog window — 3× the ping cadence, so 2 pongs can be lost. */
+const DEFAULT_IDLE_TIMEOUT_MS = 45_000;
+/** Default client keep-alive ping cadence. */
+const DEFAULT_PING_INTERVAL_MS = 15_000;
 export async function* streamCoordinatorEvents(opts) {
     const makeWs = opts.webSocketFactory ?? ((url) => new WebSocket(url));
     const isTerminal = opts.isTerminal ?? isTerminalType;
     const reconnectDelayMs = opts.reconnectDelayMs ?? 500;
     const maxReconnects = opts.maxReconnects ?? Number.POSITIVE_INFINITY;
+    const idleTimeoutMs = opts.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    const pingIntervalMs = opts.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
     let cursor = (opts.from ?? 0) - 1;
     let attempts = 0;
     let done = false;
@@ -42,7 +62,50 @@ export async function* streamCoordinatorEvents(opts) {
                 r();
             }
         };
+        let idleTimer = null;
+        let pingTimer = null;
+        const stopTimers = () => {
+            if (idleTimer !== null) {
+                clearTimeout(idleTimer);
+                idleTimer = null;
+            }
+            if (pingTimer !== null) {
+                clearInterval(pingTimer);
+                pingTimer = null;
+            }
+        };
+        // Re-arm on every inbound frame. On expiry the socket is presumed half-open
+        // → close it and let the loop fall through to reconnect (resume from cursor).
+        const armIdle = () => {
+            if (idleTimeoutMs <= 0)
+                return;
+            if (idleTimer !== null)
+                clearTimeout(idleTimer);
+            idleTimer = setTimeout(() => {
+                idleTimer = null;
+                if (closed)
+                    return;
+                closed = true;
+                disconnectReason = "idle";
+                closeQuietly(ws);
+                wake();
+            }, idleTimeoutMs);
+        };
+        ws.addEventListener("open", () => {
+            armIdle();
+            if (pingIntervalMs > 0 && typeof ws.send === "function") {
+                pingTimer = setInterval(() => {
+                    try {
+                        ws.send(COORDINATOR_PING);
+                    }
+                    catch {
+                        // socket not open / send unsupported — the idle watchdog still covers it
+                    }
+                }, pingIntervalMs);
+            }
+        });
         ws.addEventListener("message", (ev) => {
+            armIdle();
             const data = typeof ev.data === "string" ? ev.data : "";
             if (!data)
                 return;
@@ -58,22 +121,33 @@ export async function* streamCoordinatorEvents(opts) {
             }
         });
         ws.addEventListener("close", (ev) => {
-            closed = true;
-            const code = ev?.code;
-            disconnectReason = `close${typeof code === "number" ? ` code=${code}` : ""}`;
+            stopTimers();
+            // Don't clobber a reason already decided (idle/abort closes the socket too).
+            if (!closed) {
+                closed = true;
+                const code = ev?.code;
+                disconnectReason = `close${typeof code === "number" ? ` code=${code}` : ""}`;
+            }
             wake();
         });
         ws.addEventListener("error", () => {
-            closed = true;
-            disconnectReason = "error";
+            stopTimers();
+            if (!closed) {
+                closed = true;
+                disconnectReason = "error";
+            }
             wake();
         });
         const onAbort = () => {
             closeQuietly(ws);
             closed = true;
+            stopTimers();
             wake();
         };
         opts.signal?.addEventListener("abort", onAbort, { once: true });
+        // Arm immediately: a connect that never reaches "open" (and fakes that
+        // never emit it) must still time out rather than hang forever.
+        armIdle();
         try {
             while (true) {
                 while (queue.length > 0) {
@@ -95,6 +169,7 @@ export async function* streamCoordinatorEvents(opts) {
             }
         }
         finally {
+            stopTimers();
             opts.signal?.removeEventListener("abort", onAbort);
         }
         if (done || opts.signal?.aborted)

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  *
  * Used by the (future) User-Agent header on outbound SDK requests.
  */
-export declare const SDK_VERSION = "0.28.0";
+export declare const SDK_VERSION = "0.28.1";

package/dist/version.js

@@ -6,5 +6,5 @@
  *
  * Used by the (future) User-Agent header on outbound SDK requests.
  */
-export const SDK_VERSION = "0.28.0";
+export const SDK_VERSION = "0.28.1";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "description": "TypeScript SDK for running autonomous agent sessions across providers (Anthropic, OpenAI, DeepSeek, Gemini, Mistral) behind one interface.",
   "license": "Apache-2.0",
   "repository": {