@getuserfeedback/protocol 3.1.3 → 3.1.4

package/dist/host/flow-command-handle-controller.d.ts

@@ -0,0 +1,16 @@
+export type FlowCommandHandleController<THandleId extends string, TSettlement> = {
+    runCommand<TPayload>(buildPayload: (handleId: THandleId | undefined) => TPayload, dispatchAndWait: (payload: TPayload) => Promise<TSettlement>): Promise<TSettlement>;
+    getHandleId(): THandleId | undefined;
+    hasHandleId(handleId: string): boolean;
+    hasPendingCommands(): boolean;
+    subscribeHandle(subscriber: (handleId: THandleId) => void): () => void;
+    clearResolvedHandle(): THandleId | undefined;
+    reset(): void;
+};
+export type CreateFlowCommandHandleControllerOptions<THandleId extends string, TSettlement> = {
+    getHandleIdFromSettlement: (settlement: TSettlement) => THandleId | undefined;
+    isStaleHandleError: (error: unknown) => boolean;
+    onClearResolvedHandle?: (handleId: THandleId) => void;
+};
+export declare function createFlowCommandHandleController<THandleId extends string, TSettlement>({ getHandleIdFromSettlement, isStaleHandleError, onClearResolvedHandle, }: CreateFlowCommandHandleControllerOptions<THandleId, TSettlement>): FlowCommandHandleController<THandleId, TSettlement>;
+//# sourceMappingURL=flow-command-handle-controller.d.ts.map

package/dist/host/flow-command-handle-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-command-handle-controller.d.ts","sourceRoot":"","sources":["../../src/host/flow-command-handle-controller.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,2BAA2B,CACtC,SAAS,SAAS,MAAM,EACxB,WAAW,IACR;IACH,UAAU,CAAC,QAAQ,EAClB,YAAY,EAAE,CAAC,QAAQ,EAAE,SAAS,GAAG,SAAS,KAAK,QAAQ,EAC3D,eAAe,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,WAAW,CAAC,GAC1D,OAAO,CAAC,WAAW,CAAC,CAAC;IACxB,WAAW,IAAI,SAAS,GAAG,SAAS,CAAC;IACrC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACvC,kBAAkB,IAAI,OAAO,CAAC;IAC9B,eAAe,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACvE,mBAAmB,IAAI,SAAS,GAAG,SAAS,CAAC;IAC7C,KAAK,IAAI,IAAI,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,wCAAwC,CACnD,SAAS,SAAS,MAAM,EACxB,WAAW,IACR;IACH,yBAAyB,EAAE,CAAC,UAAU,EAAE,WAAW,KAAK,SAAS,GAAG,SAAS,CAAC;IAC9E,kBAAkB,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAChD,qBAAqB,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;CACtD,CAAC;AAEF,wBAAgB,iCAAiC,CAChD,SAAS,SAAS,MAAM,EACxB,WAAW,EACV,EACD,yBAAyB,EACzB,kBAAkB,EAClB,qBAAqB,GACrB,EAAE,wCAAwC,CAC1C,SAAS,EACT,WAAW,CACX,GAAG,2BAA2B,CAAC,SAAS,EAAE,WAAW,CAAC,CA6CtD"}

package/dist/host/flow-command-handle-controller.js

@@ -0,0 +1,39 @@
+import { createLazyHandleClient, } from "./lazy-handle-client.js";
+export function createFlowCommandHandleController({ getHandleIdFromSettlement, isStaleHandleError, onClearResolvedHandle, }) {
+    const handleClient = createLazyHandleClient({
+        getHandleIdFromSettlement,
+    });
+    const clearResolvedHandle = () => {
+        const previousHandleId = handleClient.getHandleId();
+        if (!previousHandleId) {
+            return undefined;
+        }
+        handleClient.reset();
+        onClearResolvedHandle?.(previousHandleId);
+        return previousHandleId;
+    };
+    const reset = () => {
+        const previousHandleId = handleClient.getHandleId();
+        handleClient.reset();
+        if (previousHandleId) {
+            onClearResolvedHandle?.(previousHandleId);
+        }
+    };
+    const runCommand = async (buildPayload, dispatchAndWait) => {
+        return handleClient.runCommandWithRetry(buildPayload, dispatchAndWait, {
+            shouldRetry: isStaleHandleError,
+            onBeforeRetry: () => {
+                clearResolvedHandle();
+            },
+        });
+    };
+    return {
+        runCommand,
+        getHandleId: () => handleClient.getHandleId(),
+        hasHandleId: (handleId) => handleClient.getHandleId() === handleId,
+        hasPendingCommands: () => handleClient.hasPendingCommands(),
+        subscribeHandle: (subscriber) => handleClient.subscribeHandle(subscriber),
+        clearResolvedHandle,
+        reset,
+    };
+}

package/dist/host/index.d.ts

@@ -6,6 +6,7 @@ export * from "./command-envelope.js";
 export * from "./command-settlement.js";
 export * from "./constants.js";
 export * from "./external-id-argument-guards.js";
+export * from "./flow-command-handle-controller.js";
 export * from "./host-event-contract.js";
 export * from "./lazy-handle-client.js";
 export { createCommandRequestId } from "./request-id.js";

package/dist/host/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oCAAoC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kCAAkC,CAAC;AACjD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oCAAoC,CAAC"}

package/dist/host/index.js

@@ -6,6 +6,7 @@ export * from "./command-envelope.js";
 export * from "./command-settlement.js";
 export * from "./constants.js";
 export * from "./external-id-argument-guards.js";
+export * from "./flow-command-handle-controller.js";
 export * from "./host-event-contract.js";
 export * from "./lazy-handle-client.js";
 export { createCommandRequestId } from "./request-id.js";

package/dist/host/lazy-handle-client.d.ts

@@ -8,7 +8,12 @@ type StageMap<TStage extends string> = {
 };
 export type LazyHandleClient<THandleId extends string, TSettlement, TStage extends string = LifecycleStage> = {
     runCommand<TPayload>(buildPayload: (handleId: THandleId | undefined) => TPayload, dispatchAndWait: (payload: TPayload) => Promise<TSettlement>): Promise<TSettlement>;
+    runCommandWithRetry<TPayload>(buildPayload: (handleId: THandleId | undefined) => TPayload, dispatchAndWait: (payload: TPayload) => Promise<TSettlement>, options: {
+        shouldRetry: (error: unknown) => boolean;
+        onBeforeRetry?: (error: unknown) => void;
+    }): Promise<TSettlement>;
     getHandleId(): THandleId | undefined;
+    hasPendingCommands(): boolean;
     subscribeHandle(subscriber: Subscriber<THandleId>): () => void;
     getStage(): TStage;
     setStage(stage: TStage): void;

package/dist/host/lazy-handle-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lazy-handle-client.d.ts","sourceRoot":"","sources":["../../src/host/lazy-handle-client.ts"],"names":[],"mappings":"AAAA,KAAK,UAAU,CAAC,SAAS,SAAS,MAAM,IAAI,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;AAC1E,KAAK,eAAe,CAAC,MAAM,SAAS,MAAM,IAAI,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;AAEtE,KAAK,cAAc,GAAG,eAAe,GAAG,OAAO,GAAG,aAAa,CAAC;AAChE,KAAK,QAAQ,CAAC,MAAM,SAAS,MAAM,IAAI;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACpB,CAAC;AAQF,MAAM,MAAM,gBAAgB,CAC3B,SAAS,SAAS,MAAM,EACxB,WAAW,EACX,MAAM,SAAS,MAAM,GAAG,cAAc,IACnC;IACH,UAAU,CAAC,QAAQ,EAClB,YAAY,EAAE,CAAC,QAAQ,EAAE,SAAS,GAAG,SAAS,KAAK,QAAQ,EAC3D,eAAe,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,WAAW,CAAC,GAC1D,OAAO,CAAC,WAAW,CAAC,CAAC;IACxB,WAAW,IAAI,SAAS,GAAG,SAAS,CAAC;IACrC,eAAe,CAAC,UAAU,EAAE,UAAU,CAAC,SAAS,CAAC,GAAG,MAAM,IAAI,CAAC;IAC/D,QAAQ,IAAI,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,CAAC,UAAU,EAAE,eAAe,CAAC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC;IAChE,KAAK,IAAI,IAAI,CAAC;IACd,UAAU,IAAI,IAAI,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,6BAA6B,CACxC,SAAS,SAAS,MAAM,EACxB,WAAW,EACX,MAAM,SAAS,MAAM,GAAG,cAAc,IACnC;IACH,yBAAyB,EAAE,CAAC,UAAU,EAAE,WAAW,KAAK,SAAS,GAAG,SAAS,CAAC;IAC9E,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,KAAK,oCAAoC,CACxC,SAAS,SAAS,MAAM,EACxB,WAAW,IACR;IACH,yBAAyB,EAAE,CAAC,UAAU,EAAE,WAAW,KAAK,SAAS,GAAG,SAAS,CAAC;IAC9E,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B,MAAM,CAAC,EAAE,SAAS,CAAC;CACnB,CAAC;AAEF,KAAK,mCAAmC,CACvC,SAAS,SAAS,MAAM,EACxB,WAAW,EACX,MAAM,SAAS,MAAM,IAClB;IACH,yBAAyB,EAAE,CAAC,UAAU,EAAE,WAAW,KAAK,SAAS,GAAG,SAAS,CAAC;IAC9E,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAuHF,wBAAgB,sBAAsB,CAAC,SAAS,SAAS,MAAM,EAAE,WAAW,EAC3E,OAAO,EAAE,oCAAoC,CAAC,SAAS,EAAE,WAAW,CAAC,GACnE,gBAAgB,CAAC,SAAS,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC;AAC5D,wBAAgB,sBAAsB,CACrC,SAAS,SAAS,MAAM,EACxB,WAAW,EACX,MAAM,SAAS,MAAM,EAErB,OAAO,EAAE,mCAAmC,CAAC,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC,GAC1E,gBAAgB,CAAC,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC"}
+{"version":3,"file":"lazy-handle-client.d.ts","sourceRoot":"","sources":["../../src/host/lazy-handle-client.ts"],"names":[],"mappings":"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"}

package/dist/host/lazy-handle-client.js

@@ -62,9 +62,49 @@ const createLazyHandleClientWithStages = (input) => {
         });
         return run;
     };
+    const runCommandWithRetry = (buildPayload, dispatchAndWait, options) => {
+        const execute = async () => {
+            let didRetry = false;
+            for (;;) {
+                if (stage === stages.invalidated) {
+                    throw new Error("Handle client is invalidated");
+                }
+                const commandEpoch = epoch;
+                const payload = buildPayload(handleId);
+                try {
+                    const settlement = await dispatchAndWait(payload);
+                    const settledHandleId = input.getHandleIdFromSettlement(settlement);
+                    if (settledHandleId && commandEpoch === epoch) {
+                        publishHandle(settledHandleId);
+                    }
+                    return settlement;
+                }
+                catch (error) {
+                    if (commandEpoch === epoch &&
+                        !didRetry &&
+                        options.shouldRetry(error)) {
+                        didRetry = true;
+                        options.onBeforeRetry?.(error);
+                        continue;
+                    }
+                    throw error;
+                }
+            }
+        };
+        const run = queuedCommandCount === 0 ? execute() : tail.then(execute, execute);
+        queuedCommandCount += 1;
+        tail = run.then(() => {
+            queuedCommandCount -= 1;
+        }, () => {
+            queuedCommandCount -= 1;
+        });
+        return run;
+    };
     return {
         runCommand,
+        runCommandWithRetry,
         getHandleId: () => handleId,
+        hasPendingCommands: () => queuedCommandCount > 0,
         subscribeHandle: (subscriber) => {
             subscribers.add(subscriber);
             if (handleId) {

package/dist/host/sdk.d.ts

@@ -4,6 +4,8 @@
  */
 export { createCommandDispatch } from "./command-dispatch.js";
 export { COMMAND_SETTLEMENT_TIMEOUT_CODE, CommandSettlementError, CommandSettlementTimeoutError, toCommandSettlementError, waitForCommandSettlement, } from "./command-settlement.js";
+export type { FlowCommandHandleController } from "./flow-command-handle-controller.js";
+export { createFlowCommandHandleController } from "./flow-command-handle-controller.js";
 export type { FlowHandleFromSettlement, FlowState, } from "./host-event-contract.js";
 export { getFlowHandleFromSettlementDetail, isFlowStateChangedDetail, isHandleInvalidatedDetail, isInstanceFlowStateChangedDetail, } from "./host-event-contract.js";
 export type { AppEventCapability, AppEventFlag, AppEventFlagProvider, AppEventFlagValue, AppEventPayload, CapabilitiesInput, ClientMeta, ClientOptions, Command, CommandEnvelope, ConfigureOptions, ContainerPolicy, FlagsInput, InitOptions, PublicCommandPayload, ResponseMetadataInput, TelemetryEvent, } from "./sdk-types.js";

package/dist/host/sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/host/sdk.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EACN,+BAA+B,EAC/B,sBAAsB,EACtB,6BAA6B,EAC7B,wBAAwB,EACxB,wBAAwB,GACxB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACX,wBAAwB,EACxB,SAAS,GACT,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACN,iCAAiC,EACjC,wBAAwB,EACxB,yBAAyB,EACzB,gCAAgC,GAChC,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACX,kBAAkB,EAClB,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,OAAO,EACP,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,WAAW,EACX,oBAAoB,EACpB,qBAAqB,EAErB,cAAc,GACd,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/host/sdk.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EACN,+BAA+B,EAC/B,sBAAsB,EACtB,6BAA6B,EAC7B,wBAAwB,EACxB,wBAAwB,GACxB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AACvF,OAAO,EAAE,iCAAiC,EAAE,MAAM,qCAAqC,CAAC;AACxF,YAAY,EACX,wBAAwB,EACxB,SAAS,GACT,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACN,iCAAiC,EACjC,wBAAwB,EACxB,yBAAyB,EACzB,gCAAgC,GAChC,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACX,kBAAkB,EAClB,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,OAAO,EACP,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,WAAW,EACX,oBAAoB,EACpB,qBAAqB,EAErB,cAAc,GACd,MAAM,gBAAgB,CAAC"}

package/dist/host/sdk.js

@@ -4,4 +4,5 @@
  */
 export { createCommandDispatch } from "./command-dispatch.js";
 export { COMMAND_SETTLEMENT_TIMEOUT_CODE, CommandSettlementError, CommandSettlementTimeoutError, toCommandSettlementError, waitForCommandSettlement, } from "./command-settlement.js";
+export { createFlowCommandHandleController } from "./flow-command-handle-controller.js";
 export { getFlowHandleFromSettlementDetail, isFlowStateChangedDetail, isHandleInvalidatedDetail, isInstanceFlowStateChangedDetail, } from "./host-event-contract.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@getuserfeedback/protocol",
-	"version": "3.1.3",
+	"version": "3.1.4",
 	"description": "getuserfeedback widget protocol — host surface and (later) wire protocol",
 	"keywords": [
 		"getuserfeedback",

package/src/host/flow-command-handle-controller.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, it } from "bun:test";
+import { createFlowCommandHandleController } from "./flow-command-handle-controller";
+
+describe("flow command handle controller", () => {
+	it("serializes commands and publishes settled handles to later payloads", async () => {
+		const dispatched: Array<{ flowHandleId?: string; kind: string }> = [];
+		const controller = createFlowCommandHandleController<
+			string,
+			{ result?: { flowHandleId?: string } }
+		>({
+			getHandleIdFromSettlement: (settlement) =>
+				settlement.result?.flowHandleId,
+			isStaleHandleError: () => false,
+		});
+
+		await controller.runCommand(
+			(flowHandleId) => ({ kind: "prefetch", flowHandleId }),
+			async (payload) => {
+				dispatched.push(payload);
+				return { result: { flowHandleId: "handle_123" } };
+			},
+		);
+		await controller.runCommand(
+			(flowHandleId) => ({ kind: "open", flowHandleId }),
+			async (payload) => {
+				dispatched.push(payload);
+				return { result: { flowHandleId: "handle_123" } };
+			},
+		);
+
+		expect(dispatched).toEqual([
+			{ kind: "prefetch", flowHandleId: undefined },
+			{ kind: "open", flowHandleId: "handle_123" },
+		]);
+		expect(controller.getHandleId()).toBe("handle_123");
+		expect(controller.hasHandleId("handle_123")).toBe(true);
+	});
+
+	it("clears stale handles and retries once without the handle", async () => {
+		const dispatched: Array<{ flowHandleId?: string; kind: string }> = [];
+		const clearedHandles: string[] = [];
+		const controller = createFlowCommandHandleController<
+			string,
+			{ result?: { flowHandleId?: string } }
+		>({
+			getHandleIdFromSettlement: (settlement) =>
+				settlement.result?.flowHandleId,
+			isStaleHandleError: (error) =>
+				error instanceof Error && error.message === "stale",
+			onClearResolvedHandle: (flowHandleId) => {
+				clearedHandles.push(flowHandleId);
+			},
+		});
+
+		await controller.runCommand(
+			(flowHandleId) => ({ kind: "prefetch", flowHandleId }),
+			async (payload) => {
+				dispatched.push(payload);
+				return { result: { flowHandleId: "handle_stale" } };
+			},
+		);
+		let didFailOnce = false;
+		await controller.runCommand(
+			(flowHandleId) => ({ kind: "open", flowHandleId }),
+			async (payload) => {
+				dispatched.push(payload);
+				if (!didFailOnce) {
+					didFailOnce = true;
+					throw new Error("stale");
+				}
+				return { result: { flowHandleId: "handle_recovered" } };
+			},
+		);
+
+		expect(dispatched).toEqual([
+			{ kind: "prefetch", flowHandleId: undefined },
+			{ kind: "open", flowHandleId: "handle_stale" },
+			{ kind: "open", flowHandleId: undefined },
+		]);
+		expect(clearedHandles).toEqual(["handle_stale"]);
+		expect(controller.getHandleId()).toBe("handle_recovered");
+	});
+
+	it("keeps stale-handle retry in the same serialized command slot", async () => {
+		const dispatched: Array<{ flowHandleId?: string; kind: string }> = [];
+		const controller = createFlowCommandHandleController<
+			string,
+			{ result?: { flowHandleId?: string } }
+		>({
+			getHandleIdFromSettlement: (settlement) =>
+				settlement.result?.flowHandleId,
+			isStaleHandleError: (error) =>
+				error instanceof Error && error.message === "stale",
+		});
+
+		await controller.runCommand(
+			(flowHandleId) => ({ kind: "prefetch", flowHandleId }),
+			async (payload) => {
+				dispatched.push(payload);
+				return { result: { flowHandleId: "handle_stale" } };
+			},
+		);
+		let didFailOnce = false;
+		const staleOpen = controller.runCommand(
+			(flowHandleId) => ({ kind: "open", flowHandleId }),
+			async (payload) => {
+				dispatched.push(payload);
+				if (!didFailOnce) {
+					didFailOnce = true;
+					throw new Error("stale");
+				}
+				return { result: { flowHandleId: "handle_recovered" } };
+			},
+		);
+		const queuedPrerender = controller.runCommand(
+			(flowHandleId) => ({ kind: "prerender", flowHandleId }),
+			async (payload) => {
+				dispatched.push(payload);
+				return { result: { flowHandleId: "handle_second" } };
+			},
+		);
+
+		await staleOpen;
+		await queuedPrerender;
+
+		expect(dispatched).toEqual([
+			{ kind: "prefetch", flowHandleId: undefined },
+			{ kind: "open", flowHandleId: "handle_stale" },
+			{ kind: "open", flowHandleId: undefined },
+			{ kind: "prerender", flowHandleId: "handle_recovered" },
+		]);
+		expect(controller.getHandleId()).toBe("handle_second");
+	});
+
+	it("does not retry non-stale failures", async () => {
+		const dispatched: Array<{ flowHandleId?: string; kind: string }> = [];
+		const controller = createFlowCommandHandleController<
+			string,
+			{ result?: { flowHandleId?: string } }
+		>({
+			getHandleIdFromSettlement: (settlement) =>
+				settlement.result?.flowHandleId,
+			isStaleHandleError: () => false,
+		});
+
+		await expect(
+			controller.runCommand(
+				(flowHandleId) => ({ kind: "open", flowHandleId }),
+				async (payload) => {
+					dispatched.push(payload);
+					throw new Error("boom");
+				},
+			),
+		).rejects.toThrow("boom");
+
+		expect(dispatched).toEqual([{ kind: "open", flowHandleId: undefined }]);
+	});
+
+	it("ignores handles from commands that settle after reset", async () => {
+		const dispatched: Array<{ flowHandleId?: string; kind: string }> = [];
+		let resolveSettlement:
+			| ((settlement: { result?: { flowHandleId?: string } }) => void)
+			| undefined;
+		const controller = createFlowCommandHandleController<
+			string,
+			{ result?: { flowHandleId?: string } }
+		>({
+			getHandleIdFromSettlement: (settlement) =>
+				settlement.result?.flowHandleId,
+			isStaleHandleError: () => false,
+		});
+
+		const pendingCommand = controller.runCommand(
+			(flowHandleId) => ({ kind: "prefetch", flowHandleId }),
+			(payload) => {
+				dispatched.push(payload);
+				return new Promise((resolve) => {
+					resolveSettlement = resolve;
+				});
+			},
+		);
+		controller.reset();
+		resolveSettlement?.({ result: { flowHandleId: "handle_from_old_epoch" } });
+		await pendingCommand;
+		await controller.runCommand(
+			(flowHandleId) => ({ kind: "open", flowHandleId }),
+			async (payload) => {
+				dispatched.push(payload);
+				return { result: { flowHandleId: "handle_current" } };
+			},
+		);
+
+		expect(dispatched).toEqual([
+			{ kind: "prefetch", flowHandleId: undefined },
+			{ kind: "open", flowHandleId: undefined },
+		]);
+		expect(controller.getHandleId()).toBe("handle_current");
+	});
+
+	it("does not retry stale failures from commands that fail after reset", async () => {
+		const dispatched: Array<{ flowHandleId?: string; kind: string }> = [];
+		let rejectSettlement: ((error: Error) => void) | undefined;
+		const controller = createFlowCommandHandleController<
+			string,
+			{ result?: { flowHandleId?: string } }
+		>({
+			getHandleIdFromSettlement: (settlement) =>
+				settlement.result?.flowHandleId,
+			isStaleHandleError: (error) =>
+				error instanceof Error && error.message === "stale",
+		});
+
+		await controller.runCommand(
+			(flowHandleId) => ({ kind: "prefetch", flowHandleId }),
+			async (payload) => {
+				dispatched.push(payload);
+				return { result: { flowHandleId: "handle_before_reset" } };
+			},
+		);
+		const pendingCommand = controller.runCommand(
+			(flowHandleId) => ({ kind: "open", flowHandleId }),
+			(payload) => {
+				dispatched.push(payload);
+				return new Promise((_resolve, reject) => {
+					rejectSettlement = reject;
+				});
+			},
+		);
+		controller.reset();
+		rejectSettlement?.(new Error("stale"));
+
+		await expect(pendingCommand).rejects.toThrow("stale");
+		expect(dispatched).toEqual([
+			{ kind: "prefetch", flowHandleId: undefined },
+			{ kind: "open", flowHandleId: "handle_before_reset" },
+		]);
+		expect(controller.getHandleId()).toBeUndefined();
+	});
+});

package/src/host/flow-command-handle-controller.ts

@@ -0,0 +1,86 @@
+import {
+	createLazyHandleClient,
+	type LazyHandleClient,
+} from "./lazy-handle-client.js";
+
+export type FlowCommandHandleController<
+	THandleId extends string,
+	TSettlement,
+> = {
+	runCommand<TPayload>(
+		buildPayload: (handleId: THandleId | undefined) => TPayload,
+		dispatchAndWait: (payload: TPayload) => Promise<TSettlement>,
+	): Promise<TSettlement>;
+	getHandleId(): THandleId | undefined;
+	hasHandleId(handleId: string): boolean;
+	hasPendingCommands(): boolean;
+	subscribeHandle(subscriber: (handleId: THandleId) => void): () => void;
+	clearResolvedHandle(): THandleId | undefined;
+	reset(): void;
+};
+
+export type CreateFlowCommandHandleControllerOptions<
+	THandleId extends string,
+	TSettlement,
+> = {
+	getHandleIdFromSettlement: (settlement: TSettlement) => THandleId | undefined;
+	isStaleHandleError: (error: unknown) => boolean;
+	onClearResolvedHandle?: (handleId: THandleId) => void;
+};
+
+export function createFlowCommandHandleController<
+	THandleId extends string,
+	TSettlement,
+>({
+	getHandleIdFromSettlement,
+	isStaleHandleError,
+	onClearResolvedHandle,
+}: CreateFlowCommandHandleControllerOptions<
+	THandleId,
+	TSettlement
+>): FlowCommandHandleController<THandleId, TSettlement> {
+	const handleClient: LazyHandleClient<THandleId, TSettlement> =
+		createLazyHandleClient<THandleId, TSettlement>({
+			getHandleIdFromSettlement,
+		});
+
+	const clearResolvedHandle = (): THandleId | undefined => {
+		const previousHandleId = handleClient.getHandleId();
+		if (!previousHandleId) {
+			return undefined;
+		}
+		handleClient.reset();
+		onClearResolvedHandle?.(previousHandleId);
+		return previousHandleId;
+	};
+
+	const reset = (): void => {
+		const previousHandleId = handleClient.getHandleId();
+		handleClient.reset();
+		if (previousHandleId) {
+			onClearResolvedHandle?.(previousHandleId);
+		}
+	};
+
+	const runCommand: FlowCommandHandleController<
+		THandleId,
+		TSettlement
+	>["runCommand"] = async (buildPayload, dispatchAndWait) => {
+		return handleClient.runCommandWithRetry(buildPayload, dispatchAndWait, {
+			shouldRetry: isStaleHandleError,
+			onBeforeRetry: () => {
+				clearResolvedHandle();
+			},
+		});
+	};
+
+	return {
+		runCommand,
+		getHandleId: () => handleClient.getHandleId(),
+		hasHandleId: (handleId) => handleClient.getHandleId() === handleId,
+		hasPendingCommands: () => handleClient.hasPendingCommands(),
+		subscribeHandle: (subscriber) => handleClient.subscribeHandle(subscriber),
+		clearResolvedHandle,
+		reset,
+	};
+}

package/src/host/index.ts

@@ -7,6 +7,7 @@ export * from "./command-envelope.js";
 export * from "./command-settlement.js";
 export * from "./constants.js";
 export * from "./external-id-argument-guards.js";
+export * from "./flow-command-handle-controller.js";
 export * from "./host-event-contract.js";
 export * from "./lazy-handle-client.js";
 export { createCommandRequestId } from "./request-id.js";

package/src/host/lazy-handle-client.ts

@@ -23,7 +23,16 @@ export type LazyHandleClient<
 		buildPayload: (handleId: THandleId | undefined) => TPayload,
 		dispatchAndWait: (payload: TPayload) => Promise<TSettlement>,
 	): Promise<TSettlement>;
+	runCommandWithRetry<TPayload>(
+		buildPayload: (handleId: THandleId | undefined) => TPayload,
+		dispatchAndWait: (payload: TPayload) => Promise<TSettlement>,
+		options: {
+			shouldRetry: (error: unknown) => boolean;
+			onBeforeRetry?: (error: unknown) => void;
+		},
+	): Promise<TSettlement>;
 	getHandleId(): THandleId | undefined;
+	hasPendingCommands(): boolean;
 	subscribeHandle(subscriber: Subscriber<THandleId>): () => void;
 	getStage(): TStage;
 	setStage(stage: TStage): void;
@@ -141,9 +150,60 @@ const createLazyHandleClientWithStages = <
 		return run;
 	};
 
+	const runCommandWithRetry: LazyHandleClient<
+		THandleId,
+		TSettlement,
+		TStage
+	>["runCommandWithRetry"] = (buildPayload, dispatchAndWait, options) => {
+		const execute = async (): Promise<TSettlement> => {
+			let didRetry = false;
+			for (;;) {
+				if (stage === stages.invalidated) {
+					throw new Error("Handle client is invalidated");
+				}
+				const commandEpoch = epoch;
+				const payload = buildPayload(handleId);
+				try {
+					const settlement = await dispatchAndWait(payload);
+					const settledHandleId = input.getHandleIdFromSettlement(settlement);
+					if (settledHandleId && commandEpoch === epoch) {
+						publishHandle(settledHandleId);
+					}
+					return settlement;
+				} catch (error) {
+					if (
+						commandEpoch === epoch &&
+						!didRetry &&
+						options.shouldRetry(error)
+					) {
+						didRetry = true;
+						options.onBeforeRetry?.(error);
+						continue;
+					}
+					throw error;
+				}
+			}
+		};
+
+		const run =
+			queuedCommandCount === 0 ? execute() : tail.then(execute, execute);
+		queuedCommandCount += 1;
+		tail = run.then(
+			() => {
+				queuedCommandCount -= 1;
+			},
+			() => {
+				queuedCommandCount -= 1;
+			},
+		);
+		return run;
+	};
+
 	return {
 		runCommand,
+		runCommandWithRetry,
 		getHandleId: () => handleId,
+		hasPendingCommands: () => queuedCommandCount > 0,
 		subscribeHandle: (subscriber) => {
 			subscribers.add(subscriber);
 			if (handleId) {

package/src/host/sdk.ts

@@ -11,6 +11,8 @@ export {
 	toCommandSettlementError,
 	waitForCommandSettlement,
 } from "./command-settlement.js";
+export type { FlowCommandHandleController } from "./flow-command-handle-controller.js";
+export { createFlowCommandHandleController } from "./flow-command-handle-controller.js";
 export type {
 	FlowHandleFromSettlement,
 	FlowState,