@space3-npm/cybersoul-client 1.0.9 → 1.1.1

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,9 @@
-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;
     constructor(config: CyberSoulClientConfig);
     /**
      * Internal wrapper for fetch that automatically injects the backend URL and Character Auth token.
@@ -10,6 +12,27 @@ export declare class CyberSoulClient {
     private buildStateContextPrompt;
     private getImageSchemaParams;
     private getVoiceSchemaParams;
+    private buildVoiceSchemaFromDynamicParams;
+    /**
+     * Returns the JSON schema snippet for voiceArgs to embed in the LLM output schema.
+     * Built from dynamic_params when available, otherwise falls back to static defaults.
+     */
+    private getVoiceSchemaFromState;
+    /**
+     * Returns the natural-language director instruction for generating voiceArgs.
+     * Uses dynamic_param_prompt_template from the voice model when configured.
+     */
+    private getVoiceDirectorInstruction;
+    /**
+     * Extracts and types voiceArgs from a raw standalone LLM response.
+     * The voice-only prompt wraps the result as { voiceArgs: { ... } } — unwraps the inner object.
+     * 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.
      */
@@ -51,6 +74,7 @@ export declare class CyberSoulClient {
      */
     generateDailyScript(): Promise<void>;
     private fetchRemoteState;
+    private getWardrobePromptStr;
     private _updateDynamicContextInternal;
     private generatePrimitive;
     private normalizeRequestTypes;

package/dist/client.js

@@ -4,6 +4,8 @@ import { MinimaxProvider } from "./providers/minimax.provider.js";
 export class CyberSoulClient {
     config;
     llm;
+    cachedWardrobeStr = null;
+    cachedWardrobeTime = 0;
     constructor(config) {
         this.config = config;
         // Setup Provider
@@ -61,7 +63,7 @@ EMOTIONAL INERTIA RULES:
     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.)",
@@ -74,7 +76,142 @@ EMOTIONAL INERTIA RULES:
   }`;
     }
     getVoiceSchemaParams() {
-        return `"voiceArgs": { "style_instruction": "How the line should be spoken (Qwen3 format)", "emotion": "happy | sad | angry | fearful | disgusted | surprised | calm | fluent | whisper (Strictly choose ONE from this exact list.)" }`;
+        // Only reached when no dynamic_params are configured on the voice model.
+        // Configure dynamic_params in DB to match the TTS provider; this fallback is provider-agnostic.
+        console.warn("[CyberSoulClient] voice_model.dynamic_params not configured — using generic fallback schema. Configure dynamic_params in DB for provider-specific behaviour.");
+        return `"voiceArgs": { "style_instruction": "How the line should be spoken (required)" }`;
+    }
+    buildVoiceSchemaFromDynamicParams(dynamicParams) {
+        const fields = dynamicParams
+            .map((p) => {
+            const hint = p.required ? `${p.description} (required)` : `${p.description} (optional)`;
+            return `"${p.name}": "${hint}"`;
+        })
+            .join(", ");
+        return `"voiceArgs": { ${fields} }`;
+    }
+    /**
+     * Returns the JSON schema snippet for voiceArgs to embed in the LLM output schema.
+     * Built from dynamic_params when available, otherwise falls back to static defaults.
+     */
+    getVoiceSchemaFromState(state) {
+        const dynamicParams = state.voice_model?.dynamic_params;
+        if (dynamicParams && dynamicParams.length > 0) {
+            return this.buildVoiceSchemaFromDynamicParams(dynamicParams);
+        }
+        return this.getVoiceSchemaParams();
+    }
+    /**
+     * Returns the natural-language director instruction for generating voiceArgs.
+     * Uses dynamic_param_prompt_template from the voice model when configured.
+     */
+    getVoiceDirectorInstruction(state) {
+        const template = state.voice_model?.dynamic_param_prompt_template?.trim();
+        if (template) {
+            return template;
+        }
+        return "Analyze the text according to the character's relationship stage and emotional inertia to determine the best dynamic voice parameters for TTS.";
+    }
+    /**
+     * Extracts and types voiceArgs from a raw standalone LLM response.
+     * The voice-only prompt wraps the result as { voiceArgs: { ... } } — unwraps the inner object.
+     * If the payload is already the inner args object (no voiceArgs wrapper), uses it as-is.
+     */
+    extractVoiceArgsFromLlmResponse(payload) {
+        const inner = payload.voiceArgs;
+        if (inner && typeof inner === "object" && !Array.isArray(inner)) {
+            return inner;
+        }
+        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.
@@ -86,25 +223,14 @@ EMOTIONAL INERTIA RULES:
      * Updates the character's relationship temperature or mood.
      */
     async updateDynamicContext(stateUpdate) {
-        if (!stateUpdate)
-            return;
-        // Map TS schema intent (temperatureDelta) to match Backend payload schema (temperature)
-        const payload = { ...stateUpdate };
-        if (payload.temperatureDelta !== undefined) {
-            payload.temperature = payload.temperatureDelta;
-            delete payload.temperatureDelta;
-        }
-        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
+        return this._updateDynamicContextInternal(stateUpdate);
     }
     /**
      * Manually generate an image of the character outside of chat flow.
      */
     async generateImage(params) {
         let imageParams = {};
-        const state = await this.getState();
+        const state = await this.fetchRemoteState();
         const prompt = `${this.buildStateContextPrompt(state, params.interactParams?.localContext)}
 
 You are an AI image prompt director. Analyze the scene description according to the character's relationship stage and emotional inertia to determine the best image generation parameters.
@@ -121,7 +247,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;
@@ -139,12 +265,14 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
      */
     async generateVoice(params) {
         let dynamicArgs = {};
-        const state = await this.getState();
+        const state = await this.fetchRemoteState();
         const prompt = `${this.buildStateContextPrompt(state, params.interactParams?.localContext)}
 
-You are a voice acting director. Analyze the text according to the character's relationship stage and emotional inertia to determine the single best emotion and a style instruction for TTS.
-Allowed emotions: "happy", "sad", "angry", "fearful", "disgusted", "surprised", "calm", "fluent", "whisper".
-Output strictly valid JSON ONLY. No markdown, no conversational filler. Return exactly this format: {"emotion": "chosen_emotion", "style_instruction": "How the line should be spoken"}`;
+You are a voice acting director. ${this.getVoiceDirectorInstruction(state)}
+Output strictly valid JSON ONLY. No markdown, no conversational filler. Return exactly matching this schema:
+{
+  ${this.getVoiceSchemaFromState(state)}
+}`;
         const promptMessages = [
             { role: "system", content: prompt },
             ...(params.interactParams?.history || []),
@@ -154,12 +282,13 @@ 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 {
-            dynamicArgs = robustJsonParse(llmRes, "generateVoice args fallback");
+            const parsedVoicePayload = robustJsonParse(llmRes, "generateVoice args fallback");
+            dynamicArgs = this.extractVoiceArgsFromLlmResponse(parsedVoicePayload);
         }
         catch (e) {
-            dynamicArgs = {}; // fallback to empty
+            dynamicArgs = {};
         }
         const res = await this.generatePrimitive("voice", {
             text: params.text,
@@ -210,6 +339,33 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
         const json = await res.json();
         return json.data;
     }
+    async getWardrobePromptStr() {
+        const now = Date.now();
+        if (this.cachedWardrobeStr && (now - this.cachedWardrobeTime <= 5 * 60 * 1000)) {
+            return this.cachedWardrobeStr;
+        }
+        let availableOutfits = "None available";
+        try {
+            const wardrobeRes = await this.apiFetch("/api/v1/cyber-soul/wardrobe");
+            if (wardrobeRes.ok) {
+                let wardrobesPayload = {};
+                try {
+                    wardrobesPayload = await wardrobeRes.json();
+                }
+                catch (e) { }
+                const wardrobes = wardrobesPayload.data || [];
+                if (wardrobes.length > 0) {
+                    availableOutfits = wardrobes
+                        .map((w) => `- ID: ${w.id} | Name: ${w.itemName} | Category: ${w.category}`)
+                        .join("\n");
+                }
+            }
+        }
+        catch (e) { }
+        this.cachedWardrobeStr = availableOutfits;
+        this.cachedWardrobeTime = now;
+        return availableOutfits;
+    }
     async _updateDynamicContextInternal(stateUpdate) {
         if (!stateUpdate)
             return;
@@ -229,8 +385,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) {
@@ -246,13 +411,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.
 
@@ -260,18 +431,21 @@ ${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).
+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" },
+  "triggerEvent": { "eventDescription": "Going to a cafe", "durationMins": 60, "outfitId": "optional wardrobe ID to change into if appropriate" },
   ${this.getImageSchemaParams()},
-  ${this.getVoiceSchemaParams()}
+  ${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", "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.`;
             const promptMessages = [
                 { role: "system", content: systemPrompt },
                 ...(params.history || []),
@@ -283,7 +457,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");
@@ -295,7 +469,7 @@ 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);
@@ -309,6 +483,17 @@ Note: If "imageParams", "voiceArgs", or "stateUpdate" are not needed, set their
             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) {
@@ -319,9 +504,12 @@ Note: If "imageParams", "voiceArgs", or "stateUpdate" are not needed, set their
             const shouldGenerateVoice = types.includes(InteractRequestType.VOICE) ||
                 (isAuto && !!parsedIntent.voiceArgs);
             if (shouldGenerateVoice) {
+                const normalizedVoiceArgs = parsedIntent.voiceArgs && typeof parsedIntent.voiceArgs === "object"
+                    ? parsedIntent.voiceArgs
+                    : {};
                 mediaTasks.push(this.generatePrimitive("voice", {
                     text: parsedIntent.textResponse,
-                    dynamicArgs: parsedIntent.voiceArgs || {},
+                    dynamicArgs: normalizedVoiceArgs,
                 }).then((res) => {
                     finalAudioUrl = res.audio_url;
                     finalDurationSec = res.duration_sec;
@@ -335,6 +523,7 @@ Note: If "imageParams", "voiceArgs", or "stateUpdate" are not needed, set their
                 imageUrl: finalImageUrl,
                 audioUrl: finalAudioUrl,
                 durationSec: finalDurationSec,
+                triggeredEvent: parsedIntent.triggerEvent || undefined,
             };
         }
         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

@@ -24,24 +24,53 @@ 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;
+    };
     error?: string;
 }
 export interface DispatcherIntent {
     textResponse?: string;
     imageParams?: any;
-    voiceArgs?: any;
+    voiceArgs?: VoiceArgs | null;
     stateUpdate?: {
         temperatureDelta?: string | number;
         userNickname?: string;
         agentNickname?: string;
         talkingStyle?: string;
     };
+    triggerEvent?: {
+        eventDescription: string;
+        durationMins?: number;
+        outfitId?: string | null;
+    } | null;
 }
 export interface CoreMemory {
     relationshipStatus: string;
@@ -50,6 +79,32 @@ export interface CoreMemory {
     keyEvents: string[];
     appointments: string[];
 }
+/**
+ * Generic dynamic voice args returned by the LLM and forwarded to backend TTS.
+ *
+ * - T lets callers/project code narrow this to model-specific fields when needed.
+ * - Defaults to fully dynamic key/value pairs for provider-agnostic SDK behavior.
+ */
+export type VoiceArgs<T extends Record<string, unknown> = Record<string, unknown>> = T;
+/**
+ * Optional compatibility shape for currently common fields.
+ * Not used as the SDK contract to avoid coupling to specific providers.
+ */
+export interface CommonVoiceArgs {
+    style_instruction?: string;
+    emotion?: string;
+}
+export interface VoiceModelState {
+    tts_provider?: string;
+    dynamic_param_prompt_template?: string;
+    dynamic_params?: Array<{
+        name: string;
+        description: string;
+        type: string;
+        required: boolean;
+        default?: unknown;
+    }>;
+}
 export interface CharacterState {
     current_time: string;
     active_event?: any;
@@ -57,6 +112,7 @@ export interface CharacterState {
     active_wardrobe?: any;
     core_memory?: CoreMemory;
     dynamic_context?: any;
+    voice_model?: VoiceModelState | null;
     relationship_stage?: string;
     name?: string;
     age?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@space3-npm/cybersoul-client",
-  "version": "1.0.9",
+  "version": "1.1.1",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -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",