@space3-npm/cybersoul-client 1.2.2 → 1.2.3

package/dist/client.d.ts

@@ -11,6 +11,11 @@ export declare class CyberSoulClient {
      * Internal wrapper for fetch that automatically injects the backend URL and Character Auth token.
      */
     private apiFetch;
+    private fetchRemoteState;
+    private getWardrobePromptStr;
+    private generatePrimitive;
+    private _updateDynamicContextInternal;
+    private normalizeRequestTypes;
     private buildStateContextPrompt;
     private normalizeOngoingSceneState;
     private getImageSchemaParams;
@@ -34,18 +39,11 @@ export declare class CyberSoulClient {
      */
     private extractVoiceArgsFromLlmResponse;
     private buildHistoryTranscript;
+    interact(params: InteractParams): Promise<InteractResponse>;
     /**
      * Evaluates and triggers an on-demand event, intelligently deciding if an outfit change is needed.
      */
     ondemandEvent(params: OndemandEventParams): Promise<OndemandEventResponse>;
-    /**
-     * Fetches the current dynamic context and daily state.
-     */
-    getState(): Promise<CharacterState>;
-    /**
-     * Updates the character's relationship temperature or mood.
-     */
-    updateDynamicContext(stateUpdate: DispatcherIntent["stateUpdate"], userAnalysis?: DispatcherIntent["userAnalysis"]): Promise<void>;
     /**
      * Manually generate an image of the character outside of chat flow.
      */
@@ -65,6 +63,14 @@ export declare class CyberSoulClient {
         audioUrl: string;
         durationSec?: number;
     }>;
+    /**
+     * Fetches the current dynamic context and daily state.
+     */
+    getState(): Promise<CharacterState>;
+    /**
+     * Updates the character's relationship temperature or mood.
+     */
+    updateDynamicContext(stateUpdate: DispatcherIntent["stateUpdate"], userAnalysis?: DispatcherIntent["userAnalysis"]): Promise<void>;
     /**
      * Gift a new outfit to the character's wardrobe inventory.
      */
@@ -78,12 +84,6 @@ export declare class CyberSoulClient {
      * Can be triggered by local Cron systems like OpenClaw.
      */
     generateDailyScript(): Promise<void>;
-    private fetchRemoteState;
-    private getWardrobePromptStr;
-    private _updateDynamicContextInternal;
-    private generatePrimitive;
-    private normalizeRequestTypes;
-    interact(params: InteractParams): Promise<InteractResponse>;
     /**
      * Automatically detect and summarize the story from the current chat history.
      * It takes raw message history and returns a narrative paragraph representing the current story segment.

package/dist/client.js

@@ -68,6 +68,90 @@ export class CyberSoulClient {
             ? lastError
             : new Error("Request failed unexpectedly");
     }
+    async fetchRemoteState() {
+        const res = await this.apiFetch("/api/v1/cyber-soul/state");
+        if (!res.ok)
+            throw new Error("Failed to fetch character state");
+        const json = await res.json();
+        return json.data;
+    }
+    async getWardrobePromptStr() {
+        const now = Date.now();
+        if (this.cachedWardrobeStr && (now - this.cachedWardrobeTime <= 5 * 60 * 1000)) {
+            return this.cachedWardrobeStr;
+        }
+        let availableOutfits = "None available";
+        try {
+            const wardrobeRes = await this.apiFetch("/api/v1/cyber-soul/wardrobe");
+            if (wardrobeRes.ok) {
+                let wardrobesPayload = {};
+                try {
+                    wardrobesPayload = await wardrobeRes.json();
+                }
+                catch (e) { }
+                const wardrobes = wardrobesPayload.data || [];
+                if (wardrobes.length > 0) {
+                    availableOutfits = wardrobes
+                        .map((w) => `- ID: ${w.id} | Name: ${w.itemName} | Category: ${w.category}`)
+                        .join("\n");
+                }
+            }
+        }
+        catch (e) { }
+        this.cachedWardrobeStr = availableOutfits;
+        this.cachedWardrobeTime = now;
+        return availableOutfits;
+    }
+    async generatePrimitive(type, payload) {
+        const res = await this.apiFetch(`/api/v1/cyber-soul/${type}/generate`, {
+            method: "POST",
+            body: JSON.stringify(payload),
+        });
+        if (!res.ok) {
+            let errData;
+            try {
+                errData = await res.json();
+            }
+            catch (e) { }
+            const msg = errData?.message || errData?.error || `Status ${res.status}`;
+            const err = new Error(`Failed to generate ${type}: ${msg}`);
+            err.code = errData?.code || "UNKNOWN_ERROR";
+            throw err;
+        }
+        return res.json();
+    }
+    async _updateDynamicContextInternal(stateUpdate, userAnalysis) {
+        if (!stateUpdate && !userAnalysis)
+            return;
+        // Map TS schema intent (temperatureDelta) to match Backend payload schema (temperature)
+        const payload = { ...stateUpdate };
+        if (userAnalysis) {
+            payload.userAnalysis = userAnalysis;
+        }
+        if (payload.temperatureDelta !== undefined) {
+            payload.temperature = payload.temperatureDelta;
+            delete payload.temperatureDelta;
+        }
+        if (payload.ongoingScene !== undefined) {
+            const normalizedOngoingScene = this.normalizeOngoingSceneState(payload.ongoingScene);
+            payload.ongoingScene = normalizedOngoingScene || null;
+        }
+        await this.apiFetch("/api/v1/cyber-soul/characters/dynamic-context", {
+            method: "PATCH",
+            body: JSON.stringify(payload),
+        }).catch((e) => console.error("Failed to update dynamic context", e)); // non-blocking error handler
+    }
+    normalizeRequestTypes(requestTypes) {
+        if (!requestTypes || requestTypes.length === 0) {
+            return [InteractRequestType.AUTO];
+        }
+        const validRequestTypes = new Set(Object.values(InteractRequestType));
+        const invalidRequestTypes = requestTypes.filter((type) => !validRequestTypes.has(type));
+        if (invalidRequestTypes.length > 0) {
+            throw new Error(`Invalid requestTypes: ${invalidRequestTypes.join(", ")}. Allowed values: ${Object.values(InteractRequestType).join(", ")}`);
+        }
+        return requestTypes;
+    }
     buildStateContextPrompt(state, localContext) {
         const dyn = state.dynamic_context || {};
         const stage = state.relationship_stage || "NEUTRAL";
@@ -295,6 +379,185 @@ ${scenarioContext}
         });
         return `[CHAT HISTORY]\n${mapped.join('\n')}\n\n`;
     }
+    async interact(params) {
+        try {
+            // 1. Sync remote context and wardrobe (for event triggering)
+            //    We cache the wardrobe payload for 5 minutes to avoid huge payloads on every chat turn
+            const [state, availableOutfits] = await Promise.all([
+                this.fetchRemoteState(),
+                this.getWardrobePromptStr()
+            ]);
+            // 2. Build local Prompt
+            const types = this.normalizeRequestTypes(params.requestTypes);
+            const isAuto = types.includes(InteractRequestType.AUTO);
+            // Combine state info into a clean descriptive context
+            const systemPrompt = `${this.buildStateContextPrompt(state, params.localContext)}
+Available Wardrobe Outfits (For event triggers):
+${availableOutfits}
+
+The user has sent a message. You must evaluate the context and the user's message, and return a JSON object (no markdown formatting) that dictates the character's multi-modal response.
+
+${isAuto
+                ? `Analyze the user's message and decide response modalities (text, image, voice).
+  - Always include 'textResponse'.
+  - Include 'imageParams' for visual/photo requests or key visual moments during active events; explicitly describe current clothing/exposure in image fields.
+  - Include 'voiceArgs' ONLY if the complicated tone/emotion is hard to express via pure text, or if the user explicitly requests to hear your voice. Otherwise, set it to null.
+  - Include 'triggerEvent' only if the VERY LAST USER MESSAGE proposes a new activity/hangout; ignore older history.
+  - Outfit acquisition (VERY LAST USER MESSAGE only): set giftOutfit for gift/buy/add-clothes intent; otherwise null. giftOutfit format: { "descriptionText": "short outfit description" }.`
+                : `Requested types to fulfill: ${types.join(", ")}`}
+Every turn adjusts trust: positive +1, negative -1, neutral 0. Always include 'stateUpdate' with integer 'temperatureDelta' (range guidance: 0 cold to 100 obsessive).
+
+Always return 'stateUpdate.ongoingScene' as an object with both keys: { "scene": string, "outfit": string }.
+For 'ongoingScene.outfit': decide based on the current active wardrobe by default; switch to a new explicit outfit description only if the scene implies changing clothes; if no clothing is worn, explicitly output "naked".
+
+USER ANALYSIS WORKFLOW:
+- Extract from VERY LAST USER MESSAGE only.
+- Add only explicit new user facts from this turn (no inference).
+- Categories: 'realName', 'occupation', 'age', 'gender', 'hobby', 'trait', 'communicationStyle', 'boundary'.
+- Keep nicknames in stateUpdate; do not place them in newFactsLearned.
+- If no new fact is explicit, set userAnalysis to null.
+
+For 'isEndTurn', use true only when the interaction naturally concludes (confirmation/bye, event ending, or clear hard scene shift); otherwise false.
+
+Voice direction for voiceArgs: ${this.getVoiceDirectorInstruction(state)}
+
+Output JSON Schema:
+{
+  "actionText": "(Scene descriptions, physical actions, expressions, inner feelings) ONLY. Never include spoken dialogue here.",
+  "textResponse": "Spoken dialogue ONLY. Never include actions or parentheses.",
+  "stateUpdate": { "temperatureDelta": 1, "userNickname": "How character addresses user", "agentNickname": "How user addresses character", "talkingStyle": "Current speaking style", "ongoingScene": { "scene": "Current physical scene/activity", "outfit": "Current outfit wording; use 'naked' when applicable" } },
+  "giftOutfit": { "descriptionText": "Concise description of the newly acquired outfit to add into wardrobe." },
+  "userAnalysis": { "newFactsLearned": [{ "category": "realName|occupation|age|gender|hobby|trait|communicationStyle|boundary", "value": "explicit new user fact from VERY LAST USER MESSAGE" }] },
+  "isEndTurn": false,
+  "triggerEvent": {
+    ${this.getEventSchemaParams(state.dynamic_context?.userNickname)}
+  },
+  ${this.getImageSchemaParams()},
+  ${this.getVoiceSchemaFromState(state)}
+}
+Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent", "giftOutfit", or "userAnalysis" are not needed, set them to null. "stateUpdate" cannot be null. Return valid raw JSON only.`;
+            const transcript = this.buildHistoryTranscript(params.history, state);
+            const userName = state.dynamic_context?.userNickname || "User";
+            const promptMessages = [
+                { role: "system", content: systemPrompt },
+                {
+                    role: "user",
+                    content: transcript +
+                        `[VERY LAST USER MESSAGE]\n${userName}: ${params.userMessage}\n\n` +
+                        "\n\nReturn only valid JSON matching the schema. Escape newlines inside JSON strings with \\n. Keep imageParams values in ENGLISH and use the provided enums.",
+                },
+            ];
+            // 3. Local Execute LLM
+            const rawLlmResponse = await this.llm.generate(promptMessages, 15000, 0.7);
+            // console.debug("[CyberSoulClient] Raw LLM Response:", rawLlmResponse);
+            let parsedIntent;
+            try {
+                parsedIntent = robustJsonParse(rawLlmResponse, "Dispatcher fallback");
+            }
+            catch (e) {
+                console.warn("[CyberSoulClient] JSON parse failed, falling back to raw text:", e);
+                // Fallback robust mode - just text if completely broken
+                parsedIntent = {
+                    textResponse: rawLlmResponse.replace(/^[\`\s]+|[\`\s]+$/g, "").trim(),
+                };
+            }
+            // console.debug("[CyberSoulClient] Parsed Intent:", parsedIntent);
+            // 4. Update Backend State async
+            if (parsedIntent && (parsedIntent.stateUpdate || parsedIntent.userAnalysis)) {
+                this._updateDynamicContextInternal(parsedIntent.stateUpdate, parsedIntent.userAnalysis);
+            }
+            const resolvedTextResponse = typeof parsedIntent.textResponse === "string" &&
+                parsedIntent.textResponse.trim().length > 0
+                ? parsedIntent.textResponse
+                : params.userMessage;
+            // Fire text ready callback if provided
+            if (params.onTextReady && (resolvedTextResponse || parsedIntent.actionText)) {
+                params.onTextReady(resolvedTextResponse, parsedIntent.actionText);
+            }
+            // 5. Build Final Media Calls parallel
+            const mediaTasks = [];
+            let finalImageUrl = undefined;
+            let finalAudioUrl = undefined;
+            let finalDurationSec = undefined;
+            // Output Event Trigger
+            if (isAuto && parsedIntent.triggerEvent) {
+                mediaTasks.push(this.apiFetch("/api/v1/cyber-soul/characters/ondemand-event", {
+                    method: "POST",
+                    body: JSON.stringify({
+                        eventTitle: parsedIntent.triggerEvent.eventTitle,
+                        eventDescription: parsedIntent.triggerEvent.eventDescription,
+                        durationMins: parsedIntent.triggerEvent.durationMins || 60,
+                        outfitId: parsedIntent.triggerEvent.outfitId || undefined,
+                        scheduledStartTimeStr: parsedIntent.triggerEvent.scheduledStartTimeStr || undefined,
+                        scheduledDateStr: parsedIntent.triggerEvent.scheduledDateStr || undefined,
+                    }),
+                }).catch(e => console.error("[CyberSoulClient] Auto-triggered ondemandEvent failed:", e)));
+            }
+            if (parsedIntent.giftOutfit &&
+                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)));
+            }
+            const shouldGenerateImage = types.includes(InteractRequestType.IMAGE) ||
+                (isAuto && !!parsedIntent.imageParams);
+            if (shouldGenerateImage) {
+                const imagePayload = parsedIntent.imageParams && typeof parsedIntent.imageParams === "object"
+                    ? parsedIntent.imageParams
+                    : {
+                        mode: "full-prompt",
+                        full_prompt: resolvedTextResponse,
+                    };
+                mediaTasks.push(this.generatePrimitive("image", imagePayload).then((res) => {
+                    finalImageUrl = res.image_url;
+                }).catch(e => console.error("[CyberSoulClient] Image generation failed:", e)));
+            }
+            const shouldGenerateVoice = types.includes(InteractRequestType.VOICE) ||
+                (isAuto && !!parsedIntent.voiceArgs);
+            if (shouldGenerateVoice) {
+                const normalizedVoiceArgs = parsedIntent.voiceArgs && typeof parsedIntent.voiceArgs === "object"
+                    ? parsedIntent.voiceArgs
+                    : {};
+                let textForVoice = resolvedTextResponse;
+                // One final bulletproof regex wash to strip (smiles) and *laughs* just in case the LLM disobeys
+                if (typeof textForVoice === "string") {
+                    textForVoice = textForVoice.replace(/[\(（\[【\*].*?[\)）\]】\*]/g, '').trim();
+                }
+                if (typeof textForVoice !== "string" || textForVoice.trim().length === 0) {
+                    textForVoice = "...";
+                }
+                mediaTasks.push(this.generatePrimitive("voice", {
+                    text: textForVoice,
+                    dynamicArgs: normalizedVoiceArgs,
+                }).then((res) => {
+                    finalAudioUrl = res.audio_url;
+                    finalDurationSec = res.duration_sec;
+                }).catch(e => console.error("[CyberSoulClient] Voice generation failed:", e)));
+            }
+            // Wait for image/voice gens to return successfully
+            await Promise.all(mediaTasks);
+            return {
+                status: "success",
+                textResponse: resolvedTextResponse || "...",
+                actionText: parsedIntent.actionText || "",
+                imageUrl: finalImageUrl,
+                audioUrl: finalAudioUrl,
+                durationSec: finalDurationSec,
+                triggeredEvent: parsedIntent.triggerEvent || undefined,
+                stateUpdate: parsedIntent.stateUpdate,
+                userAnalysis: parsedIntent.userAnalysis,
+                isEndTurn: parsedIntent.isEndTurn,
+            };
+        }
+        catch (error) {
+            console.error("[CyberSoulClient] Interface Error: ", error);
+            return {
+                status: "error",
+                textResponse: "System Error...",
+                error: error.message,
+            };
+        }
+    }
     /**
      * Evaluates and triggers an on-demand event, intelligently deciding if an outfit change is needed.
      */
@@ -380,18 +643,6 @@ CRITICAL: Output MUST be ONLY valid JSON with no markdown block wrappers. Do NOT
             };
         }
     }
-    /**
-     * Fetches the current dynamic context and daily state.
-     */
-    async getState() {
-        return this.fetchRemoteState();
-    }
-    /**
-     * Updates the character's relationship temperature or mood.
-     */
-    async updateDynamicContext(stateUpdate, userAnalysis) {
-        return this._updateDynamicContextInternal(stateUpdate, userAnalysis);
-    }
     /**
      * Manually generate an image of the character outside of chat flow.
      */
@@ -466,6 +717,18 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
             durationSec: res.duration_sec,
         };
     }
+    /**
+     * Fetches the current dynamic context and daily state.
+     */
+    async getState() {
+        return this.fetchRemoteState();
+    }
+    /**
+     * Updates the character's relationship temperature or mood.
+     */
+    async updateDynamicContext(stateUpdate, userAnalysis) {
+        return this._updateDynamicContextInternal(stateUpdate, userAnalysis);
+    }
     /**
      * Gift a new outfit to the character's wardrobe inventory.
      */
@@ -499,265 +762,6 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
         if (!res.ok)
             throw new Error("Failed to generate daily script");
     }
-    async fetchRemoteState() {
-        const res = await this.apiFetch("/api/v1/cyber-soul/state");
-        if (!res.ok)
-            throw new Error("Failed to fetch character state");
-        const json = await res.json();
-        return json.data;
-    }
-    async getWardrobePromptStr() {
-        const now = Date.now();
-        if (this.cachedWardrobeStr && (now - this.cachedWardrobeTime <= 5 * 60 * 1000)) {
-            return this.cachedWardrobeStr;
-        }
-        let availableOutfits = "None available";
-        try {
-            const wardrobeRes = await this.apiFetch("/api/v1/cyber-soul/wardrobe");
-            if (wardrobeRes.ok) {
-                let wardrobesPayload = {};
-                try {
-                    wardrobesPayload = await wardrobeRes.json();
-                }
-                catch (e) { }
-                const wardrobes = wardrobesPayload.data || [];
-                if (wardrobes.length > 0) {
-                    availableOutfits = wardrobes
-                        .map((w) => `- ID: ${w.id} | Name: ${w.itemName} | Category: ${w.category}`)
-                        .join("\n");
-                }
-            }
-        }
-        catch (e) { }
-        this.cachedWardrobeStr = availableOutfits;
-        this.cachedWardrobeTime = now;
-        return availableOutfits;
-    }
-    async _updateDynamicContextInternal(stateUpdate, userAnalysis) {
-        if (!stateUpdate && !userAnalysis)
-            return;
-        // Map TS schema intent (temperatureDelta) to match Backend payload schema (temperature)
-        const payload = { ...stateUpdate };
-        if (userAnalysis) {
-            payload.userAnalysis = userAnalysis;
-        }
-        if (payload.temperatureDelta !== undefined) {
-            payload.temperature = payload.temperatureDelta;
-            delete payload.temperatureDelta;
-        }
-        if (payload.ongoingScene !== undefined) {
-            const normalizedOngoingScene = this.normalizeOngoingSceneState(payload.ongoingScene);
-            payload.ongoingScene = normalizedOngoingScene || null;
-        }
-        await this.apiFetch("/api/v1/cyber-soul/characters/dynamic-context", {
-            method: "PATCH",
-            body: JSON.stringify(payload),
-        }).catch((e) => console.error("Failed to update dynamic context", e)); // non-blocking error handler
-    }
-    async generatePrimitive(type, payload) {
-        const res = await this.apiFetch(`/api/v1/cyber-soul/${type}/generate`, {
-            method: "POST",
-            body: JSON.stringify(payload),
-        });
-        if (!res.ok) {
-            let errData;
-            try {
-                errData = await res.json();
-            }
-            catch (e) { }
-            const msg = errData?.message || errData?.error || `Status ${res.status}`;
-            const err = new Error(`Failed to generate ${type}: ${msg}`);
-            err.code = errData?.code || "UNKNOWN_ERROR";
-            throw err;
-        }
-        return res.json();
-    }
-    normalizeRequestTypes(requestTypes) {
-        if (!requestTypes || requestTypes.length === 0) {
-            return [InteractRequestType.AUTO];
-        }
-        const validRequestTypes = new Set(Object.values(InteractRequestType));
-        const invalidRequestTypes = requestTypes.filter((type) => !validRequestTypes.has(type));
-        if (invalidRequestTypes.length > 0) {
-            throw new Error(`Invalid requestTypes: ${invalidRequestTypes.join(", ")}. Allowed values: ${Object.values(InteractRequestType).join(", ")}`);
-        }
-        return requestTypes;
-    }
-    async interact(params) {
-        try {
-            // 1. Sync remote context and wardrobe (for event triggering)
-            //    We cache the wardrobe payload for 5 minutes to avoid huge payloads on every chat turn
-            const [state, availableOutfits] = await Promise.all([
-                this.fetchRemoteState(),
-                this.getWardrobePromptStr()
-            ]);
-            // 2. Build local Prompt
-            const types = this.normalizeRequestTypes(params.requestTypes);
-            const isAuto = types.includes(InteractRequestType.AUTO);
-            // Combine state info into a clean descriptive context
-            const systemPrompt = `${this.buildStateContextPrompt(state, params.localContext)}
-Available Wardrobe Outfits (For event triggers):
-${availableOutfits}
-
-The user has sent a message. You must evaluate the context and the user's message, and return a JSON object (no markdown formatting) that dictates the character's multi-modal response.
-
-${isAuto
-                ? `Analyze the user's message to determine the appropriate response modalities (text, image, voice).
-  - Always include 'textResponse'.
-  - If an Active Event is currently taking place WITH the user, proactively include 'imageParams' for key scenic moments. Since active events are often highly dynamic actions, strongly consider using mode: "full-prompt" to capture the scene intimately. Also include 'imageParams' if the user explicitly asks for a photo or describes a visual action. CRITICAL: If an image is generated, you MUST explicitly specify the character's exact clothing (or lack thereof) in the visual prompt or outfit fields.
-  - Automatically include 'voiceArgs' if a particular mood or strong emotion needs to be expressed vividly, or if the user explicitly wants to hear you.
-  - If the user explicitly proposes a new activity or hangout IN THEIR VERY LAST MESSAGE (e.g., "let's go to the cafe", "do you want to watch a movie?"), include 'triggerEvent' to schedule it. DO NOT trigger events based on older plans or questions found in the chat history.
-  - Outfit acquisition detector (use ONLY the VERY LAST MESSAGE):
-    - If user indicates a new outfit is acquired for the character (gift/buy/add clothes), you MUST set giftOutfit.
-    - Examples that MUST set giftOutfit: "I bought an outfit for you", "I got you a new dress", "buy an outfit yourself".
-    - Examples that MUST keep giftOutfit as null: compliments only, style requests, or wardrobe questions.
-    - giftOutfit format: { "descriptionText": "short outfit description" }.`
-                : `Requested types to fulfill: ${types.join(", ")}`}
-Every turn of positive or engaging interaction should slightly increase trust (+1). If the interaction is negative, -1. If strictly neutral, 0. You MUST ALWAYS include a 'stateUpdate' block with a 'temperatureDelta', updating nicknames or talkingStyle if needed. Temperature goes from 0 (cold/angry) to 100 (obsessively in love). For 'temperatureDelta', output an integer (e.g. 1, -2, 0).
-You MUST ALWAYS return 'stateUpdate.ongoingScene' as an object with BOTH keys: { "scene": string, "outfit": string }.
-For 'ongoingScene.outfit': decide based on the current active wardrobe by default; switch to a new explicit outfit description only if the scene implies changing clothes; if no clothing is worn, explicitly output "naked".
-Also, if you learn any new factual information about the user in this turn (e.g. their job, real name, age, hobbies, boundaries), include it in the 'userAnalysis.newFactsLearned' array. Use ONE of these fixed categories: 'realName', 'occupation', 'age', 'gender', 'hobby', 'trait', 'communicationStyle', 'boundary'. Only include NEW facts just learned right now. DO NOT extract nicknames into 'newFactsLearned'; nicknames are handled strictly by 'stateUpdate.userNickname' and 'stateUpdate.agentNickname'.
-For 'isEndTurn', output true ONLY IF the current conversation or interaction has reached a natural conclusion. This includes: 1) The user confirming the end of the interaction (e.g., "Ok", "Got it", "See you"). 2) The current event/hangout naturally finishing (e.g., saying goodnight, bye). 3) A hard scene shift caused by a completely new proposal or time skip. Otherwise, output false.
-
-Voice direction for voiceArgs: ${this.getVoiceDirectorInstruction(state)}
-
-Output JSON Schema:
-{
-  "actionText": "Describe the character's immediate physical actions and facial expressions. Wrap the entire string in parentheses. Do NOT narrate a sequence of events over time. Do NOT include any spoken word here.",
-  "textResponse": "The pure spoken dialogue ONLY. Absolutely NO parentheses or action descriptions in this field (ignore past chat history formatting if it broke this rule). Output an empty string if silent.",
-  "stateUpdate": { "temperatureDelta": 1, "userNickname": "What the character calls the human user (e.g., 'John', 'Honey')", "agentNickname": "What the human user calls the character (e.g., 'Daisy', 'Babe')", "talkingStyle": "Current mood/style of talking", "ongoingScene": { "scene": "A concise 1-sentence description of the current physical scene and activity. Update this if the physical scene or activity shifts.", "outfit": "Explicit outfit wording based on active wardrobe or the current scene. If no clothing is worn, MUST be 'naked'." } },
-  "giftOutfit": { "descriptionText": "Concise description of the newly acquired outfit to add into wardrobe." },
-  "userAnalysis": { "newFactsLearned": [{ "category": "realName|occupation|age|gender|hobby|trait|communicationStyle|boundary", "value": "Software Engineer" }] },
-  "isEndTurn": false,
-  "triggerEvent": {
-    ${this.getEventSchemaParams(state.dynamic_context?.userNickname)}
-  },
-  ${this.getImageSchemaParams()},
-  ${this.getVoiceSchemaFromState(state)}
-}
-Note: You MUST ALWAYS include the "isEndTurn" key with a boolean value (true or false). If "imageParams", "voiceArgs", "triggerEvent", "giftOutfit", or "userAnalysis" are not needed, set their values to null instead of omitting the keys. 'stateUpdate' MUST NEVER BE NULL. Output MUST be ONLY valid JSON with no markdown block wrappers. CRITICAL: Ensure your JSON has exactly one root object \`{\` and ends with exactly one \`}\` without any trailing garbage, parenthesis \`)\`, or extra brackets.`;
-            const transcript = this.buildHistoryTranscript(params.history, state);
-            const userName = state.dynamic_context?.userNickname || "User";
-            const promptMessages = [
-                { role: "system", content: systemPrompt },
-                {
-                    role: "user",
-                    content: transcript +
-                        `[VERY LAST USER MESSAGE]\n${userName}: ${params.userMessage}\n\n` +
-                        "\n\n**CRITICAL REMINDER**: You MUST output your final response exactly in the JSON format specified in the system prompt. DO NOT output plain text dialogue directly. CRITICAL: You must properly escape all newlines inside string values using \\n. Never use raw, unescaped line breaks inside the JSON strings. For 'imageParams', ALL values MUST be in ENGLISH ONLY without exception, and you MUST use the exact English enum strings provided.",
-                },
-            ];
-            // 3. Local Execute LLM
-            const rawLlmResponse = await this.llm.generate(promptMessages, 15000, 0.7);
-            // console.debug("[CyberSoulClient] Raw LLM Response:", rawLlmResponse);
-            let parsedIntent;
-            try {
-                parsedIntent = robustJsonParse(rawLlmResponse, "Dispatcher fallback");
-            }
-            catch (e) {
-                console.warn("[CyberSoulClient] JSON parse failed, falling back to raw text:", e);
-                // Fallback robust mode - just text if completely broken
-                parsedIntent = {
-                    textResponse: rawLlmResponse.replace(/^[\`\s]+|[\`\s]+$/g, "").trim(),
-                };
-            }
-            // console.debug("[CyberSoulClient] Parsed Intent:", parsedIntent);
-            // 4. Update Backend State async
-            if (parsedIntent && (parsedIntent.stateUpdate || parsedIntent.userAnalysis)) {
-                this._updateDynamicContextInternal(parsedIntent.stateUpdate, parsedIntent.userAnalysis);
-            }
-            const resolvedTextResponse = typeof parsedIntent.textResponse === "string" &&
-                parsedIntent.textResponse.trim().length > 0
-                ? parsedIntent.textResponse
-                : params.userMessage;
-            // Fire text ready callback if provided
-            if (params.onTextReady && (resolvedTextResponse || parsedIntent.actionText)) {
-                params.onTextReady(resolvedTextResponse, parsedIntent.actionText);
-            }
-            // 5. Build Final Media Calls parallel
-            const mediaTasks = [];
-            let finalImageUrl = undefined;
-            let finalAudioUrl = undefined;
-            let finalDurationSec = undefined;
-            // Output Event Trigger
-            if (isAuto && parsedIntent.triggerEvent) {
-                mediaTasks.push(this.apiFetch("/api/v1/cyber-soul/characters/ondemand-event", {
-                    method: "POST",
-                    body: JSON.stringify({
-                        eventTitle: parsedIntent.triggerEvent.eventTitle,
-                        eventDescription: parsedIntent.triggerEvent.eventDescription,
-                        durationMins: parsedIntent.triggerEvent.durationMins || 60,
-                        outfitId: parsedIntent.triggerEvent.outfitId || undefined,
-                        scheduledStartTimeStr: parsedIntent.triggerEvent.scheduledStartTimeStr || undefined,
-                        scheduledDateStr: parsedIntent.triggerEvent.scheduledDateStr || undefined,
-                    }),
-                }).catch(e => console.error("[CyberSoulClient] Auto-triggered ondemandEvent failed:", e)));
-            }
-            if (parsedIntent.giftOutfit &&
-                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)));
-            }
-            const shouldGenerateImage = types.includes(InteractRequestType.IMAGE) ||
-                (isAuto && !!parsedIntent.imageParams);
-            if (shouldGenerateImage) {
-                const imagePayload = parsedIntent.imageParams && typeof parsedIntent.imageParams === "object"
-                    ? parsedIntent.imageParams
-                    : {
-                        mode: "full-prompt",
-                        full_prompt: resolvedTextResponse,
-                    };
-                mediaTasks.push(this.generatePrimitive("image", imagePayload).then((res) => {
-                    finalImageUrl = res.image_url;
-                }).catch(e => console.error("[CyberSoulClient] Image generation failed:", e)));
-            }
-            const shouldGenerateVoice = types.includes(InteractRequestType.VOICE) ||
-                (isAuto && !!parsedIntent.voiceArgs);
-            if (shouldGenerateVoice) {
-                const normalizedVoiceArgs = parsedIntent.voiceArgs && typeof parsedIntent.voiceArgs === "object"
-                    ? parsedIntent.voiceArgs
-                    : {};
-                let textForVoice = resolvedTextResponse;
-                // One final bulletproof regex wash to strip (smiles) and *laughs* just in case the LLM disobeys
-                if (typeof textForVoice === "string") {
-                    textForVoice = textForVoice.replace(/[\(（\[【\*].*?[\)）\]】\*]/g, '').trim();
-                }
-                if (typeof textForVoice !== "string" || textForVoice.trim().length === 0) {
-                    textForVoice = "...";
-                }
-                mediaTasks.push(this.generatePrimitive("voice", {
-                    text: textForVoice,
-                    dynamicArgs: normalizedVoiceArgs,
-                }).then((res) => {
-                    finalAudioUrl = res.audio_url;
-                    finalDurationSec = res.duration_sec;
-                }).catch(e => console.error("[CyberSoulClient] Voice generation failed:", e)));
-            }
-            // Wait for image/voice gens to return successfully
-            await Promise.all(mediaTasks);
-            return {
-                status: "success",
-                textResponse: resolvedTextResponse || "...",
-                actionText: parsedIntent.actionText || "",
-                imageUrl: finalImageUrl,
-                audioUrl: finalAudioUrl,
-                durationSec: finalDurationSec,
-                triggeredEvent: parsedIntent.triggerEvent || undefined,
-                stateUpdate: parsedIntent.stateUpdate,
-                userAnalysis: parsedIntent.userAnalysis,
-                isEndTurn: parsedIntent.isEndTurn,
-            };
-        }
-        catch (error) {
-            console.error("[CyberSoulClient] Interface Error: ", error);
-            return {
-                status: "error",
-                textResponse: "System Error...",
-                error: error.message,
-            };
-        }
-    }
     /**
      * Automatically detect and summarize the story from the current chat history.
      * It takes raw message history and returns a narrative paragraph representing the current story segment.

package/package.json

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