little_ghost 0.3.0 → 0.4.0

data/lib/little_ghost/subagents/manager.rb

@@ -21,11 +21,11 @@ module LittleGhost
     #   end
     #
     # LittleGhost then gives +CustomerSupportAgent+ tools to spawn, message, wait for,
-    # interrupt, and list research agents. The manager keeps each child identity
+    # interject, and list research agents. The manager keeps each child identity
     # stable across follow-up turns.
     #
-    # 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.
     #
@@ -58,16 +58,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 +368,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 +376,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 +407,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 +428,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 +504,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
@@ -559,8 +559,8 @@ module LittleGhost
             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: {
@@ -586,7 +586,7 @@ module LittleGhost
             )
           end,
           Tool.define(
-            name: "interrupt_subagent",
+            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,7 +606,7 @@ 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
@@ -1089,9 +1089,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 +1157,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 +1284,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 +1294,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 +1323,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/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

data/lib/little_ghost/tool.rb

@@ -19,20 +19,60 @@ module LittleGhost
   #     end
   #   end
   #
-  #   result = TicketStatusTool.new.execute("ticket_id" => "SUP-481")
-  #   result.success?            # => true
-  #   JSON.parse(result.content) # => {"ticket_id"=>"SUP-481", "status"=>"waiting_on_customer"}
+  #   class CustomerSupportAgent < LittleGhost::Agent
+  #     tools TicketStatusTool
+  #   end
+  #
+  #   run = CustomerSupportAgent.ask("What is happening with ticket SUP-481?")
+  #   run.response
+  #
+  # Use application context for authorization, never model-selected input:
+  #
+  #   class OrderStatusTool < LittleGhost::Tool
+  #     description "Look up an order for the current account."
+  #     input_schema type: "object", properties: {
+  #       order_number: {type: "string"}
+  #     }, required: ["order_number"], additionalProperties: false
+  #
+  #     def call(input)
+  #       Orders.status_for(
+  #         actor_id: run.invocation.actor_id,
+  #         account_id: run.invocation.context.fetch("account_id"),
+  #         order_number: input.fetch("order_number")
+  #       )
+  #     end
+  #   end
+  #
+  #   OrderSupportAgent.ask(
+  #     "Where is order 481?",
+  #     actor_id: authenticated_user.id,
+  #     context: {account_id: authenticated_user.account_id}
+  #   )
+  #
+  # These values cross different trust boundaries:
+  #
+  # [<tt>input</tt>]
+  #   Arguments selected by the model. The schema checks their shape, not their
+  #   permission to perform an operation.
+  # [<tt>run.invocation.context</tt>]
+  #   Current request values supplied by the application. Use these for
+  #   authorization after the application authenticates the caller.
+  # [<tt>context.state</tt>]
+  #   Mutable working state for the run. It may include values restored from a
+  #   Session, so check saved values again before trusting them.
+  # [Tool::Binding]
+  #   Run-scoped objects such as the Agent, Run, Runtime, workspace, and sandbox.
+  #   The Binding supplies #run; it does not contain model arguments.
   #
-  # The class DSL produces the frozen specification sent to models. +execute+
-  # validates incoming arguments, invokes +call+, and normalizes strings,
-  # JSON-compatible collections, and other return values to model-facing text.
-  # Tool.define offers the same contract for an embedded implementation.
+  # The class DSL produces the specification sent to models. During an Agent
+  # run, the tool registry creates and binds one Tool instance. Tests and custom
+  # integrations may call +execute+ directly; it validates the arguments, calls
+  # +call+, and returns an ExecutionResult. Tool.define offers the same contract
+  # for an embedded implementation.
   #
-  # A tool registry creates one instance per agent run and supplies a Binding for
-  # access to the agent, run, runtime, model, workspace, and sandbox. Mutable
-  # per-instance state therefore belongs to that run. Registries close tools that
-  # implement +close+; <tt>exclusive true</tt> serializes calls against every
-  # other exclusive tool in the same run.
+  # Mutable Tool instance state belongs to one Agent run. Registries close tool
+  # instances that implement +close+; <tt>exclusive true</tt> prevents that tool
+  # from overlapping other exclusive tools in the same run.
   #
   # Validation and application ToolError failures become error results. A
   # ToolError message is visible to the model and must be safe to disclose;
@@ -45,8 +85,10 @@ module LittleGhost
     # A binding can be copied with selected collaborators replaced.
     #
     # Tool instances expose the bound agent, run, runtime, model, workspace, and
-    # sandbox through matching accessors. ToolRegistry and Agent normally create
-    # bindings on behalf of application code.
+    # sandbox through matching accessors. A Binding does not carry model Tool
+    # arguments or application state; the current RunContext carries that state.
+    # ToolRegistry and Agent normally create bindings on behalf of application
+    # code.
     class Binding
       # Agent, run, runtime, model, workspace, and sandbox available to a tool.
       attr_reader :agent, :run, :runtime, :model, :workspace, :sandbox

data/lib/little_ghost/tools/write_todos.rb

@@ -59,7 +59,12 @@ module LittleGhost
         ids = todos.map { |todo| todo.fetch("id") }
         raise ToolError, "todo IDs must be unique" unless ids.uniq.length == ids.length
 
-        state = context ? (context.state["little_ghost.plan"] ||= empty_plan) : (@fallback_state ||= empty_plan)
+        if context
+          context.state["little_ghost.plan"] ||= empty_plan
+          state = context.state.fetch("little_ghost.plan")
+        else
+          state = @fallback_state ||= empty_plan
+        end
         state.replace("plan_title" => input.fetch("plan_title"), "todos" => todos.map(&:dup))
         state.dup
       end

data/lib/little_ghost/tracing/open_telemetry.rb

@@ -358,7 +358,7 @@ module LittleGhost
         return unless %i[diagnostic_input diagnostic_output].include?(key.to_sym)
 
         prefix = (key.to_sym == :diagnostic_input) ? "input" : "output"
-        if %i[agent interrupt tool].include?(kind) &&
+        if %i[agent interjection tool].include?(kind) &&
             !(kind == :tool && prefix == "output" && attributes[:error_type])
           result["#{prefix}.value"] = value
           result["#{prefix}.mime_type"] = diagnostic_mime_type(value)

data/lib/little_ghost/version.rb

@@ -2,5 +2,5 @@
 
 module LittleGhost
   # Current LittleGhost gem version.
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/little_ghost/workflow.rb

@@ -10,16 +10,13 @@ module LittleGhost
   # Agent or another coordinated Assembly. The workflow consumes intermediate
   # answers and streams one final participant response.
   #
-  # A support workflow can route a difficult request through research before the
-  # responder writes the caller-visible answer:
+  # A support workflow can guarantee that research happens before the responder
+  # writes the caller-visible answer:
   #
   #   class ResponseWorkflow < LittleGhost::Workflow
   #     private
   #
   #     def perform
-  #       route = invoke(RouterAgent).output
-  #       return invoke(CustomerSupportAgent) unless route["research"]
-  #
   #       evidence = invoke(ResearchAgent).output
   #       invoke CustomerSupportAgent, input: <<~PROMPT
   #         #{input.text}
@@ -31,27 +28,31 @@ module LittleGhost
   #   end
   #
   #   run = ResponseWorkflow.ask("Why is transfer 481 pending?")
-  #   run.response # => "Transfer 481 is waiting for the receiving bank."
+  #   run.response
+  #   # One possible response: Transfer 481 is waiting for the receiving bank.
+  #
+  # Call a named Workflow with
+  # ask[rdoc-ref:LittleGhost::Assembly.ask] for its final Run, or
+  # the streaming entrypoint[rdoc-ref:LittleGhost::Assembly.stream_ask] for live
+  # events.
   #
   # +invoke+ returns a lazy Workflow::Invocation. Reading +output+ consumes an
   # intermediate invocation and returns RunResult#output; +perform+ must return
   # its final invocation without consuming it so those events reach the caller.
   # Intermediate usage is added to the final result.
   #
-  # Every child inherits input, history, settings, cancellation, deadline,
-  # template paths, and trace parentage unless +invoke+ overrides its input.
-  # JSON-like context is copied for each child, preventing one intermediate agent
-  # from mutating a sibling's state. Non-JSON-like workflow context raises
-  # ArgumentError.
+  # A child receives the Workflow input unless +invoke+ supplies another one.
+  # It also inherits history, settings, cancellation, deadline, template paths,
+  # and the parent tracing relationship. JSON-like context is copied for each
+  # child, preventing one intermediate Agent from mutating a sibling's state.
+  # Non-JSON-like workflow context raises ArgumentError.
   #
-  # A workflow instance streams once. Returning the wrong value, returning an
-  # already consumed invocation, or consuming an invocation twice raises
-  # ProtocolError. Each child assembly closes after its execution attempt;
-  # cleanup failures surface from that attempt. Closing the Workflow closes its
-  # lightweight invocation wrappers in reverse declaration order. Composition
-  # errors emit an +invocation_error+ event and then re-raise.
+  # A Workflow instance streams once. Returning the wrong value, returning an
+  # already consumed invocation, or consuming one twice raises ProtocolError.
+  # A composition error fails the owning top-level Run. Each child Assembly
+  # closes after its attempt, and a cleanup failure raises from that attempt.
   class Workflow < Assembly
-    # Hold one lazy agent call inside a workflow composition.
+    # Hold one lazy Assembly call inside a workflow composition.
     # Workflow implementations normally use only its output method or return the
     # object as the final invocation.
     class Invocation
@@ -126,8 +127,10 @@ module LittleGhost
       end
     end
 
-    # Owning run and the runtime used to resolve workflow agents.
-    attr_reader :run, :runtime
+    # Run that owns this run-scoped Workflow.
+    attr_reader :run
+    # Runtime used to resolve child Assemblies.
+    attr_reader :runtime
 
     def initialize(run: nil, runtime: nil) # :nodoc:
       super(run:, runtime:, standalone: run.nil?)
@@ -269,7 +272,9 @@ module LittleGhost
     # Creates a lazy invocation for +assembly+.
     #
     # Intermediate calls may use +output+; the final call must be returned from
-    # +perform+ without being consumed.
+    # +perform+ without being consumed. +as+ supplies the participant name used
+    # in steps and telemetry. Retries default to zero; a positive +retries+
+    # value requires explicit exception classes in +retry_on+.
     def invoke(
       assembly,
       as: nil,
@@ -299,8 +304,12 @@ module LittleGhost
       invocation
     end
 
+    # :doc:
     # Consumes independent invocations concurrently and returns their outputs in
     # declaration order.
+    #
+    # +max_concurrency+ bounds active child executions. A child failure cancels
+    # siblings cooperatively before the error is raised.
     def parallel(*invocations, max_concurrency: 8)
       raise ArgumentError, "parallel requires at least one invocation" if invocations.empty?
       unless invocations.all? { |invocation| invocation.is_a?(Invocation) && !invocation.consumed? }

data/lib/little_ghost.rb

@@ -4,6 +4,7 @@ require_relative "little_ghost/version"
 require_relative "little_ghost/errors"
 require_relative "little_ghost/execution_state"
 require_relative "little_ghost/support"
+require_relative "little_ghost/data_map"
 require_relative "little_ghost/events"
 require_relative "little_ghost/instrumentation"
 require_relative "little_ghost/tracing/open_telemetry"
@@ -50,6 +51,7 @@ require_relative "little_ghost/structured_output"
 require_relative "little_ghost/prompt_resolver"
 require_relative "little_ghost/session_store"
 require_relative "little_ghost/session_stores/memory"
+require_relative "little_ghost/session_stores/filesystem"
 require_relative "little_ghost/session"
 require_relative "little_ghost/skills"
 require_relative "little_ghost/tools/write_todos"
@@ -58,7 +60,7 @@ require_relative "little_ghost/execution"
 require_relative "little_ghost/subagents/definition"
 require_relative "little_ghost/subagents/agent_path"
 require_relative "little_ghost/subagents/manager"
-require_relative "little_ghost/agent_interruptions"
+require_relative "little_ghost/agent_interjections"
 require_relative "little_ghost/assembly"
 require_relative "little_ghost/assembly_execution"
 require_relative "little_ghost/agent"
@@ -70,39 +72,32 @@ require_relative "little_ghost/agent_factory"
 require_relative "little_ghost/runtime/hook"
 require_relative "little_ghost/runtime"
 
-# Build AI features with reusable agents and composable assemblies. LittleGhost can
-# sit inside an existing Ruby system or support a dedicated AI service, keeping
-# models, prompts, tools, sessions, streaming, and instrumentation behind a
-# cohesive set of Ruby conventions.
+# LittleGhost is a Ruby library for building AI features with reusable agents
+# and composable assemblies. It can sit inside an existing Ruby system or
+# support a dedicated AI service.
 #
-# A customer support agent can answer directly, use an application tool, or ask a
-# specialist for research while the caller observes one run:
-#
-#   class ResearchAgent < LittleGhost::Agent
-#     description "Researches difficult support questions"
-#     model "openai:gpt-5.6-luna"
-#   end
+# Start with one model-driven behavior:
 #
 #   class CustomerSupportAgent < LittleGhost::Agent
 #     description "Handles support requests"
-#     model "openai:gpt-5.6-luna"
-#     tools AccountTool
-#     subagent ResearchAgent, kind: "research"
+#     model "openrouter:openai/gpt-5.6-luna"
+#     system_prompt "Answer customer questions clearly."
 #   end
 #
 #   run = CustomerSupportAgent.ask("Why is transfer 481 still pending?")
 #   run.completed? # => true
-#   run.response   # => "Transfer 481 is waiting for the receiving bank."
+#   run.response
+#   # One possible response: Transfer 481 is waiting for the receiving bank.
 #
-# Agent subclasses hold reusable behavior; Invocation objects carry one request,
-# and Run objects own execution and cleanup. Assembly gives Agent, Workflow,
-# Swarm, and Graph the same caller interface while each type owns a different
-# coordination policy.
+# Agent subclasses hold reusable behavior, Invocation objects carry one request,
+# and Run objects own execution and cleanup. When one model loop is not enough,
+# Assembly gives Agent, Workflow, Swarm, and Graph the same caller interface
+# while each type owns a different coordination policy.
 #
 # LittleGhost.configuration is process-wide unless LittleGhost.with_configuration
-# supplies an execution-scoped replacement. Configuration is loaded lazily and
-# snapshotted into a Runtime, so make application changes before the first agent
-# runtime is built.
+# supplies an execution-scoped replacement. The first standalone call lazily
+# builds one shared Runtime from that configuration, so make application changes
+# before invoking an Agent or Assembly.
 module LittleGhost
   class << self
     # The configuration active in the current execution context, falling back to
@@ -114,15 +109,24 @@ module LittleGhost
     # Opens the active Configuration for application setup and returns it.
     #
     # Configuration files are loaded lazily when a runtime is first built, so
-    # make application-level changes before invoking an agent.
+    # make application-level changes before invoking an agent. Once the shared
+    # Runtime is ready, later mutations raise ConfigurationError.
     def configure(&block)
       configuration.configure(&block)
     end
 
+    # Returns the shared Runtime for the active Configuration.
+    #
+    # Most applications do not need to call this method. Standalone Agent and
+    # Assembly entrypoints use it automatically. Runtime construction is lazy,
+    # thread-safe, and locks the active Configuration after it succeeds.
+    def runtime = configuration.runtime
+
     # Returns the model resolver owned by the active process configuration.
     def model_resolver = configuration.model_resolver
 
-    # Makes +configuration+ current only while the block runs.
+    # Makes +configuration+ and its independent shared Runtime current only
+    # while the block runs.
     #
     # Execution state restores the previous configuration even when the block
     # raises. Other execution contexts continue to see their own configuration.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: little_ghost
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Matt Robinson
@@ -117,8 +117,11 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- docs/guides/assemblies.md
 - docs/guides/core_concepts.md
 - docs/guides/getting_started.md
+- docs/guides/production.md
+- docs/guides/prompt_views.md
 - lib/little_ghost.rb
 - lib/little_ghost/ag_ui.rb
 - lib/little_ghost/ag_ui/adapter.rb
@@ -129,13 +132,14 @@ files:
 - lib/little_ghost/agent/tool_loop.rb
 - lib/little_ghost/agent_builder.rb
 - lib/little_ghost/agent_factory.rb
-- lib/little_ghost/agent_interruptions.rb
+- lib/little_ghost/agent_interjections.rb
 - lib/little_ghost/assembly.rb
 - lib/little_ghost/assembly_builder.rb
 - lib/little_ghost/assembly_execution.rb
 - lib/little_ghost/configuration.rb
 - lib/little_ghost/content.rb
 - lib/little_ghost/data/model_catalog.json
+- lib/little_ghost/data_map.rb
 - lib/little_ghost/errors.rb
 - lib/little_ghost/events.rb
 - lib/little_ghost/execution.rb
@@ -188,6 +192,7 @@ files:
 - lib/little_ghost/session.rb
 - lib/little_ghost/session_store.rb
 - lib/little_ghost/session_stores/agent_core_memory.rb
+- lib/little_ghost/session_stores/filesystem.rb
 - lib/little_ghost/session_stores/memory.rb
 - lib/little_ghost/skills.rb
 - lib/little_ghost/skills/catalog.rb