@space3-npm/cybersoul-client 1.2.6 → 1.2.8

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { CyberSoulClientConfig, InteractParams, OndemandEventParams, OndemandEventResponse, DispatcherIntent, InteractResponse, CharacterState, CoreMemory, UserCodex } from "./types.js";
+import { CyberSoulClientConfig, InteractParams, ProactiveParams, ProactiveResponse, OndemandEventParams, OndemandEventResponse, DispatcherIntent, InteractResponse, CharacterState, CoreMemory, UserCodex } from "./types.js";
 export declare class CyberSoulClient {
     private config;
     private llm;
@@ -19,6 +19,9 @@ export declare class CyberSoulClient {
     private buildStateContextPrompt;
     private normalizeOngoingSceneState;
     private getImageSchemaParams;
+    private getOutfitSelectionPrompt;
+    private getTriggerEventPolicyPrompt;
+    private getOutfitAcquisitionPolicyPrompt;
     private getEventSchemaParams;
     private getVoiceSchemaParams;
     private buildVoiceSchemaFromDynamicParams;
@@ -44,6 +47,11 @@ export declare class CyberSoulClient {
      * Evaluates and triggers an on-demand event, intelligently deciding if an outfit change is needed.
      */
     ondemandEvent(params: OndemandEventParams): Promise<OndemandEventResponse>;
+    /**
+     * Generates a proactive message when the user hasn't responded.
+     * Safely prevents spamming, and adjusts its approach based on relationship dynamics.
+     */
+    proactiveInteract(params: ProactiveParams): Promise<ProactiveResponse>;
     /**
      * Manually generate an image of the character outside of chat flow.
      */

package/dist/client.js

@@ -159,7 +159,7 @@ export class CyberSoulClient {
         }
         return normalized;
     }
-    buildStateContextPrompt(state, localContext) {
+    buildStateContextPrompt(state, localContext, isProactive = false) {
         const dyn = state.dynamic_context || {};
         const stage = state.relationship_stage || "NEUTRAL";
         const temperature = dyn.temperature ?? 50;
@@ -197,10 +197,10 @@ Current time: ${new Date(currentTimeMs).toLocaleString("zh-CN", { timeZone: "Asi
         if (state.active_event) {
             contextParts.push(`Active Event: ${state.active_event.title} (${state.active_event.narrative_context})`);
         }
-        /*     if (localContext) {
-              contextParts.push(`Additional Context: ${localContext}`);
-            }
-         */ if (state.next_event) {
+        if (localContext) {
+            contextParts.push(`Additional Context: ${localContext}`);
+        }
+        if (state.next_event) {
             contextParts.push(`Next Event: ${state.next_event.title} at ${state.next_event.start_time} (in ${state.next_event.time_until_mins} mins)`);
         }
         if (state.active_wardrobe) {
@@ -269,7 +269,9 @@ ${scenarioContext}
 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. 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.`;
+${isProactive
+            ? "5. REAL-TIME PACING: You are initiating the conversation because the user hasn't replied recently. Transition naturally from your last message or start a new topic seamlessly. Ensure everything happens in a single real-time moment."
+            : "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)
@@ -316,6 +318,15 @@ ${scenarioContext}
     "style": "e.g., photorealistic (ENGLISH ONLY)"
   }`;
     }
+    getOutfitSelectionPrompt() {
+        return `When generating a triggerEvent, you MUST provide a suitable 'triggerEvent.outfitId' if the VERY LAST USER MESSAGE explicitly asks for an outfit change, OR if the new activity implies a context/location shift that conflicts with the current outfit (e.g., currently in SLEEPWEAR at home but going outside). Otherwise, keep it null. When changing outfits, match it to the event's activity, environment, and relationship stage (e.g., DAILY, INTIMATE, SLEEPWEAR).`;
+    }
+    getTriggerEventPolicyPrompt() {
+        return `- Include 'triggerEvent' only if the VERY LAST USER MESSAGE proposes a new activity/hangout, explicitly requests an outfit change, or proposes intimate/romantic actions; ignore older history. ${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" }.`;
+    }
     getEventSchemaParams(userName) {
         const name = userName || "the user";
         return `"eventTitle": "CRITICAL: Must include BOTH ‘WHAT to do’ AND ‘WITH WHOM’ (use the user's specific name if known, e.g., 'Having coffee with ${name}'). DO NOT use your own character name in the title! If you don't explicitly include WITH WHOM the event is by name, it is a hard failure.",
@@ -323,7 +334,7 @@ ${scenarioContext}
     "scheduledDateStr": "YYYY-MM-DD (Optional. If the user specifies a future date like 'tomorrow', 'Saturday', or 'next week', calculate the exact calendar date based on the 'Current time' provided in the context and output it here. Otherwise, return null)",
     "scheduledStartTimeStr": "HH:MM (Optional, 24-hour format if a specific time is agreed upon, e.g., '14:30', otherwise null)",
     "durationMins": 60,
-    "outfitId": "optional wardrobe ID to change into if appropriate. MUST match the context of the event (e.g. SLEEPWEAR for bed, INTIMATE for romance, DAILY for going out)"`;
+    "outfitId": "Wardrobe ID. Provide ONLY if the user explicitly requested an outfit change OR if the new activity conflicts with the current outfit context (e.g., SLEEPWEAR at home -> going outside). Otherwise, use null."`;
     }
     getVoiceSchemaParams() {
         // Only reached when no dynamic_params are configured on the voice model.
@@ -437,8 +448,8 @@ ${scenarioContext}
                     modalitiesInstruction += `\n  - ALWAYS set 'voiceArgs' to null.`;
                 }
             }
-            modalitiesInstruction += `\n  - 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" }.`;
+            modalitiesInstruction += `\n  ${this.getTriggerEventPolicyPrompt()}
+        ${this.getOutfitAcquisitionPolicyPrompt()}`;
             // Combine state info into a clean descriptive context
             const systemPrompt = `${this.buildStateContextPrompt(state, params.localContext)}
 Available Wardrobe Outfits (For event triggers):
@@ -524,7 +535,7 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
             let finalAudioUrl = undefined;
             let finalDurationSec = undefined;
             // Output Event Trigger
-            if (isAuto && parsedIntent.triggerEvent) {
+            if (parsedIntent.triggerEvent) {
                 mediaTasks.push(this.apiFetch("/api/v1/cyber-soul/characters/ondemand-event", {
                     method: "POST",
                     body: JSON.stringify({
@@ -552,9 +563,15 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
                         mode: "full-prompt",
                         full_prompt: resolvedTextResponse,
                     };
-                mediaTasks.push(this.generatePrimitive("image", imagePayload).then((res) => {
+                mediaTasks.push(this.generatePrimitive("image", imagePayload)
+                    .then((res) => {
                     finalImageUrl = res.image_url;
-                }).catch(e => console.error("[CyberSoulClient] Image generation failed:", e)));
+                })
+                    .catch((e) => {
+                    console.error("[CyberSoulClient] Image generation failed:", e);
+                    if (e.code === 'INSUFFICIENT_POINTS' || e.code === 'WALLET_DEDUCTION_ERROR')
+                        throw e;
+                }));
             }
             const shouldGenerateVoice = types.includes(InteractRequestType.VOICE) &&
                 (!isAuto || !!parsedIntent.voiceArgs);
@@ -573,10 +590,16 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
                 mediaTasks.push(this.generatePrimitive("voice", {
                     text: textForVoice,
                     dynamicArgs: normalizedVoiceArgs,
-                }).then((res) => {
+                })
+                    .then((res) => {
                     finalAudioUrl = res.audio_url;
                     finalDurationSec = res.duration_sec;
-                }).catch(e => console.error("[CyberSoulClient] Voice generation failed:", e)));
+                })
+                    .catch((e) => {
+                    console.error("[CyberSoulClient] Voice generation failed:", e);
+                    if (e.code === 'INSUFFICIENT_POINTS' || e.code === 'WALLET_DEDUCTION_ERROR')
+                        throw e;
+                }));
             }
             // Wait for image/voice gens to return successfully
             await Promise.all(mediaTasks);
@@ -618,7 +641,7 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
 The user proposes a new event for you to participate in: "${params.eventDescription}".
 Evaluate this based on your current state and relationship stage.
 Decide if you will accept the event, and whether it requires changing your outfit.
-When changing outfits, perfectly match the outfit to the event's activity, environment, and relationship stage. Consider the wardrobe category (e.g., DAILY, INTIMATE, SLEEPWEAR).
+${this.getOutfitSelectionPrompt()}
 
 Available Wardrobe Outfits:
 ${availableOutfits || "None available"}
@@ -688,6 +711,135 @@ CRITICAL: Output MUST be ONLY valid JSON with no markdown block wrappers. Do NOT
             };
         }
     }
+    /**
+     * Generates a proactive message when the user hasn't responded.
+     * Safely prevents spamming, and adjusts its approach based on relationship dynamics.
+     */
+    async proactiveInteract(params) {
+        try {
+            // 1. Cold Interaction Protection (Logic-based fallback)
+            const history = params.history || [];
+            const maxUnreplied = params.maxUnreplied ?? 2;
+            let consecutiveProactive = 0;
+            // Start from the most recent message
+            for (let i = history.length - 1; i >= 0; i--) {
+                const msg = history[i];
+                if (msg.role === 'user') {
+                    break; // User responded, streak broken
+                }
+                if (msg.role === 'assistant') {
+                    consecutiveProactive++;
+                }
+            }
+            if (consecutiveProactive >= maxUnreplied) {
+                return {
+                    status: "skipped",
+                    reason: `User is busy. ${consecutiveProactive} consecutive proactive messages ignored.`
+                };
+            }
+            // 2. Fetch current character state
+            const [state, availableOutfits] = await Promise.all([
+                this.fetchRemoteState(),
+                this.getWardrobePromptStr()
+            ]);
+            // 3. Evaluate behavioral approach based on relationship and personality
+            const dyn = state.dynamic_context || {};
+            const stage = state.relationship_stage || "ACQUAINTANCE";
+            const temperature = dyn.temperature ?? 50;
+            const userTraits = state.user_codex?.psychological?.traits?.join(", ") || "";
+            let interrogationStrategy = "Do not ask 'are you there?' or 'why aren't you answering?'. Just share your current status, a passing thought, complain whimsically, or tease the user naturally like a real partner.";
+            if (stage === "INTIMATE" || stage === "PARTNER" || (stage === "WARM" && temperature > 70)) {
+                if (temperature > 70) {
+                    interrogationStrategy = "Because you are deeply intimate and highly affectionate, you MISS them. You MAY organically 'interrogate' or pout playfully about why they are ignoring you (e.g., 'Are you too busy for me?', 'Still ignoring your girl?'). Act like a real, slightly needy/attached partner.";
+                }
+                else if (temperature < 40) {
+                    interrogationStrategy = "Because you are intimate but currently feeling cold/angry, you notice they are ignoring you. You MAY be passive-aggressive or cross-examine them coldly (e.g., 'So we're just not talking today?', 'Fine, keep ignoring me.').";
+                }
+            }
+            else if (stage === "COLD" || stage === "STRANGER") {
+                interrogationStrategy = "You are distant. Do NOT double-text with neediness. If you must speak, make it a detached observation or a cold administrative remark.";
+            }
+            // History/Context awareness prompt
+            const historyAwarenessPrompt = `CRITICAL CONTEXT AWARENESS: Read the CHAT HISTORY above carefully. Remember that YOU sent the last message. Your new message MUST feel organically connected to the flow of what you two were previously talking about, or naturally bring up a known event/topic from your [CORE MEMORY]. Do not sound like a robot reading a log.`;
+            // 4. Build a Proactive-specific System Prompt
+            const baseContext = this.buildStateContextPrompt(state, params.localContext, true);
+            const types = this.normalizeRequestTypes(params.requestTypes);
+            const isAuto = types.includes(InteractRequestType.AUTO);
+            const requestedOthers = types.filter((t) => t !== InteractRequestType.AUTO && t !== InteractRequestType.TEXT);
+            // Determine modalities (reusing logic from interact)
+            let modalitiesInstruction = "You are initiating conversation without a preceding user message.\\n";
+            if (requestedOthers.includes(InteractRequestType.IMAGE)) {
+                modalitiesInstruction += "  - Include 'imageParams' for visual/photo requests or key visual moments; explicitly describe current clothing.\\n";
+            }
+            else {
+                modalitiesInstruction += "  - ALWAYS set 'imageParams' to null.\\n";
+            }
+            const systemPrompt = `${baseContext}
+
+[PROACTIVE INITIATION TASK]
+The user has NOT spoken to you recently. You sent the last message in the chat history, and they haven't replied. You are deciding to follow up proactively.
+${interrogationStrategy}
+${historyAwarenessPrompt}
+Consider the user's known traits (${userTraits}) when choosing how to act. Need to keep it strictly under 2-3 sentences max.
+
+Available Wardrobe Outfits:
+${availableOutfits}
+
+${modalitiesInstruction}
+You MUST output ONLY a valid JSON object matching exactly this structure:
+{
+  "actionText": "(Scene descriptions, physical actions, expressions, inner feelings) ONLY.",
+  "textResponse": "Spoken dialogue ONLY.",
+  "stateUpdate": { "temperatureDelta": 1, "ongoingScene": { "scene": "...", "outfit": "..." } },
+  ${this.getImageSchemaParams(requestedOthers.includes(InteractRequestType.IMAGE))},
+  "voiceArgs": null
+}`;
+            const transcript = this.buildHistoryTranscript(params.history, state);
+            const promptMessages = [
+                { role: "system", content: systemPrompt },
+                {
+                    role: "user",
+                    content: `${transcript}\n[TRIGGER PROACTIVE MESSAGE]\nBased on your active event and environment, send a new message to the user.\n\nCRITICAL: Output ONLY valid JSON matching the schema. DO NOT wrap the JSON in \`\`\`json.`
+                }
+            ];
+            // 5. Generate with LLM using a confident temperature
+            const rawLlmResponse = await this.llm.generate(promptMessages, 800, 0.7);
+            let parsedIntent;
+            try {
+                parsedIntent = robustJsonParse(rawLlmResponse, "Proactive fallback");
+            }
+            catch (e) {
+                parsedIntent = { textResponse: rawLlmResponse.replace(/^[\`\s]+|[\`\s]+$/g, "").trim() };
+            }
+            // Update Remote state if needed
+            if (parsedIntent.stateUpdate) {
+                this._updateDynamicContextInternal(parsedIntent.stateUpdate).catch(e => console.error(e));
+            }
+            // Handle Optional Media (Image only for proactive to save compute normally, but you can extend)
+            let finalImageUrl = undefined;
+            if (requestedOthers.includes(InteractRequestType.IMAGE) || !!parsedIntent.imageParams) {
+                const imagePayload = parsedIntent.imageParams || { mode: "full-prompt", full_prompt: parsedIntent.textResponse };
+                try {
+                    const res = await this.generatePrimitive("image", imagePayload);
+                    finalImageUrl = res.image_url;
+                }
+                catch (e) {
+                    console.error("[CyberSoulClient] Proactive Image generation failed:", e);
+                }
+            }
+            return {
+                status: "success",
+                textResponse: parsedIntent.textResponse,
+                actionText: parsedIntent.actionText,
+                imageUrl: finalImageUrl,
+                stateUpdate: parsedIntent.stateUpdate
+            };
+        }
+        catch (error) {
+            console.error("[CyberSoulClient] Proactive Interact Error: ", error);
+            return { status: "error", error: error.message };
+        }
+    }
     /**
      * Manually generate an image of the character outside of chat flow.
      */

package/dist/types.d.ts

@@ -21,6 +21,23 @@ export interface HistoryEntry {
     content: string;
     actionText?: string;
     mediaHint?: string;
+    isProactive?: boolean;
+}
+export interface ProactiveParams {
+    history?: HistoryEntry[];
+    maxUnreplied?: number;
+    requestTypes?: InteractRequestType[];
+    localContext?: string;
+}
+export interface ProactiveResponse {
+    status: "success" | "skipped" | "error";
+    reason?: string;
+    textResponse?: string;
+    actionText?: string;
+    imageUrl?: string;
+    audioUrl?: string;
+    stateUpdate?: DispatcherIntent["stateUpdate"];
+    error?: string;
 }
 export interface InteractParams {
     userMessage: string;

package/package.json

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