statewire 0.0.3 → 0.0.5

package/src/client/session.ts

@@ -147,6 +147,12 @@ const rejectedSend = (
 
 type AttachState = "detached" | "attached" | "finished";
 
+export type StatewireSessionOptions = StatewireSessionStoreOptions & {
+  onCommandSessionLost?:
+    | ((command: StatewireClient.SessionLostCommand) => "replay" | void)
+    | undefined;
+};
+
 type Session = {
   record: StatewireSessionRecord;
   ctx: StatewireRemoteProps;
@@ -166,13 +172,14 @@ type Session = {
   transport: RemoteLink | null;
   waiters: (() => void)[];
   lifecycle: CommandsListener | null;
+  onCommandSessionLost: StatewireSessionOptions["onCommandSessionLost"];
   notify: () => void;
   emitEvent: (event: unknown) => void;
   send: (command: StatewireWireCommand) => Promise<unknown>;
   commands: Record<string, (...params: unknown[]) => Promise<unknown>>;
 };
 
-const createSession = (options: StatewireSessionStoreOptions): Session => {
+const createSession = (options: StatewireSessionOptions): Session => {
   const store = options.sessionStore ?? createMemorySessionStore();
   const stored = store.load();
   const record = stored ?? { clientId: newClientId(), nextSeq: 1 };
@@ -212,6 +219,7 @@ const createSession = (options: StatewireSessionStoreOptions): Session => {
     transport: null,
     waiters: [],
     lifecycle: null,
+    onCommandSessionLost: options.onCommandSessionLost,
     notify: () => {},
     emitEvent: () => {},
     send: (command) => sendCommand(s, command),
@@ -274,10 +282,12 @@ const settleAll = (
     if (state.at === "awaiting-result")
       return { fate: "result-unavailable", cause };
     if (state.at === "queued") {
-      const cascades = batch.some(
+      const predecessorLost = batch.some(
         (p) => p.seq < entry.seq && p.state.at !== "queued",
       );
-      return { fate: "aborted", cause: cascades ? "cascade" : cause };
+      return predecessorLost
+        ? { fate: "aborted", cause, predecessorLost }
+        : { fate: "aborted", cause };
     }
     return { fate: "lost", cause };
   };
@@ -288,6 +298,27 @@ const settleAll = (
   }
 };
 
+// Offers every unsettled real command for replay, in seq order. Not caught:
+// a throwing callback aborts the eviction before any entry settles; the
+// attach retry evicts again and re-offers.
+const claimReplays = (s: Session): Pending[] => {
+  const handler = s.onCommandSessionLost;
+  if (!handler) return [];
+  const claimed = new Set<Pending>();
+  for (const entry of s.pending) {
+    if (!entry.inv || isResolved(entry.state)) continue;
+    const decision = handler({
+      method: entry.inv.method,
+      params: [...entry.inv.params],
+      seq: entry.seq,
+    });
+    if (decision === "replay") claimed.add(entry);
+  }
+  if (claimed.size === 0) return [];
+  s.pending = s.pending.filter((p) => !claimed.has(p));
+  return [...claimed];
+};
+
 const evict = (
   s: Session,
   verdict?: {
@@ -295,6 +326,7 @@ const evict = (
     failure: StatewireClient.SendFailure;
   },
 ) => {
+  const replays = claimReplays(s);
   settleAll(s, "evicted", verdict);
   s.record = { clientId: newClientId(), nextSeq: 1 };
   s.store.save(s.record);
@@ -302,6 +334,10 @@ const evict = (
   // The server dropped this client's record and its stored context with it:
   // the new session opens with a fresh full root replace.
   if (s.context !== undefined) void s.send({ context: s.context });
+  for (const old of replays) {
+    if (old.inv) s.lifecycle?.onCovered?.(old.inv);
+    enqueue(s, old.command, old.resolve, old.reject);
+  }
   publish(s);
   wake(s);
 };
@@ -645,16 +681,12 @@ const setTransport = (s: Session, transport: RemoteLink) => {
   wake(s);
 };
 
-const sendCommand = (
+const enqueue = (
   s: Session,
   command: StatewireWireCommand,
-): Promise<unknown> => {
-  if (!s.running) {
-    return rejectedSend({ fate: "aborted", cause: "unmount" });
-  }
-  if (isFinished(s)) {
-    return rejectedSend({ fate: "aborted", cause: "stream-gone" });
-  }
+  resolve: (payload: unknown) => void,
+  reject: (error: StatewireSendError) => void,
+) => {
   const seq = s.record.nextSeq;
   s.record = { ...s.record, nextSeq: seq + 1 };
   s.store.save(s.record);
@@ -672,17 +704,28 @@ const sendCommand = (
             clientId: s.record.clientId,
           },
     state: { at: "queued", pendingMarked: false },
-    resolve: () => {},
-    reject: () => {},
+    resolve,
+    reject,
   };
-  const result = new Promise<unknown>((resolve, reject) => {
-    entry.resolve = resolve;
-    entry.reject = reject;
-  });
-  result.catch(() => {});
   s.pending.push(entry);
   if (entry.inv) s.lifecycle?.onStart(entry.inv);
   void pump(s);
+};
+
+const sendCommand = (
+  s: Session,
+  command: StatewireWireCommand,
+): Promise<unknown> => {
+  if (!s.running) {
+    return rejectedSend({ fate: "aborted", cause: "unmount" });
+  }
+  if (isFinished(s)) {
+    return rejectedSend({ fate: "aborted", cause: "stream-gone" });
+  }
+  const result = new Promise<unknown>((resolve, reject) => {
+    enqueue(s, command, resolve, reject);
+  });
+  result.catch(() => {});
   return result;
 };
 
@@ -698,10 +741,11 @@ const setContext = (
 };
 
 export const useStatewireSession = (
-  options: StatewireSessionStoreOptions,
+  options: StatewireSessionOptions,
   emit: (event: unknown) => void,
 ): Session => {
   const [s] = useState(() => createSession(options));
+  s.onCommandSessionLost = options.onCommandSessionLost;
   useEffect(() => {
     s.emitEvent = emit;
     return () => {

package/src/host/host.ts

@@ -250,6 +250,9 @@ const STALL_WARN_MS = 5000;
 
 // In-process dispatch has no wire client: never any ambient context, trivially attached.
 const LOCAL_CALLER: StatewireHost.Caller = Object.freeze({
+  get clientId(): string {
+    throw new Error("statewire: in-process dispatch has no client id");
+  },
   context: null,
   isConnected: true,
 });

package/src/host/socket.ts

@@ -387,6 +387,7 @@ const createSocketHost = (
   ) => settleResponse(rec, adm, responseOf(adm, outcome));
 
   const callerOf = (rec: ClientRec): StatewireHost.Caller => ({
+    clientId: rec.id,
     get context() {
       return rec.context;
     },

package/src/host.ts

@@ -48,11 +48,13 @@ export namespace StatewireHost {
 
   /**
    * The submitting client, bound as `this` of a command handler. Holdable
-   * across a long run: `context` reads the client's current ambient context
-   * live (null until the client sends one), `isConnected` reports whether the
-   * client has an active stream attachment.
+   * across a long run: `clientId` is the client's `Statewire-Client-Id`
+   * (in-process dispatch has none — reading it throws), `context` reads the
+   * client's current ambient context live (null until the client sends one),
+   * `isConnected` reports whether the client has an active stream attachment.
    */
   export type Caller = {
+    readonly clientId: string;
     readonly context: Record<string, unknown> | null;
     readonly isConnected: boolean;
   };

package/src/statewire.ts

@@ -8,7 +8,6 @@ import {
 import type { ResourceElement } from "@assistant-ui/tap";
 import { LIVE_CONNECTION, useStatewireCore } from "./client/core";
 import type { Statewire } from "./types";
-import type { ConnectionState } from "./transports/sse";
 import type { StatewireSessionStoreOptions } from "./client/sessionStore";
 
 export const useStatewire = <
@@ -136,6 +135,18 @@ export namespace StatewireClient {
     setContext: (value: Record<string, unknown>) => Promise<unknown>;
   };
 
+  export type ConnectionState =
+    | { status: "connecting" }
+    | { status: "live" }
+    | {
+        status: "reconnecting";
+        cause: "dropped" | "evicted" | "error";
+        attempt: number;
+        nextRetryAt: number;
+        lastError?: string;
+        message?: string;
+      }
+    | { status: "gone"; message?: string; payload?: unknown };
   export type Connection = ConnectionState & { reconnect: () => void };
   export type ConnectionStatus = Connection["status"];
 
@@ -183,23 +194,31 @@ export namespace StatewireClient {
       }
     | {
         fate: "aborted";
-        cause:
-          | "cascade"
-          | "unmount"
-          | "stream-gone"
-          | "session-lost"
-          | "superseded";
+        cause: "unmount" | "stream-gone" | "session-lost" | "superseded";
+        predecessorLost?: true;
       }
     | {
         fate: "lost";
         cause: "unmount" | "stream-gone" | "session-lost" | "superseded";
       };
 
+  /**
+   * A pending command offered for replay while the session is being evicted.
+   * Return "replay" to re-enqueue it under the rotated client id instead of
+   * settling it as a session-lost failure.
+   */
+  export type SessionLostCommand = {
+    method: string;
+    params: unknown[];
+    seq: number;
+  };
+
   export type SSEOptions = StatewireSessionStoreOptions & {
     url: string;
     headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
     fetch?: typeof globalThis.fetch;
     onChange?: (connection: Connection) => void;
+    onCommandSessionLost?: (command: SessionLostCommand) => "replay" | void;
   };
 
   export type WSOptions = StatewireSessionStoreOptions & {
@@ -210,5 +229,6 @@ export namespace StatewireClient {
       | (() => Record<string, string> | Promise<Record<string, string>>);
     webSocket?: new (url: string, protocols?: string | string[]) => WebSocket;
     onChange?: (connection: Connection) => void;
+    onCommandSessionLost?: (command: SessionLostCommand) => "replay" | void;
   };
 }

package/src/transports/remote.ts

@@ -6,7 +6,7 @@ import {
   setTransport,
   useStatewireSession,
 } from "../client/session";
-import type { StatewireSessionStoreOptions } from "../client/sessionStore";
+import type { StatewireSessionOptions } from "../client/session";
 import type { StatewireClient } from "../statewire";
 import type { RemoteLink, StatewireRemoteProps } from "./sse";
 
@@ -14,13 +14,19 @@ export const useStatewireRemote = <
   TOptions extends {
     url: string;
     onChange?: (connection: StatewireClient.Connection) => void;
-  } & StatewireSessionStoreOptions,
+  } & StatewireSessionOptions,
 >(
   options: TOptions,
   useLink: (options: TOptions, ctx: StatewireRemoteProps) => RemoteLink,
 ): Statewire<any, any, any> => {
   const emit = useStatewireEmit<any>();
-  const s = useStatewireSession({ sessionStore: options.sessionStore }, emit);
+  const s = useStatewireSession(
+    {
+      sessionStore: options.sessionStore,
+      onCommandSessionLost: options.onCommandSessionLost,
+    },
+    emit,
+  );
   const conn = useLink(options, s.ctx);
   useEffect(() => setTransport(s, conn), [s, conn]);
 

package/src/transports/sse.ts

@@ -58,18 +58,7 @@ export type StatewireSubmitResult =
   | { type: "unknown-client" }
   | { type: "stale-lease" };
 
-export type ConnectionState =
-  | { status: "connecting" }
-  | { status: "live" }
-  | {
-      status: "reconnecting";
-      cause: "dropped" | "evicted" | "error";
-      attempt: number;
-      nextRetryAt: number;
-      lastError?: string;
-      message?: string;
-    }
-  | { status: "gone"; message?: string; payload?: unknown };
+export type ConnectionState = StatewireClient.ConnectionState;
 
 /** The live wire a remote session drives: connection status plus command POST. */
 export type RemoteLink = {