little_ghost 0.1.0

data/lib/little_ghost/session_stores/memory.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Ready-to-use persistence implementations for LittleGhost conversations.
+  module SessionStores
+    # Memory keeps conversations available for the life of one Ruby process. It
+    # is the default store and needs no application setup.
+    #
+    # Data disappears when the process exits. Supplying an actor ID binds the
+    # session key to that actor; a later mismatch raises an error.
+    class Memory < SessionStore
+      # Starts with no saved conversations.
+      def initialize
+        super
+        @records = {}
+        @records_mutex = Mutex.new
+      end
+
+      # Loads the snapshot for +id+, returning +nil+ before the first checkpoint.
+      # A supplied +actor_id+ claims a new ID and must match on later access.
+      def load(id, actor_id: nil)
+        @records_mutex.synchronize do
+          key = id.to_s
+          record = @records[key]
+          validate_actor!(record, actor_id)
+          @records[key] = {actor_id: actor_id.to_s, snapshot: nil} if !record && actor_id
+          record&.fetch(:snapshot)
+        end
+      end
+
+      # Appends sanitized +messages+ when +expected_count+ still matches the
+      # stored conversation, then returns the updated snapshot.
+      def append(id, messages:, state:, metadata:, expected_count:, actor_id: nil)
+        messages = persistable_messages(messages)
+        @records_mutex.synchronize do
+          key = id.to_s
+          record = @records[key]
+          validate_actor!(record, actor_id)
+          current = record&.fetch(:snapshot) || empty_snapshot
+          unless current.fetch(:messages).length == expected_count
+            raise ProtocolError, "Session changed while it was being updated"
+          end
+
+          @records[key] = {
+            actor_id: actor_id&.to_s,
+            snapshot: {
+              messages: [*current.fetch(:messages), *messages].freeze,
+              state:,
+              metadata:
+            }.freeze
+          }.freeze
+          @records[key].fetch(:snapshot)
+        end
+      end
+
+      # Replaces the complete in-memory snapshot with sanitized +messages+.
+      def replace(id, messages:, state:, metadata:, actor_id: nil)
+        messages = persistable_messages(messages)
+        @records_mutex.synchronize do
+          key = id.to_s
+          validate_actor!(@records[key], actor_id)
+          @records[key] = {
+            actor_id: actor_id&.to_s,
+            snapshot: {messages:, state:, metadata:}.freeze
+          }.freeze
+          @records[key].fetch(:snapshot)
+        end
+      end
+
+      private
+
+      def empty_snapshot
+        {messages: [].freeze, state: {}.freeze, metadata: {}.freeze}.freeze
+      end
+
+      def validate_actor!(record, actor_id)
+        actor = actor_id&.to_s
+        return unless record
+        return if record[:actor_id].nil? && actor.nil?
+        return if record[:actor_id] == actor
+
+        raise Error, "Session actor does not match"
+      end
+    end
+  end
+end

data/lib/little_ghost/skills/catalog.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "erb"
+require "pathname"
+
+module LittleGhost
+  module Skills
+    # A Catalog lets an agent discover focused instructions without putting every
+    # skill in its prompt. The model sees short descriptions first and can load a
+    # skill's full instructions when the task calls for them.
+    #
+    #   catalog = LittleGhost::Skills::Catalog.new(paths: ["app/skills"])
+    #   catalog.names # => ["refund_policy", "search_orders"]
+    #   catalog.discovery_prompt.include?("refund_policy") # => true
+    #   catalog.tool # a LittleGhost::Tool that loads full instructions on demand
+    #
+    # Each immediate child directory may contain one +SKILL.md+ with YAML front
+    # matter. Symbolic-link escapes, unsafe names, oversized files, and invalid
+    # YAML are rejected or skipped before instructions reach a model. Optional
+    # resource listings are limited by count and depth.
+    #
+    # === Security and trust
+    #
+    # Configured roots and their contents are fully trusted instruction sources.
+    # The +allowed-tools+ field is metadata shown to the model, not an
+    # authorization boundary. Applications must enforce tool access separately
+    # and keep skill roots non-user-writable.
+    class Catalog
+      include Enumerable
+
+      class InvalidSkillError < ConfigurationError; end # :nodoc:
+      private_constant :InvalidSkillError
+
+      DEFAULT_MAX_SKILLS = 1_000 # :nodoc:
+      DEFAULT_MAX_FILE_BYTES = 1_000_000 # :nodoc:
+      DEFAULT_MAX_RESOURCE_FILES = 20 # :nodoc:
+      MAX_RESOURCE_DEPTH = 3 # :nodoc:
+      RESOURCE_DIRECTORIES = %w[scripts references assets].freeze # :nodoc:
+      SAFE_NAME_PATTERN = /\A[a-zA-Z0-9_-]+\z/ # :nodoc:
+
+      # Loads valid skills immediately using the supplied safety limits.
+      def initialize(
+        paths:,
+        max_skills: DEFAULT_MAX_SKILLS,
+        max_file_bytes: DEFAULT_MAX_FILE_BYTES,
+        max_resource_files: DEFAULT_MAX_RESOURCE_FILES,
+        only: nil,
+        resource_root: nil
+      )
+        @paths = PathSet.new(paths)
+        @max_skills = positive_integer(max_skills, :max_skills)
+        @max_file_bytes = positive_integer(max_file_bytes, :max_file_bytes)
+        @max_resource_files = positive_integer(max_resource_files, :max_resource_files)
+        @only = Array(only).map(&:to_s).freeze if only
+        @resource_root = canonical_resource_root(resource_root)
+        @skills = load_skills
+      end
+
+      # Yields each Skill in lookup order.
+      def each(&block)
+        @skills.each_value(&block)
+      end
+
+      # Finds the named Skill or raises ConfigurationError.
+      def fetch(name)
+        @skills.fetch(name.to_s) { raise ConfigurationError, "Unknown skill: #{name}" }
+      end
+
+      # Lists immutable skill names in lookup order.
+      def names
+        @skills.keys.freeze
+      end
+
+      # Produces the escaped, metadata-only prompt used for discovery.
+      def discovery_prompt
+        return "" if @skills.empty?
+
+        lines = ["<available_skills>"]
+        @skills.each_value do |skill|
+          lines.concat([
+            "<skill>",
+            "<name>#{ERB::Util.html_escape(skill.name)}</name>",
+            "<description>#{ERB::Util.html_escape(skill.description)}</description>",
+            "<location>#{ERB::Util.html_escape(skill.path)}</location>",
+            "</skill>"
+          ])
+        end
+        lines << "</available_skills>"
+        lines.join("\n")
+      end
+
+      # Exposes full instructions on demand through a +skills+ Tool.
+      def tool
+        catalog = self
+        Tool.define(
+          name: "skills",
+          description: <<~DESCRIPTION.strip,
+            Activate a skill to load its full instructions.
+
+            Use this tool to load the complete instructions for a skill listed in
+            the available_skills section of your system prompt.
+          DESCRIPTION
+          input_schema: {
+            type: "object",
+            properties: {skill_name: {type: "string", description: "Name of the skill to activate."}},
+            required: ["skill_name"],
+            additionalProperties: false
+          }
+        ) do |input|
+          catalog.format(catalog.fetch(input.fetch("skill_name")))
+        rescue ConfigurationError => error
+          raise ToolError, error.message
+        end
+      end
+
+      # Formats one Skill, including allowed tools, compatibility, and bounded
+      # resource paths.
+      def format(skill)
+        parts = [skill.instructions]
+        metadata = []
+        metadata << "Allowed tools: #{skill.allowed_tools.join(", ")}" unless skill.allowed_tools.empty?
+        metadata << "Compatibility: #{skill.compatibility}" if skill.compatibility
+        metadata << "Location: #{skill.path}"
+        parts << "\n---\n#{metadata.join("\n")}" unless metadata.empty?
+        resources = skill_resources(skill)
+        unless resources.empty?
+          parts << "\nAvailable resources:\n#{resources.map { |path| "  #{path}" }.join("\n")}"
+        end
+        parts.join("\n")
+      end
+
+      private
+
+      def load_skills
+        missing_root = @paths.find { |root| !Dir.exist?(root.path) && !root.boundary }
+        raise Errno::ENOENT, missing_root.path if missing_root
+        @paths.each do |root|
+          next unless Dir.exist?(root.path)
+
+          real_root = File.realpath(root.path)
+          next if boundary_allows?(real_root, root.boundary)
+
+          raise ConfigurationError, "Skill root escapes its configured boundary: #{root.path}"
+        end
+
+        paths = @paths.flat_map do |root|
+          next [] unless Dir.exist?(root.path)
+
+          Dir.glob(File.join(root.path, "*", "SKILL.md")).sort
+        end
+        raise ConfigurationError, "Skill catalog exceeds #{@max_skills} skills" if paths.length > @max_skills
+
+        paths.each_with_object({}) do |path, loaded|
+          skill = begin
+            parse(path)
+          rescue InvalidSkillError, SystemCallError
+            next
+          end
+          next if @only && !@only.include?(skill.name)
+
+          loaded[skill.name] = skill
+        end.freeze
+      end
+
+      def parse(path)
+        real_path = File.realpath(path)
+        root = @paths.find do |candidate|
+          next false unless Dir.exist?(candidate.path)
+
+          real_root = File.realpath(candidate.path)
+          inside_root?(real_path, real_root) && boundary_allows?(real_root, candidate.boundary)
+        end
+        raise ConfigurationError, "Skill path escapes its configured root: #{path}" unless root
+        root_path = File.realpath(root.path)
+        raise ConfigurationError, "Skill exceeds #{@max_file_bytes} bytes: #{path}" if File.size(real_path) > @max_file_bytes
+
+        text = File.read(real_path, encoding: "UTF-8")
+        raise InvalidSkillError, "Skill is not valid UTF-8: #{path}" unless text.valid_encoding?
+
+        match = text.match(/\A---\s*\n(.*?)\n---\s*\n(.*)\z/m)
+        raise InvalidSkillError, "Skill must have YAML front matter: #{path}" unless match
+
+        metadata = YAML.safe_load(match[1], permitted_classes: [], aliases: false) || {}
+        raise InvalidSkillError, "Skill front matter must be a mapping: #{path}" unless metadata.is_a?(Hash)
+
+        name = metadata["name"].to_s.strip
+        description = metadata["description"].to_s.strip
+        raise InvalidSkillError, "Skill name is required: #{path}" if name.empty?
+        raise InvalidSkillError, "Skill description is required: #{path}" if description.empty?
+        raise InvalidSkillError, "Skill name contains unsafe characters: #{path}" unless SAFE_NAME_PATTERN.match?(name)
+        raise InvalidSkillError, "Skill description must be one line: #{path}" if description.match?(/[\r\n]/)
+
+        allowed_tools = metadata["allowed-tools"] || metadata["allowed_tools"]
+        allowed_tools = allowed_tools.split if allowed_tools.is_a?(String)
+        allowed_tools = Array(allowed_tools).map(&:to_s).freeze
+        compatibility = metadata["compatibility"]&.to_s
+        Skill.new(
+          name:, description:, instructions: match[2].strip,
+          path: agent_path(real_path, root_path), source_path: real_path,
+          allowed_tools:, compatibility:
+        )
+      rescue Psych::Exception => error
+        raise InvalidSkillError, "Invalid skill front matter in #{path}: #{error.message}"
+      end
+
+      def inside_root?(path, root)
+        path == root || path.start_with?("#{root}#{File::SEPARATOR}")
+      end
+
+      def boundary_allows?(path, boundary)
+        return true unless boundary
+
+        boundary = File.realpath(boundary)
+        inside_root?(path, boundary)
+      end
+
+      def skill_resources(skill)
+        directory = File.dirname(skill.source_path)
+        files = RESOURCE_DIRECTORIES.flat_map do |name|
+          root = File.join(directory, name)
+          next [] unless File.directory?(root) && !File.symlink?(root)
+
+          resource_files(root, prefix: name)
+        end.sort
+        files.map! { |path| resource_path(skill, path) } if @resource_root
+        return files if files.length <= @max_resource_files
+
+        [*files.first(@max_resource_files), "... (truncated at #{@max_resource_files} files)"]
+      end
+
+      def resource_files(directory, prefix:, depth: 0)
+        return [] if depth >= MAX_RESOURCE_DEPTH
+
+        Dir.children(directory).sort.flat_map do |name|
+          path = File.join(directory, name)
+          relative = "#{prefix}/#{name}"
+          stat = File.lstat(path)
+          if stat.directory? && !stat.symlink?
+            resource_files(path, prefix: relative, depth: depth + 1)
+          elsif stat.file?
+            [relative]
+          else
+            []
+          end
+        rescue Errno::ENOENT, Errno::EACCES
+          []
+        end
+      rescue Errno::ENOENT, Errno::EACCES
+        []
+      end
+
+      def positive_integer(value, name)
+        integer = Integer(value)
+        raise ArgumentError, "#{name} must be positive" unless integer.positive?
+
+        integer
+      end
+
+      def canonical_resource_root(value)
+        return unless value
+
+        path = value.to_s
+        if path.include?("\0") || !Pathname.new(path).absolute? || path.split(File::SEPARATOR).include?("..")
+          raise ArgumentError, "resource_root must be an absolute path"
+        end
+
+        File.expand_path(path).freeze
+      end
+
+      def agent_path(source_path, source_root)
+        return source_path unless @resource_root
+
+        relative = source_path.delete_prefix("#{source_root}#{File::SEPARATOR}")
+        File.join(@resource_root, relative)
+      end
+
+      def resource_path(skill, relative)
+        File.join(File.dirname(skill.path), relative)
+      end
+    end
+  end
+end

data/lib/little_ghost/skills/skill.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Skills give agents focused instructions and supporting resources on demand.
+  module Skills
+    # Skill holds the metadata and instructions loaded from one +SKILL.md+ file.
+    # +path+ is shown to the model; +source_path+ is the local file used for
+    # boundary validation and resource discovery.
+    Skill = Data.define( # :nodoc:
+      :name,
+      :description,
+      :instructions,
+      :path,
+      :source_path,
+      :allowed_tools,
+      :compatibility
+    )
+
+    # Holds the metadata and instructions loaded from one +SKILL.md+ file.
+    # +path+ is shown to the model; +source_path+ is the local file used for
+    # boundary validation and resource discovery.
+    class Skill < Data # :doc:
+      ##
+      # :singleton-method: new
+      # :call-seq:
+      #   new(name:, description:, instructions:, path:, source_path:,
+      #       allowed_tools:, compatibility:) -> Skill
+      #
+      # Collects one validated skill definition loaded by Skills::Catalog.
+
+      ##
+      # :attr_reader: name
+      # The skill name declared in front matter.
+
+      ##
+      # :attr_reader: description
+      # The short description used for model-visible discovery.
+
+      ##
+      # :attr_reader: instructions
+      # The complete instructions loaded on activation.
+
+      ##
+      # :attr_reader: path
+      # The model-visible skill path.
+
+      ##
+      # :attr_reader: source_path
+      # The trusted local source path used for boundary checks.
+
+      ##
+      # :attr_reader: allowed_tools
+      # Informational tool names from front matter; this is not authorization.
+
+      ##
+      # :attr_reader: compatibility
+      # Optional compatibility guidance from front matter.
+    end
+  end
+end

data/lib/little_ghost/skills.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "skills/skill"
+require_relative "skills/catalog"

data/lib/little_ghost/stream_event.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # StreamEvent gives every provider and interface the same language for live
+  # agent output. Consumers can handle text, reasoning, tools, usage, retries,
+  # and completion without branching on a provider SDK.
+  #
+  # Providers emit events such as +:message_start+, +:text_delta+,
+  # +:reasoning_delta+, +:tool_call_start+, +:tool_call_delta+,
+  # +:tool_call_stop+, +:usage+, +:model_retry+, and +:message_stop+. The
+  # terminal event carries a {ModelResponse}[rdoc-ref:LittleGhost::ModelResponse]
+  # in +data[:response]+.
+  StreamEvent = Data.define(:type, :data) do # :nodoc:
+    # Creates an immutable event with a symbol +type+ and keyword payload.
+    def self.build(type, **data)
+      new(type: type.to_sym, data: data.freeze)
+    end
+  end
+
+  # StreamEvent gives every provider and interface the same language for live
+  # agent output. Consumers can handle text, reasoning, tools, usage, retries,
+  # and completion without branching on a provider SDK.
+  #
+  # Providers emit events such as +:message_start+, +:text_delta+,
+  # +:reasoning_delta+, +:tool_call_start+, +:tool_call_delta+,
+  # +:tool_call_stop+, +:usage+, +:model_retry+, and +:message_stop+. The
+  # terminal event carries a {ModelResponse}[rdoc-ref:LittleGhost::ModelResponse]
+  # in +data[:response]+.
+  #
+  #   event = LittleGhost::StreamEvent.build(:text_delta, text: "Hello")
+  #   event.type        # => :text_delta
+  #   event.data[:text] # => "Hello"
+  class StreamEvent < Data # :doc:
+    ##
+    # :attr_reader: type
+    # The event kind, such as +:text_delta+, +:usage+, or +:message_stop+.
+
+    ##
+    # :attr_reader: data
+    # The immutable payload for this event kind.
+
+    ##
+    # :singleton-method: build
+    # :call-seq:
+    #   build(type, **data) -> StreamEvent
+    #
+    # Creates an immutable event with a symbol +type+ and keyword payload.
+  end
+end

data/lib/little_ghost/structured_output.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module StructuredOutput # :nodoc: all
+    STRATEGIES = %i[auto provider tool].freeze
+
+    class Strategy
+      attr_reader :configuration
+
+      def initialize(configuration)
+        @configuration = configuration
+      end
+
+      def schema_name = configuration.fetch(:name)
+      def provider? = false
+      def tool? = false
+      def tools(ordinary_tools) = ordinary_tools
+      def output_schema = nil
+      def tool_choice(repair:) = nil
+      def required_capabilities = [].freeze
+    end
+
+    class ProviderStrategy < Strategy
+      def provider? = true
+      def output_schema = configuration
+      def required_capabilities = [:native_structured_output].freeze
+    end
+
+    class ToolStrategy < Strategy
+      def tool? = true
+
+      def tools(ordinary_tools)
+        [*ordinary_tools, result_tool].freeze
+      end
+
+      def tool_choice(repair:)
+        repair ? {name: schema_name}.freeze : :required
+      end
+
+      def required_capabilities = %i[tools tool_choice].freeze
+
+      def result_tool
+        {
+          name: schema_name,
+          description: configuration[:description] ||
+            "Submit the final structured result. Call this tool only as the final action.",
+          input_schema: configuration.fetch(:schema),
+          strict: true
+        }.freeze
+      end
+    end
+
+    module_function
+
+    def resolve(configuration, model:, ordinary_tools:)
+      return unless configuration
+
+      requested = configuration.fetch(:strategy, :auto).to_sym
+      capabilities = if model.respond_to?(:capabilities)
+        model.capabilities
+      else
+        ModelCapabilities.legacy
+      end
+      strategy = case requested
+      when :auto then automatic_strategy(model, capabilities, ordinary_tools)
+      when :provider
+        validate_explicit_provider!(model, capabilities)
+        ProviderStrategy
+      when :tool
+        validate_explicit_tool!(model, capabilities)
+        ToolStrategy
+      else
+        raise ConfigurationError, "Unknown structured output strategy: #{requested}"
+      end
+      resolved = strategy.new(configuration)
+      validate_tool_collision!(resolved, ordinary_tools)
+      resolved
+    end
+
+    def validate_tool_collision!(strategy, ordinary_tools)
+      return unless strategy.tool?
+      return unless ordinary_tools.any? { |tool| tool.fetch(:name).to_s == strategy.schema_name }
+
+      raise ConfigurationError, "Structured result tool name collides with an agent tool: #{strategy.schema_name}"
+    end
+
+    def automatic_strategy(model, capabilities, ordinary_tools)
+      unless capabilities.known?
+        raise ConfigurationError,
+          "Structured output capabilities are unavailable for #{model_identity(model)}; " \
+          "provide model capability metadata or select a strategy explicitly"
+      end
+      if capabilities.native_structured_output? && (ordinary_tools.empty? || capabilities.tools?)
+        return ProviderStrategy
+      end
+      return ToolStrategy if capabilities.tools? && capabilities.tool_choice?
+
+      raise ConfigurationError,
+        "#{model_identity(model)} supports neither provider-native structured output nor reliable tool-based output"
+    end
+    private_class_method :automatic_strategy
+
+    def validate_explicit_provider!(model, capabilities)
+      return unless capabilities.known?
+      return if capabilities.native_structured_output?
+
+      raise ConfigurationError, "#{model_identity(model)} does not support provider-native structured output"
+    end
+    private_class_method :validate_explicit_provider!
+
+    def validate_explicit_tool!(model, capabilities)
+      return unless capabilities.known?
+      return if capabilities.tools? && capabilities.tool_choice?
+
+      raise ConfigurationError, "#{model_identity(model)} does not support reliable tool-based structured output"
+    end
+    private_class_method :validate_explicit_tool!
+
+    def model_identity(model)
+      provider = model.respond_to?(:provider_name) ? model.provider_name : model.class.name
+      id = model.respond_to?(:id) ? model.id : nil
+      [provider, id].compact.join("/")
+    end
+    private_class_method :model_identity
+  end
+end

data/lib/little_ghost/subagents/agent_path.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module Subagents
+    # AgentPath gives every delegated conversation a stable place beneath its
+    # parent. Paths begin at +/root+, keeping nested delegation visible in logs
+    # and metadata.
+    #
+    # Child task names contain only lowercase letters,
+    # digits, and underscores, are limited to 40 characters, and must be unique
+    # among siblings when reserved by a manager.
+    #
+    #   AgentPath.join("/root", "review_api") # => "/root/review_api"
+    class AgentPath
+      ROOT = "/root" # :nodoc:
+      MAX_NAME_LENGTH = 40 # :nodoc:
+      MAX_PATH_LENGTH = 1024 # :nodoc:
+      NAME_PATTERN = /\A[a-z0-9_]+\z/ # :nodoc:
+
+      class << self
+        # Validates an absolute agent path and returns it unchanged.
+        def validate!(path)
+          value = String(path)
+          raise ArgumentError, "agent path must start with /root" unless value == ROOT || value.start_with?("#{ROOT}/")
+          raise ArgumentError, "agent path must not end with /" if value.end_with?("/")
+          raise ArgumentError, "agent path is too long" if value.length > MAX_PATH_LENGTH
+
+          segments = value.split("/").drop(2)
+          raise ArgumentError, "agent path must not contain empty segments" if segments.any?(&:empty?)
+
+          segments.each { |segment| validate_name!(segment) }
+          value
+        end
+
+        # Validates both parts and returns a direct child path.
+        def join(parent, name)
+          validate!("#{validate!(parent)}/#{validate_name!(name)}")
+        end
+
+        # Validates and returns one model-chosen task name.
+        def validate_name!(name)
+          value = String(name)
+          if value.length > MAX_NAME_LENGTH
+            raise ArgumentError, "task_name must be at most #{MAX_NAME_LENGTH} characters"
+          end
+          if value == "root" || !value.match?(NAME_PATTERN)
+            raise ArgumentError, "task_name must use lowercase letters, digits, and underscores"
+          end
+
+          value
+        end
+
+        # Checks whether +path+ is exactly one level beneath +parent+.
+        def immediate_child?(path, parent)
+          value = validate!(path)
+          ancestor = validate!(parent)
+          value.start_with?("#{ancestor}/") &&
+            !value.delete_prefix("#{ancestor}/").include?("/")
+        end
+      end
+    end
+  end
+end