@space3-npm/cybersoul-client 1.4.3 → 1.4.5

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { CyberSoulClientConfig, InteractParams, ProactiveParams, ProactiveResponse, OndemandEventParams, OndemandEventResponse, DispatcherIntent, InteractResponse, CharacterState, CoreMemory, UserCodex, HistoryEntry, LikedPicture } from "./types.js";
+import { CyberSoulClientConfig, InteractParams, ProactiveParams, ProactiveResponse, OndemandEventParams, OndemandEventResponse, DispatcherIntent, InteractResponse, CharacterState, CoreMemory, UserCodex, HistoryEntry, LikedPicture, PersistedDynamicContext } from "./types.js";
 export declare class CyberSoulClient {
     private config;
     private llm;
@@ -14,6 +14,18 @@ export declare class CyberSoulClient {
     private fetchRemoteState;
     private getWardrobePromptStr;
     private generatePrimitive;
+    /**
+     * PATCH the backend dynamic context. The server applies stage-based
+     * dampening, familiarity soft-caps, hard floor, and stage re-evaluation,
+     * then returns the *authoritative* persisted `temperature` and
+     * `relationshipStage`. We surface those so callers (and ultimately the UI)
+     * can avoid recomputing the delta locally — local math would diverge from
+     * the server because the LLM-supplied `temperatureDelta` is just raw intent.
+     *
+     * Returns `null` when there's nothing to send, or when the request fails
+     * (failure is non-fatal for the chat turn; callers must treat `null` as
+     * "no fresh server snapshot available").
+     */
     private _updateDynamicContextInternal;
     private normalizeRequestTypes;
     private getElapsedTimeInfo;
@@ -42,6 +54,22 @@ export declare class CyberSoulClient {
      * If the payload is already the inner args object (no voiceArgs wrapper), uses it as-is.
      */
     private extractVoiceArgsFromLlmResponse;
+    /**
+     * Strip content the TTS engine can't speak naturally:
+     *   - Stage-direction wrappers like (smiles), （挑眉）, [pauses], 【动作】, *grins*
+     *     — these slip through despite prompt instructions and the engine will
+     *     literally read the brackets/asterisks if left in.
+     *   - Emoji and emoji-component codepoints (Extended_Pictographic plus the
+     *     ZWJ / variation-selector / skin-tone / regional-indicator scaffolding
+     *     that builds composite emoji). TTS providers either read these aloud
+     *     as the literal Unicode name ("face with tears of joy") or produce a
+     *     glitchy artifact, both of which sound wrong.
+     *
+     * Collapses runs of whitespace introduced by removals and trims the result.
+     * Returns "" if everything gets stripped — callers should fall back to a
+     * neutral placeholder (e.g. "...") so the TTS call still has valid input.
+     */
+    private sanitizeTextForVoice;
     private formatHistoryEntries;
     private buildHistoryTranscript;
     interact(params: InteractParams): Promise<InteractResponse>;
@@ -79,8 +107,10 @@ export declare class CyberSoulClient {
     getState(): Promise<CharacterState>;
     /**
      * Updates the character's relationship temperature or mood.
+     * Returns the server-authoritative post-write `{ temperature, relationshipStage }`
+     * snapshot (or `null` if there was nothing to send / the request failed).
      */
-    updateDynamicContext(stateUpdate: DispatcherIntent["stateUpdate"], userAnalysis?: DispatcherIntent["userAnalysis"]): Promise<void>;
+    updateDynamicContext(stateUpdate: DispatcherIntent["stateUpdate"], userAnalysis?: DispatcherIntent["userAnalysis"]): Promise<PersistedDynamicContext | null>;
     /**
      * Gift a new outfit to the character's wardrobe inventory.
      */

package/dist/client.js

@@ -13,7 +13,7 @@ export class CyberSoulClient {
         this.requestTimeoutMs = config.requestTimeoutMs ?? 120000;
         this.maxRetries = Math.max(0, config.maxRetries ?? 1);
         // Setup Provider
-        this.llm = new GenericLLMProvider(config.llmConfig, config.backendUrl, config.characterKey);
+        this.llm = new GenericLLMProvider(config.llmConfig, config.backendUrl, config.characterKey, config.fetchImpl);
     }
     /**
      * Internal wrapper for fetch that automatically injects the backend URL and Character Auth token.
@@ -33,7 +33,8 @@ export class CyberSoulClient {
             const controller = new AbortController();
             const timeout = setTimeout(() => controller.abort(), this.requestTimeoutMs);
             try {
-                const response = await fetch(url, {
+                const fetchFn = this.config.fetchImpl ?? fetch;
+                const response = await fetchFn(url, {
                     ...options,
                     headers,
                     signal: controller.signal,
@@ -115,9 +116,21 @@ export class CyberSoulClient {
         }
         return res.json();
     }
+    /**
+     * PATCH the backend dynamic context. The server applies stage-based
+     * dampening, familiarity soft-caps, hard floor, and stage re-evaluation,
+     * then returns the *authoritative* persisted `temperature` and
+     * `relationshipStage`. We surface those so callers (and ultimately the UI)
+     * can avoid recomputing the delta locally — local math would diverge from
+     * the server because the LLM-supplied `temperatureDelta` is just raw intent.
+     *
+     * Returns `null` when there's nothing to send, or when the request fails
+     * (failure is non-fatal for the chat turn; callers must treat `null` as
+     * "no fresh server snapshot available").
+     */
     async _updateDynamicContextInternal(stateUpdate, userAnalysis) {
         if (!stateUpdate && !userAnalysis)
-            return;
+            return null;
         // Map TS schema intent (temperatureDelta) to match Backend payload schema (temperature)
         const payload = { ...stateUpdate };
         if (userAnalysis) {
@@ -131,10 +144,39 @@ export class CyberSoulClient {
             const normalizedOngoingScene = this.normalizeOngoingSceneState(payload.ongoingScene);
             payload.ongoingScene = normalizedOngoingScene || null;
         }
-        await this.apiFetch("/api/v1/cyber-soul/characters/dynamic-context", {
-            method: "PATCH",
-            body: JSON.stringify(payload),
-        }).catch((e) => console.error("Failed to update dynamic context", e)); // non-blocking error handler
+        let res;
+        try {
+            res = 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);
+            return null;
+        }
+        if (!res.ok) {
+            console.error(`Failed to update dynamic context: HTTP ${res.status}`);
+            return null;
+        }
+        try {
+            const body = (await res.json());
+            const temperature = typeof body.dynamicContext?.temperature === "number" &&
+                Number.isFinite(body.dynamicContext.temperature)
+                ? body.dynamicContext.temperature
+                : undefined;
+            const relationshipStage = typeof body.relationshipStage === "string"
+                ? body.relationshipStage
+                : undefined;
+            if (temperature === undefined && relationshipStage === undefined) {
+                return null;
+            }
+            return { temperature, relationshipStage };
+        }
+        catch (e) {
+            console.error("Failed to parse dynamic-context PATCH response", e);
+            return null;
+        }
     }
     normalizeRequestTypes(requestTypes) {
         let normalized = requestTypes;
@@ -408,6 +450,32 @@ ${isProactive
         }
         return payload;
     }
+    /**
+     * Strip content the TTS engine can't speak naturally:
+     *   - Stage-direction wrappers like (smiles), （挑眉）, [pauses], 【动作】, *grins*
+     *     — these slip through despite prompt instructions and the engine will
+     *     literally read the brackets/asterisks if left in.
+     *   - Emoji and emoji-component codepoints (Extended_Pictographic plus the
+     *     ZWJ / variation-selector / skin-tone / regional-indicator scaffolding
+     *     that builds composite emoji). TTS providers either read these aloud
+     *     as the literal Unicode name ("face with tears of joy") or produce a
+     *     glitchy artifact, both of which sound wrong.
+     *
+     * Collapses runs of whitespace introduced by removals and trims the result.
+     * Returns "" if everything gets stripped — callers should fall back to a
+     * neutral placeholder (e.g. "...") so the TTS call still has valid input.
+     */
+    sanitizeTextForVoice(text) {
+        if (typeof text !== "string")
+            return "";
+        return text
+            // (parens), （全角）, [brackets], 【全角】, *asterisks*
+            .replace(/[\(（\[【\*].*?[\)）\]】\*]/g, "")
+            // emoji + ZWJ + variation selectors + skin-tone modifiers + regional indicators
+            .replace(/[\p{Extended_Pictographic}\u200D\uFE0F\uFE0E\u{1F3FB}-\u{1F3FF}\u{1F1E6}-\u{1F1FF}]/gu, "")
+            .replace(/\s+/g, " ")
+            .trim();
+    }
     formatHistoryEntries(history, userName, agentName, promptDirective = "") {
         const contextLines = [];
         for (let i = 0; i < history.length; i++) {
@@ -574,9 +642,15 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
                 };
             }
             // console.debug("[CyberSoulClient] Parsed Intent:", parsedIntent);
-            // 4. Update Backend State async
+            // 4. Update Backend State async (in parallel with media generation
+            //    below). We keep the promise so we can resolve the
+            //    server-authoritative `temperature` / `relationshipStage` and
+            //    return it in the final response — clients cannot reproduce the
+            //    server's stage dampening + soft caps locally, so this is the only
+            //    reliable source of truth.
+            let persistedStatePromise = Promise.resolve(null);
             if (parsedIntent && (parsedIntent.stateUpdate || parsedIntent.userAnalysis)) {
-                this._updateDynamicContextInternal(parsedIntent.stateUpdate, parsedIntent.userAnalysis);
+                persistedStatePromise = this._updateDynamicContextInternal(parsedIntent.stateUpdate, parsedIntent.userAnalysis);
             }
             const resolvedTextResponse = typeof parsedIntent.textResponse === "string" &&
                 parsedIntent.textResponse.trim().length > 0
@@ -642,12 +716,8 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
                 const normalizedVoiceArgs = parsedIntent.voiceArgs && typeof parsedIntent.voiceArgs === "object"
                     ? parsedIntent.voiceArgs
                     : {};
-                let textForVoice = resolvedTextResponse;
-                // One final bulletproof regex wash to strip (smiles) and *laughs* just in case the LLM disobeys
-                if (typeof textForVoice === "string") {
-                    textForVoice = textForVoice.replace(/[\(（\[【\*].*?[\)）\]】\*]/g, '').trim();
-                }
-                if (typeof textForVoice !== "string" || textForVoice.trim().length === 0) {
+                let textForVoice = this.sanitizeTextForVoice(resolvedTextResponse);
+                if (textForVoice.length === 0) {
                     textForVoice = "...";
                 }
                 mediaTasks.push(this.generatePrimitive("voice", {
@@ -666,6 +736,11 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
             }
             // Wait for image/voice gens to return successfully
             await Promise.all(mediaTasks);
+            // Await the dynamic-context PATCH alongside media so the final
+            // response carries the server's authoritative temperature/stage.
+            // This adds at most ~1 small request to the critical path; in
+            // practice the PATCH usually resolves before media generation.
+            const persistedDynamicContext = (await persistedStatePromise) ?? undefined;
             return {
                 status: "success",
                 textResponse: resolvedTextResponse || "...",
@@ -678,6 +753,7 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
                 stateUpdate: parsedIntent.stateUpdate,
                 userAnalysis: parsedIntent.userAnalysis,
                 isEndTurn: parsedIntent.isEndTurn,
+                persistedDynamicContext,
             };
         }
         catch (error) {
@@ -886,9 +962,11 @@ You MUST output ONLY a valid JSON object matching exactly this structure:
                     reason: parsedIntent.skipReason || "Character decided to skip proactive message based on mood/stage."
                 };
             }
-            // Update Remote state if needed
+            // Update Remote state if needed (capture promise for authoritative
+            // server snapshot — see notes in interact()).
+            let persistedStatePromise = Promise.resolve(null);
             if (parsedIntent.stateUpdate) {
-                this._updateDynamicContextInternal(parsedIntent.stateUpdate).catch(e => console.error(e));
+                persistedStatePromise = this._updateDynamicContextInternal(parsedIntent.stateUpdate);
             }
             const resolvedTextResponse = typeof parsedIntent.textResponse === "string" &&
                 parsedIntent.textResponse.trim().length > 0
@@ -915,12 +993,14 @@ You MUST output ONLY a valid JSON object matching exactly this structure:
                     console.error("[CyberSoulClient] Proactive Image generation failed:", e);
                 }
             }
+            const persistedDynamicContext = (await persistedStatePromise) ?? undefined;
             return {
                 status: "success",
                 textResponse: parsedIntent.textResponse,
                 actionText: parsedIntent.actionText,
                 imageUrl: finalImageUrl,
-                stateUpdate: parsedIntent.stateUpdate
+                stateUpdate: parsedIntent.stateUpdate,
+                persistedDynamicContext,
             };
         }
         catch (error) {
@@ -994,7 +1074,7 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
             dynamicArgs = {};
         }
         const res = await this.generatePrimitive("voice", {
-            text: params.text,
+            text: this.sanitizeTextForVoice(params.text) || "...",
             dynamicArgs,
         });
         return {
@@ -1010,6 +1090,8 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
     }
     /**
      * Updates the character's relationship temperature or mood.
+     * Returns the server-authoritative post-write `{ temperature, relationshipStage }`
+     * snapshot (or `null` if there was nothing to send / the request failed).
      */
     async updateDynamicContext(stateUpdate, userAnalysis) {
         return this._updateDynamicContextInternal(stateUpdate, userAnalysis);

package/dist/llm.provider.d.ts

@@ -3,8 +3,10 @@ export declare class GenericLLMProvider implements BaseLLMProvider {
     private config;
     private backendApiUrl;
     private backendAuthToken?;
+    private fetchImpl?;
     private static templateCache;
-    constructor(config: GenericLLMConfig, backendApiUrl: string, backendAuthToken?: string | undefined);
+    constructor(config: GenericLLMConfig, backendApiUrl: string, backendAuthToken?: string | undefined, fetchImpl?: typeof fetch | undefined);
+    private get fetchFn();
     private fetchTemplate;
     private extractResponse;
     generate(messages: {

package/dist/llm.provider.js

@@ -2,11 +2,16 @@ export class GenericLLMProvider {
     config;
     backendApiUrl;
     backendAuthToken;
+    fetchImpl;
     static templateCache = new Map();
-    constructor(config, backendApiUrl, backendAuthToken) {
+    constructor(config, backendApiUrl, backendAuthToken, fetchImpl) {
         this.config = config;
         this.backendApiUrl = backendApiUrl;
         this.backendAuthToken = backendAuthToken;
+        this.fetchImpl = fetchImpl;
+    }
+    get fetchFn() {
+        return this.fetchImpl ?? fetch;
     }
     async fetchTemplate() {
         const cacheKey = `${this.config.provider}:${this.config.model}`;
@@ -24,7 +29,7 @@ export class GenericLLMProvider {
             provider: this.config.provider,
             model: this.config.model
         });
-        const resp = await fetch(`${this.backendApiUrl}/api/v1/cyber-soul/llm-models/template?${qs.toString()}`, {
+        const resp = await this.fetchFn(`${this.backendApiUrl}/api/v1/cyber-soul/llm-models/template?${qs.toString()}`, {
             headers
         });
         if (!resp.ok) {
@@ -66,7 +71,7 @@ export class GenericLLMProvider {
         if (!payload.messages || (Array.isArray(payload.messages) && payload.messages.length === 0)) {
             payload.messages = messages;
         }
-        const response = await fetch(template.apiUrl, {
+        const response = await this.fetchFn(template.apiUrl, {
             method: 'POST',
             headers,
             body: JSON.stringify(payload)

package/dist/types.d.ts

@@ -10,6 +10,15 @@ export interface CyberSoulClientConfig {
     llmConfig: GenericLLMConfig;
     requestTimeoutMs?: number;
     maxRetries?: number;
+    /**
+     * Optional fetch override. When provided, the client uses this in
+     * place of the global `fetch` for every HTTP call (backend + LLM
+     * provider). Intended for environments where the global fetch is
+     * suspended by the host platform — e.g. React Native on Samsung
+     * BBA / Doze — and a native HTTP path must be used instead. Must
+     * conform to the standard `fetch` signature.
+     */
+    fetchImpl?: typeof fetch;
 }
 export declare enum InteractRequestType {
     AUTO = "auto",
@@ -32,6 +41,18 @@ export interface InteractMetadata {
     triggerEvent?: DispatcherIntent["triggerEvent"];
     likePreviousPicture?: boolean;
 }
+/**
+ * Server-authoritative snapshot returned by PATCH /characters/dynamic-context
+ * after the backend applies stage dampening, familiarity soft caps, hard
+ * floors, rounding, and stage re-evaluation. Use this instead of recomputing
+ * the delta on the client.
+ */
+export interface PersistedDynamicContext {
+    /** Persisted absolute temperature (0-100), post all server-side adjustments. */
+    temperature?: number;
+    /** Persisted relationship stage label after re-evaluation. */
+    relationshipStage?: string;
+}
 export interface ProactiveParams {
     history?: HistoryEntry[];
     maxUnreplied?: number;
@@ -47,6 +68,8 @@ export interface ProactiveResponse {
     imageUrl?: string;
     audioUrl?: string;
     stateUpdate?: DispatcherIntent["stateUpdate"];
+    /** Server-authoritative post-write snapshot (see PersistedDynamicContext). */
+    persistedDynamicContext?: PersistedDynamicContext;
     error?: string;
 }
 export interface InteractParams {
@@ -105,6 +128,8 @@ export interface InteractResponse {
     stateUpdate?: DispatcherIntent["stateUpdate"];
     userAnalysis?: DispatcherIntent["userAnalysis"];
     isEndTurn?: boolean;
+    /** Server-authoritative post-write snapshot (see PersistedDynamicContext). */
+    persistedDynamicContext?: PersistedDynamicContext;
     error?: string;
 }
 export interface OngoingSceneState {

package/package.json

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