statewire 0.13.1 → 0.14.0

package/src/host-internal.ts

@@ -14,9 +14,20 @@ export namespace StatewireHostInternal {
     close: () => void;
   };
 
+  export type SocketConnectOptions = {
+    /** The adapter restored this socket from an already-authorized session. */
+    authorized?: boolean;
+    /** Persist authorization before the first snapshot is released. */
+    onAuthorized?: () => void;
+  };
+
   export type SocketHost = {
     /** Null means refused: the socket was told (fin and/or close) and is dead. */
-    connect: (clientId: string, socket: Socket) => SocketConnection | null;
+    connect: (
+      clientId: string,
+      socket: Socket,
+      options?: SocketConnectOptions,
+    ) => SocketConnection | null;
     stream: (request: Request) => Promise<Response>;
     frames: (request: Request) => Promise<Response>;
     finish: (fin: StatewireHost.Fin) => void;
@@ -27,6 +38,8 @@ export namespace StatewireHostInternal {
     authorize?: (ctx: {
       headers: Record<string, string>;
     }) => void | Promise<void>;
+    /** Time allowed to complete WebSocket initialization and authorization. */
+    wsInitTimeoutMs?: number;
     heartbeatIntervalMs?: number;
     /** LRU cap on stored client records; live or in-flight records are exempt. */
     clientRecordLimit?: number;

package/src/statewire.ts

@@ -9,7 +9,7 @@ import {
   withKey,
 } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
-import { LIVE_CONNECTION, useStatewireCore } from "./client/core";
+import { CONNECTED_CONNECTION, useStatewireCore } from "./client/core";
 import type { Statewire } from "./types";
 import type { TERMINAL } from "./client/connection";
 import { SessionStorageContext } from "./client/sessionStore";
@@ -64,7 +64,7 @@ export const useStatewire = <
     core.getFailed,
     core.getFailed,
   );
-  const connection = value.connection ?? LIVE_CONNECTION;
+  const connection = value.connection ?? CONNECTED_CONNECTION;
 
   return useMemo(() => {
     const failures = (): NonNullable<typeof value.failures> => {
@@ -211,20 +211,29 @@ export namespace StatewireClient {
     discardFailed: (entry: FailedCommand) => void;
   };
 
+  /** `cause`/`nextRetryAt`/`lastError` are present only while waiting out the backoff timer; a dial in flight carries `attempt` alone. */
   export type ConnectionState =
-    | { status: "connecting" }
-    | { status: "live" }
-    | { status: "idle" }
     | {
-        status: "reconnecting";
-        cause: "dropped" | "evicted" | "error" | "unauthorized";
+        status: "disconnected";
+        reason: "deferred" | "idle" | "gone";
+        message?: string;
+        payload?: unknown;
+      }
+    | {
+        status: "connecting";
+        /** 0 = the episode's first dial, >0 = retry. */
         attempt: number;
-        nextRetryAt: number;
+        cause?: "dropped" | "evicted" | "error" | "unauthorized";
+        nextRetryAt?: number;
         lastError?: string;
         message?: string;
       }
-    | { status: "gone"; message?: string; payload?: unknown };
-  export type Connection = ConnectionState & { reconnect: () => void };
+    | { status: "connected" };
+  export type Connection = ConnectionState & {
+    reconnect: () => void;
+    /** True while retrying (`connecting` with `attempt > 0`) or parked `gone`. */
+    degraded: boolean;
+  };
   export type ConnectionStatus = Connection["status"];
 
   /**