@space3-npm/cybersoul-client 1.4.4 → 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;
@@ -95,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

@@ -116,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) {
@@ -132,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;
@@ -601,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
@@ -689,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 || "...",
@@ -701,6 +753,7 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
                 stateUpdate: parsedIntent.stateUpdate,
                 userAnalysis: parsedIntent.userAnalysis,
                 isEndTurn: parsedIntent.isEndTurn,
+                persistedDynamicContext,
             };
         }
         catch (error) {
@@ -909,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
@@ -938,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) {
@@ -1033,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/types.d.ts

@@ -41,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;
@@ -56,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 {
@@ -114,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.4",
+  "version": "1.4.5",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",