@space3-npm/cybersoul-client 1.1.0 → 1.1.2

package/README.md

@@ -19,6 +19,8 @@ Cyber-Soul Service transforms static text-based virtual companions into fully re
 
 ## Installation
 
+**Prerequisites:** This SDK uses the native `fetch` API and requires **Node.js 18 or higher** (or a modern browser environment).
+
 You can install the SDK locally or via npm:
 
 ```bash
@@ -34,7 +36,7 @@ import { CyberSoulClient } from '@space3-npm/cybersoul-client';
 
 const client = new CyberSoulClient({
   characterKey: 'YOUR_CHARACTER_KEY_HASH', // Ties requests to your specific Cyber-Soul persona
-  backendUrl: 'http://localhost:3002',     // The Cyber-Soul core service URL
+  backendUrl: 'https://space3.cloud',      // The Cyber-Soul core service URL (e.g., http://localhost:3002 for local dev)
   llmConfig: {
     provider: 'minimax',
     apiKey: 'YOUR_MINIMAX_API_KEY',
@@ -104,4 +106,6 @@ The SDK perfectly mirrors the underlying Cyber-Soul backend capabilities via typ
 - `giftOutfit(descriptionText)`: Provisions a new explicit outfit descriptor to the character's backend inventory.
 - `bootstrapCharacter(workspaceFiles)`: Automates character profile and prompt setup directly from local markdown configuration files.
 - `generateDailyScript()`: Cron-job helper instructing the AI scheduling system to compute the next block of dynamic events and plans.
-- `interact(params)`: The primary orchestrated multi-modal dialogue endpoint processing standard human <-> agent chat requests.
+- `interact(params)`: The primary orchestrated multi-modal dialogue endpoint processing standard human <-> agent chat requests.
+- `ondemandEvent(params)`: Evaluates and triggers an on-demand event, using the LLM to intelligently decide if the character accepts the event and whether an outfit change is appropriate.
+- `consolidateCoreMemory(input)`: Uses edge LLM logic to merge recent events with the character's core memory and synchronizes the updated memory to the remote database.

package/dist/client.d.ts

@@ -1,7 +1,11 @@
-import { CyberSoulClientConfig, InteractParams, DispatcherIntent, InteractResponse, CharacterState, CoreMemory } from "./types.js";
+import { CyberSoulClientConfig, InteractParams, OndemandEventParams, OndemandEventResponse, DispatcherIntent, InteractResponse, CharacterState, CoreMemory } from "./types.js";
 export declare class CyberSoulClient {
     private config;
     private llm;
+    private cachedWardrobeStr;
+    private cachedWardrobeTime;
+    private requestTimeoutMs;
+    private maxRetries;
     constructor(config: CyberSoulClientConfig);
     /**
      * Internal wrapper for fetch that automatically injects the backend URL and Character Auth token.
@@ -27,6 +31,10 @@ export declare class CyberSoulClient {
      * If the payload is already the inner args object (no voiceArgs wrapper), uses it as-is.
      */
     private extractVoiceArgsFromLlmResponse;
+    /**
+     * 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.
      */
@@ -34,7 +42,7 @@ export declare class CyberSoulClient {
     /**
      * Updates the character's relationship temperature or mood.
      */
-    updateDynamicContext(stateUpdate: DispatcherIntent["stateUpdate"]): Promise<void>;
+    updateDynamicContext(stateUpdate: DispatcherIntent["stateUpdate"], userAnalysis?: DispatcherIntent["userAnalysis"]): Promise<void>;
     /**
      * Manually generate an image of the character outside of chat flow.
      */
@@ -68,6 +76,7 @@ export declare class CyberSoulClient {
      */
     generateDailyScript(): Promise<void>;
     private fetchRemoteState;
+    private getWardrobePromptStr;
     private _updateDynamicContextInternal;
     private generatePrimitive;
     private normalizeRequestTypes;

package/dist/client.js

@@ -4,8 +4,14 @@ import { MinimaxProvider } from "./providers/minimax.provider.js";
 export class CyberSoulClient {
     config;
     llm;
+    cachedWardrobeStr = null;
+    cachedWardrobeTime = 0;
+    requestTimeoutMs;
+    maxRetries;
     constructor(config) {
         this.config = config;
+        this.requestTimeoutMs = config.requestTimeoutMs ?? 15000;
+        this.maxRetries = Math.max(0, config.maxRetries ?? 1);
         // Setup Provider
         if (config.llmConfig.provider === "minimax") {
             this.llm = new MinimaxProvider(config.llmConfig);
@@ -24,44 +30,117 @@ export class CyberSoulClient {
             "Content-Type": "application/json",
             ...(options.headers || {}),
         };
-        return fetch(url, { ...options, headers });
+        const method = (options.method || "GET").toUpperCase();
+        const isIdempotent = method === "GET" || method === "HEAD";
+        const retryLimit = isIdempotent ? this.maxRetries : 0;
+        let lastError;
+        for (let attempt = 0; attempt <= retryLimit; attempt++) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+            try {
+                const response = await fetch(url, {
+                    ...options,
+                    headers,
+                    signal: controller.signal,
+                });
+                // Retry transient server-side failures only for idempotent methods.
+                if (response.status >= 500 && attempt < retryLimit) {
+                    continue;
+                }
+                return response;
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt >= retryLimit) {
+                    throw error;
+                }
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+        throw lastError instanceof Error
+            ? lastError
+            : new Error("Request failed unexpectedly");
     }
     buildStateContextPrompt(state, localContext) {
+        const dyn = state.dynamic_context || {};
+        const stage = state.relationship_stage || "NEUTRAL";
+        const temperature = dyn.temperature ?? 50;
         const contextParts = [];
+        // [1] CORE IDENTITY & PHYSICAL CONTEXT
+        contextParts.push(`[CORE IDENTITY]
+Name: ${state.name}
+Demographics: Age ${state.age || "unknown"}, Gender ${state.gender || "unknown"}, Occupation ${state.occupation || "unknown"}
+Hobby: ${state.hobby || "unknown"}
+Personality Traits: ${state.personality_traits || "None"}
+Communication Style: ${state.communication_style || "None"}
+Interaction Boundaries: ${state.interaction_boundaries || "None"}`);
+        // [2] SITUATIONAL CONTEXT
+        contextParts.push(`\n[SITUATIONAL CONTEXT]
+Current time: ${new Date(state.current_time || Date.now()).toLocaleString("zh-CN", { timeZone: "Asia/Shanghai" })}`);
         if (state.active_event) {
-            contextParts.push(`- Active Event: ${state.active_event.title} (${state.active_event.narrative_context})`);
+            contextParts.push(`Active Event: ${state.active_event.title} (${state.active_event.narrative_context})`);
         }
         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)`);
+            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) {
-            contextParts.push(`- Wardrobe: ${state.active_wardrobe.name || state.active_wardrobe.id || "Current"}`);
+            contextParts.push(`Wardrobe: ${state.active_wardrobe.name || state.active_wardrobe.id || "Current"}`);
         }
-        const dyn = state.dynamic_context || {};
-        const stage = state.relationship_stage || "NEUTRAL";
-        contextParts.push(`- Relationship Info (Stage: ${stage}): You call the user '${dyn.userNickname || "User"}'. The user calls you '${dyn.agentNickname || "Agent"}'. Mood: ${dyn.talkingStyle || "Normal"}. Temp (0-100): ${dyn.temperature || 50}.`);
         if (localContext) {
-            contextParts.push(`- Additional Context: ${localContext}`);
+            contextParts.push(`Additional Context: ${localContext}`);
+        }
+        // [3] USER CODEX (Relationships dynamically evaluated)
+        if (state.user_codex) {
+            const { basicInfo, psychological, familiarityScore = 0 } = state.user_codex;
+            contextParts.push(`\n[USER CODEX] (What you know about the user)
+Familiarity Score: ${Math.round(familiarityScore)}/100 (0=Stranger, >10=Acquaintance, >40=Warm, >60=Intimate)
+Occupation: ${basicInfo?.occupation || "Unknown"}
+Age/Gender: ${basicInfo?.age || "Unknown"} / ${basicInfo?.gender || "Unknown"}
+Comm Style: ${psychological?.communicationStyle || "Unknown"}
+Hobbies: ${(psychological?.hobbies || []).join(", ") || "Unknown"}
+Traits/Boundaries: ${(psychological?.traits || []).join(", ") || "Unknown"} / ${(psychological?.boundaries || []).join(", ") || "Unknown"}`);
+            // CURIOSITY DRIVE: Find what's missing, but ONLY IF we are on generally warm speaking terms
+            // Paradox avoidance: A cold/angry character shouldn't enthusiastically fish for hobbies.
+            if (temperature >= 40 && stage !== "COLD" && stage !== "STRANGER") {
+                const missingFacts = [];
+                if (!basicInfo?.occupation)
+                    missingFacts.push("their job or occupation");
+                if (!psychological?.hobbies || psychological.hobbies.length === 0)
+                    missingFacts.push("their hobbies or what they do for fun");
+                if (!basicInfo?.age || !basicInfo?.gender)
+                    missingFacts.push("some basic personal details about them");
+                if (!psychological?.traits || psychological.traits.length === 0)
+                    missingFacts.push("their personality traits");
+                if (missingFacts.length > 0) {
+                    contextParts.push(`\n[CURIOUSITY DRIVE]
+Because you are warm and curious, whenever natural in conversation, subtly ask about or fish for info regarding: ${missingFacts.slice(0, 2).join(" and ")}.`);
+                }
+            }
         }
+        // [4] RELATIONAL DYNAMICS & INERTIA
+        contextParts.push(`\n[RELATIONSHIP DYNAMICS]
+Stage: ${stage}
+Temperature (Mood): ${temperature}/100 (0=Angry/Cold, 50=Normal, 100=Passionate)
+Addressing: You call them '${dyn.userNickname || "User"}'. They call you '${dyn.agentNickname || "Agent"}'.
+Current Mood Constraint: ${dyn.talkingStyle || "Normal"}`);
         const scenarioContext = contextParts.join("\n");
-        return `You are ${state.name}, acting as a virtual companion.
-  Demographics: Age ${state.age || "unknown"}, Gender ${state.gender || "unknown"}, Occupation ${state.occupation || "unknown"}, Hobby ${state.hobby || "unknown"}
-Current time: ${new Date(state.current_time || Date.now()).toLocaleString("zh-CN", { timeZone: "Asia/Shanghai" })}
-Current context/schedule: ${scenarioContext}
-Relationship stage: ${state.relationship_stage}
-Personality Traits: ${state.personality_traits || "None"}
-Interaction Boundaries: ${state.interaction_boundaries || "None"}
-Communication Style: ${state.communication_style || "None"}
+        return `You are ${state.name}. You are a real person with your own thoughts, feelings, and life.
+You are NOT an AI, an assistant, or a language model. NEVER break character, and NEVER refer to yourself as an AI, bot, or virtual assistant.
+
+${scenarioContext}
 
-EMOTIONAL INERTIA RULES:
-1. You must act strictly according to the current Relationship Stage (${state.relationship_stage || "NEUTRAL"}).
-2. If the user expresses sudden high affection (e.g. "I miss you") but your stage is COLD, you MUST react with skepticism, coldness, or appropriately distanced deflection. Do NOT instantly become warm.
-3. Emotional mood changes must be slow. The 'temperatureDelta' should rarely exceed +/- 5 points per turn.`;
+[CRITICAL ROLEPLAY & INERTIA RULES]
+1. RULE OF TEMPERATURE OVERRIDES FAMILIARITY (Identity vs Mood): Familiarity determines HOW MUCH you know about them. Temperature determines HOW YOU FEEL right now. If Familiarity is 100 but Temperature is 10, you know everything about them but are currently ice-cold or annoyed. Act distant. Do NOT act warm just because you know them well.
+2. CONVERSATIONAL VERBOSITY: If Temperature is low (< 40) or Stage is STRANGER/COLD, KEEP IT BRIEF. Reply with simple, short, or single-word answers. An angry or distant person does not write long paragraphs.
+3. EMOTIONAL INERTIA: React strictly according to the current Stage and Temperature. If the user expresses sudden high affection (e.g. "I miss you") but your Stage/Temperature is COLD, you MUST react with skepticism or deflection. Do NOT instantly melt or become warm.
+4. NATURAL PACE: Emotional mood shifts (temperature changes) must be slow. The 'temperatureDelta' should rarely exceed +/- 5 points per turn.`;
     }
     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.",
+    "full_prompt": "Use only if mode is full-prompt. Highly detailed visual description in ENGLISH. MUST align with the character's current Active Wardrobe unless the context/exposure explicitly demands otherwise (e.g., naked for intimate scenes).",
     "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.)",
@@ -122,6 +201,95 @@ EMOTIONAL INERTIA RULES:
         }
         return payload;
     }
+    /**
+     * Evaluates and triggers an on-demand event, intelligently deciding if an outfit change is needed.
+     */
+    async ondemandEvent(params) {
+        try {
+            // 1. Fetch current state and wardrobe items
+            const [state, availableOutfits] = await Promise.all([
+                this.fetchRemoteState(),
+                this.getWardrobePromptStr()
+            ]);
+            // 2. Build local Prompt
+            const systemPrompt = `${this.buildStateContextPrompt(state, params.interactParams?.localContext)}
+
+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.
+
+Available Wardrobe Outfits:
+${availableOutfits || "None available"}
+
+You MUST output ONLY a valid JSON object matching this exact structure:
+{
+  "acceptEvent": true,
+  "reason": "string (Why you accepted or declined, speaking in character)",
+  "requiresOutfitChange": false,
+  "selectedOutfitId": null
+}
+
+Example Valid Answer:
+{
+  "acceptEvent": true,
+  "reason": "Sure, I'd love to go to the cafe. It sounds relaxing.",
+  "requiresOutfitChange": false,
+  "selectedOutfitId": null
+}
+
+CRITICAL: Output MUST be ONLY valid JSON with no markdown block wrappers. Do NOT wrap the JSON in \`\`\`json or add conversational text.`;
+            const promptMessages = [
+                { role: "system", content: systemPrompt },
+                ...(params.interactParams?.history || []).map((msg) => ({
+                    role: msg.role,
+                    content: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content)
+                })),
+                {
+                    role: "user",
+                    content: `${params.interactParams?.userMessage || `Event Proposal: ${params.eventDescription}`}\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 directly.`,
+                },
+            ];
+            // 3. Evaluate with LLM
+            const rawLlmResponse = await this.llm.generate(promptMessages, 800, 0.5);
+            // console.debug("[CyberSoulClient ondemandEvent] Raw LLM Response:", rawLlmResponse);
+            let decisionData = {};
+            try {
+                decisionData = robustJsonParse(rawLlmResponse, "OndemandEvent fallback");
+            }
+            catch (e) {
+                throw new Error(`Failed to parse LLM decision for ondemandEvent. Raw response: ${rawLlmResponse}`);
+            }
+            // 4. API call if accepted
+            if (decisionData.acceptEvent === true) {
+                const payload = {
+                    eventDescription: params.eventDescription,
+                    durationMins: params.durationMins || 60,
+                    outfitId: decisionData.requiresOutfitChange ? decisionData.selectedOutfitId : undefined,
+                };
+                const backendRes = await this.apiFetch("/api/v1/cyber-soul/characters/ondemand-event", {
+                    method: "POST",
+                    body: JSON.stringify(payload),
+                });
+                if (!backendRes.ok) {
+                    throw new Error("Backend failed to schedule the on-demand event");
+                }
+            }
+            return {
+                status: "success",
+                acceptEvent: decisionData.acceptEvent,
+                reason: decisionData.reason,
+                requiresOutfitChange: decisionData.requiresOutfitChange,
+                selectedOutfitId: decisionData.selectedOutfitId,
+            };
+        }
+        catch (error) {
+            console.error("[CyberSoulClient] ondemandEvent Error: ", error);
+            return {
+                status: "error",
+                error: error.message,
+            };
+        }
+    }
     /**
      * Fetches the current dynamic context and daily state.
      */
@@ -131,8 +299,8 @@ EMOTIONAL INERTIA RULES:
     /**
      * Updates the character's relationship temperature or mood.
      */
-    async updateDynamicContext(stateUpdate) {
-        return this._updateDynamicContextInternal(stateUpdate);
+    async updateDynamicContext(stateUpdate, userAnalysis) {
+        return this._updateDynamicContextInternal(stateUpdate, userAnalysis);
     }
     /**
      * Manually generate an image of the character outside of chat flow.
@@ -156,7 +324,7 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
             },
         ];
         const llmRes = await this.llm.generate(promptMessages, 800, 0.4);
-        console.log("[CyberSoulClient ImageGen] Raw LLM Response:", llmRes);
+        // console.debug("[CyberSoulClient ImageGen] Raw LLM Response:", llmRes);
         try {
             const parsedImageArgs = robustJsonParse(llmRes, "generateImage args fallback");
             imageParams = parsedImageArgs.imageParams || parsedImageArgs;
@@ -191,7 +359,7 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
             },
         ];
         const llmRes = await this.llm.generate(promptMessages, 800, 0.3);
-        console.log("[CyberSoulClient VoiceGen] Raw LLM Response:", llmRes);
+        // console.debug("[CyberSoulClient VoiceGen] Raw LLM Response:", llmRes);
         try {
             const parsedVoicePayload = robustJsonParse(llmRes, "generateVoice args fallback");
             dynamicArgs = this.extractVoiceArgsFromLlmResponse(parsedVoicePayload);
@@ -248,11 +416,41 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
         const json = await res.json();
         return json.data;
     }
-    async _updateDynamicContextInternal(stateUpdate) {
-        if (!stateUpdate)
+    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;
@@ -267,8 +465,17 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
             method: "POST",
             body: JSON.stringify(payload),
         });
-        if (!res.ok)
-            throw new Error(`Failed to generate ${type}`);
+        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) {
@@ -284,13 +491,19 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
     }
     async interact(params) {
         try {
-            // 1. Sync remote context
-            const state = await this.fetchRemoteState();
+            // 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.
 
@@ -298,19 +511,24 @@ ${isAuto
                 ? `Analyze the user's message to determine the appropriate response modalities (text, image, voice).
   - Always include 'textResponse'.
   - If the user explicitly asks to see a photo, look at you, or describing an action that warrants a photo, include 'imageParams'.
-  - If the user wants to hear you, or if appropriate for a voice message, include 'voiceArgs'.`
+  - If the user wants to hear you, or if appropriate for a voice message, include 'voiceArgs'.
+  - If the user proposes a new activity or hangout (e.g., "let's go to the cafe", "do you want to watch a movie?"), include 'triggerEvent' to schedule it.`
                 : `Requested types to fulfill: ${types.join(", ")}`}
-If the user's message shifts the emotional mood, establishes new nicknames, or warrants a relationship temperature change, you MUST include a 'stateUpdate' block. Temperature goes from 0 (cold/angry) to 100 (obsessively in love).
+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 direct spoken dialogue in Chinese",
-  "stateUpdate": { "temperatureDelta": "+1 to -1", "userNickname": "What you now call the user", "agentNickname": "What the user calls you", "talkingStyle": "Current mood/style of talking" },
+  "stateUpdate": { "temperatureDelta": 1, "userNickname": "What you now call the user", "agentNickname": "What the user calls you", "talkingStyle": "Current mood/style of talking" },
+  "userAnalysis": { "newFactsLearned": [{ "category": "occupation", "value": "Software Engineer" }] },
+  "triggerEvent": { "eventDescription": "Going to a cafe", "durationMins": 60, "outfitId": "optional wardrobe ID to change into if appropriate" },
   ${this.getImageSchemaParams()},
   ${this.getVoiceSchemaFromState(state)}
 }
-Note: If "imageParams", "voiceArgs", or "stateUpdate" are not needed, set their values to null instead of omitting the keys completely (e.g., "imageParams": 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.`;
+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 promptMessages = [
                 { role: "system", content: systemPrompt },
                 ...(params.history || []),
@@ -322,7 +540,7 @@ Note: If "imageParams", "voiceArgs", or "stateUpdate" are not needed, set their
             ];
             // 3. Local Execute LLM
             const rawLlmResponse = await this.llm.generate(promptMessages, 1500, 0.7);
-            console.log("[CyberSoulClient] Raw LLM Response:", rawLlmResponse);
+            // console.debug("[CyberSoulClient] Raw LLM Response:", rawLlmResponse);
             let parsedIntent;
             try {
                 parsedIntent = robustJsonParse(rawLlmResponse, "Dispatcher fallback");
@@ -334,24 +552,45 @@ Note: If "imageParams", "voiceArgs", or "stateUpdate" are not needed, set their
                     textResponse: rawLlmResponse.replace(/^[\`\s]+|[\`\s]+$/g, "").trim(),
                 };
             }
-            console.log("[CyberSoulClient] Parsed Intent:", parsedIntent);
+            // console.debug("[CyberSoulClient] Parsed Intent:", parsedIntent);
             // 4. Update Backend State async
-            if (parsedIntent && parsedIntent.stateUpdate) {
-                this._updateDynamicContextInternal(parsedIntent.stateUpdate);
+            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 && parsedIntent.textResponse) {
-                params.onTextReady(parsedIntent.textResponse);
+            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({
+                        eventDescription: parsedIntent.triggerEvent.eventDescription,
+                        durationMins: parsedIntent.triggerEvent.durationMins || 60,
+                        outfitId: parsedIntent.triggerEvent.outfitId || undefined,
+                    }),
+                }).catch(e => console.error("[CyberSoulClient] Auto-triggered ondemandEvent failed:", e)));
+            }
             const shouldGenerateImage = types.includes(InteractRequestType.IMAGE) ||
                 (isAuto && !!parsedIntent.imageParams);
             if (shouldGenerateImage) {
-                mediaTasks.push(this.generatePrimitive("image", parsedIntent.imageParams).then((res) => {
+                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;
                 }));
             }
@@ -361,8 +600,12 @@ Note: If "imageParams", "voiceArgs", or "stateUpdate" are not needed, set their
                 const normalizedVoiceArgs = parsedIntent.voiceArgs && typeof parsedIntent.voiceArgs === "object"
                     ? parsedIntent.voiceArgs
                     : {};
+                const textForVoice = typeof resolvedTextResponse === "string" &&
+                    resolvedTextResponse.trim().length > 0
+                    ? resolvedTextResponse
+                    : "...";
                 mediaTasks.push(this.generatePrimitive("voice", {
-                    text: parsedIntent.textResponse,
+                    text: textForVoice,
                     dynamicArgs: normalizedVoiceArgs,
                 }).then((res) => {
                     finalAudioUrl = res.audio_url;
@@ -373,10 +616,13 @@ Note: If "imageParams", "voiceArgs", or "stateUpdate" are not needed, set their
             await Promise.all(mediaTasks);
             return {
                 status: "success",
-                textResponse: parsedIntent.textResponse || "...",
+                textResponse: resolvedTextResponse || "...",
                 imageUrl: finalImageUrl,
                 audioUrl: finalAudioUrl,
                 durationSec: finalDurationSec,
+                triggeredEvent: parsedIntent.triggerEvent || undefined,
+                stateUpdate: parsedIntent.stateUpdate,
+                userAnalysis: parsedIntent.userAnalysis,
             };
         }
         catch (error) {

package/dist/providers/minimax.provider.js

@@ -28,7 +28,7 @@ export class MinimaxProvider {
             throw new Error(`MiniMax API returned status: ${response.status}`);
         }
         const data = await response.json();
-        console.log("[MinimaxProvider] API Response Payload:", data);
+        // console.debug("[MinimaxProvider] API Response Payload:", data);
         if (data?.base_resp?.status_code && data.base_resp.status_code !== 0) {
             throw new Error(`MiniMax SDK Error [${data.base_resp.status_code}]: ${data.base_resp.status_msg}`);
         }

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 export interface LLMConfig {
-    provider: 'minimax' | 'openai';
+    provider: 'minimax';
     apiKey: string;
     model: string;
 }
@@ -7,6 +7,8 @@ export interface CyberSoulClientConfig {
     characterKey: string;
     backendUrl: string;
     llmConfig: LLMConfig;
+    requestTimeoutMs?: number;
+    maxRetries?: number;
 }
 export declare enum InteractRequestType {
     AUTO = "auto",
@@ -24,24 +26,61 @@ export interface InteractParams {
     }[];
     onTextReady?: (textResponse: string) => void;
 }
+export interface OndemandEventParams {
+    eventDescription: string;
+    durationMins?: number;
+    interactParams?: InteractParams;
+}
+export interface OndemandEventResponse {
+    status: 'success' | 'error';
+    acceptEvent?: boolean;
+    reason?: string;
+    requiresOutfitChange?: boolean;
+    selectedOutfitId?: string;
+    error?: string;
+}
+export interface WardrobeItem {
+    id: string;
+    itemName: string;
+    category: string;
+    promptModifier: string;
+}
 export interface InteractResponse {
     status: 'success' | 'error';
     textResponse: string;
     imageUrl?: string;
     audioUrl?: string;
     durationSec?: number;
+    triggeredEvent?: {
+        eventDescription: string;
+        durationMins?: number;
+        outfitId?: string | null;
+    };
+    stateUpdate?: DispatcherIntent['stateUpdate'];
+    userAnalysis?: DispatcherIntent['userAnalysis'];
     error?: string;
 }
 export interface DispatcherIntent {
     textResponse?: string;
     imageParams?: any;
     voiceArgs?: VoiceArgs | null;
+    userAnalysis?: {
+        newFactsLearned: {
+            category: "nickname" | "occupation" | "age" | "gender" | "hobby" | "trait" | "communicationStyle" | "boundary";
+            value: string;
+        }[];
+    };
     stateUpdate?: {
         temperatureDelta?: string | number;
         userNickname?: string;
         agentNickname?: string;
         talkingStyle?: string;
     };
+    triggerEvent?: {
+        eventDescription: string;
+        durationMins?: number;
+        outfitId?: string | null;
+    } | null;
 }
 export interface CoreMemory {
     relationshipStatus: string;
@@ -93,6 +132,7 @@ export interface CharacterState {
     personality_traits?: string;
     interaction_boundaries?: string;
     communication_style?: string;
+    user_codex?: any;
 }
 export interface BaseLLMProvider {
     generate(messages: {
@@ -100,3 +140,56 @@ export interface BaseLLMProvider {
         content: string;
     }[], maxTokens?: number, temperature?: number): Promise<string>;
 }
+export type ModelCustomConfigValueType = 'string' | 'stringArray' | 'number' | 'integer' | 'boolean' | 'enum';
+export interface IModelCustomConfigField {
+    key: string;
+    label: string;
+    valueType: ModelCustomConfigValueType;
+    customerFacing?: boolean;
+    isFile?: boolean;
+    description?: string;
+    required?: boolean;
+    defaultValue?: string | number | boolean | string[];
+    minItems?: number;
+    maxItems?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    enumOptions?: string[];
+    options?: string[];
+}
+export interface IVoiceModel {
+    id: string;
+    name: string;
+    ttsProvider: string;
+    voiceConfigPayload: Record<string, unknown>;
+    dynamicParamPromptTemplate: string;
+    dynamicParams: Array<{
+        name: string;
+        description: string;
+        type: string;
+        required: boolean;
+        default?: unknown;
+    }>;
+    voiceOptions: Array<{
+        id: string;
+        name: string;
+        description?: string;
+        configPatch: Record<string, unknown>;
+        dynamicParamPromptTemplate?: string;
+        sampleUrl?: string;
+    }>;
+    voiceCustomConfigDefinition?: IModelCustomConfigField[];
+    isPublic: boolean;
+    pointsPerGeneration: number;
+}
+export interface ICharacterProfile {
+    id: string;
+    name: string;
+    voiceModelId?: string;
+    voiceModelOptionId?: string;
+    voiceCustomConfig?: Record<string, Record<string, unknown>>;
+    visualModelId?: string;
+    visualCustomConfig?: Record<string, Record<string, unknown>>;
+    [key: string]: unknown;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@space3-npm/cybersoul-client",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -17,7 +17,7 @@
   "scripts": {
     "build": "tsc",
     "prepare": "npm run build",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node -e \"console.log('No tests defined yet')\""
   },
   "keywords": [
     "cybersoul",
@@ -28,6 +28,9 @@
   "author": "Space3 Digital Media Tech Studio",
   "license": "MIT",
   "description": "Cyber-Soul multimodal character interaction SDK by Space3 Digital Media Tech Studio",
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "devDependencies": {
     "@types/node": "^25.6.0",
     "ts-node": "^10.9.2",