@space3-npm/cybersoul-client 1.4.4 → 1.4.7

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, SupportedLLMModel } 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;
@@ -78,6 +90,7 @@ export declare class CyberSoulClient {
         interactParams?: InteractParams;
     }): Promise<{
         imageUrl: string;
+        imageMediaId?: string;
     }>;
     /**
      * Manually synthesize voice audio outside of chat flow.
@@ -87,16 +100,27 @@ export declare class CyberSoulClient {
         interactParams?: InteractParams;
     }): Promise<{
         audioUrl: string;
+        audioMediaId?: string;
         durationSec?: number;
     }>;
     /**
      * Fetches the current dynamic context and daily state.
      */
     getState(): Promise<CharacterState>;
+    /**
+     * List the public LLM models the backend currently supports, including the
+     * `customConfigDefinition` schema for each model's `customSettings`.
+     *
+     * Use this to discover valid `provider` / `model` strings and the keys
+     * each model accepts via `llmConfig.customSettings`.
+     */
+    listSupportedLLMs(): Promise<SupportedLLMModel[]>;
     /**
      * 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
@@ -622,7 +669,9 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
             // 5. Build Final Media Calls parallel
             const mediaTasks = [];
             let finalImageUrl = undefined;
+            let finalImageMediaId = undefined;
             let finalAudioUrl = undefined;
+            let finalAudioMediaId = undefined;
             let finalDurationSec = undefined;
             // Output Event Trigger
             if (parsedIntent.triggerEvent) {
@@ -656,6 +705,7 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
                 mediaTasks.push(this.generatePrimitive("image", imagePayload)
                     .then((res) => {
                     finalImageUrl = res.image_url;
+                    finalImageMediaId = res.id;
                 })
                     .catch((e) => {
                     console.error("[CyberSoulClient] Image generation failed:", e);
@@ -679,6 +729,7 @@ Note: Always include "isEndTurn". If "imageParams", "voiceArgs", "triggerEvent",
                 })
                     .then((res) => {
                     finalAudioUrl = res.audio_url;
+                    finalAudioMediaId = res.id;
                     finalDurationSec = res.duration_sec;
                 })
                     .catch((e) => {
@@ -689,18 +740,26 @@ 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 || "...",
                 actionText: parsedIntent.actionText || "",
                 imageUrl: finalImageUrl,
+                imageMediaId: finalImageMediaId,
                 audioUrl: finalAudioUrl,
+                audioMediaId: finalAudioMediaId,
                 likePreviousPicture: parsedIntent.likePreviousPicture,
                 durationSec: finalDurationSec,
                 triggeredEvent: parsedIntent.triggerEvent || undefined,
                 stateUpdate: parsedIntent.stateUpdate,
                 userAnalysis: parsedIntent.userAnalysis,
                 isEndTurn: parsedIntent.isEndTurn,
+                persistedDynamicContext,
             };
         }
         catch (error) {
@@ -909,9 +968,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
@@ -929,21 +990,26 @@ You MUST output ONLY a valid JSON object matching exactly this structure:
             }
             // Handle Optional Media (Image only for proactive to save compute normally, but you can extend)
             let finalImageUrl = undefined;
+            let finalImageMediaId = undefined;
             if (parsedIntent.imageParams) {
                 try {
                     const res = await this.generatePrimitive("image", parsedIntent.imageParams);
                     finalImageUrl = res.image_url;
+                    finalImageMediaId = res.id;
                 }
                 catch (e) {
                     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
+                imageMediaId: finalImageMediaId,
+                stateUpdate: parsedIntent.stateUpdate,
+                persistedDynamicContext,
             };
         }
         catch (error) {
@@ -984,6 +1050,7 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
         const res = await this.generatePrimitive("image", imageParams);
         return {
             imageUrl: res.image_url,
+            imageMediaId: res.id,
         };
     }
     /**
@@ -1022,6 +1089,7 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
         });
         return {
             audioUrl: res.audio_url,
+            audioMediaId: res.id,
             durationSec: res.duration_sec,
         };
     }
@@ -1031,8 +1099,30 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
     async getState() {
         return this.fetchRemoteState();
     }
+    /**
+     * List the public LLM models the backend currently supports, including the
+     * `customConfigDefinition` schema for each model's `customSettings`.
+     *
+     * Use this to discover valid `provider` / `model` strings and the keys
+     * each model accepts via `llmConfig.customSettings`.
+     */
+    async listSupportedLLMs() {
+        const res = await this.apiFetch("/api/v1/cyber-soul/llm-models");
+        if (!res.ok) {
+            throw new Error(`Failed to list supported LLMs: ${res.status}`);
+        }
+        const body = (await res.json());
+        if (Array.isArray(body))
+            return body;
+        if (body && typeof body === "object" && Array.isArray(body.data)) {
+            return body.data;
+        }
+        throw new Error("Unexpected response shape from /llm-models");
+    }
     /**
      * 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;
@@ -54,8 +66,12 @@ export interface ProactiveResponse {
     textResponse?: string;
     actionText?: string;
     imageUrl?: string;
+    imageMediaId?: string;
     audioUrl?: string;
+    audioMediaId?: string;
     stateUpdate?: DispatcherIntent["stateUpdate"];
+    /** Server-authoritative post-write snapshot (see PersistedDynamicContext). */
+    persistedDynamicContext?: PersistedDynamicContext;
     error?: string;
 }
 export interface InteractParams {
@@ -102,7 +118,9 @@ export interface InteractResponse {
     textResponse: string;
     actionText?: string;
     imageUrl?: string;
+    imageMediaId?: string;
     audioUrl?: string;
+    audioMediaId?: string;
     likePreviousPicture?: boolean;
     durationSec?: number;
     triggeredEvent?: {
@@ -114,6 +132,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 {
@@ -287,6 +307,20 @@ export interface IVoiceModel {
     isPublic: boolean;
     pointsPerGeneration: number;
 }
+/**
+ * Public LLM model entry returned by `GET /api/v1/cyber-soul/llm-models`.
+ *
+ * - `provider` is the value to pass as `llmConfig.provider`.
+ * - `name` is the value to pass as `llmConfig.model`.
+ * - `customConfigDefinition` describes the keys (and their constraints) that
+ *   the model accepts via `llmConfig.customSettings`.
+ */
+export interface SupportedLLMModel {
+    id: string;
+    name: string;
+    provider: string;
+    customConfigDefinition: IModelCustomConfigField[];
+}
 export interface ICharacterProfile {
     id: string;
     name: string;

package/package.json

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