utils.go

Overview

This file provides utility functions for managing and manipulating session state deltas within the system. It handles the segregation and merging of state information categorized by different scopes: application-wide (app), user-specific (user), and session-specific (session). The main purpose is to facilitate clean separation and reassembly of these states when processing client-server interactions or internal session management.

The file defines two core functions:

• ExtractStateDeltas: Decomposes a combined state delta map into separate maps based on key prefixes.

• MergeStates: Recombines separate state maps into a single map by reapplying the appropriate prefixes.

These utilities are essential for managing session state in a structured manner, ensuring that state updates and retrievals conform to the expected scope boundaries.

Constants

• appPrefix = "app:"
  Prefix used to identify keys belonging to the application state.

• userPrefix = "user:"
  Prefix used to identify keys belonging to the user state.

• tempPrefix = "temp:"
  Prefix that identifies temporary keys which are ignored during state extraction.

Functions

ExtractStateDeltas

func ExtractStateDeltas(delta map[string]any) (
	appStateDelta, userStateDelta, sessionStateDelta map[string]any,
)

Description

Splits a single combined state delta map (delta) into three separate maps corresponding to application, user, and session states. It uses key prefixes to determine which map each key-value pair belongs to:

• Keys starting with app: are assigned to the application state map (prefix stripped).

• Keys starting with user: are assigned to the user state map (prefix stripped).

• Keys with no recognized prefix (and not starting with the temporary prefix temp:) are assigned to the session state map as-is.

Temporary keys (starting with temp:) are ignored and excluded from all output maps.

Parameters

• delta: A map of string keys to arbitrary values (any) representing combined state changes.

Returns

• appStateDelta: Map containing application state keys and values (prefix removed).

• userStateDelta: Map containing user state keys and values (prefix removed).

• sessionStateDelta: Map containing session state keys and values (keys unchanged).

Usage Example

delta := map[string]any{
	"app:theme": "dark",
	"user:locale": "en-US",
	"session_id": "abc123",
	"temp:cache": 42,
}

appState, userState, sessionState := ExtractStateDeltas(delta)

// appState => {"theme": "dark"}
// userState => {"locale": "en-US"}
// sessionState => {"session_id": "abc123"}

Implementation Details

• Uses strings.CutPrefix for efficient prefix removal.

• Initializes returned maps even if the input delta is nil to prevent nil map usage.

• Skips keys prefixed with temp: to avoid including transient or ephemeral state.

MergeStates

func MergeStates(appState, userState, sessionState map[string]any) map[string]any

Description

Combines three separate state maps (appState, userState, sessionState) into a single map suitable for client responses or unified state representation. It prefixes keys from the application and user states with their respective prefixes (app: and user:) to maintain their identity in the merged map. Session state keys remain unchanged.

Parameters

• appState: Map representing application state key-value pairs (keys without prefix).

• userState: Map representing user state key-value pairs (keys without prefix).

• sessionState: Map representing session state key-value pairs (keys without prefix).

Returns

• A single merged map combining all input states with appropriate prefixes applied.

Usage Example

appState := map[string]any{"theme": "dark"}
userState := map[string]any{"locale": "en-US"}
sessionState := map[string]any{"session_id": "abc123"}

merged := MergeStates(appState, userState, sessionState)

// merged => {
//    "app:theme": "dark",
//    "user:locale": "en-US",
//    "session_id": "abc123",
// }

Implementation Details

• Pre-allocates the map capacity for performance based on total input size.

• Copies session state entries as-is.

• Adds prefixes when inserting app and user state entries to avoid key collisions.

• Uses maps.Copy for efficient copying of session state entries.

Interaction with Other Parts of the System

This file is part of the session state management utilities within the broader Session Management topic. It supports the breakdown and reassembly of state deltas which are central to:

• Persisting and loading session state fragments from storage.

• Preparing state data for agent invocation contexts (Agent Invocation Context).

• Handling state updates in the Agent Execution Runner or session services (In-Memory Session Service, Database Session Service).

The state maps manipulated here are commonly used in workflows where states must be scoped properly—application-wide, user-specific, or per-session—to maintain consistency and separation of concerns.

Diagram: Function Workflow and Relationships

flowchart TD
A[Input: Combined delta map] -->|ExtractStateDeltas| B1[appStateDelta map]
A -->|ExtractStateDeltas| B2[userStateDelta map]
A -->|ExtractStateDeltas| B3[sessionStateDelta map]
B1 -->|MergeStates| C[Merged map]
B2 -->|MergeStates| C
B3 -->|MergeStates| C
style A fill:none,stroke:none
style B1 fill:none,stroke:none
style B2 fill:none,stroke:none
style B3 fill:none,stroke:none
style C fill:none,stroke:none

This flowchart illustrates the primary data flow:

1. ExtractStateDeltas takes a combined delta and splits it into three maps by prefix.

2. MergeStates takes the three separated maps and recombines them into a single map with prefixes restored.

Notes on Algorithms and Efficiency

• The prefix-based splitting and merging allow for clear state scoping without complex parsing.

• Pre-sizing maps in MergeStates optimizes memory allocation.

• Use of strings.CutPrefix (introduced in Go 1.20) offers a cleaner and more efficient prefix removal compared to older HasPrefix + slicing methods.

• Temporary keys filtering ensures ephemeral data does not persist or interfere with session state logic.

This file forms a fundamental building block for state handling in the session management subsystem, enabling clean separation and unified representation of multi-scoped state data. It directly supports workflows that require clear boundaries between app, user, and session level data for agents and services.