little_ghost 0.2.1 → 0.4.0

data/lib/little_ghost/runtime.rb

@@ -4,45 +4,86 @@ require "json"
 require_relative "configuration"
 
 module LittleGhost
-  # Prepare the shared services that agents and workflows use across many runs.
-  # A runtime owns model resolution, loading, persistence, lookup paths, hooks,
-  # and resource factories for one Ruby setup.
+  # Owns the shared services that assemblies reuse across many Runs.
+  #
+  # Most applications do not construct this class. Configure LittleGhost once
+  # and call a named Agent or Assembly; the first standalone call lazily builds
+  # +LittleGhost.runtime+, and later calls reuse it automatically. Each call
+  # still receives a fresh Run, bound participants, Tools, workspace, and
+  # sandbox.
+  #
+  # Construct Runtime directly when one process intentionally hosts an isolated
+  # LittleGhost setup:
   #
   #   configuration = LittleGhost::Configuration.new(
   #     root: Dir.pwd,
   #     providers: {
-  #       openai: {adapter: :openai, api_key: ENV.fetch("OPENAI_API_KEY")}
+  #       openrouter: {adapter: :openrouter, api_key: ENV.fetch("OPENROUTER_API_KEY")}
   #     },
-  #     models: {customer_support: {target: "openai:gpt-5.6-luna"}},
-  #     default_model: "customer_support",
+  #     models: {customer_support: {target: "openrouter:openai/gpt-5.6-luna"}},
+  #     default_model: :customer_support,
   #     service_name: "support-api"
   #   )
   #   runtime = LittleGhost::Runtime.new(configuration: configuration)
   #
-  #   runtime.service_name # => "support-api"
-  #   runtime.root == Pathname.new(File.realpath(Dir.pwd)) # => true
+  #   CustomerSupportAgent.new(runtime: runtime)
+  #     .ask("Where is order 481?")
+  #     .response
+  #
+  # Explicit construction snapshots the supplied Configuration but does not
+  # replace LittleGhost's shared default Runtime.
+  #
+  # A Runtime may build independent Runs concurrently. Each Run gets its own
+  # bound participants and Tools. By default, Runtime also creates a workspace
+  # and sandbox owned by that Run. Existing workspace or sandbox instances
+  # passed by the application remain caller-owned. Other supplied objects may
+  # receive calls from several threads, so custom stores, resolvers, hooks,
+  # subscribers, providers, and resource factories must be thread-safe. One
+  # SessionStore instance serializes calls sharing a Session; multi-process
+  # deployments need coordination provided by their store.
   #
-  # Without explicit +settings+, construction canonicalizes the root, loads
-  # +config/little_ghost.rb+ once through the Configuration, snapshots settings,
-  # configures instrumentation, eager-loads application constants, and builds the
-  # selected model resolver and session store. Supplying +settings+ is the
-  # lower-level path used to create a sibling runtime from an existing snapshot.
+  # == Advanced construction and ownership
   #
-  # Reuse a runtime across runs. +build_run+ creates any missing workspace and
-  # sandbox, transfers ownership only after both are built, and closes partial
-  # resources if construction fails. +build+ creates a sibling with explicit
-  # overrides and reuses the loader only when the application root is unchanged.
+  # Normal construction reads the application's configured definitions and
+  # builds shared model resolution, persistence, hooks, and resource factories.
+  # The +settings+ form and #build are lower-level extension points for deriving
+  # another Runtime from an existing configuration snapshot.
   #
-  # Startup emits structured lifecycle instrumentation; a failed phase emits a
-  # failure event, flushes instrumentation, and re-raises the original exception.
-  # Session actor resolution must use trusted authenticated identity for tenant
-  # isolation. The default UnrestrictedSandbox is convenient application plumbing,
-  # not a security boundary for untrusted work.
+  # #build_run creates a workspace and sandbox when needed. Once the Run owns
+  # them, it closes them; if construction stops halfway through, Runtime closes
+  # the partial resources. Startup failures are reported to instrumentation and
+  # then raised. Session actor resolution must use authenticated application
+  # identity. The default UnrestrictedSandbox uses host permissions and is not a
+  # security boundary for untrusted work.
+  #
+  # Runtime has no shutdown operation. Runs close resources created for their
+  # request. The application shuts down shared services and process-wide
+  # Instrumentation subscribers with the rest of the process.
   class Runtime
-    # The snapshotted setup and materialized services used by new runs.
-    attr_reader :configuration, :settings, :root, :loader, :prompt_paths, :skill_paths,
-      :skill_resource_root, :model_resolver, :session_store, :workspace_class, :sandbox_class,
-      :runtime_hooks
+    # Configuration object used to construct this Runtime.
+    attr_reader :configuration
+    # Settings snapshot used by new Runs.
+    attr_reader :settings
+    # Canonical application root.
+    attr_reader :root
+    # Loader used for conventional application definitions.
+    attr_reader :loader
+    # Ordered directories searched for prompt templates.
+    attr_reader :prompt_paths
+    # Ordered directories searched for skill definitions.
+    attr_reader :skill_paths
+    # Root used for skill-owned resources, when configured.
+    attr_reader :skill_resource_root
+    # Resolver that turns model roles and targets into executable Models.
+    attr_reader :model_resolver
+    # Shared store used to open per-Run Sessions.
+    attr_reader :session_store
+    # Configured Workspace implementation, or +nil+ for the default.
+    attr_reader :workspace_class
+    # Configured Sandbox implementation, or +nil+ for the default.
+    attr_reader :sandbox_class
+    # Runtime hooks called around request and session preparation.
+    attr_reader :runtime_hooks
 
     # Starts a runtime from +configuration+ or an existing settings snapshot.
     def initialize(configuration:, settings: nil)
@@ -91,8 +132,8 @@ module LittleGhost
         @prompt_paths = build_lookup_paths(:prompt_paths)
         @skill_paths = build_lookup_paths(:skill_paths)
 
-        @startup_phase = "agent_builder"
-        @agent_builder = AgentBuilder.new(
+        @startup_phase = "agent_factory"
+        @agent_factory = AgentFactory.new(
           runtime: self,
           prompt_paths: @prompt_paths,
           resolve_agent: method(:resolve_agent_class)
@@ -129,15 +170,22 @@ module LittleGhost
       payload.is_a?(@invocation_class) ? payload : @invocation_class.new(payload)
     end
 
-    # Creates a Run and transfers ownership of newly created workspace and
-    # sandbox resources to it.
+    # Creates a Run that owns any workspace and sandbox built for the request.
     def build_run(
       payload,
-      agent_class:,
-      entrypoint_class: agent_class,
+      agent_class: nil,
+      assembly_class: nil,
+      entrypoint_class: nil,
+      execution_class: nil,
+      cancellation_token: Support::CancellationToken.new,
       workspace: nil,
       sandbox: nil
     )
+      entrypoint_class ||= assembly_class || agent_class
+      raise ArgumentError, "entrypoint_class is required" unless entrypoint_class
+
+      execution_class ||= assembly_class || entrypoint_class
+      agent_class ||= entrypoint_class if entrypoint_class <= Agent
       owned_resources = []
       workspace ||= build_workspace.tap { |resource| owned_resources << resource }
       sandbox ||= build_sandbox(workspace:).tap { |resource| owned_resources << resource }
@@ -146,6 +194,8 @@ module LittleGhost
         runtime: self,
         agent_class:,
         entrypoint_class:,
+        execution_class:,
+        cancellation_token:,
         workspace:,
         sandbox:
       )
@@ -183,10 +233,44 @@ module LittleGhost
       tools: [],
       agent_path: Subagents::AgentPath::ROOT
     )
-      @agent_builder.build(agent_class_or_name, run:, model:, tools:, agent_path:)
+      agent_class_or_name = agent_class_or_name.definition if agent_class_or_name.is_a?(AgentBuilder)
+      if agent_class_or_name.is_a?(AssemblyDefinition)
+        unless agent_class_or_name.kind == :agent
+          raise ConfigurationError, "agent definition must have kind :agent"
+        end
+        agent_class_or_name = agent_class_or_name.implementation
+      end
+      @agent_factory.build(agent_class_or_name, run:, model:, tools:, agent_path:)
     end
 
-    # The low-cardinality service name attached to runtime telemetry.
+    # Builds an Agent through AgentFactory or constructs another Assembly for +run+.
+    def build_assembly(assembly_class_or_name, run:, **options) # :nodoc:
+      if assembly_class_or_name.is_a?(AssemblyBuilder)
+        assembly_class_or_name = assembly_class_or_name.definition
+      end
+      if assembly_class_or_name.is_a?(Class) && assembly_class_or_name <= Assembly
+        assembly_class_or_name = assembly_class_or_name.definition
+      end
+      if assembly_class_or_name.is_a?(AssemblyDefinition)
+        return build_agent(assembly_class_or_name, run:, **options) if assembly_class_or_name.kind == :agent
+        raise ArgumentError, "composite assembly definitions do not accept agent build options" unless options.empty?
+
+        return assembly_class_or_name.implementation.new(run:, runtime: self)
+      end
+      if !assembly_class_or_name.is_a?(Class) || assembly_class_or_name <= Agent
+        return build_agent(assembly_class_or_name, run:, **options)
+      end
+      unless assembly_class_or_name <= Assembly
+        raise ConfigurationError, "assembly must inherit from LittleGhost::Assembly"
+      end
+      unless options.empty?
+        raise ArgumentError, "composite assemblies do not accept agent build options"
+      end
+
+      assembly_class_or_name.new(run:, runtime: self)
+    end
+
+    # The stable service name attached to runtime telemetry.
     def service_name
       @settings&.[](:service_name) || default_service_name
     end
@@ -205,14 +289,24 @@ module LittleGhost
       )
     end
 
+    def session_history(run, session, fallback:) # :nodoc:
+      stored = session.history
+      runtime_hooks.each do |hook|
+        history = hook.session_history(run, stored:, fallback:)
+        return normalize_history(history) unless history.nil?
+      end
+
+      session.history(fallback:)
+    end
+
     def prepare_run(run) # :nodoc:
       runtime_hooks.each { |hook| hook.prepare_run(run) }
       run
     end
 
-    def prepare_interruption(run, payload) # :nodoc:
+    def prepare_interjection(run, payload) # :nodoc:
       runtime_hooks.reduce(payload) do |prepared, hook|
-        hook.prepare_interruption(run, prepared)
+        hook.prepare_interjection(run, prepared)
       end
     end
 
@@ -282,6 +376,10 @@ module LittleGhost
       Array(hook_classes).map(&:new)
     end
 
+    def normalize_history(history)
+      Array(history).map { |message| Message.coerce(message) }.freeze
+    end
+
     def build_session_store(definition)
       return SessionStores::Memory.new unless definition
 

data/lib/little_ghost/sandbox.rb

@@ -20,7 +20,7 @@ module LittleGhost
   #       result = @container.run(
   #         command, timeout:, cancellation: context&.cancellation_token
   #       )
-  #       Execution.new(**result)
+  #       LittleGhost::Sandbox::Execution.new(**result)
   #     end
   #   end
   #

data/lib/little_ghost/session.rb

@@ -21,7 +21,7 @@ module LittleGhost
   #     store: session.store
   #   )
   #   reopened.history.last.text # => "Hello"
-  #   reopened.state              # => {language: "en"}
+  #   reopened.state[:language]  # => "en"
   #
   # === Persistence and trust
   #
@@ -43,7 +43,7 @@ module LittleGhost
       @actor_id = actor_id&.to_s
       @store = store
       @operation_id = operation_id
-      @metadata = metadata.to_h.freeze
+      @metadata = DataMap.new(metadata).freeze
       @loaded = false
     end
 
@@ -63,16 +63,18 @@ module LittleGhost
       load&.fetch(:messages) || fallback
     end
 
-    # Exposes a mutable copy of the persisted application state.
+    # Exposes a mutable DataMap copy of the persisted application state. String
+    # and Symbol keys address the same value; persisted snapshots use Strings.
     def state
       snapshot = load
-      snapshot ? mutable_copy(snapshot.fetch(:state)) : {}
+      DataMap.new(snapshot ? snapshot.fetch(:state) : {})
     end
 
     # Uses persisted metadata when present and otherwise keeps the metadata from
-    # construction.
+    # construction. The returned DataMap is frozen.
     def metadata
-      load&.fetch(:metadata) || @metadata
+      loaded = load
+      loaded ? DataMap.new(loaded.fetch(:metadata)).freeze : @metadata
     end
 
     # Atomically appends +messages+ when the store still has the expected
@@ -165,8 +167,8 @@ module LittleGhost
     def build_snapshot(messages:, state:, metadata:)
       {
         messages: persistable_messages(messages),
-        state: Support.deep_dup(state.to_h),
-        metadata: Support.deep_dup(metadata.to_h)
+        state: DataMap.new(state).to_h,
+        metadata: DataMap.new(metadata).to_h
       }.freeze
     end
 
@@ -193,8 +195,8 @@ module LittleGhost
 
       {
         messages: persistable_messages(Array(value.fetch(:messages))),
-        state: Support.deep_dup(value.fetch(:state, {}).to_h),
-        metadata: Support.deep_dup(value.fetch(:metadata, {}).to_h)
+        state: DataMap.new(value.fetch(:state, {})).to_h,
+        metadata: DataMap.new(value.fetch(:metadata, {})).to_h
       }.freeze
     rescue KeyError, NoMethodError, TypeError => error
       raise ProtocolError, "Session store returned an invalid value: #{error.class}"
@@ -212,18 +214,5 @@ module LittleGhost
         sanitized
       end.freeze
     end
-
-    def mutable_copy(value)
-      case value
-      when Hash
-        value.to_h { |key, child| [mutable_copy(key), mutable_copy(child)] }
-      when Array
-        value.map { |child| mutable_copy(child) }
-      when String
-        value.dup
-      else
-        value
-      end
-    end
   end
 end

data/lib/little_ghost/session_store.rb

@@ -21,9 +21,11 @@ module LittleGhost
   #     end
   #   end
   #
-  # A snapshot contains +:messages+, +:state+, and +:metadata+. Implementations
-  # provide #load, #append, and #replace; #append must check +expected_count+
-  # atomically so two writers cannot silently lose a turn.
+  # A snapshot contains +:messages+, +:state+, and +:metadata+. State and
+  # metadata cross this boundary as deeply string-keyed JSON mappings. Sessions
+  # expose the same data through DataMap, which accepts String or Symbol keys.
+  # Implementations provide #load, #append, and #replace; #append must check
+  # +expected_count+ atomically so two writers cannot silently lose a turn.
   #
   # Actor identity always comes from the caller. A store must not infer it from
   # ambient process state.
@@ -39,14 +41,16 @@ module LittleGhost
       raise AbstractMethodError, "#{self.class} must implement #load"
     end
 
-    # Atomically appends sanitized messages and stores state and metadata.
+    # Atomically appends sanitized messages and stores canonical JSON state and
+    # metadata.
     # Implementations raise ProtocolError if the persisted message count differs
     # from +expected_count+.
     def append(_id, messages:, state:, metadata:, expected_count:, actor_id: nil)
       raise AbstractMethodError, "#{self.class} must implement #append"
     end
 
-    # Replaces the complete snapshot for +id+ atomically.
+    # Replaces the complete snapshot for +id+ atomically with canonical JSON
+    # state and metadata.
     def replace(_id, messages:, state:, metadata:, actor_id: nil)
       raise AbstractMethodError, "#{self.class} must implement #replace"
     end

data/lib/little_ghost/session_stores/agent_core_memory.rb

@@ -3,6 +3,7 @@
 require "digest"
 require "json"
 require "securerandom"
+require_relative "../data_map"
 require_relative "../session_store"
 
 module LittleGhost
@@ -49,10 +50,15 @@ module LittleGhost
     # but horizontally scaled applications need an external lock or unique
     # active-run record. Commits use generation and checkpoint records so an
     # incomplete write is never exposed as a successful snapshot.
+    #
+    # AgentCore checkpoints are versioned. This store reads supported historical
+    # versions without writing during #load, then writes the current checkpoint
+    # format when the session next appends or replaces its snapshot.
     class AgentCoreMemory < SessionStore
       MESSAGE_PREFIX = "little_ghost:message:v4:" # :nodoc:
       MESSAGE_CHUNK_PREFIX = "little_ghost:message_chunk:v4:" # :nodoc:
-      CHECKPOINT_PREFIX = "little_ghost:checkpoint:v4:" # :nodoc:
+      CHECKPOINT_PREFIX = "little_ghost:checkpoint:v5:" # :nodoc:
+      LEGACY_CHECKPOINT_PREFIX = "little_ghost:checkpoint:v4:" # :nodoc:
       CONVERSATIONAL_TEXT_LIMIT = 100_000 # :nodoc:
       MESSAGE_CHUNK_CONTENT_LIMIT = 90_000 # :nodoc:
       EVENT_PAYLOAD_LIMIT = 100 # :nodoc:
@@ -63,7 +69,8 @@ module LittleGhost
       SYMBOL_KEY_PREFIX = "little_ghost:symbol:" # :nodoc:
       STRING_KEY_PREFIX = "little_ghost:string:" # :nodoc:
       MESSAGE_EVENT_TYPE = "message_v4" # :nodoc:
-      CHECKPOINT_EVENT_TYPE = "checkpoint_v4" # :nodoc:
+      CHECKPOINT_EVENT_TYPE = "checkpoint_v5" # :nodoc:
+      LEGACY_CHECKPOINT_EVENT_TYPE = "checkpoint_v4" # :nodoc:
       CONVERSATION_PROJECTION_EVENT_TYPE = "conversation_projection_v1" # :nodoc:
       PROJECTION_METADATA_KEYS = %w[
         little_ghost_parent_link
@@ -135,27 +142,39 @@ module LittleGhost
       # +expected_count+ matches the latest remote generation.
       def append(id, messages:, state:, metadata:, expected_count:, actor_id: nil)
         messages = persistable_messages(messages)
+        state = DataMap.new(state).to_h
+        metadata = DataMap.new(metadata).to_h
         actor = self.class.safe_id(required_actor_id(actor_id))
         session = self.class.safe_id(id)
         key = [actor, session]
         synchronize_persistence(key) do
-          head, = latest_checkpoint(actor, session)
+          head, lineage = latest_checkpoint(actor, session)
           persistence = head&.fetch(:checkpoint)
           persisted_count = persistence&.fetch(:message_count, 0) || 0
           unless persisted_count == expected_count
             raise ProtocolError, "Session changed while it was being updated"
           end
 
-          generation = persistence&.fetch(:generation) || SecureRandom.uuid
+          if head && head.fetch(:format) != CHECKPOINT_EVENT_TYPE
+            existing = messages_from(message_records_for(actor, session, lineage:), lineage:)
+            messages = [*existing, *messages].freeze
+            expected_count = 0
+            persistence = head.fetch(:checkpoint)
+            root = true
+            generation = SecureRandom.uuid
+          else
+            root = persistence.nil?
+            generation = persistence&.fetch(:generation) || SecureRandom.uuid
+          end
           commit_id = SecureRandom.uuid
           plan = plan_messages(messages, generation:, commit_id:, offset: expected_count)
           checkpoint = build_checkpoint(
             persistence:,
             generation:,
             commit_id:,
-            root: persistence.nil?,
+            root:,
             plan:,
-            message_count: expected_count + messages.length,
+            message_count: root ? messages.length : expected_count + messages.length,
             state:,
             metadata:
           )
@@ -167,6 +186,8 @@ module LittleGhost
       # Replaces the visible snapshot by committing a new remote generation.
       def replace(id, messages:, state:, metadata:, actor_id: nil)
         messages = persistable_messages(messages)
+        state = DataMap.new(state).to_h
+        metadata = DataMap.new(metadata).to_h
         actor = self.class.safe_id(required_actor_id(actor_id))
         session = self.class.safe_id(id)
         key = [actor, session]
@@ -379,27 +400,29 @@ module LittleGhost
 
       def checkpoint_entries(actor_id, session_id)
         entries = []
-        each_event(
-          actor_id,
-          session_id,
-          filter: metadata_filter(type: CHECKPOINT_EVENT_TYPE),
-          event_limit: MAX_CHECKPOINT_EVENTS,
-          payload_limit: MAX_CHECKPOINT_EVENTS,
-          byte_limit: MAX_CHECKPOINT_READ_BYTES
-        ) do |event|
-          data = event_session_data(event)
-          raise ProtocolError, "AgentCore session checkpoint event is invalid" unless data
-          unless event.event_timestamp.is_a?(Time)
-            raise ProtocolError, "AgentCore session checkpoint timestamp is invalid"
-          end
+        [LEGACY_CHECKPOINT_EVENT_TYPE, CHECKPOINT_EVENT_TYPE].each do |format|
+          each_event(
+            actor_id,
+            session_id,
+            filter: metadata_filter(type: format),
+            event_limit: MAX_CHECKPOINT_EVENTS,
+            payload_limit: MAX_CHECKPOINT_EVENTS,
+            byte_limit: MAX_CHECKPOINT_READ_BYTES
+          ) do |event|
+            data = event_session_data(event, format:)
+            raise ProtocolError, "AgentCore session checkpoint event is invalid" unless data
+            unless event.event_timestamp.is_a?(Time)
+              raise ProtocolError, "AgentCore session checkpoint timestamp is invalid"
+            end
 
-          checkpoint = normalize_checkpoint(data)
-          unless event_metadata_value(event, GENERATION_METADATA_KEY) == checkpoint.fetch(:generation) &&
-              event_metadata_value(event, COMMIT_METADATA_KEY) == checkpoint.fetch(:commit_id)
-            raise ProtocolError, "AgentCore session checkpoint metadata is invalid"
-          end
+            checkpoint = normalize_checkpoint(data, format:)
+            unless event_metadata_value(event, GENERATION_METADATA_KEY) == checkpoint.fetch(:generation) &&
+                event_metadata_value(event, COMMIT_METADATA_KEY) == checkpoint.fetch(:commit_id)
+              raise ProtocolError, "AgentCore session checkpoint metadata is invalid"
+            end
 
-          entries << {checkpoint:, event_timestamp: event.event_timestamp}.freeze
+            entries << {checkpoint:, event_timestamp: event.event_timestamp, format:}.freeze
+          end
         end
         entries
       end
@@ -666,12 +689,13 @@ module LittleGhost
         expected.length.times.map { |sequence| indexed.fetch(sequence) }
       end
 
-      def event_session_data(event)
+      def event_session_data(event, format:)
+        prefix = (format == LEGACY_CHECKPOINT_EVENT_TYPE) ? LEGACY_CHECKPOINT_PREFIX : CHECKPOINT_PREFIX
         values = event_payloads(event).filter_map do |payload|
           blob = payload.respond_to?(:blob) ? payload.blob : nil
-          next unless blob.is_a?(String) && blob.start_with?(CHECKPOINT_PREFIX)
+          next unless blob.is_a?(String) && blob.start_with?(prefix)
 
-          checkpoint = deserialize_checkpoint(blob.delete_prefix(CHECKPOINT_PREFIX))
+          checkpoint = deserialize_checkpoint(blob.delete_prefix(prefix), format:)
           checkpoint if checkpoint.is_a?(Hash)
         end
         values.one? ? values.first : nil
@@ -854,37 +878,21 @@ module LittleGhost
       end
 
       def serialize_checkpoint(checkpoint)
-        document = checkpoint.merge(
-          "state" => encode_hash_keys(checkpoint.fetch("state")),
-          "metadata" => encode_hash_keys(checkpoint.fetch("metadata"))
-        )
-        JSON.generate(document)
+        JSON.generate(checkpoint)
       end
 
-      def deserialize_checkpoint(value)
+      def deserialize_checkpoint(value, format: CHECKPOINT_EVENT_TYPE)
         document = JSON.parse(value)
         return document unless document.is_a?(Hash)
 
-        document["state"] = decode_hash_keys(document.fetch("state", {}))
-        document["metadata"] = decode_hash_keys(document.fetch("metadata", {}))
-        document
-      end
-
-      def encode_hash_keys(value)
-        case value
-        when Hash
-          value.to_h do |key, child|
-            prefix = key.is_a?(Symbol) ? SYMBOL_KEY_PREFIX : STRING_KEY_PREFIX
-            ["#{prefix}#{key}", encode_hash_keys(child)]
-          end
-        when Array
-          value.map { |child| encode_hash_keys(child) }
-        else
-          value
+        if format == LEGACY_CHECKPOINT_EVENT_TYPE
+          document["state"] = decode_legacy_hash_keys(document.fetch("state", {}))
+          document["metadata"] = decode_legacy_hash_keys(document.fetch("metadata", {}))
         end
+        document
       end
 
-      def decode_hash_keys(value)
+      def decode_legacy_hash_keys(value)
         case value
         when Hash
           value.to_h do |key, child|
@@ -893,10 +901,10 @@ module LittleGhost
             else
               key.delete_prefix(STRING_KEY_PREFIX)
             end
-            [decoded_key, decode_hash_keys(child)]
+            [decoded_key, decode_legacy_hash_keys(child)]
           end
         when Array
-          value.map { |child| decode_hash_keys(child) }
+          value.map { |child| decode_legacy_hash_keys(child) }
         else
           value
         end
@@ -984,7 +992,7 @@ module LittleGhost
         end
       end
 
-      def normalize_checkpoint(value)
+      def normalize_checkpoint(value, format: CHECKPOINT_EVENT_TYPE)
         if serialize_checkpoint(value.transform_keys(&:to_s)).bytesize > MAX_CHECKPOINT_SERIALIZED_BYTES
           raise ProtocolError, "AgentCore session checkpoint exceeds the byte limit"
         end
@@ -1002,8 +1010,8 @@ module LittleGhost
         serialized_bytes = data.fetch("serialized_bytes")
         event_count = data.fetch("event_count")
         payload_count = data.fetch("payload_count")
-        state = data.fetch("state", {})
-        metadata = data.fetch("metadata", {})
+        state = DataMap.new(data.fetch("state", {})).to_h
+        metadata = DataMap.new(data.fetch("metadata", {})).to_h
         valid = valid_identifier?(generation) && valid_identifier?(commit_id) &&
           (parent_commit_id.nil? || valid_identifier?(parent_commit_id)) &&
           generation_revision.is_a?(Integer) && generation_revision.between?(1, MAX_REVISION) &&