@space3-npm/cybersoul-client 1.1.1 → 1.1.2

package/dist/client.d.ts

@@ -4,6 +4,8 @@ export declare class CyberSoulClient {
     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.
@@ -40,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.
      */

package/dist/client.js

@@ -6,8 +6,12 @@ export class CyberSoulClient {
     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);
@@ -26,39 +30,112 @@ 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": {
@@ -222,8 +299,8 @@ CRITICAL: Output MUST be ONLY valid JSON with no markdown block wrappers. Do NOT
     /**
      * 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.
@@ -366,11 +443,14 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
         this.cachedWardrobeTime = now;
         return availableOutfits;
     }
-    async _updateDynamicContextInternal(stateUpdate) {
-        if (!stateUpdate)
+    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;
@@ -434,18 +514,21 @@ ${isAuto
   - 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", "stateUpdate", or "triggerEvent" 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 || []),
@@ -471,12 +554,16 @@ Note: If "imageParams", "voiceArgs", "stateUpdate", or "triggerEvent" are not ne
             }
             // 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 = [];
@@ -497,7 +584,13 @@ Note: If "imageParams", "voiceArgs", "stateUpdate", or "triggerEvent" are not ne
             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;
                 }));
             }
@@ -507,8 +600,12 @@ Note: If "imageParams", "voiceArgs", "stateUpdate", or "triggerEvent" are not ne
                 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;
@@ -519,11 +616,13 @@ Note: If "imageParams", "voiceArgs", "stateUpdate", or "triggerEvent" are not ne
             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/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",
@@ -54,12 +56,20 @@ export interface InteractResponse {
         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;
@@ -122,6 +132,7 @@ export interface CharacterState {
     personality_traits?: string;
     interaction_boundaries?: string;
     communication_style?: string;
+    user_codex?: any;
 }
 export interface BaseLLMProvider {
     generate(messages: {
@@ -129,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.1",
+  "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",