@space3-npm/cybersoul-client 1.4.23 → 1.4.24

package/dist/client.d.ts

@@ -83,6 +83,15 @@ export declare class CyberSoulClient {
      * reply is already in flight.
      */
     private buildMediaError;
+    /**
+     * Shared giftOutfit handler for `interact()` / `proactiveInteract()`.
+     * Validates the LLM's `giftOutfit` intent, performs the wardrobe write,
+     * fires the `onOutfitGifted` callback, and resolves to the
+     * [OutfitGiftedPayload] (or `undefined` when there was nothing to gift
+     * or the write failed). Failures are swallowed (logged) so a wardrobe
+     * hiccup never aborts the chat turn.
+     */
+    private processGiftOutfit;
     private formatHistoryEntries;
     private buildHistoryTranscript;
     interact(params: InteractParams): Promise<InteractResponse>;
@@ -144,8 +153,11 @@ export declare class CyberSoulClient {
     updateDynamicContext(stateUpdate: DispatcherIntent["stateUpdate"], userAnalysis?: DispatcherIntent["userAnalysis"]): Promise<PersistedDynamicContext | null>;
     /**
      * Gift a new outfit to the character's wardrobe inventory.
+     * Returns the number of wardrobe items the backend created (the
+     * backend may expand a single description into multiple items), or
+     * `undefined` when the server did not report a count.
      */
-    giftOutfit(descriptionText: string): Promise<void>;
+    giftOutfit(descriptionText: string): Promise<number | undefined>;
     /**
      * Bootstrap character profile from OpenClaw workspace files.
      */

package/dist/client.js

@@ -482,7 +482,10 @@ ${isProactive
         return `- Include 'triggerEvent' only if the VERY LAST USER MESSAGE proposes a new activity/hangout AND you accept the invitation, explicitly requests an outfit change AND you agree, or proposes intimate/romantic actions AND you agree; ignore older history. DO NOT include it if you decline or reject the proposal. ${this.getOutfitSelectionPrompt()}`;
     }
     getOutfitAcquisitionPolicyPrompt() {
-        return `- Outfit acquisition (VERY LAST USER MESSAGE only): set giftOutfit for gift/buy/add-clothes intent; otherwise null. giftOutfit format: { "descriptionText": "short outfit description" }.`;
+        return `- Outfit acquisition (giftOutfit): set 'giftOutfit' to { "descriptionText": "short outfit description" } when a genuinely NEW outfit (one that is NOT already in the Available Wardrobe) is obtained THIS turn, triggered by EITHER:
+    (a) USER-GIFTED: the VERY LAST USER MESSAGE expresses gift/buy/add-clothes intent for you (e.g. "I bought you a dress", "here, wear this new outfit", "adding some lingerie to your closet").
+    (b) CHARACTER-ACQUIRED: the conversation or active event naturally leads YOU to acquire a new outfit you don't already own (e.g. you went shopping, received/made clothes, or the scene requires changing into a brand-new outfit that is absent from your Available Wardrobe).
+  Keep 'descriptionText' to a concise English-or-matching-language description of the single new outfit. Otherwise set 'giftOutfit' to null. Do NOT fire it for outfits already present in the Available Wardrobe, and do NOT fire it just because you changed into an existing outfit.`;
     }
     getEventSchemaParams(userName) {
         const name = userName || "the user";
@@ -607,6 +610,45 @@ ${isProactive
             affected,
         };
     }
+    /**
+     * Shared giftOutfit handler for `interact()` / `proactiveInteract()`.
+     * Validates the LLM's `giftOutfit` intent, performs the wardrobe write,
+     * fires the `onOutfitGifted` callback, and resolves to the
+     * [OutfitGiftedPayload] (or `undefined` when there was nothing to gift
+     * or the write failed). Failures are swallowed (logged) so a wardrobe
+     * hiccup never aborts the chat turn.
+     */
+    async processGiftOutfit(giftOutfitIntent, onOutfitGifted) {
+        if (!giftOutfitIntent ||
+            typeof giftOutfitIntent !== "object" ||
+            typeof giftOutfitIntent.descriptionText !== "string" ||
+            giftOutfitIntent.descriptionText.trim().length === 0) {
+            return undefined;
+        }
+        const outfitDescription = giftOutfitIntent.descriptionText.trim();
+        try {
+            const count = await this.giftOutfit(outfitDescription);
+            const giftedOutfit = {
+                descriptionText: outfitDescription,
+            };
+            if (typeof count === "number") {
+                giftedOutfit.count = count;
+            }
+            if (onOutfitGifted) {
+                try {
+                    onOutfitGifted(giftedOutfit);
+                }
+                catch (cbErr) {
+                    console.warn("[CyberSoulClient] onOutfitGifted callback threw:", cbErr);
+                }
+            }
+            return giftedOutfit;
+        }
+        catch (e) {
+            console.error("[CyberSoulClient] giftOutfit failed:", e);
+            return undefined;
+        }
+    }
     formatHistoryEntries(history, userName, agentName, promptDirective = "") {
         const contextLines = [];
         for (let i = 0; i < history.length; i++) {
@@ -846,6 +888,7 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
             let finalAudioUrl = undefined;
             let finalAudioMediaId = undefined;
             let finalDurationSec = undefined;
+            let giftedOutfit = undefined;
             // Partial-failure capture: text was already produced and emitted
             // via [onTextReady], so a wallet / insufficient-points failure on
             // image or voice MUST NOT abort the whole turn. We collect the
@@ -886,7 +929,10 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
                 typeof parsedIntent.giftOutfit === "object" &&
                 typeof parsedIntent.giftOutfit.descriptionText === "string" &&
                 parsedIntent.giftOutfit.descriptionText.trim().length > 0) {
-                mediaTasks.push(this.giftOutfit(parsedIntent.giftOutfit.descriptionText.trim()).catch((e) => console.error("[CyberSoulClient] Auto giftOutfit failed:", e)));
+                mediaTasks.push(this.processGiftOutfit(parsedIntent.giftOutfit, params.onOutfitGifted).then((result) => {
+                    if (result)
+                        giftedOutfit = result;
+                }));
             }
             const shouldGenerateImage = types.includes(InteractRequestType.IMAGE) &&
                 (!isAuto || !!parsedIntent.imageParams);
@@ -989,6 +1035,7 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
                 isEndTurn: parsedIntent.isEndTurn,
                 persistedDynamicContext,
                 mediaError,
+                giftedOutfit,
             };
         }
         catch (error) {
@@ -1190,6 +1237,7 @@ Modalities:
                 ? "'imageParams' may be included only if sending a photo right now would feel natural for this character in this relationship — otherwise set null. Do not attach a photo just because you can."
                 : "ALWAYS set 'imageParams' to null."}
   - ALWAYS set 'voiceArgs' to null.
+  ${this.getOutfitAcquisitionPolicyPrompt()}
 
 Output ONLY a valid JSON object matching exactly this structure (no markdown wrappers).
 If "shouldSkipProactive" is true, set "skipReason" to one short sentence and set every other field to null.
@@ -1200,6 +1248,7 @@ If "shouldSkipProactive" is false, "textResponse" is required and "stateUpdate"
   "actionText": "(Scene descriptions, physical actions, expressions, inner feelings) ONLY.",
   "textResponse": "Spoken dialogue ONLY.",
   "stateUpdate": { "temperatureDelta": 0, "ongoingScene": { "scene": "...", "outfit": "..." } },
+  "giftOutfit": { "descriptionText": "Concise description of the newly acquired outfit to add into wardrobe." },
   ${this.getImageSchemaParams(imageAllowed)},
   "voiceArgs": null
 }`;
@@ -1265,6 +1314,11 @@ If "shouldSkipProactive" is false, "textResponse" is required and "stateUpdate"
                     stateUpdate: parsedIntent.stateUpdate,
                 });
             }
+            // Outfit acquisition: the character may decide, on its own, to pick
+            // up a brand-new outfit while reaching out. Fire-and-capture in
+            // parallel with image generation; surface it via callback + the
+            // final response so upstream can show "New outfit added".
+            const giftOutfitPromise = this.processGiftOutfit(parsedIntent.giftOutfit, params.onOutfitGifted);
             let finalImageUrl;
             let finalImageMediaId;
             let proactiveMediaError = null;
@@ -1300,6 +1354,7 @@ If "shouldSkipProactive" is false, "textResponse" is required and "stateUpdate"
                 }
             }
             const persistedDynamicContext = (await persistedStatePromise) ?? undefined;
+            const giftedOutfit = (await giftOutfitPromise) ?? undefined;
             const proactiveMediaErrorEnv = proactiveMediaError
                 ? this.buildMediaError(proactiveMediaError, proactiveAffected)
                 : undefined;
@@ -1312,6 +1367,7 @@ If "shouldSkipProactive" is false, "textResponse" is required and "stateUpdate"
                 stateUpdate: parsedIntent.stateUpdate,
                 persistedDynamicContext,
                 mediaError: proactiveMediaErrorEnv,
+                giftedOutfit,
             };
         }
         catch (error) {
@@ -1435,6 +1491,9 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
     }
     /**
      * Gift a new outfit to the character's wardrobe inventory.
+     * Returns the number of wardrobe items the backend created (the
+     * backend may expand a single description into multiple items), or
+     * `undefined` when the server did not report a count.
      */
     async giftOutfit(descriptionText) {
         const res = await this.apiFetch("/api/v1/cyber-soul/characters/gift-outfit", {
@@ -1443,6 +1502,18 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
         });
         if (!res.ok)
             throw new Error("Failed to gift outfit");
+        try {
+            const body = (await res.json());
+            return typeof body.count === "number" && Number.isFinite(body.count)
+                ? body.count
+                : undefined;
+        }
+        catch {
+            // The gift already succeeded server-side (res.ok); a missing/
+            // unparseable count is non-fatal — report "unknown" rather than
+            // fabricating a number.
+            return undefined;
+        }
     }
     /**
      * Bootstrap character profile from OpenClaw workspace files.

package/dist/types.d.ts

@@ -80,6 +80,26 @@ export interface MediaReadyPayload {
     /** Voice only — TTS duration in seconds when known. */
     durationSec?: number;
 }
+/**
+ * Payload delivered by [InteractParams.onOutfitGifted] /
+ * [ProactiveParams.onOutfitGifted] when a new outfit is successfully
+ * added to the character's wardrobe during a turn. Fires for BOTH
+ * trigger paths: (a) the user explicitly gifts/buys an outfit, and
+ * (b) the conversation or an active event leads the character to
+ * acquire a brand-new outfit. Lets upstream consumers (e.g.
+ * cybersoul-chat) render a system message like
+ * "New outfit added to wardrobe".
+ */
+export interface OutfitGiftedPayload {
+    /** Human-readable description of the newly acquired outfit. */
+    descriptionText: string;
+    /**
+     * Number of wardrobe items the backend created for this gift, when
+     * the server reported it. Omitted when the count is unknown — never
+     * fabricated.
+     */
+    count?: number;
+}
 export interface ProactiveParams {
     history?: HistoryEntry[];
     maxUnreplied?: number;
@@ -95,6 +115,13 @@ export interface ProactiveParams {
     onStateReady?: (persisted: PersistedDynamicContext) => void;
     /** Fires per modality as each media task settles successfully. */
     onMediaReady?: (payload: MediaReadyPayload) => void;
+    /**
+     * Fires when an outfit has been successfully added to the wardrobe
+     * during this turn (user-initiated gift OR character-initiated
+     * acquisition). Lets the UI render a system message like
+     * "New outfit added to wardrobe" in real time.
+     */
+    onOutfitGifted?: (payload: OutfitGiftedPayload) => void;
 }
 export interface ProactiveResponse {
     status: "success" | "skipped" | "error";
@@ -113,6 +140,10 @@ export interface ProactiveResponse {
      * can still render the text reply and explain the missing media
      * without losing the conversation. See [InteractMediaError]. */
     mediaError?: InteractMediaError;
+    /** Set when an outfit was successfully added to the wardrobe this turn.
+     * Mirrors the [ProactiveParams.onOutfitGifted] callback for consumers
+     * that only read the final response. See [OutfitGiftedPayload]. */
+    giftedOutfit?: OutfitGiftedPayload;
     error?: string;
 }
 export interface InteractParams {
@@ -132,6 +163,13 @@ export interface InteractParams {
     onStateReady?: (persisted: PersistedDynamicContext) => void;
     /** Fires per modality as each media task settles successfully. */
     onMediaReady?: (payload: MediaReadyPayload) => void;
+    /**
+     * Fires when an outfit has been successfully added to the wardrobe
+     * during this turn (user-initiated gift OR character-initiated
+     * acquisition). Lets the UI render a system message like
+     * "New outfit added to wardrobe" in real time.
+     */
+    onOutfitGifted?: (payload: OutfitGiftedPayload) => void;
 }
 export interface OndemandEventParams {
     eventDescription: string;
@@ -173,6 +211,10 @@ export interface InteractResponse {
     imageMediaId?: string;
     audioUrl?: string;
     audioMediaId?: string;
+    /** Set when an outfit was successfully added to the wardrobe this turn.
+     * Mirrors the [InteractParams.onOutfitGifted] callback for consumers
+     * that only read the final response. See [OutfitGiftedPayload]. */
+    giftedOutfit?: OutfitGiftedPayload;
     likePreviousPicture?: boolean;
     durationSec?: number;
     triggeredEvent?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@space3-npm/cybersoul-client",
-  "version": "1.4.23",
+  "version": "1.4.24",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",