scout-ai 1.2.3 → 2.0.0

data/lib/scout/llm/agent/delegate.rb

@@ -1,113 +1,155 @@
 module LLM
   class Agent
 
+    SOCIAL_INHERIT_MODES = %w[none tools conversation].freeze
+    SOCIAL_AGENT_NAME = /\A[a-z_.-]+\z/i
+    SOCIAL_CONVERSATION_NAME = /\A[a-z0-9][a-z0-9_.-]*\z/i
+    SOCIAL_PRIVATE_OPTIONS = %i[
+      agent client current_meta format messages no_ask_override previous_response_id
+      process return_messages tool_choice tools
+    ].freeze
+
     attr_accessor :society, :chats
 
-    def load_agent(agent_name, options)
-      raise ParameterException, 
-        "Agent name must be a single word optionally including a few puntuation characters" unless agent_name =~ /^[a-z_.-]*$/i
+    # Load one immutable template per specialist. Conversations clone this
+    # template so that their current chats and start chats remain independent.
+    def load_agent(agent_name, options = {})
+      agent_name = normalize_social_agent_name(agent_name)
       @society ||= {}
-      @society[agent_name] ||= LLM.load_agent agent_name, options.merge(self.other_options)
+      @society[agent_name] ||= begin
+                                 agent = LLM.load_agent(agent_name, social_agent_options(options))
+                                 agent
+                               end
     end
 
-    def load_chat(agent_name, options, chat)
+    # Return a persistent specialist conversation. Conversation identifiers are
+    # scoped by specialist, so Worker/work_A and Critic/work_A cannot collide.
+    # `inherit` is only used when the conversation is first created.
+    def load_chat(agent_name, options = {}, conversation = nil, inherit: 'tools')
+      agent_name = normalize_social_agent_name(agent_name)
+      conversation = normalize_social_conversation_name(conversation)
+      inherit = normalize_social_inherit(inherit)
+
       @chats ||= {}
-      @chats[chat] ||= load_agent(agent_name, options).clone
+      key = social_chat_key(agent_name, conversation)
+      @chats[key] ||= begin 
+                        agent = start_social_chat(agent_name, options, inherit)
+                        agent.save_file = society_save_file(agent_name, conversation)
+                        agent
+                      end
+
+    end
+
+    # Ask a specialist using a plain-text prompt.
+    #
+    # With no conversation identifier this is a one-shot call. With an
+    # identifier, later calls continue the same specialist instance. The
+    # inheritance policy seeds a new call or conversation after the
+    # specialist's own start_chat:
+    #
+    # - none:         no context from the caller
+    # - tools:        only declarative tooling from the caller's task chat
+    # - conversation: the caller's complete task chat
+    #
+    # ScoutCoder: Agent#prompt parses String input as Scout chat-file syntax.
+    # Delegated prompts must instead be appended with Agent#user so role-looking
+    # text such as "tool:" cannot turn into a control message or grant tools.
+    def ask_agent(agent_name, prompt, conversation: nil, inherit: 'tools', options: {})
+      raise ParameterException, 'The delegated prompt must be a String' unless String === prompt
+
+      agent_name = normalize_social_agent_name(agent_name)
+      inherit = normalize_social_inherit(inherit)
+
+      agent = if conversation.nil?
+                load_chat(agent_name, options, 'default', inherit: inherit)
+              else
+                conversation = normalize_social_conversation_name(conversation)
+                load_chat(agent_name, options, conversation, inherit: inherit)
+              end
+
+      agent.user(prompt)
+
+      agent
     end
 
+    # Expose a deliberately narrow `ask` tool to this agent. The model can send
+    # only a specialist name, a plain-text prompt, an optional persistent
+    # conversation identifier, and an inheritance policy. It never receives or
+    # edits the specialist's Chat object.
     def socialize(options = {})
       @other_options[:tools] ||= {}
       @society ||= {}
+      social_options = social_duplicate(options || {})
 
       task_name = :ask
-      block ||= Proc.new do |name, parameters|
-        agent_name, prompt, chat_id = IndiferentHash.process_options parameters.dup, 
-          :agent, :prompt, :chat, 
-          chat: 'current'
-
+      block = Proc.new do |_name, parameters|
         begin
-          options = options.dup
-
-          res = case chat_id
-                when 'current'
-                  agent = load_chat agent_name, options, 'current'
-                  chat = self.current_chat - self.start_chat
-                  agent.concat chat
-                  agent.user prompt
-                  agent.chat 
-                when 'none', nil, 'false'
-                  agent = load_agent agent_name, options
-                  agent.prompt prompt
-                else
-                  agent = load_chat agent_name, options, chat_id
-                  agent.user prompt
-                  agent.chat
-                end
-          res
-        rescue ScoutException
-          next $!
+          agent_name, prompt, conversation, inherit = social_tool_parameters(parameters)
+          ask_agent(agent_name, prompt,
+                    conversation: conversation,
+                    inherit: inherit,
+                    options: social_options)
+        rescue ScoutException => e
+          e
         end
       end
 
       properties = {
         agent: {
-          "type": :string,
-          "description": "Name of the agent"
+          type: 'string',
+          description: 'Name of the specialist agent to ask'
         },
         prompt: {
-          "type": :string,
-          "description": "Prompt to pass to the agent"
+          type: 'string',
+          description: 'Plain-text prompt sent as one user message to the specialist'
         },
-        chat: {
-          "type": :string,
-          "description": "(Optional) Chat identifier used to keep conversation history. The default is 'current' uses the conversation that the caller agent is involved with",
-          "default": 'current'
+        conversation: {
+          type: 'string',
+          pattern: '^[A-Za-z0-9][A-Za-z0-9_.-]*$',
+          description: 'Optional conversation or chat identifier; reuse it with the same agent to continue that conversation across several calls'
+        },
+        inherit: {
+          type: 'string',
+          enum: SOCIAL_INHERIT_MODES,
+          default: 'tools',
+          description: "Context copied only when starting the call or named conversation: 'none' uses only the specialist start_chat, 'tools' also copies caller task tooling, and 'conversation' copies the caller task conversation"
         }
       }
 
-      required_inputs = [:agent, :prompt]
-
-      description =<<-EOF
-
-The 'ask' function is used to send a prompt to an agent, returning the agents
-response. You can keep one-shot questions or keep running conversations with
-the same agent by giving the chat an identifier. The chat id 'current' has the
-special meaning of passing the entire conversation to the agent, not just the
-prompt.
-
+      description = <<-EOF
+Ask another agent and receive only its text answer. Omit `conversation` for an
+independent one-shot call. Set `conversation` to a name and reuse the same name
+with the same agent for follow-up turns. `inherit` controls only how a new call
+or named conversation is initialized; follow-up turns retain their own history.
+The specialist's own start_chat is always applied first.
       EOF
 
       function = {
         name: task_name,
         description: description,
         parameters: {
-          type: "object",
+          type: 'object',
           properties: properties,
-          required: required_inputs
+          required: [:agent, :prompt],
+          additionalProperties: false
         }
       }
 
-      definition = IndiferentHash.setup function.merge(type: 'function', function: function)
-
-
+      definition = IndiferentHash.setup(function.merge(type: 'function', function: function))
       @other_options[:tools][task_name] = [block, definition]
     end
-  end
-    def delegate(agent, name, description, &block)
+
+    def delegate(agent, name, description, task_name = nil, &block)
       @other_options[:tools] ||= {}
-      task_name = "hand_off_to_#{name}".to_sym
+      task_name = "hand_off_to_#{name}".to_sym if task_name.nil?
 
-      block ||= Proc.new do |name, parameters|
+      block ||= Proc.new do |_name, parameters|
         message = parameters[:message]
         new_conversation = parameters[:new_conversation]
         Log.medium "Delegated to #{agent}: " + Log.fingerprint(message)
-        if new_conversation
-          agent.start
-        else
-          agent.purge
-        end
+        agent.start if new_conversation
         agent.user message
-        agent.chat
+        agent
       end
 
       properties = {
@@ -136,8 +178,175 @@ prompt.
 
       definition = IndiferentHash.setup function.merge(type: 'function', function: function)
 
-
       @other_options[:tools][task_name] = [block, definition]
     end
 
+    private
+
+    def normalize_social_agent_name(agent_name)
+      agent_name = agent_name.to_s if Symbol === agent_name
+      unless String === agent_name && SOCIAL_AGENT_NAME.match?(agent_name)
+        raise ParameterException,
+              'Agent name must contain only letters, dots, underscores, or hyphens'
+      end
+      agent_name
+    end
+
+    def normalize_social_conversation_name(conversation)
+      conversation = conversation.to_s if Symbol === conversation
+      unless String === conversation && SOCIAL_CONVERSATION_NAME.match?(conversation)
+        raise ParameterException,
+              'Conversation identifier must start with a letter or number and contain only letters, numbers, dots, underscores, or hyphens'
+      end
+      conversation
+    end
+
+    def normalize_social_inherit(inherit)
+      inherit = inherit.to_s
+      return inherit if SOCIAL_INHERIT_MODES.include?(inherit)
+
+      raise ParameterException,
+            "Unknown inheritance policy #{inherit.inspect}; expected one of #{SOCIAL_INHERIT_MODES * ', '}"
+    end
+
+    def social_chat_key(agent_name, conversation)
+      "#{agent_name}/#{conversation}"
+    end
+
+    def society_save_file(agent_name, conversation)
+      # ScoutCoder: the society directory is derived with the CANONICAL rule
+      # (Agent.society_dir_for / Agent#society_dir), never by string
+      # substitution here. An earlier version did
+      # `save_file.sub(/\.chat/, '.society')`: the sub had no anchor, so it
+      # replaced the FIRST '.chat' occurrence and a CLI-shaped save_file like
+      # `cli.chat.files/agent.chat` turned into
+      # `cli.society.files/agent.chat/...`, growing a second `.files` tree
+      # instead of `cli.chat.files/agent.society/...`.
+      # society_dir_for is the single source of truth for the root
+      # (name-derived) rule; society_dir adds the location rule for nested
+      # chats.
+      #
+      # save.rb simply does not auto-save without a save_file; mirror that
+      # here instead of raising on nil (a society conversation started by an
+      # agent with no save_file just never persists).
+      return nil if save_file.nil?
+
+      File.join(society_dir(save_file), agent_name.to_s, conversation.to_s, SOCIETY_CHAT_FILE)
+    end
+
+    # Provider session state and executable Ruby tool objects belong to the
+    # caller. Model/backend defaults may flow to specialists, but capabilities
+    # are inherited only through the specialist start_chat or an explicit
+    # declarative inheritance policy.
+    def social_agent_options(options)
+      defaults = IndiferentHash.setup(social_duplicate(other_options || {}))
+      supplied = IndiferentHash.setup(social_duplicate(options || {}))
+      merged = defaults.merge(supplied)
+      SOCIAL_PRIVATE_OPTIONS.each { |name| merged.delete(name) }
+      merged
+    end
+
+    def social_duplicate(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, item), copy|
+          copy[social_duplicate(key)] = social_duplicate(item)
+        end
+      when Array
+        value.collect { |item| social_duplicate(item) }
+      when String
+        value.dup
+      else
+        value
+      end
+    end
+
+    def social_chat_copy(chat)
+      Chat.setup(social_duplicate(chat || []))
+    end
+
+    def clone_social_agent(template)
+      agent = template.clone
+      agent.start_chat = social_chat_copy(template.start_chat)
+      agent.other_options = IndiferentHash.setup(social_duplicate(template.other_options || {}))
+      agent.society = nil
+      agent.chats = nil
+      agent.instance_variable_set(:@current_chat, nil)
+      agent
+    end
+
+    def start_social_chat(agent_name, options, inherit)
+      template = load_agent(agent_name, options)
+      agent = clone_social_agent(template)
+      initial_chat = social_chat_copy(agent.start_chat)
+      initial_chat.follow(social_inherited_context(inherit))
+      agent.start(initial_chat)
+      agent
+    end
+
+    # In the usual Agent#start branch, start-chat messages are the same Hash
+    # objects in both arrays, which lets us remove the caller agent's policy
+    # exactly even if Agent#ask has removed control roles. The prefix fallback
+    # covers callers that adopted an equivalent, separately parsed Chat.
+    def social_caller_context
+      current = current_chat || []
+      base = start_chat || []
+      base_ids = base.each_with_object({}) { |message, ids| ids[message.object_id] = true }
+
+      context = if current.any? { |message| base_ids[message.object_id] }
+                  current.reject { |message| base_ids[message.object_id] }
+                else
+                  prefix = 0
+                  limit = [current.length, base.length].min
+                  prefix += 1 while prefix < limit && current[prefix] == base[prefix]
+                  current.drop(prefix)
+                end
+
+      social_chat_copy(context)
+    end
+
+    def social_inherited_context(inherit)
+      case inherit
+      when 'none'
+        Chat.setup([])
+      when 'tools'
+        #tooling = social_caller_context.tooling
+        tooling = self.current_chat.tooling
+        social_chat_copy(tooling)
+      when 'conversation'
+        social_caller_context
+      end
+    end
+
+    # Accept the former `chat` argument when a stored tool call is replayed, but
+    # do not advertise it in the schema. New calls keep conversation identity
+    # and inheritance as independent concepts.
+    def social_tool_parameters(parameters)
+      parameters = IndiferentHash.setup((parameters || {}).dup)
+      agent_name = parameters[:agent]
+      prompt = parameters[:prompt]
+      conversation = parameters[:conversation]
+      inherit = parameters[:inherit]
+
+      if parameters.include?(:chat)
+        raise ParameterException, 'Use either conversation or the legacy chat argument, not both' if conversation
+
+        legacy_chat = parameters[:chat]
+        case legacy_chat.to_s
+        when 'current'
+          conversation = 'current'
+          inherit ||= 'conversation'
+        when '', 'none', 'false'
+          conversation = nil
+          inherit ||= 'none'
+        else
+          conversation = legacy_chat
+          inherit ||= 'tools'
+        end
+      end
+
+      inherit ||= 'tools'
+      [agent_name, prompt, conversation, inherit]
+    end
+  end
 end

data/lib/scout/llm/agent/iterate.rb

@@ -25,7 +25,7 @@ module LLM
       list.each &block
     end
 
-    def iterate_dictionary(prompt = nil, &block)
+    def iterate_dictionary(prompt = nil, **kwargs, &block)
       self.endpoint :responses
       self.user prompt if prompt
 
@@ -38,7 +38,7 @@ module LLM
 
       self.option :format, :text
 
-      dict.each &block
+      TSV.traverse dict, **kwargs, &block
     end
   end
 end

data/lib/scout/llm/agent/save.rb

@@ -0,0 +1,273 @@
+require 'set'
+
+module LLM
+  class Agent
+    # Directory holding the saved conversations of every nested specialist
+    # (the "society") reachable from this agent.
+    SOCIETY_DIR = 'society'.freeze
+
+    # File name used for every saved conversation inside the society tree.
+    SOCIETY_CHAT_FILE = 'agent.chat'.freeze
+
+    # Hard recursion cap while saving nested societies. Object cycles are
+    # already cut by the visited sets; the cap is belt and braces against
+    # pathological trees that keep minting fresh agents and paths.
+    SAVE_DEPTH_LIMIT = 32
+
+    # Conservative fallback for society key parts that do not match the
+    # socialization name patterns. No dots, so '.'/'..' can never survive.
+    SAVE_SANITIZER = /[^a-zA-Z0-9_-]/
+
+    # Chat file this agent appends to / auto-saves to. Setting it makes `save`
+    # work with no arguments and makes every successful chat round auto-save
+    # this agent's full state (chat + nested society) there.
+    attr_accessor :save_file
+
+    class << self
+      # Society directory of a ROOT chat saved at `chat_path`:
+      # `.../<name>.society` for a chat file `.../<name>.chat`
+      # (`agent.chat` -> `agent.society`; `worker.chat` -> `worker.society`).
+      #
+      # ScoutCoder: this is the NAME-DERIVED rule, used at depth 0 only. A
+      # path that does not end in `.chat` is normalized by dropping its last
+      # component (defensive: `society_dir_for(dir)` still yields a directory
+      # sibling, never `<dir>.files/...`); both Path and String inputs are
+      # accepted and the result is always a plain String.
+      #
+      # This is the ROOT rule only. The general rule (Agent#society_dir) is
+      # decided from the location of the chat being written, so a nested
+      # agent.chat never grows a second `.files` tree of its own:
+      #
+      #   chat.chat
+      #   chat.chat.society/<agent>/<conversation>/agent.chat
+      #   chat.chat.society/<agent>/<conversation>/society/<agent>/<conversation>/agent.chat
+      def society_dir_for(chat_path)
+        p = chat_path.to_s
+        p = File.dirname(p) unless p =~ /\.chat\z/
+        File.join(File.dirname(p), File.basename(p).sub(/\.chat\z/, '.society'))
+      end
+
+      # ScoutCoder: LEGACY root society directory (`<path>.files/log/society`)
+      # from before the flat layout change. Kept read-only: nothing writes
+      # here anymore, but provenance traversal must still glob it so chats
+      # saved by older versions remain visible (see
+      # Chat.direct_chat_sidecar_files).
+      def legacy_society_dir_for(chat_path)
+        "#{chat_path}.files/log/#{SOCIETY_DIR}"
+      end
+
+      # Is `path` the chat file of a NESTED conversation, i.e. does it already
+      # live inside a society tree? A nested chat file sits at
+      # <society>/<agent>/<conversation>/<file>, so the directory three levels
+      # up from the file is the society directory itself.
+      # (Two levels up would be <agent>, one level up <conversation>.)
+      #
+      # The society directory of a depth-0 chat is named after it
+      # (<name>.society), while every deeper level keeps the plain 'society'
+      # sibling dir, so BOTH basenames count here.
+      def nested_save?(path)
+        parent = File.basename(File.dirname(File.dirname(File.dirname(path.to_s))))
+        parent == SOCIETY_DIR || parent.end_with?('.' + SOCIETY_DIR)
+      end
+    end
+
+    def society_dir_for(chat_path)
+      self.class.society_dir_for(chat_path)
+    end
+
+    # Society directory for the chat written at `path`, whatever the entry
+    # point was (root save, recursion, or a later standalone auto-save of a
+    # child that had its save_file assigned by a parent):
+    #
+    # - root chat (`.../conversation.chat`):        sibling `<name>.society`
+    # - nested chat (`.../society/<a>/<c>/<file>`): sibling `<dirname>/society`
+    #
+    # Deciding by LOCATION (not by recursion depth) is what keeps the layout
+    # canonical: a nested agent.chat never produces `<nested>.files/...`, no
+    # matter who triggered the save.
+    def society_dir(path)
+      if self.class.nested_save?(path)
+        File.join(File.dirname(path), SOCIETY_DIR)
+      else
+        self.class.society_dir_for(path)
+      end
+    end
+
+    def nested_save?(path)
+      self.class.nested_save?(path)
+    end
+
+    # Save the current conversation of this agent and of every nested
+    # specialist conversation (`chats`) reachable from it.
+    #
+    # `path` defaults to the configured `save_file`; when both are nil a
+    # ScoutException is raised explaining how to configure the target.
+    #
+    # Serialization: the FULL current_chat is written, not the delta against
+    # start_chat. These files are recovery/restart artifacts, so the saved
+    # conversation must be complete. AgentWorkflow#chat_task keeps its own
+    # delta semantics (result = current_chat - start_chat) for job results.
+    #
+    # Layout: this agent's chat is written at `path`; each society entry is
+    # written at `<society_dir(path)>/<agent_name>/<conversation>/agent.chat`,
+    # where society_dir is computed from the LOCATION of `path` (see
+    # Agent#society_dir), so nested societies always sit next to their
+    # agent.chat and the tree nests one level deeper each time.
+    #
+    # Children are saved by recursing into `child.save(child_path, ...)`, and
+    # each child's `save_file` is assigned so a later independent ask by that
+    # child auto-saves to exactly the same place.
+    #
+    # Cycle safety: `visited` (resolved target paths) and `seen_agents`
+    # (agent objects) are threaded through the recursion; a target path or an
+    # agent already saved by this run is skipped with a debug log, and
+    # SAVE_DEPTH_LIMIT stops (with a warning, not an exception) anything that
+    # still runs away.
+    #
+    # Lazy: nothing is created eagerly. Open.sensible_write makes parent
+    # directories on demand, so an agent with no live society writes ONLY its
+    # chat file and no `.files` tree appears.
+    #
+    # Returns the sorted Array of absolute paths whose content is now on disk
+    # and current, whether this call just wrote them or found them already up
+    # to date (an unchanged file is not rewritten but IS reported, because the
+    # useful contract is "these files now hold this state").
+    def save(path = nil, visited: nil, seen_agents: nil, depth: 0)
+      path ||= save_file
+      raise ScoutException,
+            "No save file for agent. Pass a path or configure agent.save_file = <chat file>" if path.nil?
+
+      path = path.to_s
+      visited ||= Set.new
+      seen_agents ||= Set.new
+      resolved = File.expand_path(path)
+
+      if depth > SAVE_DEPTH_LIMIT
+        Log.warn "Agent save deeper than #{SAVE_DEPTH_LIMIT} levels under #{resolved}; stopping recursion"
+        return []
+      end
+
+      if visited.include?(resolved)
+        Log.debug "Agent save: conversation already saved at #{resolved}"
+        return []
+      end
+      if seen_agents.include?(self)
+        Log.debug "Agent save: agent already saved in this run, skipping #{resolved}"
+        return []
+      end
+
+      # current_chat is normally never nil (it lazily builds from start_chat),
+      # but be explicit: an agent asked to save before any conversation exists
+      # saves its (possibly empty) start-based chat rather than crashing.
+      chat = current_chat || start
+      content = chat.print
+
+      # Recovery artifact: always complete, so refresh it when it changed
+      # (Open.sensible_write alone would keep the first version forever).
+      if Open.exist?(path) && Open.read(path) == content
+        Log.debug "Agent save: #{resolved} is up to date"
+      else
+        Open.sensible_write(path, content, force: true)
+      end
+
+      visited << resolved
+      seen_agents << self
+      written = []
+
+      # Report only files that verifiably hold the expected content.
+      written << resolved if Open.exist?(path)
+      save_society(path, visited, seen_agents, depth, written)
+
+      written.sort
+    end
+
+    # Auto-save after a turn that changed this agent's conversation. Only
+    # fires on agents with a configured save_file and is never fatal (a save
+    # failure is logged and the agent run continues). It is a full recursive
+    # save, so the tree stays complete after any turn anywhere in it.
+    def save_if_configured
+      return if save_file.nil?
+      save
+    end
+
+    # Snapshot the conversation as it stood before a restart, so a restarted
+    # conversation can still be recovered. Writes only when there is a prior,
+    # non-empty current_chat (lazy: no empty resets), and never lets a save
+    # problem break the restart. Timestamp collisions (two restarts within
+    # the same millisecond) get a _1, _2, ... suffix instead of clobbering.
+    def save_restart_snapshot
+      return if save_file.nil?
+      prior = @current_chat
+      return unless Chat === prior && prior.any?
+
+      dir = File.join("#{save_file}.files", 'resets')
+      # Colons are legal on unix but hostile to portability and tooling
+      base = Chat.timestamp.gsub(':', '')
+      file = File.join(dir, "#{base}.chat")
+      suffix = 0
+      while Open.exist?(file)
+        suffix += 1
+        file = File.join(dir, "#{base}_#{suffix}.chat")
+      end
+      Open.sensible_write(file, prior.print)
+      nil
+    end
+
+    private
+
+    # Save every live nested conversation of this agent under its society
+    # directory. Non-Agent values are ignored; keys are expected to look like
+    # `agent_name/conversation` but are sanitized defensively so a malformed
+    # key can never escape the society directory.
+    def save_society(path, visited, seen_agents, depth, written)
+      chats = @chats
+      return unless Hash === chats && chats.any?
+
+      society_dir = society_dir(path)
+
+      # Keys are normally Strings but nothing forbids Symbols (or mixed
+      # hashes); coerce to String so the sort can never raise a TypeError.
+      chats.sort_by { |key, _agent| key.to_s }.each do |key, agent|
+        next unless LLM::Agent === agent
+
+        agent_name, conversation = save_split_social_key(key)
+        next if agent_name.nil? || conversation.nil?
+
+        child_path = File.join(society_dir, agent_name, conversation, SOCIETY_CHAT_FILE)
+        next if Open.exists?(child_path) && Path.newer?(child_path, save_file)
+        # The child remembers its own file so a later independent ask by that
+        # child auto-saves in place instead of needing the parent save.
+        agent.save_file = child_path
+        written.concat(agent.save(child_path, visited: visited,
+                                               seen_agents: seen_agents,
+                                               depth: depth + 1))
+      end
+    end
+
+    # Split an `agent_name/conversation` society key into its sanitized parts.
+    # Both parts must be non-empty; names matching the socialization regexes
+    # are kept verbatim, anything else falls back to a conservative sanitizer
+    # (path-traversal characters replaced by '_').
+    def save_split_social_key(key)
+      key = key.to_s
+      return [nil, nil] unless key.include?('/')
+
+      raw_agent, raw_conversation = key.split('/', 2)
+      return [nil, nil] if raw_agent.to_s.empty? || raw_conversation.to_s.empty?
+
+      [
+        save_sanitize_part(raw_agent, SOCIAL_AGENT_NAME),
+        save_sanitize_part(raw_conversation, SOCIAL_CONVERSATION_NAME)
+      ]
+    end
+
+    def save_sanitize_part(part, pattern)
+      part = part.to_s
+      return part if !part.empty? && !part.include?('/') &&
+                     part != '.' && part != '..' && pattern.match?(part)
+
+      sanitized = part.gsub(SAVE_SANITIZER, '_')
+      sanitized.empty? ? '_' : sanitized
+    end
+  end
+end