@volley/recognition-client-sdk 0.1.800 → 0.1.803

package/dist/simplified-vgf-recognition-client.d.ts

@@ -9,7 +9,7 @@
  */
 import { RecognitionState } from './vgf-recognition-state.js';
 import { IRecognitionClient, IRecognitionClientConfig, IRecognitionClientStats, ClientState } from './recognition-client.types.js';
-import type { GameContextV1 } from '@recog/shared-types';
+import { type GameContextV1 } from '@recog/shared-types';
 /**
  * Configuration for SimplifiedVGFRecognitionClient
  */
@@ -82,7 +82,6 @@ export declare class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRec
     sendGameContext(context: GameContextV1): void;
     isServerReady(): boolean;
     getVGFState(): RecognitionState;
-    private isTerminalStatus;
     private notifyStateChange;
 }
 /**

package/dist/simplified-vgf-recognition-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"simplified-vgf-recognition-client.d.ts","sourceRoot":"","sources":["../src/simplified-vgf-recognition-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACH,gBAAgB,EAInB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACH,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,WAAW,EACd,MAAM,+BAA+B,CAAC;AAUvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,yBAA0B,SAAQ,wBAAwB;IACvE;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAElD;;;OAGG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACnC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,+BAAgC,SAAQ,kBAAkB;IACvE;;;;OAIG;IACH,WAAW,IAAI,gBAAgB,CAAC;CACnC;AAED;;;GAGG;AACH,qBAAa,8BAA+B,YAAW,+BAA+B;IAClF,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,gBAAgB,CAAkB;IAC1C,OAAO,CAAC,mBAAmB,CAAkD;IAC7E,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAqC;IACnD,OAAO,CAAC,oBAAoB,CAAuB;gBAEvC,MAAM,EAAE,yBAAyB;IAuMvC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B,SAAS,CAAC,SAAS,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,GAAG,IAAI;IAKhE,uBAAuB,CACnB,SAAS,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,EAC/C,gBAAgB,EAAE,MAAM,GACzB,IAAI;IAKP,eAAe,CAAC,SAAS,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,GAAG,IAAI;IAOtE,QAAQ,IAAI,uBAAuB;IAInC;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAWtB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BpC,cAAc,IAAI,IAAI;IAiCtB,mBAAmB,IAAI,MAAM;IAI7B,MAAM,IAAI,MAAM;IAIhB,QAAQ,IAAI,WAAW;IAIvB,WAAW,IAAI,OAAO;IAItB,YAAY,IAAI,OAAO;IAIvB,UAAU,IAAI,OAAO;IAIrB,uBAAuB,IAAI,OAAO;IAIlC,mBAAmB,IAAI,OAAO;IAI9B,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAI7C,aAAa,IAAI,OAAO;IAMxB,WAAW,IAAI,gBAAgB;IAI/B,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,iBAAiB;CA8B5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,yBAAyB,GAAG,+BAA+B,CAE5G"}
+{"version":3,"file":"simplified-vgf-recognition-client.d.ts","sourceRoot":"","sources":["../src/simplified-vgf-recognition-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACH,gBAAgB,EAKnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACH,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,WAAW,EACd,MAAM,+BAA+B,CAAC;AAUvC,OAAO,EAA4B,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,yBAA0B,SAAQ,wBAAwB;IACvE;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAElD;;;OAGG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACnC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,+BAAgC,SAAQ,kBAAkB;IACvE;;;;OAIG;IACH,WAAW,IAAI,gBAAgB,CAAC;CACnC;AAED;;;GAGG;AACH,qBAAa,8BAA+B,YAAW,+BAA+B;IAClF,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,gBAAgB,CAAkB;IAC1C,OAAO,CAAC,mBAAmB,CAAkD;IAC7E,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAqC;IACnD,OAAO,CAAC,oBAAoB,CAAuB;gBAEvC,MAAM,EAAE,yBAAyB;IAoNvC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B,SAAS,CAAC,SAAS,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,GAAG,IAAI;IAKhE,uBAAuB,CACnB,SAAS,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,EAC/C,gBAAgB,EAAE,MAAM,GACzB,IAAI;IAKP,eAAe,CAAC,SAAS,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,GAAG,IAAI;IAOtE,QAAQ,IAAI,uBAAuB;IAInC;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAWtB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BpC,cAAc,IAAI,IAAI;IAiCtB,mBAAmB,IAAI,MAAM;IAI7B,MAAM,IAAI,MAAM;IAIhB,QAAQ,IAAI,WAAW;IAIvB,WAAW,IAAI,OAAO;IAItB,YAAY,IAAI,OAAO;IAIvB,UAAU,IAAI,OAAO;IAIrB,uBAAuB,IAAI,OAAO;IAIlC,mBAAmB,IAAI,OAAO;IAI9B,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAI7C,aAAa,IAAI,OAAO;IAMxB,WAAW,IAAI,gBAAgB;IAI/B,OAAO,CAAC,iBAAiB;CA8B5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,yBAAyB,GAAG,+BAA+B,CAE5G"}

package/dist/vgf-recognition-state.d.ts

@@ -64,6 +64,8 @@ export declare const RecognitionVGFStateSchema: z.ZodObject<{
     functionCallMetadata: z.ZodOptional<z.ZodString>;
     functionCallConfidence: z.ZodOptional<z.ZodNumber>;
     finalFunctionCallTimestamp: z.ZodOptional<z.ZodString>;
+    gameId: z.ZodOptional<z.ZodString>;
+    gamePhase: z.ZodOptional<z.ZodString>;
     promptSlotMap: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
     promptSTT: z.ZodOptional<z.ZodString>;
     promptSTF: z.ZodOptional<z.ZodString>;
@@ -118,6 +120,8 @@ export declare const RecognitionVGFStateSchema: z.ZodObject<{
     functionCallMetadata?: string | undefined;
     functionCallConfidence?: number | undefined;
     finalFunctionCallTimestamp?: string | undefined;
+    gameId?: string | undefined;
+    gamePhase?: string | undefined;
     promptSlotMap?: Record<string, string[]> | undefined;
     promptSTT?: string | undefined;
     promptSTF?: string | undefined;
@@ -160,6 +164,8 @@ export declare const RecognitionVGFStateSchema: z.ZodObject<{
     functionCallMetadata?: string | undefined;
     functionCallConfidence?: number | undefined;
     finalFunctionCallTimestamp?: string | undefined;
+    gameId?: string | undefined;
+    gamePhase?: string | undefined;
     promptSlotMap?: Record<string, string[]> | undefined;
     promptSTT?: string | undefined;
     promptSTF?: string | undefined;
@@ -196,5 +202,6 @@ export declare const RecognitionActionProcessingState: {
 };
 export type RecognitionActionProcessingStateType = typeof RecognitionActionProcessingState[keyof typeof RecognitionActionProcessingState];
 export declare function createInitialRecognitionState(audioUtteranceId: string): RecognitionState;
+export declare function isTerminal(state: Pick<RecognitionState, "transcriptionStatus">): boolean;
 export declare function isValidRecordingStatusTransition(from: string | undefined, to: string): boolean;
 //# sourceMappingURL=vgf-recognition-state.d.ts.map

package/dist/vgf-recognition-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vgf-recognition-state.d.ts","sourceRoot":"","sources":["../src/vgf-recognition-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkDpC,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAGxE,eAAO,MAAM,eAAe;;;;;CAKlB,CAAA;AAEV,MAAM,MAAM,mBAAmB,GAAG,OAAO,eAAe,CAAC,MAAM,OAAO,eAAe,CAAC,CAAA;AAEtF,eAAO,MAAM,mBAAmB;;;;;;CAMtB,CAAA;AAEV,MAAM,MAAM,uBAAuB,GAAG,OAAO,mBAAmB,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAA;AAElG,eAAO,MAAM,gCAAgC;;;;CAInC,CAAA;AAEV,MAAM,MAAM,oCAAoC,GAAG,OAAO,gCAAgC,CAAC,MAAM,OAAO,gCAAgC,CAAC,CAAA;AAGzI,wBAAgB,6BAA6B,CAAC,gBAAgB,EAAE,MAAM,GAAG,gBAAgB,CAQxF;AAGD,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAa9F"}
+{"version":3,"file":"vgf-recognition-state.d.ts","sourceRoot":"","sources":["../src/vgf-recognition-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2DpC,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAGxE,eAAO,MAAM,eAAe;;;;;CAKlB,CAAA;AAEV,MAAM,MAAM,mBAAmB,GAAG,OAAO,eAAe,CAAC,MAAM,OAAO,eAAe,CAAC,CAAA;AAEtF,eAAO,MAAM,mBAAmB;;;;;;CAMtB,CAAA;AAEV,MAAM,MAAM,uBAAuB,GAAG,OAAO,mBAAmB,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAA;AAElG,eAAO,MAAM,gCAAgC;;;;CAInC,CAAA;AAEV,MAAM,MAAM,oCAAoC,GAAG,OAAO,gCAAgC,CAAC,MAAM,OAAO,gCAAgC,CAAC,CAAA;AAGzI,wBAAgB,6BAA6B,CAAC,gBAAgB,EAAE,MAAM,GAAG,gBAAgB,CAQxF;AAUD,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,qBAAqB,CAAC,GAAG,OAAO,CAMxF;AAGD,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAa9F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volley/recognition-client-sdk",
-  "version": "0.1.800",
+  "version": "0.1.803",
   "description": "Recognition Service TypeScript/Node.js Client SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -54,9 +54,9 @@
     "semantic-release": "25.0.1",
     "ts-jest": "29.2.5",
     "typescript": "5.1.6",
-    "@recog/shared-config": "1.0.0",
-    "@recog/shared-types": "1.0.0",
     "@recog/shared-utils": "1.0.0",
+    "@recog/shared-types": "1.0.0",
+    "@recog/shared-config": "1.0.0",
     "@recog/websocket": "1.0.0"
   },
   "keywords": [

package/src/index.ts

@@ -66,6 +66,7 @@ export {
   type RecordingStatusType,
   type TranscriptionStatusType,
   createInitialRecognitionState,
+  isTerminal,
   isValidRecordingStatusTransition
 } from './vgf-recognition-state.js';
 

package/src/simplified-vgf-recognition-client.ts

@@ -12,7 +12,8 @@ import {
     RecognitionState,
     TranscriptionStatus,
     RecordingStatus,
-    RecognitionActionProcessingState
+    RecognitionActionProcessingState,
+    isTerminal
 } from './vgf-recognition-state.js';
 import {
     IRecognitionClient,
@@ -29,7 +30,7 @@ import {
     updateStateOnStop,
     resetRecognitionVGFState
 } from './vgf-recognition-mapper.js';
-import type { GameContextV1 } from '@recog/shared-types';
+import { RecognitionContextTypeV1, type GameContextV1 } from '@recog/shared-types';
 
 /**
  * Configuration for SimplifiedVGFRecognitionClient
@@ -139,6 +140,19 @@ export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognition
         // Track the expected UUID for this session
         this.expectedUuid = this.state.audioUtteranceId;
 
+        // Backfill gameContext from state if the caller didn't pass one in config.
+        // Lets RecognitionState carry session identity (gameId + gamePhase) alongside
+        // runtime prompt inputs (promptSlotMap, promptSTT/STF/TTF), so a single
+        // initialState object is sufficient — no separate gameContext required.
+        // Backward-compatible: if both are provided, clientConfig.gameContext wins.
+        if (!clientConfig.gameContext && this.state.gameId && this.state.gamePhase) {
+            clientConfig.gameContext = {
+                type: RecognitionContextTypeV1.GAME_CONTEXT,
+                gameId: this.state.gameId,
+                gamePhase: this.state.gamePhase,
+            };
+        }
+
         // Forward optional VGF inputs (promptSlotMap, promptSTT/STF/TTF) into the GameContext.
         const hasPromptInputs =
             this.state.promptSlotMap !== undefined ||
@@ -153,10 +167,10 @@ export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognition
             }
 
             if (!clientConfig.gameContext) {
-                // Only create gameContext if we have gameId and gamePhase
-                // These should come from the game's configuration
+                // No gameContext from config, and state didn't carry gameId+gamePhase
+                // either — prompt inputs have nowhere to ride. Warn and drop.
                 if (clientConfig.logger) {
-                    clientConfig.logger('warn', '[VGF] prompt inputs found but no gameContext provided. They will not be sent.');
+                    clientConfig.logger('warn', '[VGF] prompt inputs found but no gameContext provided and state has no gameId/gamePhase. They will not be sent.');
                 }
             } else {
                 if (this.state.promptSlotMap !== undefined) {
@@ -433,16 +447,10 @@ export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognition
         return { ...this.state };
     }
 
-    private isTerminalStatus(status: string | undefined): boolean {
-        return status === TranscriptionStatus.FINALIZED ||
-               status === TranscriptionStatus.ABORTED ||
-               status === TranscriptionStatus.ERROR;
-    }
-
     private notifyStateChange(): void {
 
         // Block duplicate terminal status emissions for THIS session
-        if (this.isTerminalStatus(this.state.transcriptionStatus)) {
+        if (isTerminal(this.state)) {
             if (this.lastSentTerminalUuid === this.expectedUuid) {
                 // Already sent a terminal status for this session - suppress duplicate
                 if (this.logger) {

package/src/vgf-recognition-state.ts

@@ -46,6 +46,15 @@ export const RecognitionVGFStateSchema = z.object({
     functionCallConfidence: z.number().optional(), // Confidence score for the function call.
     finalFunctionCallTimestamp: z.string().optional(), // When the final action after interpreting the transcript was taken. Immutable.
 
+    // Session identity — when set, the VGF client backfills these into
+    // GameContextV1 if the caller didn't pass a `gameContext` in config.
+    // Lets RecognitionState be the single source of truth: server seeds
+    // `gameId` + `gamePhase` + `promptSlotMap` per player, controller passes
+    // the whole state as `initialState`, no separate `gameContext` needed.
+    // Backward-compatible: if `gameContext` is also passed in config, it wins.
+    gameId: z.string().optional(),
+    gamePhase: z.string().optional(),
+
     // Support for prompt slot mapping - passed to recognition context when present
     promptSlotMap: z.record(z.string(), z.array(z.string())).optional(), // Optional map of slot names to prompt values for recognition context
 
@@ -107,6 +116,22 @@ export function createInitialRecognitionState(audioUtteranceId: string): Recogni
     }
 }
 
+// Helper for "session ended — no more state updates coming".
+// Terminal states are FINALIZED (clean end with transcript), ABORTED
+// (user cancelled), and ERROR (something failed). Use this anywhere
+// you forward RecognitionState updates to a server thunk: persist
+// every update, but only do cleanup / observability / scoring work
+// after isTerminal(state) is true. Branch on `transcriptionStatus`
+// when the action depends on *which* terminal state (e.g. only score
+// on FINALIZED, only emit "cancelled" telemetry on ABORTED).
+export function isTerminal(state: Pick<RecognitionState, "transcriptionStatus">): boolean {
+    return (
+        state.transcriptionStatus === TranscriptionStatus.FINALIZED ||
+        state.transcriptionStatus === TranscriptionStatus.ABORTED ||
+        state.transcriptionStatus === TranscriptionStatus.ERROR
+    )
+}
+
 // Helper function to validate state transitions
 export function isValidRecordingStatusTransition(from: string | undefined, to: string): boolean {
     const statusOrder = [