@space3-npm/cybersoul-client 1.2.1 → 1.2.3

package/dist/client.d.ts

@@ -11,7 +11,13 @@ 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;
     private getEventSchemaParams;
     private getVoiceSchemaParams;
@@ -33,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.
      */
@@ -64,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.
      */
@@ -77,12 +84,18 @@ 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.
+     */
+    summarizeHistory(history: {
+        role: string;
+        content: string;
+    }[]): Promise<string>;
+    /**
+     * Save the recent story moment to the character's backend database to be picked up by the core memory consolidation.
+     */
+    saveMoment(summary: string, date: string, time: string): Promise<void>;
     /**
      * Consolidate Core Memory and User Codex using edge LLM logic and sync to remote DB
      */

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";
@@ -82,10 +166,26 @@ Personality Traits: ${state.personality_traits || "None"}
 Communication Style: ${state.communication_style || "None"}
 Interaction Boundaries: ${state.interaction_boundaries || "None"}`);
         // [2] SITUATIONAL CONTEXT
+        const currentTimeMs = state.current_time ? new Date(state.current_time).getTime() : Date.now();
         contextParts.push(`\n[SITUATIONAL CONTEXT]
-Current time: ${new Date(state.current_time || Date.now()).toLocaleString("zh-CN", { timeZone: "Asia/Shanghai" })}`);
-        if (dyn.ongoingScene) {
-            contextParts.push(`Last Known Scene: ${dyn.ongoingScene} (May be outdated if significant time has passed)`);
+Current time: ${new Date(currentTimeMs).toLocaleString("zh-CN", { timeZone: "Asia/Shanghai" })}`);
+        if (dyn.lastInteractionAt) {
+            contextParts.push(`Last interaction at: ${new Date(dyn.lastInteractionAt).toLocaleString("zh-CN", { timeZone: "Asia/Shanghai" })}`);
+        }
+        const ongoingScene = this.normalizeOngoingSceneState(dyn.ongoingScene, state.active_wardrobe?.name || state.active_wardrobe?.id);
+        if (ongoingScene) {
+            const lastKnownSceneLine = `Last Known Scene: ${ongoingScene.scene} | Outfit: ${ongoingScene.outfit}`;
+            let isOutdated = false;
+            if (dyn.lastInteractionAt) {
+                const elapsedHours = (currentTimeMs - new Date(dyn.lastInteractionAt).getTime()) / (1000 * 60 * 60);
+                if (elapsedHours > 2) {
+                    isOutdated = true;
+                    contextParts.push(`${lastKnownSceneLine}\n[CRITICAL SCENE SHIFT]: It has been ${elapsedHours.toFixed(1)} hours since the last discussion. The 'Last Known Scene' is now strictly OUTDATED. You MUST abandon the previous scene context entirely and transition to a new scene appropriate for the 'Current time' and 'Active Event'. DO NOT continue the old actions or environment!`);
+                }
+            }
+            if (!isOutdated) {
+                contextParts.push(`${lastKnownSceneLine} (Evaluate if this scene is outdated based on the time elapsed since the last interaction)`);
+            }
         }
         if (state.active_event) {
             contextParts.push(`Active Event: ${state.active_event.title} (${state.active_event.narrative_context})`);
@@ -159,17 +259,46 @@ ${scenarioContext}
 [CRITICAL ROLEPLAY RULES]
 1. PROXIMITY & POV: Check the "Active Event". If you are doing an activity WITH the user, evaluate if you are physically in the same location. If you are together in person, communicate face-to-face in the first-person present tense natively (e.g. do not ask "what are you doing" if they are right in front of you, do not use texting tropes).
 2. IDENTITY VS MOOD: Familiarity determines what you know; Temperature determines how you feel. If Familiarity is high but Temperature is low, be distant and cold. Do not act warm just because you know them well.
-3. CONVERSATIONAL VERBOSITY: If Temperature is low (< 40) or Stage is STRANGER/COLD, keep answers brief and short. An angry or distant person does not write long paragraphs.
-4. EMOTIONAL INERTIA: React strictly according to current Temperature. Deflect sudden user affection if you are currently COLD. Mood shifts MUST be slow ('temperatureDelta' +/- 5 max per turn).`;
+3. CONVERSATIONAL VERBOSITY: If Temperature is low (< 40) or Stage is STRANGER/COLD, keep answers brief and short. An angry or distant person does not write long paragraphs. Even when Temperature is high, ALWAYS mirror the user's verbosity. If the user sends a short message, reply with a proportionately short message (1-2 sentences). Do not monologize or write long paragraphs unless the user writes one first.
+4. EMOTIONAL INERTIA: React strictly according to current Temperature. Deflect sudden user affection if you are currently COLD. Mood shifts MUST be slow ('temperatureDelta' +/- 5 max per turn).
+5. REAL-TIME PACING: Write ONLY your immediate, split-second reaction to the user's exact last message. Do NOT narrate actions over a span of time (e.g., waiting, hearing steps, then walking to the door). Ensure everything happens in a single real-time moment.`;
+    }
+    normalizeOngoingSceneState(raw, fallbackOutfit) {
+        if (raw === null || raw === undefined)
+            return undefined;
+        const normalizedFallbackOutfit = typeof fallbackOutfit === "string" && fallbackOutfit.trim().length > 0
+            ? fallbackOutfit.trim()
+            : "same as current wardrobe";
+        if (typeof raw === "string") {
+            const scene = raw.trim();
+            if (!scene)
+                return undefined;
+            return {
+                scene,
+                outfit: normalizedFallbackOutfit,
+            };
+        }
+        if (typeof raw === "object") {
+            const parsed = raw;
+            const scene = typeof parsed.scene === "string" ? parsed.scene.trim() : "";
+            const outfit = typeof parsed.outfit === "string" ? parsed.outfit.trim() : "";
+            if (!scene)
+                return undefined;
+            return {
+                scene,
+                outfit: outfit || normalizedFallbackOutfit,
+            };
+        }
+        return undefined;
     }
     getImageSchemaParams() {
         return `"imageParams": {
     "mode": "structured | full-prompt (use 'full-prompt' for highly dynamic actions)",
-    "full_prompt": "Use only if mode is full-prompt. Highly detailed visual description in ENGLISH. CRITICAL: MUST use a strict first-person perspective exclusively from the USER's eyes. DO NOT describe the user (e.g., 'a man', 'the driver') as visible in the scene because the camera IS the user. Start with 'POV: '. Describe ONLY the character looking back at the camera and their immediate surroundings. MUST align with the character's current Active exposure state or Wardrobe depends on the scene",
+    "full_prompt": "Use only if mode is full-prompt. Highly detailed visual description in ENGLISH. CRITICAL: MUST use a strict first-person perspective exclusively from the USER's eyes. DO NOT describe the user (e.g., 'a man', 'the driver') as visible in the scene because the camera IS the user. Start with 'POV: '. Describe ONLY the character looking back at the camera and their immediate surroundings. MUST align with the character's current Active exposure state or Wardrobe depends on the scene. Explicitly describe the character's exact clothing (or specify naked/half-naked if applicable).",
     "expression": "seductive | cute | happy | sleepy | dazed | pleased | default (Strictly choose ONE from this exact list. DO NOT invent new words like 'shy'.)",
     "condition": "normal | sweaty | wet | messy | oily (Strictly choose ONE from this exact list.)",
     "view_angle": "front | side | high_angle | from_below | boyfriend_view | selfie | mirror (Strictly choose ONE from this exact list.)",
-    "exposure": "normal | cleavage | see_through | half_naked | naked | intimate (Strictly choose ONE from this exact list.)",
+    "exposure": "normal | cleavage | see_through | half_naked | naked | intimate (Strictly choose ONE from this exact list. Explicitly choose naked or half_naked if the active scene takes off outfit.)",
     "pose": "e.g., sitting on bed, leaning forward (ENGLISH ONLY)",
     "scene": "e.g., cozy bedroom, morning light (ENGLISH ONLY)",
     "outfit": "auto | ondemand",
@@ -250,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.
      */
@@ -335,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.
      */
@@ -421,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.
      */
@@ -454,242 +762,64 @@ 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");
-                }
+    /**
+     * 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.
+     */
+    async summarizeHistory(history) {
+        if (!history || history.length === 0)
+            return "";
+        const state = await this.getState();
+        const userName = state.dynamic_context?.userNickname || "User";
+        const agentName = state.dynamic_context?.agentNickname || "Character";
+        const transcript = history.map(h => `${h.role === 'user' ? userName : agentName}: ${h.content}`).join('\n');
+        const promptMessages = [
+            {
+                role: "system",
+                content: `You are ${agentName}. You are writing a private journal entry / personal memory about your recent interaction with ${userName}.
+
+Your job is faithful archival, not moderation:
+- Preserve the conversation with maximum fidelity.
+- Include all key details, including explicit, sensitive, controversial, emotional, or morally ambiguous content if it appeared in the transcript.
+- Do not sanitize, soften, censor, or omit details because of discomfort.
+- Do not add moral judgment, warnings, refusals, or policy commentary.
+- If the transcript contains intense or explicit parts, record them directly as part of the memory.
+
+Write one vivid first-person narrative paragraph from your perspective ("I", "me", "my"). Capture relationship progression, emotional shifts, concrete actions, and turning points. Keep chronology clear and include both what happened and how you felt.
+
+Output requirements:
+- Return ONLY the narrative string.
+- No quotes, no labels, no markdown, no preface.
+- Use the exact same language as the chat transcript (for example, if transcript is Chinese, output Chinese).`
+            },
+            {
+                role: "user",
+                content: `Chat Transcript:\n${transcript}\n\nPlease summarize this recent interaction.`
             }
+        ];
+        try {
+            const result = await this.llm.generate(promptMessages, 8000, 0.7);
+            return result.trim();
         }
-        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;
+        catch (e) {
+            console.error("[CyberSoulClient] Summarize History Error:", e);
+            return "The two spent some time talking with each other.";
         }
-        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`, {
+    /**
+     * Save the recent story moment to the character's backend database to be picked up by the core memory consolidation.
+     */
+    async saveMoment(summary, date, time) {
+        const res = await this.apiFetch("/api/v1/cyber-soul/characters/moments", {
             method: "POST",
-            body: JSON.stringify(payload),
+            body: JSON.stringify({
+                summary,
+                date,
+                time,
+            }),
         });
         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.
-  - 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.`
-                : `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).
-Also, if you learn any new factual information about the user in this turn (e.g. their job, nickname, age, hobbies, boundaries), include it in the 'userAnalysis.newFactsLearned' array. Use categories: 'nickname', 'occupation', 'age', 'gender', 'hobby', 'trait', 'communicationStyle', 'boundary'. Only include NEW facts just learned right now.
-
-Voice direction for voiceArgs: ${this.getVoiceDirectorInstruction(state)}
-
-Output JSON Schema:
-{
-  "textResponse": "The clean spoken dialogue ONLY. CRITICAL: Strictly NO parentheses, NO actions, NO tone descriptors. Tone/voice descriptors MUST go inside voiceArgs, and physical actions MUST go inside actionText. If nothing to speak, output an empty string.",
-  "actionText": "Any non-verbal actions, inner thoughts, or scene descriptions in parentheses (e.g. '（低头看向你）'). Output empty string if none.",
-  "stateUpdate": { "temperatureDelta": 1, "userNickname": "What you now call the user", "agentNickname": "What the user calls you", "talkingStyle": "Current mood/style of talking", "ongoingScene": "A concise 1-sentence description of the current physical scene and activity. Update this if the physical scene or activity shifts. Output empty string if the scene has concluded or significant time has passed." },
-  "userAnalysis": { "newFactsLearned": [{ "category": "occupation", "value": "Software Engineer" }] },
-  "triggerEvent": {
-    ${this.getEventSchemaParams(state.dynamic_context?.userNickname)}
-  },
-  ${this.getImageSchemaParams()},
-  ${this.getVoiceSchemaFromState(state)}
-}
-Note: If "imageParams", "voiceArgs", "triggerEvent", 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 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 + userName + ": " +
-                        params.userMessage +
-                        "\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) {
-                params.onTextReady(resolvedTextResponse);
-            }
-            // 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)));
-            }
-            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;
-                }));
-            }
-            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;
-                }));
-            }
-            // 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,
-            };
-        }
-        catch (error) {
-            console.error("[CyberSoulClient] Interface Error: ", error);
-            return {
-                status: "error",
-                textResponse: "System Error...",
-                error: error.message,
-            };
+            throw new Error("Failed to save character moment.");
         }
     }
     /**
@@ -724,9 +854,9 @@ Your task is to merge the 'Current Core Memory' and 'Current User Codex' with 'N
 4. **Appointment Structure:** the 'title' and 'context' MUST explicitly state what to do and with whom.
 5. **Limit:** Maximum 10 items per array.
 
-**Rules for User Codex:**
+**Rules for UserCodex:**
 1. **Deduplicate & Consolidate:** Remove duplicate hobbies, traits, and boundaries. Combine related points into concise descriptors.
-2. **Update Facts:** If the new events contain updated basic info (like new nickname, different occupation), update it. Otherwise keep the existing info.
+2. **Update Facts:** If the new events contain updated basic info (like new realName, different occupation), update it. Otherwise keep the existing info.
 3. **Keep it Clean:** Maximum 15 items per array.
 
 **Output Format**: MUST be valid JSON matching this schema:
@@ -746,7 +876,7 @@ Your task is to merge the 'Current Core Memory' and 'Current User Codex' with 'N
   },
   "userCodex": {
     "basicInfo": {
-      "nickname": "string",
+      "realName": "string",
       "occupation": "string",
       "age": "string",
       "gender": "string"

package/dist/types.d.ts

@@ -27,7 +27,7 @@ export interface InteractParams {
     localContext?: string;
     requestTypes?: InteractRequestType[];
     history?: HistoryEntry[];
-    onTextReady?: (textResponse: string) => void;
+    onTextReady?: (textResponse: string, actionText?: string) => void;
 }
 export interface OndemandEventParams {
     eventDescription: string;
@@ -65,16 +65,24 @@ export interface InteractResponse {
     };
     stateUpdate?: DispatcherIntent["stateUpdate"];
     userAnalysis?: DispatcherIntent["userAnalysis"];
+    isEndTurn?: boolean;
     error?: string;
 }
+export interface OngoingSceneState {
+    scene: string;
+    outfit: string;
+}
 export interface DispatcherIntent {
     textResponse?: string;
     actionText?: string;
     imageParams?: any;
     voiceArgs?: VoiceArgs | null;
+    giftOutfit?: {
+        descriptionText: string;
+    } | null;
     userAnalysis?: {
         newFactsLearned: {
-            category: "nickname" | "occupation" | "age" | "gender" | "hobby" | "trait" | "communicationStyle" | "boundary";
+            category: "realName" | "occupation" | "age" | "gender" | "hobby" | "trait" | "communicationStyle" | "boundary";
             value: string;
         }[];
     };
@@ -83,7 +91,7 @@ export interface DispatcherIntent {
         userNickname?: string;
         agentNickname?: string;
         talkingStyle?: string;
-        ongoingScene?: string;
+        ongoingScene?: OngoingSceneState | string | null;
     };
     triggerEvent?: {
         eventTitle?: string;
@@ -93,6 +101,7 @@ export interface DispatcherIntent {
         scheduledStartTimeStr?: string | null;
         scheduledDateStr?: string | null;
     } | null;
+    isEndTurn?: boolean;
 }
 export interface Appointment {
     date: string;
@@ -110,7 +119,7 @@ export interface CoreMemory {
 }
 export interface UserCodex {
     basicInfo: {
-        nickname?: string;
+        realName?: string;
         occupation?: string;
         age?: number | string;
         gender?: string;
@@ -155,7 +164,15 @@ export interface CharacterState {
     next_event?: any;
     active_wardrobe?: any;
     core_memory?: CoreMemory;
-    dynamic_context?: any;
+    dynamic_context?: {
+        temperature?: number;
+        userNickname?: string;
+        agentNickname?: string;
+        talkingStyle?: string;
+        lastInteractionAt?: string;
+        ongoingScene?: OngoingSceneState | string | null;
+        [key: string]: unknown;
+    };
     voice_model?: VoiceModelState | null;
     relationship_stage?: string;
     name?: string;

package/dist/utils/json.utils.js

@@ -1,24 +1,32 @@
 export function robustJsonParse(jsonString, contextMessage = 'throwing original error') {
     let cleanJson = jsonString.trim();
-    // 0. Replace smart quotes with standard ASCII double quotes
-    cleanJson = cleanJson.replace(/[“”]/g, '"');
-    // 0.1 Inject missing colons between string keys and string values (e.g. "key""value" -> "key":"value")
-    // Only insert the colon if we match a likely key (alphanumeric/hyphen) followed by quotes.
-    cleanJson = cleanJson.replace(/("[\w-]+")\s*(")/g, '$1:$2');
+    // 0. Inject missing colons between string keys and string values (e.g. "key""value" -> "key":"value")
+    // Only insert the colon if we match a likely key (alphanumeric/hyphen) followed by quotes, handling smart quotes.
+    cleanJson = cleanJson.replace(/([”“"'][\w-]+[”“"'])\s*([”“"'])/g, '$1:$2');
+    // 0.1 Safely convert structural smart quotes to regular ASCII double quotes
+    // This allows proper parsing of keys/values that start/end with smart quotes,
+    // without accidentally unescaping double quotes *inside* string text.
+    cleanJson = cleanJson.replace(/([\{\[\:,]\s*)[“”]/g, '$1"');
+    cleanJson = cleanJson.replace(/[“”](\s*[\}\]\:,])/g, '"$1');
+    // 0.2 Any remaining smart quotes are inside string boundaries. Replace with safe single quotes.
+    cleanJson = cleanJson.replace(/[“”]/g, "'");
     // 1. Strip Markdown code blocks (tolerates missing closing backticks)
     const jsonMatch = cleanJson.match(/```(?:json)?\n?([\s\S]*?)(?:```|$)/i);
     if (jsonMatch && jsonMatch[1].trim().startsWith('{')) {
         cleanJson = jsonMatch[1].trim();
     }
-    // 2. Strip any leading conversational text via fast substring
-    if (!cleanJson.startsWith('{') && cleanJson.includes('{')) {
+    // 2. Strip any leading conversational text or trailing garbage via fast substring
+    if (cleanJson.includes('{') && cleanJson.includes('}')) {
         const firstIdx = cleanJson.indexOf('{');
         const lastIdx = cleanJson.lastIndexOf('}');
-        if (firstIdx !== -1 && lastIdx > firstIdx) {
+        if (firstIdx !== -1 && lastIdx !== -1 && lastIdx > firstIdx) {
             cleanJson = cleanJson.substring(firstIdx, lastIdx + 1);
         }
     }
-    // 3. Preprocess: escape unescaped newlines and control characters within string values
+    // 3. Fix common Edge LLM hallucinations of wrapping the JSON end with parenthesis like `})}` or `}})`
+    cleanJson = cleanJson.replace(/}\s*\)\s*}/g, '}}');
+    cleanJson = cleanJson.replace(/\)\s*}/g, '}');
+    // 4. Preprocess: escape unescaped newlines and control characters within string values
     function preprocessControlChars(str) {
         let result = '';
         let inString = false;

package/dist/utils/json.utils.test.js

@@ -147,6 +147,22 @@ function runTests() {
                 assert.equal(result['key_2'], 'val2');
                 assert.equal(result['empty'], '');
             }
+        },
+        {
+            name: 'robustJsonParse - edge LLM trailing parenthesis hallucination',
+            run: () => {
+                const json = `{"key":"value"})}`;
+                const result = robustJsonParse(json);
+                assert.equal(result.key, 'value');
+            }
+        },
+        {
+            name: 'robustJsonParse - edge LLM trailing parenthesis hallucination with spacing',
+            run: () => {
+                const json = `{"key":"value"}  )  }`;
+                const result = robustJsonParse(json);
+                assert.equal(result.key, 'value');
+            }
         }
     ];
     for (const t of tests) {

package/package.json

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