@getuserfeedback/protocol 3.1.3 → 3.1.5

package/dist/command-kinds.d.ts

@@ -14,6 +14,8 @@ export declare const coreCommandKindSchema: z.ZodMiniEnum<{
     init: "init";
     close: "close";
     reset: "reset";
+    "instanceFeedback.capture": "instanceFeedback.capture";
+    "instanceFeedback.listMine": "instanceFeedback.listMine";
 }>;
 export declare const publicCommandKindSchema: z.ZodMiniEnum<{
     open: "open";
@@ -45,6 +47,8 @@ export declare const allCommandKindSchema: z.ZodMiniEnum<{
     init: "init";
     close: "close";
     reset: "reset";
+    "instanceFeedback.capture": "instanceFeedback.capture";
+    "instanceFeedback.listMine": "instanceFeedback.listMine";
     updateHostContext: "updateHostContext";
     emitHostSignal: "emitHostSignal";
     setContainer: "setContainer";

package/dist/command-kinds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-kinds.d.ts","sourceRoot":"","sources":["../src/command-kinds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAmC9B,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;EAA2B,CAAC;AAC9D,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;EAA6B,CAAC;AAKlE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;EAA0B,CAAC"}
+{"version":3,"file":"command-kinds.d.ts","sourceRoot":"","sources":["../src/command-kinds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAqC9B,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;EAA2B,CAAC;AAC9D,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;EAA6B,CAAC;AAKlE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;EAA0B,CAAC"}

package/dist/command-kinds.js

@@ -13,6 +13,8 @@ const coreCommandKinds = [
     "init",
     "close",
     "reset",
+    "instanceFeedback.capture",
+    "instanceFeedback.listMine",
     "error",
 ];
 const publicCommandKinds = [

package/dist/core-command-envelope.d.ts

@@ -329,6 +329,35 @@ export declare const coreCommandEnvelopeSchema: z.ZodMiniObject<{
         }>>;
     }, z.core.$strip>, z.ZodMiniObject<{
         kind: z.ZodMiniLiteral<"reset">;
+    }, z.core.$strip>, z.ZodMiniObject<{
+        kind: z.ZodMiniLiteral<"instanceFeedback.capture">;
+        payload: z.ZodMiniObject<{
+            targetBindingToken: z.ZodMiniString<string>;
+            capturedAt: z.ZodMiniString<string>;
+            comment: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniString<string>>>;
+            dataType: z.ZodMiniEnum<{
+                boolean: "boolean";
+                categorical: "categorical";
+                numeric: "numeric";
+            }>;
+            label: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniString<string>>>;
+            name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+            reasonCategories: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniString<string>>>;
+            scoreValue: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniNumber<number>>>;
+            valence: z.ZodMiniEnum<{
+                positive: "positive";
+                negative: "negative";
+                neutral: "neutral";
+            }>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodMiniObject<{
+        kind: z.ZodMiniLiteral<"instanceFeedback.listMine">;
+        payload: z.ZodMiniObject<{
+            targets: z.ZodMiniArray<z.ZodMiniObject<{
+                name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                targetBindingToken: z.ZodMiniString<string>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
     }, z.core.$strip>, z.ZodMiniObject<{
         kind: z.ZodMiniLiteral<"error">;
         event: z.ZodMiniObject<{

package/dist/core-command-envelope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core-command-envelope.d.ts","sourceRoot":"","sources":["../src/core-command-envelope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAC9B,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,kBAAkB,CAAC;AAOrE,sEAAsE;AACtE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAOpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE7E,wEAAwE;AACxE,MAAM,MAAM,cAAc,GAAG;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,UAAU,CAAC;CACxB,CAAC"}
+{"version":3,"file":"core-command-envelope.d.ts","sourceRoot":"","sources":["../src/core-command-envelope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAC9B,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,kBAAkB,CAAC;AAOrE,sEAAsE;AACtE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAOpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE7E,wEAAwE;AACxE,MAAM,MAAM,cAAc,GAAG;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,UAAU,CAAC;CACxB,CAAC"}

package/dist/core-commands.d.ts

@@ -286,6 +286,35 @@ export declare const coreCommandPayloadSchema: z.ZodMiniUnion<readonly [z.ZodMin
     }>>;
 }, z.core.$strip>, z.ZodMiniObject<{
     kind: z.ZodMiniLiteral<"reset">;
+}, z.core.$strip>, z.ZodMiniObject<{
+    kind: z.ZodMiniLiteral<"instanceFeedback.capture">;
+    payload: z.ZodMiniObject<{
+        targetBindingToken: z.ZodMiniString<string>;
+        capturedAt: z.ZodMiniString<string>;
+        comment: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniString<string>>>;
+        dataType: z.ZodMiniEnum<{
+            boolean: "boolean";
+            categorical: "categorical";
+            numeric: "numeric";
+        }>;
+        label: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniString<string>>>;
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        reasonCategories: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniString<string>>>;
+        scoreValue: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniNumber<number>>>;
+        valence: z.ZodMiniEnum<{
+            positive: "positive";
+            negative: "negative";
+            neutral: "neutral";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodMiniObject<{
+    kind: z.ZodMiniLiteral<"instanceFeedback.listMine">;
+    payload: z.ZodMiniObject<{
+        targets: z.ZodMiniArray<z.ZodMiniObject<{
+            name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+            targetBindingToken: z.ZodMiniString<string>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
 }, z.core.$strip>, z.ZodMiniObject<{
     kind: z.ZodMiniLiteral<"error">;
     event: z.ZodMiniObject<{

package/dist/core-commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core-commands.d.ts","sourceRoot":"","sources":["../src/core-commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AA8M9B,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAInC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC"}
+{"version":3,"file":"core-commands.d.ts","sourceRoot":"","sources":["../src/core-commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AA8N9B,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAInC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/core-commands.js

@@ -1,6 +1,7 @@
 import * as z from "zod/mini";
 import { appEventCustomerTrackSchema, appEventExternalIdSchema, appEventSystemTrackSchema, } from "./app-event.js";
 import { ErrorEventSchema } from "./errors.js";
+import { captureInstanceFeedbackRequestSchema, listInstanceFeedbackMineRequestSchema, } from "./instance-feedback.js";
 import { responseMetadataInputSchema } from "./response-metadata.js";
 import { configureOptionsSchema, initOptionsSchema } from "./widget-config.js";
 const flowHandleIdSchema = z.string().check(z.trim(), z.minLength(1));
@@ -145,6 +146,14 @@ const initCorePayloadSchema = z.strictObject({
 const resetPayloadSchema = z.object({
     kind: z.literal("reset"),
 });
+const instanceFeedbackCapturePayloadSchema = z.object({
+    kind: z.literal("instanceFeedback.capture"),
+    payload: captureInstanceFeedbackRequestSchema,
+});
+const instanceFeedbackListMinePayloadSchema = z.object({
+    kind: z.literal("instanceFeedback.listMine"),
+    payload: listInstanceFeedbackMineRequestSchema,
+});
 const coreCommandPayloadWithoutIdentifySchema = z.union([
     z.union([openPersistedCorePayloadSchema, openInlineCorePayloadSchema]),
     z.union([prefetchPayloadSchema, prefetchInlinePayloadSchema]),
@@ -160,6 +169,8 @@ const coreCommandPayloadWithoutIdentifySchema = z.union([
     initCorePayloadSchema,
     closeCorePayloadSchema,
     resetPayloadSchema,
+    instanceFeedbackCapturePayloadSchema,
+    instanceFeedbackListMinePayloadSchema,
     errorPayloadSchema,
 ]);
 export const coreCommandPayloadSchema = z.union([

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/host-event-schemas.d.ts

@@ -32,6 +32,8 @@ export declare const commandSettledDetailSchema: z.ZodMiniDiscriminatedUnion<[z.
         init: "init";
         close: "close";
         reset: "reset";
+        "instanceFeedback.capture": "instanceFeedback.capture";
+        "instanceFeedback.listMine": "instanceFeedback.listMine";
         updateHostContext: "updateHostContext";
         emitHostSignal: "emitHostSignal";
         setContainer: "setContainer";
@@ -60,6 +62,8 @@ export declare const commandSettledDetailSchema: z.ZodMiniDiscriminatedUnion<[z.
         init: "init";
         close: "close";
         reset: "reset";
+        "instanceFeedback.capture": "instanceFeedback.capture";
+        "instanceFeedback.listMine": "instanceFeedback.listMine";
         updateHostContext: "updateHostContext";
         emitHostSignal: "emitHostSignal";
         setContainer: "setContainer";

package/dist/host/host-event-schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-event-schemas.d.ts","sourceRoot":"","sources":["../../src/host/host-event-schemas.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAoB9B;;;GAGG;AACH,eAAO,MAAM,gCAAgC;;;kBAG3C,CAAC;AAEH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAChD,OAAO,gCAAgC,CACvC,CAAC;AAcF,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAGrC,CAAC;AAEH,YAAY,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAUrE,eAAO,MAAM,4BAA4B;;;;;;;kBAGvC,CAAC;AAEH,YAAY,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEvE,eAAO,MAAM,oCAAoC;;;;;;;kBAG/C,CAAC;AAEH,YAAY,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAC;AAE/E,eAAO,MAAM,yBAAyB;;;;;;;;;kBAMpC,CAAC;AAEH,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;kBASxC,CAAC;AAEH,YAAY,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAExE;;GAEG;AACH,wBAAgB,+BAA+B,CAC9C,MAAM,EAAE,OAAO,GACb,0BAA0B,GAAG,IAAI,CAGnC;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,MAAM,EAAE;IACzD,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,0BAA0B,GAAG,IAAI,CAUpC;AAED,YAAY,EAAE,kCAAkC,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,EAAE,qCAAqC,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"host-event-schemas.d.ts","sourceRoot":"","sources":["../../src/host/host-event-schemas.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAoB9B;;;GAGG;AACH,eAAO,MAAM,gCAAgC;;;kBAG3C,CAAC;AAEH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAChD,OAAO,gCAAgC,CACvC,CAAC;AAcF,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAGrC,CAAC;AAEH,YAAY,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAUrE,eAAO,MAAM,4BAA4B;;;;;;;kBAGvC,CAAC;AAEH,YAAY,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEvE,eAAO,MAAM,oCAAoC;;;;;;;kBAG/C,CAAC;AAEH,YAAY,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAC;AAE/E,eAAO,MAAM,yBAAyB;;;;;;;;;kBAMpC,CAAC;AAEH,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;kBASxC,CAAC;AAEH,YAAY,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAExE;;GAEG;AACH,wBAAgB,+BAA+B,CAC9C,MAAM,EAAE,OAAO,GACb,0BAA0B,GAAG,IAAI,CAGnC;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,MAAM,EAAE;IACzD,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,0BAA0B,GAAG,IAAI,CAUpC;AAED,YAAY,EAAE,kCAAkC,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,EAAE,qCAAqC,EAAE,MAAM,0BAA0B,CAAC"}

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.5",
 	"description": "getuserfeedback widget protocol — host surface and (later) wire protocol",
 	"keywords": [
 		"getuserfeedback",

package/src/command-kinds.ts

@@ -14,6 +14,8 @@ const coreCommandKinds = [
 	"init",
 	"close",
 	"reset",
+	"instanceFeedback.capture",
+	"instanceFeedback.listMine",
 	"error",
 ] as const;
 

package/src/core-commands.ts

@@ -5,6 +5,10 @@ import {
 	appEventSystemTrackSchema,
 } from "./app-event.js";
 import { ErrorEventSchema } from "./errors.js";
+import {
+	captureInstanceFeedbackRequestSchema,
+	listInstanceFeedbackMineRequestSchema,
+} from "./instance-feedback.js";
 import { responseMetadataInputSchema } from "./response-metadata.js";
 import { configureOptionsSchema, initOptionsSchema } from "./widget-config.js";
 
@@ -186,6 +190,16 @@ const resetPayloadSchema = z.object({
 	kind: z.literal("reset"),
 });
 
+const instanceFeedbackCapturePayloadSchema = z.object({
+	kind: z.literal("instanceFeedback.capture"),
+	payload: captureInstanceFeedbackRequestSchema,
+});
+
+const instanceFeedbackListMinePayloadSchema = z.object({
+	kind: z.literal("instanceFeedback.listMine"),
+	payload: listInstanceFeedbackMineRequestSchema,
+});
+
 const coreCommandPayloadWithoutIdentifySchema = z.union([
 	z.union([openPersistedCorePayloadSchema, openInlineCorePayloadSchema]),
 	z.union([prefetchPayloadSchema, prefetchInlinePayloadSchema]),
@@ -201,6 +215,8 @@ const coreCommandPayloadWithoutIdentifySchema = z.union([
 	initCorePayloadSchema,
 	closeCorePayloadSchema,
 	resetPayloadSchema,
+	instanceFeedbackCapturePayloadSchema,
+	instanceFeedbackListMinePayloadSchema,
 	errorPayloadSchema,
 ]);
 

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/host-event-schemas.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "bun:test";
+import { commandSettledDetailSchema } from "./host-event-schemas";
+
+describe("commandSettledDetailSchema", () => {
+	it("accepts instance feedback command settlements", () => {
+		for (const kind of [
+			"instanceFeedback.capture",
+			"instanceFeedback.listMine",
+		] as const) {
+			expect(
+				commandSettledDetailSchema.safeParse({
+					instanceId: "instance_123",
+					kind,
+					ok: true,
+					requestId: "req_123",
+					result: { status: "accepted" },
+				}).success,
+			).toBe(true);
+			expect(
+				commandSettledDetailSchema.safeParse({
+					error: { code: "INSTANCE_FEEDBACK_FAILED", message: "failed" },
+					instanceId: "instance_123",
+					kind,
+					ok: false,
+					requestId: "req_123",
+				}).success,
+			).toBe(true);
+		}
+	});
+});

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,