little_ghost 0.1.0

data/lib/little_ghost/ag_ui/adapter.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module LittleGhost
+  # AG-UI connects LittleGhost streams to user interfaces that speak the AG-UI
+  # protocol. Require +little_ghost/ag_ui+ to load this optional integration.
+  module AGUI
+    # Adapter turns a LittleGhost stream into AG-UI event hashes. It lets a Ruby
+    # agent drive compatible chat interfaces without changing the agent itself.
+    #
+    #   events = CustomerSupportAgent.new.stream_ask("Where is my order?")
+    #   adapter = LittleGhost::AGUI::Adapter.new
+    #   adapter.stream(events, thread_id: "thread-1", run_id: "run-1").each do |event|
+    #     websocket.write(JSON.generate(event))
+    #   end
+    #
+    # The adapter has no state between #stream calls, so one instance can
+    # translate independent runs.
+    #
+    # === Security and trust
+    #
+    # Provider plaintext reasoning becomes AG-UI reasoning events. Tool
+    # arguments and results, invocation metadata, subagent events, trace context,
+    # and selected error text also pass through without redaction. Authorize and
+    # filter the complete stream before transport, and send it only to an
+    # interface trusted to display that data. Encrypted reasoning and provider
+    # continuity artifacts are never exposed here.
+    class Adapter
+      TERMINAL_EVENTS = %i[run_partial run_cancel run_stop run_error].freeze # :nodoc:
+
+      # Lazily translates +events+ for one AG-UI run.
+      def stream(events, thread_id:, run_id:)
+        Enumerator.new do |output|
+          message_id = nil
+          message_started = false
+          reasoning_id = nil
+          reasoning_message_id = nil
+          tool_call_ids = {}
+
+          events.each do |source|
+            superseded_message_id = message_id if source.type == :model_retry && message_started
+            if reasoning_id && source.type != :reasoning_delta
+              output << event("REASONING_MESSAGE_END", messageId: reasoning_message_id)
+              output << event("REASONING_END", messageId: reasoning_id)
+              reasoning_id = nil
+              reasoning_message_id = nil
+            end
+            if message_started && (TERMINAL_EVENTS.include?(source.type) || source.type == :model_retry)
+              output << event("TEXT_MESSAGE_END", messageId: message_id)
+              message_id = nil
+              message_started = false
+            end
+            if message_started && source.type == :message_start
+              output << event("TEXT_MESSAGE_END", messageId: message_id)
+              message_id = nil
+              message_started = false
+            end
+
+            case source.type
+            when :run_start
+              output << event("RUN_STARTED", threadId: thread_id, runId: run_id)
+            when :message_start
+              message_id = SecureRandom.uuid
+            when :reasoning_delta
+              if message_started
+                output << event("TEXT_MESSAGE_END", messageId: message_id)
+                message_id = nil
+                message_started = false
+              end
+              unless reasoning_id
+                reasoning_id = SecureRandom.uuid
+                reasoning_message_id = SecureRandom.uuid
+                output << event("REASONING_START", messageId: reasoning_id)
+                output << event(
+                  "REASONING_MESSAGE_START",
+                  messageId: reasoning_message_id,
+                  role: "reasoning"
+                )
+              end
+              output << event(
+                "REASONING_MESSAGE_CONTENT",
+                messageId: reasoning_message_id,
+                delta: source.data.fetch(:text)
+              )
+            when :text_delta
+              message_id ||= SecureRandom.uuid
+              unless message_started
+                output << event("TEXT_MESSAGE_START", messageId: message_id, role: "assistant")
+                message_started = true
+              end
+              output << event("TEXT_MESSAGE_CONTENT", messageId: message_id, delta: source.data.fetch(:text))
+            when :message_stop
+              if message_started
+                output << event("TEXT_MESSAGE_END", messageId: message_id)
+              end
+              message_id = nil
+              message_started = false
+            when :tool_call_start
+              tool_call_ids[source.data.fetch(:index)] = source.data.fetch(:id)
+              output << event(
+                "TOOL_CALL_START",
+                toolCallId: source.data.fetch(:id),
+                toolCallName: source.data.fetch(:name),
+                parentMessageId: (message_id if message_started)
+              )
+            when :tool_call_delta
+              output << event(
+                "TOOL_CALL_ARGS",
+                toolCallId: tool_call_ids.fetch(source.data.fetch(:index), source.data.fetch(:index).to_s),
+                delta: source.data.fetch(:arguments)
+              )
+            when :tool_call_stop
+              output << event("TOOL_CALL_END", toolCallId: source.data.fetch(:tool_use).id)
+            when :tool_stop
+              tool_use = source.data.fetch(:tool_use)
+              result = source.data.fetch(:result)
+              output << event(
+                "TOOL_CALL_RESULT",
+                messageId: SecureRandom.uuid,
+                toolCallId: tool_use.id,
+                content: result.content,
+                status: result.status,
+                role: "tool"
+              )
+            when :invocation_stop
+              result = source.data.fetch(:result)
+              output << custom(
+                "little_ghost.usage",
+                usage: result.usage.to_h,
+                metadata: source.data.fetch(:metadata, {})
+              )
+            when :invocation_error
+              output << custom(
+                "little_ghost.usage",
+                usage: source.data.fetch(:usage).to_h,
+                metadata: source.data.fetch(:metadata, {})
+              )
+            when :model_retry
+              tool_call_ids.clear
+              output << custom(
+                "little_ghost.model_retry",
+                source.data.merge(superseded_message_id:).compact
+              )
+            when :agent_interrupt_delivered
+              output << custom(
+                "little_ghost.agent_interrupt_delivered",
+                source.data.slice(:interruption_ids, :batch_key).compact
+              )
+            when :subagent
+              output << custom("little_ghost.subagent", source.data.fetch(:event, source.data))
+            when :trace_context
+              output << custom("little_ghost.trace_context", source.data.fetch(:context, source.data))
+            when :run_partial
+              output << custom(
+                "little_ghost.run.partial",
+                response: source.data.fetch(:response),
+                message: source.data[:error]&.message
+              )
+              output << event(
+                "RUN_FINISHED", threadId: thread_id, runId: run_id,
+                result: {response: source.data.fetch(:response)}
+              )
+            when :run_cancel
+              output << custom("little_ghost.run.canceled", reason: source.data[:error]&.message)
+              output << event("RUN_FINISHED", threadId: thread_id, runId: run_id)
+            when :run_stop
+              output << event(
+                "RUN_FINISHED", threadId: thread_id, runId: run_id,
+                result: {response: source.data.fetch(:response)}
+              )
+            when :run_error
+              output << event(
+                "RUN_ERROR", threadId: thread_id, runId: run_id,
+                message: source.data.fetch(:message),
+                cleanupFailed: source.data.fetch(:cleanup_failed, true)
+              )
+            end
+          end
+        end
+      end
+
+      private
+
+      def event(type, **attributes)
+        {type:, **attributes.compact}
+      end
+
+      def custom(name, value = nil, **attributes)
+        event("CUSTOM", name:, value: value || attributes)
+      end
+    end
+  end
+end

data/lib/little_ghost/ag_ui.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Loads LittleGhost's optional AG-UI adapter. Requiring +little_ghost+ alone does
+# not load interface-specific translation code.
+require_relative "ag_ui/adapter"

data/lib/little_ghost/agent/context_management.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module LittleGhost
+  class Agent
+    # Keep long conversations within the model's available context window.
+    # The capability summarizes older turns while preserving trusted instructions
+    # and recent messages.
+    #
+    #   class CustomerSupportAgent < LittleGhost::Agent
+    #     manage_context compression_threshold: 0.75,
+    #       preserve_recent_messages: 12
+    #   end
+    #
+    # As a support thread reaches the threshold, the next model request contains
+    # a generated summary and targets retaining its 12 most recent conversation
+    # messages. System and developer messages remain intact, and tool-use/result
+    # pairs are never split merely to hit the requested count.
+    #
+    # Context management is inactive until +manage_context+ is declared. The
+    # configured window is a fallback: provider metadata takes precedence when
+    # it advertises a positive context-window size. Compaction uses the current
+    # model with the request's settings, cancellation token, and deadline.
+    #
+    # Proactive compaction failures leave the original request unchanged and emit
+    # diagnostic instrumentation. A provider context-overflow error triggers one
+    # compaction replacement through the model-error callback; cancellation,
+    # deadlines, and cleanup failures still escape as control flow.
+    module ContextManagement
+      DEFAULT_CONTEXT_WINDOW_TOKENS = 200_000 # :nodoc:
+      DEFAULT_COMPRESSION_THRESHOLD = 0.85 # :nodoc:
+      DEFAULT_SUMMARY_RATIO = 0.3 # :nodoc:
+      DEFAULT_PRESERVE_RECENT_MESSAGES = 10 # :nodoc:
+      ESTIMATED_CHARS_PER_TOKEN = 4 # :nodoc:
+      OUTPUT_LIMIT_STOP_REASONS = %i[max_tokens limit_output_tokens limit_total_tokens limit_turns].freeze # :nodoc:
+      SUMMARIZATION_PROMPT = <<~PROMPT # :nodoc:
+        You are a conversation summarizer. Provide a concise summary of the conversation history.
+
+        Format requirements:
+        - Create a structured, concise summary in bullet-point format.
+        - Do not respond conversationally, address the user directly, or comment on tool availability.
+        - Preserve key topics, questions, significant tool executions and results, code or technical information, and key insights.
+        - Do not assume tool executions failed unless otherwise stated.
+        - Write the summary in the third person.
+      PROMPT
+
+      def self.included(base) # :nodoc:
+        base.extend(ClassMethods)
+        base.class_attribute :context_management_configuration_value
+      end
+
+      # Exposes context-management declarations on agent classes.
+      # These methods become inheritable DSL entries when the capability is included.
+      module ClassMethods
+        # Enables automatic context compaction for the agent class.
+        #
+        # The defaults assume a 200,000-token window, compact at 85% usage,
+        # summarize about 30% of conversation messages, and preserve the 10 most
+        # recent messages. The model's declared context window takes precedence
+        # over +context_window_tokens+ when available.
+        #
+        # Invalid ranges raise ArgumentError when the agent class is defined.
+        def manage_context(
+          context_window_tokens: DEFAULT_CONTEXT_WINDOW_TOKENS,
+          compression_threshold: DEFAULT_COMPRESSION_THRESHOLD,
+          summary_ratio: DEFAULT_SUMMARY_RATIO,
+          preserve_recent_messages: DEFAULT_PRESERVE_RECENT_MESSAGES
+        )
+          context_window_tokens = Integer(context_window_tokens)
+          compression_threshold = Float(compression_threshold)
+          summary_ratio = Float(summary_ratio)
+          preserve_recent_messages = Integer(preserve_recent_messages)
+          raise ArgumentError, "context_window_tokens must be positive" unless context_window_tokens.positive?
+          unless compression_threshold.positive? && compression_threshold <= 1
+            raise ArgumentError, "compression_threshold must be between 0 and 1"
+          end
+          unless summary_ratio.between?(0.1, 0.8)
+            raise ArgumentError, "summary_ratio must be between 0.1 and 0.8"
+          end
+          raise ArgumentError, "preserve_recent_messages must be at least 2" if preserve_recent_messages < 2
+
+          self.context_management_configuration_value = {
+            context_window_tokens:,
+            compression_threshold:,
+            summary_ratio:,
+            preserve_recent_messages:
+          }
+          before_model :compact_model_context
+          after_model_error :compact_context_after_overflow
+        end
+
+        def context_management_configuration = context_management_configuration_value # :nodoc:
+      end
+
+      private
+
+      def compact_model_context(payload, context: nil)
+        request = payload.fetch(:request)
+        configuration = self.class.context_management_configuration
+        limit = model_context_window_tokens(configuration)
+        threshold = limit * configuration.fetch(:compression_threshold)
+        return Support::Callbacks.continue if estimated_request_tokens(request) < threshold
+
+        compacted = compact_context(
+          request,
+          configuration,
+          context,
+          context_window_tokens: limit,
+          parent_operation_id: payload[:parent_operation_id]
+        )
+        Support::Callbacks.replace(payload.merge(request: compacted))
+      rescue CancelledError, DeadlineExceededError, CleanupError
+        raise
+      rescue => error
+        Instrumentation.publish(:context_compaction, outcome: :error, error_class: error.class.name)
+        Support::Callbacks.continue
+      end
+
+      def compact_context_after_overflow(payload, context: nil)
+        return Support::Callbacks.continue unless payload.fetch(:error).is_a?(ContextWindowOverflowError)
+
+        configuration = self.class.context_management_configuration
+        request = payload.fetch(:request)
+        compacted = compact_context(
+          request,
+          configuration,
+          context,
+          context_window_tokens: model_context_window_tokens(configuration),
+          reason: :overflow,
+          parent_operation_id: payload[:parent_operation_id]
+        )
+        Support::Callbacks.replace(payload.merge(request: compacted))
+      end
+
+      def summarize_oldest_messages(request, configuration, context, parent_operation_id:)
+        trusted, conversation = request.messages.partition { |message| %i[system developer].include?(message.role) }
+        preserve = configuration.fetch(:preserve_recent_messages)
+        split = [(conversation.length * configuration.fetch(:summary_ratio)).floor, 1].max
+        split = [split, conversation.length - preserve].min
+        raise ProtocolError, "Not enough conversation history to compact" unless split.positive?
+
+        split = safe_summary_split(conversation, split)
+        to_summarize = conversation.first(split)
+        summary = generate_context_summary(to_summarize, request, context, parent_operation_id:)
+        ModelRequest.new(
+          messages: [*trusted, summary, *conversation.drop(split)],
+          tools: request.tools,
+          settings: request.settings,
+          output_schema: request.output_schema,
+          tool_choice: request.tool_choice,
+          required_capabilities: request.required_capabilities,
+          cancellation_token: request.cancellation_token,
+          deadline: request.deadline
+        )
+      end
+
+      def compact_context(
+        request,
+        configuration,
+        context,
+        context_window_tokens:,
+        parent_operation_id:,
+        reason: :threshold
+      )
+        compacted = summarize_oldest_messages(request, configuration, context, parent_operation_id:)
+        Instrumentation.publish(
+          :context_compaction,
+          reason:,
+          removed_messages: request.messages.length - compacted.messages.length,
+          estimated_tokens: estimated_request_tokens(request),
+          context_window_tokens:
+        )
+        compacted
+      end
+
+      def safe_summary_split(messages, split)
+        while split < messages.length
+          current = messages.fetch(split)
+          previous = messages.fetch(split - 1)
+          current_results = current.content.grep(Content::ToolResult).map(&:tool_use_id)
+          previous_uses = previous.content.grep(Content::ToolUse).map(&:id)
+          break if current_results.empty? && previous_uses.empty?
+
+          split += 1
+        end
+        split
+      end
+
+      def generate_context_summary(messages, request, context, parent_operation_id:)
+        operation_id = SecureRandom.uuid
+        started_at = monotonic_time
+        summary_request = ModelRequest.new(
+          messages: [
+            Message.new(role: :system, content: SUMMARIZATION_PROMPT),
+            *messages,
+            Message.new(role: :user, content: "Please summarize this conversation.")
+          ],
+          tools: [],
+          settings: request.settings,
+          cancellation_token: request.cancellation_token,
+          deadline: request.deadline
+        )
+        instrument(
+          :model_start,
+          operation_id:,
+          parent_operation_id:,
+          purpose: :context_compaction,
+          diagnostic: {
+            input: summary_request.messages.map { |message| diagnostic_message(message) },
+            tool_definitions: summary_request.tools
+          },
+          model_settings: summary_request.settings,
+          **model_attributes
+        )
+        response = nil
+        time_to_first_token = nil
+        model.stream(summary_request).each do |event|
+          context&.check!
+          time_to_first_token ||= duration_seconds(started_at) if model_output_event?(event)
+          response = event.data[:response] if event.type == :message_stop
+        end
+        raise ProtocolError, "Context summarization ended without a response" unless response
+        context&.record_usage(response.usage)
+        if OUTPUT_LIMIT_STOP_REASONS.include?(response.stop_reason)
+          raise OutputLimitError, "The context summary stopped before completion"
+        end
+
+        instrument(
+          :model_stop,
+          operation_id:,
+          parent_operation_id:,
+          purpose: :context_compaction,
+          outcome: :completed,
+          duration_ms: duration_ms(started_at),
+          time_to_first_token:,
+          stop_reason: response.stop_reason,
+          **response_attributes(response),
+          diagnostic: {output: diagnostic_message(response.message)},
+          **model_attributes,
+          **usage_attributes(response.usage)
+        )
+        Message.new(role: :user, content: response.message.content)
+      rescue => error
+        instrument(
+          :model_stop,
+          operation_id:,
+          parent_operation_id:,
+          purpose: :context_compaction,
+          outcome: :error,
+          duration_ms: duration_ms(started_at),
+          time_to_first_token:,
+          error_type: error.class.name,
+          diagnostic: {exception: diagnostic_exception(error)},
+          **model_attributes
+        )
+        raise
+      end
+
+      def model_context_window_tokens(configuration)
+        value = model.respond_to?(:metadata) && (
+          model.metadata[:context_window_tokens] || model.metadata["context_window_tokens"] ||
+          model.metadata[:context_window] || model.metadata["context_window"]
+        )
+        value = Integer(value) if value
+        value&.positive? ? value : configuration.fetch(:context_window_tokens)
+      rescue ArgumentError, TypeError
+        configuration.fetch(:context_window_tokens)
+      end
+
+      def estimated_request_tokens(request)
+        characters = JSON.generate(
+          messages: request.messages.map(&:to_h),
+          tools: request.tools,
+          output_schema: request.output_schema,
+          tool_choice: request.tool_choice
+        ).length
+        (characters.to_f / ESTIMATED_CHARS_PER_TOKEN).ceil
+      rescue JSON::GeneratorError
+        request.messages.sum { |message| message.text.length } / ESTIMATED_CHARS_PER_TOKEN
+      end
+    end
+  end
+end

data/lib/little_ghost/agent/delegation.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  class Agent
+    # Give one agent a bounded way to ask another agent for help.
+    # Delegated agents can run as managed subagents or behind an ordinary tool call.
+    #
+    #   class CustomerSupportAgent < LittleGhost::Agent
+    #     subagent ResearchAgent, kind: "research"
+    #     agent_as_tool SentimentAgent, name: "classify_sentiment"
+    #   end
+    #
+    # The support model receives spawn, messaging, interruption, waiting, and
+    # listing tools for the +research+ kind. It sees the sentiment agent as one
+    # regular tool whose result is returned to the current turn.
+    #
+    # Static declarations may be combined with a resolver that returns dynamic
+    # Subagents::Definition objects. Managed conversations persist when a session
+    # store is configured unless <tt>persist: false</tt> keeps them local to one
+    # invocation. An agent exposed as a tool starts with empty history unless
+    # <tt>preserve_context: true</tt> serializes calls and retains its history.
+    #
+    # Tool overrides must be classes. A delegated agent otherwise receives only
+    # its own declared tools; it does not inherit the parent's registry. The
+    # manager enforces its concurrency, identity, polling, and persistence bounds.
+    module Delegation
+      def self.included(base) # :nodoc:
+        base.extend(ClassMethods)
+        base.class_attribute :subagent_long_poll_duration_value,
+          default: Subagents::Manager::DEFAULT_WAIT_TIMEOUT
+        base.class_attribute :subagent_declarations_value, default: []
+        base.class_attribute :subagent_resolvers_value, default: []
+        base.class_attribute :agent_tool_declarations_value, default: []
+      end
+
+      # Exposes delegation declarations on agent classes.
+      # These methods become inheritable DSL entries when the capability is included.
+      module ClassMethods
+        # :call-seq:
+        #   subagent_long_poll_duration() -> Float
+        #   subagent_long_poll_duration(seconds) -> Float
+        #
+        # The maximum long-poll duration used by subagent wait tools.
+        #
+        # The default comes from Subagents::Manager. Values must be positive,
+        # finite numbers and are normalized to Float.
+        def subagent_long_poll_duration(*values)
+          return subagent_long_poll_duration_value if values.empty?
+
+          timeout = Float(values.fetch(0))
+          unless timeout.positive? && timeout.finite?
+            raise ConfigurationError, "subagent_long_poll_duration must be a positive finite number"
+          end
+
+          self.subagent_long_poll_duration_value = timeout
+        rescue ArgumentError, TypeError
+          raise ConfigurationError, "subagent_long_poll_duration must be a positive finite number"
+        end
+
+        # Adds +agent_class+ as an available managed subagent.
+        #
+        # +kind+ defaults to the agent ID and +description+ defaults to the
+        # agent description. Conversations persist when a session store exists;
+        # pass <tt>persist: false</tt> for invocation-local work.
+        #
+        #   subagent ResearchAgent, kind: "research"
+        def subagent(agent_class, kind: nil, description: nil, model: nil, tools: nil, factory: nil, persist: true)
+          validate_delegated_tools!(tools)
+          declaration = {
+            agent: agent_class,
+            kind: (kind || agent_class.agent_id).to_s,
+            description: description || agent_class.description,
+            model:,
+            tools:,
+            factory:,
+            persist:
+          }
+          self.subagent_declarations_value = [*subagent_declarations, declaration]
+        end
+
+        # Adds several static subagents and an optional dynamic definition resolver.
+        def subagents(*agent_classes, **options, &resolver)
+          agent_classes.each { |agent_class| subagent(agent_class, **options) }
+          self.subagent_resolvers_value = [*subagent_resolvers, resolver] if resolver
+          subagent_declarations
+        end
+
+        def subagent_declarations = subagent_declarations_value # :nodoc:
+
+        def subagent_resolvers = subagent_resolvers_value # :nodoc:
+
+        # Exposes +agent_class+ as one ordinary tool.
+        #
+        # Pass <tt>preserve_context: true</tt> to retain the delegated agent's
+        # conversational history between calls to that tool instance.
+        def agent_as_tool(agent_class, name: nil, description: nil, model: nil, tools: nil,
+          preserve_context: false)
+          validate_delegated_tools!(tools)
+          declaration = {
+            agent: agent_class,
+            name: (name || agent_class.agent_id).to_s,
+            description: description || agent_class.description,
+            model:,
+            tools:,
+            preserve_context:
+          }
+          self.agent_tool_declarations_value = [*agent_tool_declarations, declaration]
+        end
+
+        # Exposes several agent classes as ordinary tools with shared options.
+        def agents_as_tools(*agent_classes, **options)
+          agent_classes.each { |agent_class| agent_as_tool(agent_class, **options) }
+          agent_tool_declarations
+        end
+
+        def agent_tool_declarations = agent_tool_declarations_value # :nodoc:
+
+        private
+
+        def validate_delegated_tools!(tools)
+          return unless Array(tools).flatten.any? { |tool| !tool.is_a?(Class) }
+
+          raise ConfigurationError, "Delegated tools must be classes"
+        end
+      end
+    end
+  end
+end