little_ghost 0.7.0 → 0.9.0

data/lib/little_ghost/agent_builder.rb

@@ -104,12 +104,20 @@ module LittleGhost
       tools = []
       agent_class.assembly_tool_declarations.each do |declaration|
         child = declared_assembly(declaration, run, agent_stream_path:)
+        factory = if !declaration.fetch(:preserve_context) && child.is_a?(Agent)
+          -> { declared_assembly(declaration, run, agent_stream_path:) }
+        end
         begin
-          tools << child.as_tool(
+          options = {
             name: declaration.fetch(:name),
             description: declaration.fetch(:description),
             preserve_context: declaration.fetch(:preserve_context)
-          )
+          }
+          tools << if factory
+            child.as_tool_with_factory(**options, factory:)
+          else
+            child.as_tool(**options)
+          end
         rescue
           child.close
           raise
@@ -123,8 +131,12 @@ module LittleGhost
 
     def declared_assembly(declaration, run, agent_stream_path:)
       assembly_class = declaration.fetch(:assembly)
-      if assembly_class.is_a?(AssemblyDefinition) && assembly_class.kind == :agent
-        declared_agent(declaration.merge(agent: assembly_class.implementation), run, agent_stream_path:)
+      if assembly_class.is_a?(AssemblyDefinition)
+        if assembly_class.kind == :agent
+          declared_agent(declaration.merge(agent: assembly_class.implementation), run, agent_stream_path:)
+        else
+          runtime.build_assembly(assembly_class, run:, agent_stream_path:)
+        end
       elsif assembly_class <= Agent
         declared_agent(declaration.merge(agent: assembly_class), run, agent_stream_path:)
       else

data/lib/little_ghost/artifacts/workspace_store.rb

@@ -59,7 +59,7 @@ module LittleGhost
         max_total_bytes: DEFAULT_MAX_TOTAL_BYTES,
         max_artifacts: DEFAULT_MAX_ARTIFACTS
       )
-        raise ToolError, "Artifact workspace path is unavailable" unless workspace
+        raise ToolError, FrameworkPrompts.reference("artifacts/storage/errors/workspace_unavailable") unless workspace
 
         @workspace = workspace
         @path = path.to_sym
@@ -125,7 +125,7 @@ module LittleGhost
 
         data = String(entry.fetch(:data)).b
         if data.bytesize > @max_artifact_bytes
-          raise ToolError, "Artifact exceeds the #{@max_artifact_bytes}-byte limit"
+          raise ToolError, FrameworkPrompts.reference("artifacts/storage/feedback/too_large", maximum: @max_artifact_bytes)
         end
         media_type = entry[:media_type]
         name = normalized_name(entry[:name], media_type:)
@@ -166,9 +166,11 @@ module LittleGhost
       end
 
       def reserve!(bytes)
-        raise ToolError, "Artifact count exceeds the #{@max_artifacts}-item limit" if @artifacts.length >= @max_artifacts
+        if @artifacts.length >= @max_artifacts
+          raise ToolError, FrameworkPrompts.reference("artifacts/storage/feedback/count_limit", maximum: @max_artifacts)
+        end
         if @total_bytes + bytes > @max_total_bytes
-          raise ToolError, "Artifacts exceed the #{@max_total_bytes}-byte total limit"
+          raise ToolError, FrameworkPrompts.reference("artifacts/storage/feedback/total_limit", maximum: @max_total_bytes)
         end
 
         @total_bytes += bytes
@@ -200,9 +202,9 @@ module LittleGhost
           metadata:
         )
       rescue Errno::EEXIST
-        raise ToolError, "Artifact destination already exists"
+        raise ToolError, FrameworkPrompts.reference("artifacts/storage/feedback/destination_exists")
       rescue Errno::ELOOP
-        raise ToolError, "Artifact destination is unsafe"
+        raise ToolError, FrameworkPrompts.reference("artifacts/storage/errors/destination_unsafe")
       rescue => error
         cleanup_created_file(directory, file_name, error:) if created
         raise
@@ -241,7 +243,7 @@ module LittleGhost
 
       def validate_root!
         unless OPENAT && UNLINKAT
-          raise ToolError, "Secure artifact storage is unavailable on this platform"
+          raise ToolError, FrameworkPrompts.reference("artifacts/storage/errors/secure_unavailable")
         end
 
         @workspace.validate!
@@ -251,20 +253,20 @@ module LittleGhost
         workspace_real = File.realpath(@workspace.root)
         location_safe = !beneath?(root, @workspace.root) || beneath?(real, workspace_real)
         unless stat.directory? && !stat.symlink? && location_safe
-          raise ToolError, "Artifact workspace path is unsafe"
+          raise ToolError, FrameworkPrompts.reference("artifacts/storage/errors/workspace_unsafe")
         end
 
         directory = File.open(root, directory_flags)
         descriptor_stat = directory.stat
         unless descriptor_stat.directory?
-          raise ToolError, "Artifact workspace path is unsafe"
+          raise ToolError, FrameworkPrompts.reference("artifacts/storage/errors/workspace_unsafe")
         end
         @workspace.validate!
         [root.freeze, [descriptor_stat.dev, descriptor_stat.ino].freeze].freeze
       rescue KeyError, Errno::ENOENT, Errno::ENOTDIR
-        raise ToolError, "Artifact workspace path is unavailable"
+        raise ToolError, FrameworkPrompts.reference("artifacts/storage/errors/workspace_unavailable")
       rescue SystemCallError
-        raise ToolError, "Artifact workspace path is unavailable"
+        raise ToolError, FrameworkPrompts.reference("artifacts/storage/errors/workspace_unavailable")
       ensure
         directory&.close
       end
@@ -274,13 +276,13 @@ module LittleGhost
         directory = File.open(@root, directory_flags)
         stat = directory.stat
         unless stat.directory? && [stat.dev, stat.ino] == @root_identity
-          raise ToolError, "Artifact workspace path changed after initialization"
+          raise ToolError, FrameworkPrompts.reference("artifacts/storage/errors/workspace_changed")
         end
         @workspace.validate!
         directory
       rescue Errno::ENOENT, Errno::ELOOP, Errno::ENOTDIR
         directory&.close
-        raise ToolError, "Artifact workspace path changed after initialization"
+        raise ToolError, FrameworkPrompts.reference("artifacts/storage/errors/workspace_changed")
       rescue
         directory&.close
         raise
@@ -308,7 +310,7 @@ module LittleGhost
       def validate_regular_file!(file)
         stat = file.stat
         unless stat.file? && stat.nlink == 1 && (stat.mode & 0o777) == 0o600
-          raise ToolError, "Artifact destination is unsafe"
+          raise ToolError, FrameworkPrompts.reference("artifacts/storage/errors/destination_unsafe")
         end
       end
 

data/lib/little_ghost/assembly.rb

@@ -50,7 +50,8 @@ module LittleGhost
       # +context+, +settings+, +metadata+, +session_id+, +actor_id+, and
       # +deadline_at+.
       def ask(message, **options)
-        definition.implementation.new.ask(message, **options)
+        snapshot = definition
+        snapshot.implementation.new.bind_assembly_definition(snapshot).ask(message, **options)
       end
 
       # Lazily streams +message+ through a fresh standalone assembly.
@@ -66,7 +67,7 @@ module LittleGhost
         snapshot = definition
         stream = nil
         Enumerator.new do |events|
-          stream ||= snapshot.implementation.new.stream_ask(message, **options)
+          stream ||= snapshot.implementation.new.bind_assembly_definition(snapshot).stream_ask(message, **options)
           stream.each { |event| events << event }
         end
       end
@@ -157,6 +158,7 @@ module LittleGhost
       @runtime = runtime || run&.runtime || LittleGhost.runtime
       @workspace = workspace || run&.workspace
       @sandbox = sandbox || run&.sandbox
+      @assembly_definition = nil
       @standalone = standalone
       @assembly_mutex = Mutex.new
       @assembly_closed = false
@@ -169,6 +171,11 @@ module LittleGhost
       self
     end
 
+    def bind_assembly_definition(definition) # :nodoc:
+      @assembly_definition = definition
+      self
+    end
+
     # Builds the top-level Run used by a standalone assembly.
     def build_run(payload = nil, include_agent_events_by_default: false, **payload_options) # :nodoc:
       payload = entrypoint_payload(payload, payload_options) unless payload_options.empty?
@@ -178,7 +185,8 @@ module LittleGhost
       end
       source_class = run_entrypoint_class
       options = {entrypoint_class: source_class}
-      options[:execution_class] = self.class unless source_class.equal?(self.class)
+      execution = @assembly_definition || self.class
+      options[:execution_class] = execution unless source_class.equal?(execution)
       options[:agent_class] = source_class if is_a?(Agent)
       options[:cancellation_token] = cancellation_token if cancellation_token
       options[:workspace] = workspace if workspace
@@ -248,9 +256,37 @@ module LittleGhost
     # the invoking Tool's current RunContext#state, which may include current
     # request values or values restored from a Session. Nested tools must still
     # authorize privileged work with current, application-established values.
+    # A directly bound Agent remains the target for every call, so overlapping
+    # calls raise AgentBusyError. Class-level Agent#agent_as_tool declarations
+    # build a fresh Agent per context-free call.
     def as_tool(name: self.class.assembly_id, description: self.class.description, preserve_context: false)
+      build_tool(name:, description:, preserve_context:, factory: nil)
+    end
+
+    def as_tool_with_factory(name:, description:, preserve_context:, factory:) # :nodoc:
+      first_target = self
+      first_target_mutex = Mutex.new
+      target_factory = lambda do
+        first_target_mutex.synchronize do
+          target = first_target
+          first_target = nil
+          target
+        end || factory.call
+      end
+      build_tool(name:, description:, preserve_context:, factory: target_factory)
+    end
+
+    private
+
+    def build_tool(name:, description:, preserve_context:, factory:)
       assembly = self
-      description = "Delegate a task to #{name}." if description.to_s.empty?
+      if description.to_s.empty?
+        description = if is_a?(Agent)
+          render_framework_prompt("assembly/tools/fallback/description", name: name.to_s)
+        else
+          FrameworkPrompts.for_runtime(runtime).render("assembly/tools/fallback/description", locals: {name: name.to_s})
+        end
+      end
       mutex = Mutex.new
       retained_history = []
       tool_class = Tool.define(
@@ -264,7 +300,10 @@ module LittleGhost
         }
       ) do |input, context: nil|
         invocation = lambda do
-          target = if assembly.is_a?(Agent)
+          factory_target = !factory.nil?
+          target = if factory_target
+            factory.call
+          elsif assembly.is_a?(Agent)
             assembly
           elsif assembly.run
             assembly.send(:build_tool_assembly)
@@ -293,7 +332,7 @@ module LittleGhost
           retained_history.replace(result.messages.reject { |message| message.role == :system }) if preserve_context
           result.structured? ? result.structured_result.value : result.text
         ensure
-          target&.close unless target.equal?(assembly)
+          target&.close if factory_target || !target.equal?(assembly)
         end
         preserve_context ? mutex.synchronize(&invocation) : invocation.call
       end
@@ -308,6 +347,8 @@ module LittleGhost
       ))
     end
 
+    public
+
     # Adds an interjection to the single active leaf Agent.
     def interject(message, **options)
       child = @assembly_mutex.synchronize do
@@ -377,7 +418,7 @@ module LittleGhost
     end
 
     def build_tool_assembly
-      child = runtime.build_assembly(self.class, run:, agent_stream_path:)
+      child = runtime.build_assembly(@assembly_definition || self.class, run:, agent_stream_path:)
       child.bind_agent_stream_path(agent_stream_path)
       child
     end

data/lib/little_ghost/assembly_builder.rb

@@ -123,7 +123,7 @@ module LittleGhost
       snapshot = definition
       return (runtime || run.runtime).build_assembly(snapshot, run:) if run
 
-      snapshot.implementation.new(runtime:)
+      snapshot.implementation.new(runtime:).bind_assembly_definition(snapshot)
     end
 
     # Executes the current declarations and returns their Run.
@@ -133,7 +133,7 @@ module LittleGhost
     def stream_ask(message, **options)
       snapshot = definition
       Enumerator.new do |events|
-        snapshot.implementation.new(runtime:).stream_ask(message, **options).each { |event| events << event }
+        snapshot.implementation.new(runtime:).bind_assembly_definition(snapshot).stream_ask(message, **options).each { |event| events << event }
       end
     end
 
@@ -263,7 +263,7 @@ module LittleGhost
   class AgentBuilder < AssemblyBuilder
     DECLARATIONS = %i[
       model limits result_schema capture_diagnostics system_template system_prompt
-      tools prompt_local after_initialize before_invocation after_invocation
+      tools after_initialize before_invocation after_invocation
       before_model after_model after_model_error before_tool after_tool
       manage_context detect_tool_loops skills subagent subagents
       subagent_long_poll_duration agent_as_tool agents_as_tools