@vincemakes/kiso-client 0.53.0 → 0.54.1

package/dist/client.d.ts

@@ -16,12 +16,28 @@ export interface ClientOptions {
     readonly headers?: () => Record<string, string> | Promise<Record<string, string>>;
     /** Injected for tests or non-global environments. Default: globalThis.fetch. */
     readonly fetch?: typeof fetch;
-    /** Reconnect backoff for `events()`: first wait and cap, in ms. */
+    /** Reconnect backoff for `events()`: first wait and cap, in ms (defaults 250 and 30 000), jittered to 0.5..1 of the step;
+     *  `idleMs`: no frame (event or keepalive comment) for this long and the connection is dead (default 35 000). */
     readonly reconnect?: {
         readonly initialMs?: number;
         readonly maxMs?: number;
+        readonly idleMs?: number;
     };
 }
+/** Where `events()` is: dialing, streaming, waiting to dial again (attempt, and the time of the next try), or turned away for good. */
+export type ConnectionState = {
+    readonly kind: "connecting";
+} | {
+    readonly kind: "open";
+} | {
+    readonly kind: "retrying";
+    readonly attempt: number;
+    readonly nextAt: number;
+} | {
+    readonly kind: "refused";
+    readonly status: number;
+    readonly code: WireErrorCode;
+};
 /** A non-2xx reply, carrying the wire's error shape. */
 export declare class ClientError extends Error {
     readonly status: number;
@@ -53,6 +69,10 @@ export interface EventsOptions {
     readonly until?: (event: ClientEvent) => boolean;
     /** Called before each reconnect with the attempt number and the wait. */
     readonly onReconnect?: (attempt: number, waitMs: number) => void;
+    /** Called on every change of the connection's state. A refusal (a 4xx) is reported here and ends the stream. */
+    readonly onState?: (state: ConnectionState) => void;
+    /** While true no reconnect is tried (a hidden tab); `retryNow()` or the next check ends the wait. */
+    readonly paused?: () => boolean;
 }
 export interface RunStreamOptions extends Omit<EventsOptions, "until"> {
     readonly source?: WireSource;
@@ -61,6 +81,8 @@ export interface RunStreamOptions extends Omit<EventsOptions, "until"> {
 export declare class SessionClient {
     #private;
     readonly id: string;
+    /** Cut a sleeping reconnect wait short and dial now (the browser came back online, the tab became visible, a button). */
+    retryNow(): void;
     constructor(options: ClientOptions, sessionId: string);
     /** Start a turn; refusals arrive as ClientError (in_flight, open_run, draining, forbidden). */
     run(input: WireInput, options?: {
@@ -75,6 +97,11 @@ export declare class SessionClient {
     steer(input: WireInput): Promise<SteerReply>;
     resume(): Promise<RunReply>;
     /** Stop the run in flight. A parked run is a REPLY (kind "parked"), not an error. */
+    /** ADR-0057 — take back the steers the live run has not admitted yet; `count` is how many. */
+    retract(): Promise<{
+        readonly runId: string | null;
+        readonly count: number;
+    }>;
     abort(options?: {
         force?: boolean;
     }): Promise<AbortReply>;

package/dist/client.js

@@ -15,6 +15,11 @@ export class ClientError extends Error {
 export class SessionClient {
     #options;
     id;
+    #wake = null;
+    /** Cut a sleeping reconnect wait short and dial now (the browser came back online, the tab became visible, a button). */
+    retryNow() {
+        this.#wake?.();
+    }
     constructor(options, sessionId) {
         this.#options = options;
         this.id = sessionId;
@@ -67,6 +72,10 @@ export class SessionClient {
         return this.#json(await this.#request("POST", "resume", {}));
     }
     /** Stop the run in flight. A parked run is a REPLY (kind "parked"), not an error. */
+    /** ADR-0057 — take back the steers the live run has not admitted yet; `count` is how many. */
+    async retract() {
+        return this.#json(await this.#request("POST", "retract", {}));
+    }
     async abort(options = {}) {
         return this.#json(await this.#request("POST", "abort", options), [200, 409]);
     }
@@ -102,29 +111,40 @@ export class SessionClient {
         let lastSeq = options.after ?? -1;
         let attempt = 0;
         const initial = this.#options.reconnect?.initialMs ?? 250;
-        const cap = this.#options.reconnect?.maxMs ?? 5_000;
+        const cap = this.#options.reconnect?.maxMs ?? 30_000;
+        const idle = this.#options.reconnect?.idleMs ?? 35_000;
+        const report = options.onState ?? (() => { });
         for (;;) {
             if (options.signal?.aborted)
                 return;
-            let res;
+            report({ kind: "connecting" });
+            // the watchdog: no frame for `idle` aborts this connection, and the loop below dials again
+            const conn = new AbortController();
+            const forward = () => conn.abort();
+            options.signal?.addEventListener("abort", forward, { once: true });
+            let dog;
+            const feed = () => {
+                clearTimeout(dog);
+                dog = setTimeout(forward, idle);
+            };
+            feed();
             try {
-                res = await this.#request("GET", "events", undefined, {
-                    headers: { accept: "text/event-stream", "last-event-id": String(lastSeq) },
-                    ...(options.signal !== undefined ? { signal: options.signal } : {}),
-                });
-            }
-            catch (err) {
-                if (options.signal?.aborted)
-                    return;
-                res = null;
-                void err;
-            }
-            if (res !== null) {
-                if (res.status !== 200 || res.body === null)
-                    await this.#json(res, []); // a refusal is final: forbidden, not_found
-                attempt = 0;
-                try {
+                const res = await this.#request("GET", "events", undefined, { headers: { accept: "text/event-stream", "last-event-id": String(lastSeq) }, signal: conn.signal });
+                if (res.status >= 400 && res.status < 500) {
+                    try {
+                        await this.#json(res, []);
+                    }
+                    catch (err) {
+                        if (err instanceof ClientError)
+                            report({ kind: "refused", status: err.status, code: err.code });
+                    }
+                    return; // a refusal is final, and now it is said
+                }
+                if (res.status === 200 && res.body !== null) {
+                    attempt = 0;
+                    report({ kind: "open" });
                     for await (const frame of readSse(res.body)) {
+                        feed();
                         if (options.signal?.aborted)
                             return;
                         const ev = toClientEvent(frame);
@@ -140,18 +160,41 @@ export class SessionClient {
                             return;
                     }
                 }
-                catch {
-                    // the connection dropped mid-stream — fall through to reconnect
-                }
+            }
+            catch {
+                // the connection dropped or went silent — fall through to reconnect
+            }
+            finally {
+                clearTimeout(dog);
+                options.signal?.removeEventListener("abort", forward);
             }
             if (options.signal?.aborted)
                 return;
             attempt += 1;
-            const wait = Math.min(cap, initial * 2 ** (attempt - 1));
+            const wait = (0.5 + Math.random() / 2) * Math.min(cap, initial * 2 ** (attempt - 1));
             options.onReconnect?.(attempt, wait);
-            await sleep(wait, options.signal);
+            report({ kind: "retrying", attempt, nextAt: Date.now() + wait });
+            await this.#nap(wait, options.signal);
+            while (options.paused?.() === true && options.signal?.aborted !== true)
+                await this.#nap(1_000, options.signal);
         }
     }
+    #nap(ms, signal) {
+        return new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", done);
+                this.#wake = null;
+                resolve();
+            };
+            const timer = setTimeout(done, ms);
+            this.#wake = done;
+            if (signal?.aborted)
+                done();
+            else
+                signal?.addEventListener("abort", done, { once: true });
+        });
+    }
 }
 export class KisoClient {
     #options;
@@ -182,16 +225,3 @@ function toClientEvent(frame) {
 function isWireError(value) {
     return typeof value === "object" && value !== null && typeof value.code === "string" && typeof value.message === "string";
 }
-function sleep(ms, signal) {
-    return new Promise((resolve) => {
-        if (signal?.aborted)
-            return resolve();
-        const timer = setTimeout(done, ms);
-        function done() {
-            clearTimeout(timer);
-            signal?.removeEventListener("abort", done);
-            resolve();
-        }
-        signal?.addEventListener("abort", done, { once: true });
-    });
-}

package/dist/index.d.ts

@@ -6,6 +6,6 @@
  * event. Browser and Node; depends on `@vincemakes/kiso-protocol` alone.
  */
 export { ClientError, createClient, KisoClient, SessionClient } from "./client.js";
-export type { ClientEvent, ClientOptions, EventsOptions, RunStreamOptions } from "./client.js";
+export type { ClientEvent, ClientOptions, ConnectionState, EventsOptions, RunStreamOptions } from "./client.js";
 export { parseSseBlock, readSse } from "./sse.js";
 export type { SseFrame } from "./sse.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-client",
-	"version": "0.53.0",
+	"version": "0.54.1",
 	"description": "kiso client — the typed client for a hosted kiso session over the wire protocol: run, resume, abort, approve, the snapshot, and a stream that reconnects with Last-Event-ID and never repeats an event. Browser and Node; depends on the protocol package only.",
 	"type": "module",
 	"license": "MIT",
@@ -21,13 +21,13 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@vincemakes/kiso-protocol": "0.53.0"
+		"@vincemakes/kiso-protocol": "0.54.1"
 	},
 	"devDependencies": {
-		"@vincemakes/kiso-core": "0.53.0",
-		"@vincemakes/kiso-evals": "0.53.0",
-		"@vincemakes/kiso-runtime": "0.53.0",
-		"@vincemakes/kiso-server": "0.53.0",
+		"@vincemakes/kiso-core": "0.54.1",
+		"@vincemakes/kiso-evals": "0.54.1",
+		"@vincemakes/kiso-runtime": "0.54.1",
+		"@vincemakes/kiso-server": "0.54.1",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"