little_ghost 0.3.0 → 0.5.0

data/lib/little_ghost/skills/resource_root.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module LittleGhost
+  module Skills
+    module ResourceRoot # :nodoc:
+      module_function
+
+      def normalize(value)
+        return unless value
+
+        path = value.to_s
+        return normalize_workspace_reference(path) if path.start_with?("workspace://")
+
+        unless valid_absolute_path?(path)
+          raise ArgumentError, "resource_root must be an absolute path or workspace:// reference"
+        end
+
+        File.expand_path(path).freeze
+      end
+
+      def normalize_workspace_reference(path)
+        logical = path.delete_prefix("workspace://")
+        components = logical.split("/", -1)
+        name = components.shift
+        invalid = name.nil? || !name.match?(/\A[a-zA-Z0-9_-]+\z/) ||
+          components.any? { |component| component.empty? || component == "." || component == ".." }
+        if invalid || path.include?("\0") || path.include?("\\")
+          raise ArgumentError, "resource_root must be an absolute path or workspace:// reference"
+        end
+
+        path.dup.freeze
+      end
+
+      def valid_absolute_path?(path)
+        !path.include?("\0") && Pathname.new(path).absolute? &&
+          !path.split(File::SEPARATOR).include?("..")
+      end
+    end
+  end
+end

data/lib/little_ghost/skills/skill.rb

@@ -3,9 +3,6 @@
 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,

data/lib/little_ghost/stream_event.rb

@@ -1,17 +1,8 @@
 # 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.
+    # Creates an event with a symbol +type+ and frozen outer payload Hash.
     def self.build(type, **data)
       new(type: type.to_sym, data: data.freeze)
     end
@@ -25,7 +16,10 @@ module LittleGhost
   # +: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]+.
+  # in +data[:response]+. An +:agent_stream+ event wraps a copied, frozen Agent
+  # event with an
+  # AgentStreamSource[rdoc-ref:LittleGhost::AgentStreamSource] when a Run exposes
+  # nested work.
   #
   #   event = LittleGhost::StreamEvent.build(:text_delta, text: "Hello")
   #   event.type        # => :text_delta
@@ -37,13 +31,14 @@ module LittleGhost
 
     ##
     # :attr_reader: data
-    # The immutable payload for this event kind.
+    # The frozen outer payload Hash. Nested values are retained and must not be
+    # mutated by callers.
 
     ##
     # :singleton-method: build
     # :call-seq:
     #   build(type, **data) -> StreamEvent
     #
-    # Creates an immutable event with a symbol +type+ and keyword payload.
+    # Creates an event with a symbol +type+ and frozen outer payload Hash.
   end
 end

data/lib/little_ghost/subagents/control_tool.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module Subagents
+    class ControlTool < Tool # :nodoc:
+    end
+  end
+end

data/lib/little_ghost/subagents/manager.rb

@@ -5,6 +5,7 @@ require "base64"
 require "digest"
 require "time"
 require_relative "definition"
+require_relative "control_tool"
 
 module LittleGhost
   module Subagents
@@ -20,12 +21,14 @@ module LittleGhost
     #       description: "Investigates policies and account history"
     #   end
     #
-    # LittleGhost then gives +CustomerSupportAgent+ tools to spawn, message, wait for,
-    # interrupt, and list research agents. The manager keeps each child identity
-    # stable across follow-up turns.
+    # LittleGhost then gives +CustomerSupportAgent+ tools to spawn, message,
+    # check on, interject, and list research agents. The manager keeps each child
+    # identity stable across follow-up turns. A progress check returns after 30
+    # seconds by default when the selected subagents are still working; it does
+    # not pause or restart them.
     #
-    # Follow-up messages are FIFO turns and never interrupt active work.
-    # #interrupt is the separate synchronous path for delivery at the next model
+    # Follow-up messages are FIFO turns and never interject active work.
+    # #interject is the separate synchronous path for delivery at the next model
     # boundary; delivery does not stop the child, and tool calls from that model
     # response continue in the child run.
     #
@@ -46,7 +49,7 @@ module LittleGhost
       DEFAULT_MAX_QUEUED_TURNS_PER_IDENTITY = 8 # :nodoc:
       DEFAULT_MAX_MESSAGE_CHARS = 50_000 # :nodoc:
       DEFAULT_MAX_RESPONSE_CHARS = 100_000 # :nodoc:
-      DEFAULT_WAIT_TIMEOUT = 20.0 # :nodoc:
+      DEFAULT_WAIT_TIMEOUT = 30.0 # :nodoc:
       DEFAULT_CLOSE_TIMEOUT = 5.0 # :nodoc:
       DEFAULT_LIST_LIMIT = 20 # :nodoc:
       MAX_LIST_LIMIT = 100 # :nodoc:
@@ -58,16 +61,16 @@ module LittleGhost
       CURSOR_MAX_BYTES = 512 # :nodoc:
       UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/ # :nodoc:
 
-      InterruptExchange = Struct.new(:message, :response, :complete) # :nodoc:
+      InterjectionExchange = Struct.new(:message, :response, :complete) # :nodoc:
       Turn = Struct.new( # :nodoc:
         :number,
         :message,
         :completion,
         :operation_id,
         :parent_operation_id,
-        :interrupts,
-        :interruption_metadata,
-        :interruption_ids
+        :interjections,
+        :interjection_metadata,
+        :interjection_ids
       )
       Identity = Struct.new( # :nodoc:
         :subagent_id,
@@ -368,7 +371,7 @@ module LittleGhost
       # model response. The returned +response_disposition+ says whether that
       # response also initiated tool calls; it does not imply the subagent has
       # stopped.
-      def interrupt(subagent_id:, message:, cancellation_token: @cancellation_token, deadline: @deadline)
+      def interject(subagent_id:, message:, cancellation_token: @cancellation_token, deadline: @deadline)
         unless message.is_a?(String)
           raise ToolError, "Subagent messages must be strings."
         end
@@ -376,30 +379,30 @@ module LittleGhost
           raise ToolError, "Subagent messages cannot exceed #{@max_message_chars} characters."
         end
 
-        exchange = InterruptExchange.new(message:, complete: false)
+        exchange = InterjectionExchange.new(message:, complete: false)
         identity, turn = @mutex.synchronize do
           ensure_open!
           value = fetch_identity!(subagent_id)
-          unless value.agent.respond_to?(:interrupt_response)
-            raise ToolError, "Subagent #{subagent_id.inspect} does not support interruptions."
+          unless value.agent.respond_to?(:interject)
+            raise ToolError, "Subagent #{subagent_id.inspect} does not support interjections."
           end
           unless value.status == "running"
             raise ToolError, "Subagent #{subagent_id.inspect} is not currently running."
           end
-          if value.current.interrupts.length >= @max_queued_turns_per_identity
-            raise ToolError, "Subagent #{subagent_id.inspect} has reached its interrupt limit."
+          if value.current.interjections.length >= @max_queued_turns_per_identity
+            raise ToolError, "Subagent #{subagent_id.inspect} has reached its interject limit."
           end
-          interrupt_chars = value.current.interrupts.sum { |pending| pending.message.length }
-          if interrupt_chars + message.length > @max_message_chars
-            raise ToolError, "Subagent interrupt messages cannot exceed #{@max_message_chars} total characters."
+          interjection_chars = value.current.interjections.sum { |pending| pending.message.length }
+          if interjection_chars + message.length > @max_message_chars
+            raise ToolError, "Subagent interjection messages cannot exceed #{@max_message_chars} total characters."
           end
 
-          value.current.interrupts << exchange
+          value.current.interjections << exchange
           [value, value.current]
         end
 
-        interrupt_response = begin
-          identity.agent.interrupt_response(
+        result = begin
+          identity.agent.interject(
             message,
             cancellation_token:,
             deadline:,
@@ -407,16 +410,16 @@ module LittleGhost
           )
         rescue
           @mutex.synchronize do
-            turn.interrupts.delete(exchange)
+            turn.interjections.delete(exchange)
             @condition.broadcast
           end
           raise
         end
-        response = interrupt_response.text
+        response = result.text
         truncated = response.length > @max_response_chars
         returned_response = truncated ? response[0, @max_response_chars] : response
         @mutex.synchronize do
-          used_response_chars = turn.interrupts.sum do |pending|
+          used_response_chars = turn.interjections.sum do |pending|
             pending.equal?(exchange) ? 0 : pending.response.to_s.length
           end
           remaining_response_chars = [@max_response_chars - used_response_chars, 0].max
@@ -428,17 +431,17 @@ module LittleGhost
           snapshot(identity, include_response: true, include_progress: true)
         end
         value = {
-          status: "interruption_delivered",
+          status: "interjection_delivered",
           subagent_id: identity.subagent_id,
           kind: identity.definition.kind,
           subagent:,
           turn: turn.number,
           response: returned_response,
-          response_disposition: interrupt_response.tool_calls? ? "text_with_tool_calls" : "text_only"
+          response_disposition: result.tool_calls? ? "text_with_tool_calls" : "text_only"
         }
         value[:response_truncated] = true if truncated
         value
-      rescue AgentInterruptError => error
+      rescue AgentInterjectionError => error
         raise ToolError, error.message
       end
 
@@ -504,7 +507,7 @@ module LittleGhost
         end
       end
 
-      # Builds spawn, follow-up, interrupt, wait, and list tools bound to this
+      # Builds spawn, follow-up, interject, wait, and list tools bound to this
       # manager. Closing the first tool closes the shared manager.
       def tools
         manager = self
@@ -512,7 +515,7 @@ module LittleGhost
           "- #{definition.kind}: #{definition.description}"
         end.join("\n")
         tools = [
-          Tool.define(
+          ControlTool.define(
             name: "spawn_subagent",
             description: <<~DESCRIPTION.strip,
               Create a new subagent identity for an independent task. Mode controls delivery: sync waits for the
@@ -554,13 +557,13 @@ module LittleGhost
               parent_operation_id: context&.agent_operation_id
             )
           end,
-          Tool.define(
+          ControlTool.define(
             name: "send_message_to_subagent",
             description: <<~DESCRIPTION.strip,
               Send a follow-up turn to an existing active or persisted subagent identity. Persisted conversations
               are restored transparently before the follow-up. Messages are processed in order after the
-              current turn and never interrupt active work. Do not use this for status, steering, stopping, or
-              finalization; use interrupt_subagent for an active subagent. Mode controls delivery: sync waits for the
+              current turn and never interject active work. Do not use this for status, steering, stopping, or
+              finalization; use interject_subagent for an active subagent. Mode controls delivery: sync waits for the
               later turn's response, while async enqueues the turn and returns immediately.
             DESCRIPTION
             input_schema: {
@@ -585,8 +588,8 @@ module LittleGhost
               parent_operation_id: context&.agent_operation_id
             )
           end,
-          Tool.define(
-            name: "interrupt_subagent",
+          ControlTool.define(
+            name: "interject_subagent",
             description: <<~DESCRIPTION.strip,
               Interrupt an actively running subagent in its current turn. The message is added at the next model
               boundary. This call waits for that model response and reports its ordinary text, whether the same
@@ -606,13 +609,13 @@ module LittleGhost
             options = {}
             options[:cancellation_token] = context.cancellation_token if context
             options[:deadline] = context.deadline if context&.deadline
-            manager.interrupt(
+            manager.interject(
               subagent_id: input.fetch("subagent_id"),
               message: input.fetch("message"),
               **options
             )
           end,
-          Tool.define(
+          ControlTool.define(
             name: "wait_for_subagents",
             description: <<~DESCRIPTION.strip,
               Wait briefly for selected subagents, or all subagents when omitted. A still_working response is expected
@@ -633,7 +636,7 @@ module LittleGhost
               additionalProperties: false
             }
           ) { |input| manager.wait(subagent_ids: input["subagent_ids"]) },
-          Tool.define(
+          ControlTool.define(
             name: "list_subagents",
             description: <<~DESCRIPTION.strip,
               List active and persisted subagent conversations newest-first without restoring inactive agents.
@@ -1089,9 +1092,9 @@ module LittleGhost
             completion: Completion.new,
             operation_id: SecureRandom.uuid,
             parent_operation_id:,
-            interrupts: [],
-            interruption_metadata: context&.interruption_metadata,
-            interruption_ids: context&.interruption_ids || []
+            interjections: [],
+            interjection_metadata: context&.interjection_metadata,
+            interjection_ids: context&.interjection_ids || []
           )
           identity.next_turn += 1
           @turn_count += 1 if count_turn
@@ -1157,8 +1160,8 @@ module LittleGhost
                   options[:history] = identity.history
                   options[:context] = identity.state
                   options[:conversation_id] = identity.conversation_id
-                  options[:interruption_metadata] = turn.interruption_metadata
-                  options[:interruption_ids] = turn.interruption_ids
+                  options[:interjection_metadata] = turn.interjection_metadata
+                  options[:interjection_ids] = turn.interjection_ids
                 end
                 result = if identity.agent.is_a?(Agent)
                   run_agent_turn(identity, turn, options)
@@ -1284,8 +1287,8 @@ module LittleGhost
         response = serialized_response[0, @max_response_chars] if truncated
         persisted_response = response.is_a?(String) ? response : serialized_response
 
-        interrupt_exchanges = @mutex.synchronize do
-          while identity.durable && turn.interrupts.any? { |exchange| !exchange.complete } && !@closed
+        interject_exchanges = @mutex.synchronize do
+          while identity.durable && turn.interjections.any? { |exchange| !exchange.complete } && !@closed
             @condition.wait(@mutex, CANCELLATION_POLL_INTERVAL)
           end
           if @closed
@@ -1294,11 +1297,11 @@ module LittleGhost
           end
 
           identity.status = "persisting" if identity.durable
-          turn.interrupts.select(&:complete).map { |exchange| [exchange.message, exchange.response] }
+          turn.interjections.select(&:complete).map { |exchange| [exchange.message, exchange.response] }
         end
-        return unless interrupt_exchanges
+        return unless interject_exchanges
 
-        retain_agent_conversation(identity, turn, result, persisted_response, interrupt_exchanges)
+        retain_agent_conversation(identity, turn, result, persisted_response, interject_exchanges)
 
         @mutex.synchronize do
           identity.latest_turn = turn.number
@@ -1323,11 +1326,11 @@ module LittleGhost
         end
       end
 
-      def retain_agent_conversation(identity, turn, result, persisted_response, interrupt_exchanges)
+      def retain_agent_conversation(identity, turn, result, persisted_response, interject_exchanges)
         if identity.durable
           state = result.is_a?(RunResult) ? result.state : identity.state
           messages = [Message.new(role: :user, content: turn.message)]
-          interrupt_exchanges.each do |message, response|
+          interject_exchanges.each do |message, response|
             messages << Message.new(role: :user, content: message)
             messages << Message.new(role: :assistant, content: response)
           end

data/lib/little_ghost/support/callbacks.rb

@@ -16,7 +16,9 @@ module LittleGhost
     # concrete class.
     #
     #   callbacks = LittleGhost::Support::Callbacks.new(:prepare)
-    #   callbacks.on(:prepare) { |payload| Callbacks.replace(payload.merge(debug: true)) }
+    #   callbacks.on(:prepare) do |payload|
+    #     LittleGhost::Support::Callbacks.replace(payload.merge(debug: true))
+    #   end
     #   decision = callbacks.run(:prepare, {})
     #   decision.value # => {debug: true}
     class Callbacks

data/lib/little_ghost/support/content_capture.rb

@@ -15,12 +15,12 @@ module LittleGhost
     #   )
     #   LittleGhost::Instrumentation.capture_content(policy)
     #
-    # === Security and trust
+    # === Choose captured data
     #
     # Enabling capture may place model input, output, tool definitions, and
     # exception details into telemetry. Redaction and a custom scrubber reduce
-    # accidental disclosure but are not a security boundary. Configure one
-    # policy per trusted process and apply exporter-side controls as well.
+    # accidental disclosure but cannot recognize every sensitive value. Configure
+    # one capture policy per process and apply exporter-side controls as well.
     class ContentCapture
       CaptureLimitExceeded = Class.new(StandardError) # :nodoc:
 

data/lib/little_ghost/support/http_client.rb

@@ -10,10 +10,10 @@ module LittleGhost
     # It applies cancellation, deadlines, timeouts, and response-size limits while
     # yielding response chunks as they arrive.
     #
-    # === Security and trust
+    # === HTTPS defaults
     #
     # HTTPS is required by default. Enabling +allow_insecure_http+ can expose API
-    # keys and model content in transit; use it only with a trusted local
+    # keys and model content in transit; use it only with a local
     # development endpoint.
     class HTTPClient
       # Default upper bound for a complete provider response (50 MiB).

data/lib/little_ghost/support/redactor.rb

@@ -8,7 +8,7 @@ module LittleGhost
     #
     # Redaction is a defense-in-depth aid, not proof that arbitrary
     # sensitive content is safe to export. Applications should add known secret
-    # values and keep telemetry within an appropriate trust boundary.
+    # values and send telemetry only to the intended destination.
     class Redactor
       SENSITIVE_KEY = /(authorization|api[_-]?key|credential|password|secret|(?:^|[_-])token(?:$|[_-])|cookie|private[_-]?key)/i # :nodoc:
       SECRET_PATTERNS = [

data/lib/little_ghost/swarm.rb

@@ -7,8 +7,8 @@ module LittleGhost
   # Lets configured Agent members hand one request directly to one another.
   #
   # A swarm is an Assembly for model-selected routing. One member is active at a
-  # time. It either produces the final answer or calls a reserved handoff tool
-  # to select an allowed next member.
+  # time. It either produces the final answer or uses a model-visible handoff
+  # tool to choose one of the next members allowed by the application.
   #
   #   class ProblemSolverSwarm < LittleGhost::Swarm
   #     member TriageAgent
@@ -23,10 +23,15 @@ module LittleGhost
   #   run = ProblemSolverSwarm.ask("Why was I charged twice?")
   #   run.response
   #
+  # Call a named Swarm with
+  # ask[rdoc-ref:LittleGhost::Assembly.ask] for its final Run, or
+  # the streaming entrypoint[rdoc-ref:LittleGhost::Assembly.stream_ask] for
+  # coordination and final-response events.
+  #
   # Swarm members are Agent definitions rather than arbitrary assemblies so a
   # handoff remains a direct model-to-model transition. Original conversation
   # history and application context stay isolated unless a member opts in with
-  # +history: true+ or +context: true+. Streams expose coordination lifecycle
+  # <tt>history: true</tt> or <tt>context: true</tt>. Streams expose coordination
   # events and the final member response, but not intermediate model text.
   class Swarm < Assembly
     MAX_BUFFERED_EVENTS = 10_000 # :nodoc:
@@ -91,7 +96,10 @@ module LittleGhost
         self.swarm_max_steps_value = value
       end
 
-      # Reads or assigns the repeated directed-handoff limit.
+      # Reads or assigns how often the same directed handoff may repeat.
+      #
+      # For example, a value of +2+ allows the transition from triage to billing
+      # twice during one Swarm run. +max_steps+ still limits total member calls.
       def max_handoff_repeats(value = nil)
         return swarm_max_handoff_repeats_value if value.nil?
 
@@ -101,7 +109,7 @@ module LittleGhost
         self.swarm_max_handoff_repeats_value = value
       end
 
-      # Validates the member set and topology and returns this Swarm class.
+      # Validates the members and allowed handoff routes, then returns this class.
       def validate!
         swarm_definition!
         self