little_ghost 0.4.0 → 0.5.0

data/lib/little_ghost/agent.rb

@@ -45,10 +45,6 @@ module LittleGhost
   # as skills, context management, loop detection, and delegation stay inactive
   # until their DSL is used.
   #
-  # Calling LittleGhost::Agent itself uses <tt>You are a helpful agent.</tt> as
-  # the system prompt. Subclasses use the inline or conventional prompt they
-  # declare.
-  #
   # Models may return text or locally validated structured data. LittleGhost
   # hides unexpected Tool exception messages from the model. See
   # Run[rdoc-ref:LittleGhost::Run] for outcomes, cancellation, and cleanup, and
@@ -69,9 +65,12 @@ module LittleGhost
       before_model after_model after_model_error
       before_tool after_tool
     ].freeze # :nodoc:
-    ExecutedTool = Data.define(:result, :companion_content) do # :nodoc:
+    ExecutedTool = Data.define(:result, :execution_result) do # :nodoc:
       def status = result.status
       def content = result.content
+      def value = execution_result.value
+      def artifacts = execution_result.artifacts
+      def presentation_content = execution_result.presentation_content
     end
 
     extend Support::ClassAttributes
@@ -84,6 +83,7 @@ module LittleGhost
     class_attribute :system_prompt_value
     class_attribute :system_prompt_builder_value
     class_attribute :tool_declarations_value, default: []
+    class_attribute :code_mode_configuration_value
     class_attribute :prompt_local_values, default: {}
     class_attribute :callback_values, default: Support::Callbacks.new(*CALLBACKS)
 
@@ -254,8 +254,9 @@ module LittleGhost
 
       # Adds tool or provider classes to the agent.
       #
-      # Every declaration must be a class. A provider class can supply tools
-      # dynamically by implementing <tt>tools(binding)</tt>.
+      # Every declaration must be a class. Pass Tool classes directly, or pass
+      # provider classes that supply tools dynamically through
+      # <tt>tools(binding)</tt>. Multiple declarations are cumulative.
       def tools(*values)
         invalid = values.flatten.compact.find { |value| !value.is_a?(Class) }
         if invalid
@@ -269,6 +270,20 @@ module LittleGhost
 
       def tool_declarations = tool_declarations_value # :nodoc:
 
+      # Enables code mode for this agent. +except+ names the application Tools
+      # that remain model-facing; every other application Tool moves into the
+      # engine catalog and is called through the parent-process Broker.
+      # Framework-owned subagent controls remain model-facing automatically.
+      def code_mode(engine: nil, except: nil, **options)
+        unknown = options.keys - %i[sandbox limits]
+        raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
+
+        declaration = options.merge(engine:, except:).compact
+        self.code_mode_configuration_value = declaration.freeze
+      end
+
+      def code_mode_configuration = code_mode_configuration_value # :nodoc:
+
       # Adds a named value or resolver to every prompt rendered for the agent.
       def prompt_local(name, *values, &resolver)
         raise ArgumentError, "Provide a prompt local value or block" if values.empty? && !resolver
@@ -300,8 +315,9 @@ module LittleGhost
       ##
       # Runs before one invocation begins.
       #
-      # The payload may be continued, replaced, or cancelled with a decision
-      # from Support::Callbacks.
+      # The payload is <tt>{messages: Array<Message>}</tt>. A replacement must
+      # contain +:messages+. Cancellation stops the invocation. A callback may
+      # also accept <tt>context:</tt> to receive the current RunContext.
       #
       # :singleton-method: before_invocation
       # :call-seq:
@@ -310,6 +326,10 @@ module LittleGhost
       ##
       # Observes or transforms the terminal invocation payload.
       #
+      # The payload is <tt>{result: RunResult}</tt>. A replacement must contain
+      # +:result+. Cancellation stops result delivery. A callback may accept
+      # <tt>context:</tt>.
+      #
       # :singleton-method: after_invocation
       # :call-seq:
       #   after_invocation(callable = nil, prepend: false) { |payload| ... } -> self
@@ -317,6 +337,11 @@ module LittleGhost
       ##
       # Runs before a model request is sent.
       #
+      # The payload contains +:request+ (ModelRequest), zero-based +:turn+, and
+      # +:parent_operation_id+. A replacement must contain +:request+.
+      # Cancellation stops the invocation. A callback may accept
+      # <tt>context:</tt>.
+      #
       # :singleton-method: before_model
       # :call-seq:
       #   before_model(callable = nil, prepend: false) { |payload| ... } -> self
@@ -324,6 +349,11 @@ module LittleGhost
       ##
       # Observes or transforms a successful model response.
       #
+      # The payload contains +:request+, +:response+ (ModelResponse), and
+      # zero-based +:turn+. A replacement must contain +:response+.
+      # Cancellation stops the invocation. A callback may accept
+      # <tt>context:</tt>.
+      #
       # :singleton-method: after_model
       # :call-seq:
       #   after_model(callable = nil, prepend: false) { |payload| ... } -> self
@@ -331,6 +361,11 @@ module LittleGhost
       ##
       # Handles a model error before it leaves the agent loop.
       #
+      # The payload contains +:request+, +:error+, zero-based +:turn+, and
+      # +:parent_operation_id+. Replacing +:request+ with a ModelRequest retries
+      # the model call, up to the framework recovery limit. Cancellation stops
+      # the invocation. A callback may accept <tt>context:</tt>.
+      #
       # :singleton-method: after_model_error
       # :call-seq:
       #   after_model_error(callable = nil, prepend: false) { |payload| ... } -> self
@@ -338,6 +373,11 @@ module LittleGhost
       ##
       # Runs after validation but before a tool call starts.
       #
+      # The payload contains +:tool_use+, the bound +:tool+, +:operation_id+,
+      # and +:parent_operation_id+. Cancellation returns a model-visible Tool
+      # error, so its reason must be safe to disclose. Replacements are not
+      # consumed. A callback may accept <tt>context:</tt>.
+      #
       # :singleton-method: before_tool
       # :call-seq:
       #   before_tool(callable = nil, prepend: false) { |payload| ... } -> self
@@ -345,6 +385,10 @@ module LittleGhost
       ##
       # Observes or transforms a completed tool result.
       #
+      # The payload contains the before-tool fields plus the normalized
+      # +:result+. A replacement must contain +:result+.
+      # Cancellation is not consumed. A callback may accept <tt>context:</tt>.
+      #
       # :singleton-method: after_tool
       # :call-seq:
       #   after_tool(callable = nil, prepend: false) { |payload| ... } -> self
@@ -539,6 +583,7 @@ module LittleGhost
       self.class.tool_declarations.each do |declaration|
         @tool_registry.register(declaration, replace: true)
       end
+      initialize_code_mode
       @structured_output_strategy = StructuredOutput.resolve(
         self.class.result_schema,
         model:,
@@ -564,9 +609,13 @@ module LittleGhost
       raise ArgumentError, "max_turns must be at least 1" if @max_turns < 1
       raise ArgumentError, "max_tool_calls must be at least 1" if @max_tool_calls < 1
       raise ArgumentError, "max_tool_result_tokens must be at least 1" if @max_tool_result_tokens < 1
+      @artifact_lifecycle = if runtime&.respond_to?(:runtime_hooks)
+        runtime.runtime_hooks.find { |hook| hook.is_a?(Runtime::Hooks::Artifacts) }
+      end
       apply_cancellation_decision!(run_callbacks(:after_initialize, self))
     rescue
       @tool_registry&.close
+      @code_mode_runtime&.close
       raise
     end
 
@@ -576,7 +625,19 @@ module LittleGhost
     def entrypoint_name = self.class.agent_id # :nodoc:
 
     def dispatch_tools(tool_uses, context:, events:, parent_operation_id:, parent_trace_context: nil) # :nodoc:
-      execute_tools(tool_uses, context, events, parent_operation_id:, parent_trace_context:)
+      counted = tool_uses.count { |tool_use| !code_mode_control_tool?(tool_use) }
+      context.record_tool_calls!(counted, maximum: @max_tool_calls) if counted.positive?
+      execute_tools(
+        tool_uses,
+        context,
+        events,
+        parent_operation_id:,
+        parent_trace_context:
+      )
+    end
+
+    def code_mode_runtime # :nodoc:
+      @code_mode_runtime || raise(ConfigurationError, "code mode is not enabled for this agent")
     end
 
     def request_assembly_transition(value, context:) # :nodoc:
@@ -668,9 +729,9 @@ module LittleGhost
     # Streams one invocation as StreamEvent objects.
     #
     # Agents built inside a run accept history, JSON-like context, cancellation,
-    # deadlines, settings, and trusted invocation template paths. An agent
-    # instance may be streamed only according to the lifecycle managed by its
-    # owning run. Every template path must be an application-created TrustedPath;
+    # deadlines, settings, and trusted invocation template paths. An Agent
+    # instance may be streamed only by its owning Run. Every template path must
+    # be an application-created TrustedPath;
     # the wrapper records a trust decision and must never contain unchecked
     # request or model input.
     def stream(
@@ -747,6 +808,7 @@ module LittleGhost
           interjections.close(error)
           raise
         ensure
+          @code_mode_runtime&.close(context: run_context)
           interjections.close(AgentInterjectionError.new("Agent finished before the interjection was delivered"))
           unregister_interjections(interjections)
         end
@@ -765,7 +827,7 @@ module LittleGhost
       end.freeze
     end
 
-    # The materialized tools available during this agent run.
+    # The Tool registry available during this Agent run.
     def tools = tool_registry
 
     # Closes owned tools, interjections, sandbox, and workspace resources.
@@ -776,7 +838,7 @@ module LittleGhost
 
         @closed = true
         [
-          [tool_registry, (@sandbox if @owns_resources), (@workspace if @owns_resources)],
+          [@code_mode_runtime, tool_registry, (@sandbox if @owns_resources), (@workspace if @owns_resources)],
           @interjections_mutex.synchronize { @active_interjections.dup }
         ]
       end
@@ -805,7 +867,15 @@ module LittleGhost
     # Returns the tools exposed to the model for +turn+. Subclasses may override
     # this hook to filter the already-authorized tool list.
     def model_tools(tools, context:, turn:)
-      tools
+      return tools unless @code_mode_runtime
+
+      exceptions = Array(@code_mode_declaration[:except]).map(&:to_s)
+      tools.select do |specification|
+        name = specification.fetch(:name, specification["name"]).to_s
+        tool = tool_registry.fetch(name) if tool_registry.names.include?(name)
+        exceptions.include?(name) || %w[exec wait stop].include?(name) ||
+          tool.is_a?(Subagents::ControlTool) || !tool
+      end
     end
 
     # :doc:
@@ -906,6 +976,12 @@ module LittleGhost
     )
       started_at = monotonic_time
       operation_id = SecureRandom.uuid
+      events = agent_stream_events(
+        events,
+        input:,
+        operation_id:,
+        parent_operation_id:
+      )
       context.bind_agent_operation_id(operation_id)
       @assembly_transitions_mutex.synchronize { @assembly_transition = nil }
       interjections.bind(operation_id, target_operation_id: parent_operation_id)
@@ -923,7 +999,6 @@ module LittleGhost
       prompt = rendered_system_prompt(template_locals, template_paths)
       messages.unshift(Message.new(role: :system, content: prompt)) unless prompt.to_s.empty?
       messages << (input.is_a?(Message) ? input : Message.new(role: :user, content: input))
-      tool_call_count = 0
       structured_result_repair_due = false
 
       decision = run_callbacks(:before_invocation, {messages: messages}, context: context)
@@ -951,7 +1026,7 @@ module LittleGhost
             structured_result_repair_due:,
             interjections:
           )
-          messages.reject! { |message| tool_companion_message?(message) }
+          messages.reject! { |message| artifact_presentation_message?(message) }
           messages << response.message
           tool_uses = response.message.content.grep(Content::ToolUse)
           result_tool_uses = structured_result_tool_uses(tool_uses)
@@ -1140,9 +1215,6 @@ module LittleGhost
             )
           end
 
-          tool_call_count += tool_uses.length
-          raise ProtocolError, "The agent reached its maximum tool calls" if tool_call_count > @max_tool_calls
-
           executed_tools = with_assembly_tool_batch(context, tool_uses.length) do
             dispatch_tools(
               tool_uses,
@@ -1153,15 +1225,16 @@ module LittleGhost
           end
           messages << Message.new(
             role: :tool,
-            content: executed_tools.map(&:result)
+            content: executed_tools.map(&:result),
+            metadata: artifact_message_metadata(executed_tools)
           )
           executed_tools.each do |executed_tool|
-            next if executed_tool.companion_content.empty?
+            next if executed_tool.presentation_content.empty?
 
             messages << Message.new(
               role: :user,
-              content: executed_tool.companion_content,
-              metadata: {transient: true, little_ghost_tool_companion: true}
+              content: executed_tool.presentation_content,
+              metadata: {transient: true, little_ghost_artifact_presentation: true}
             )
           end
           context.checkpoint(messages)
@@ -1328,6 +1401,7 @@ module LittleGhost
       response = nil
       time_to_first_token = nil
       buffered_events = strategy ? [] : nil
+      code_mode_control_indexes = {}
 
       model.stream(request).each do |event|
         context.check!
@@ -1348,7 +1422,9 @@ module LittleGhost
             **model_attributes
           )
         end
-        buffered_events ? buffered_events << event : events << event
+        unless code_mode_control_event?(event, code_mode_control_indexes)
+          buffered_events ? buffered_events << event : events << event
+        end
         response = event.data[:response] if event.type == :message_stop
       end
       raise ProtocolError, "The model stream ended without a response" unless response
@@ -1471,7 +1547,8 @@ module LittleGhost
         raise ProtocolError, "The model returned duplicate tool use ids"
       end
 
-      tool_uses.each { |tool_use| emit(events, :tool_start, tool_use: tool_use) }
+      tool_uses.each { |tool_use| emit(events, :tool_start, tool_use: tool_use) unless code_mode_control_tool?(tool_use) }
+      presentation_budget = Artifacts::PresentationBudget.new
       pairs = tool_uses.map do |tool_use|
         [tool_use, tool_registry.fetch(tool_use.name)]
       rescue ToolError => error
@@ -1510,7 +1587,8 @@ module LittleGhost
               exception: diagnostic_tool_exception(tool, tool:)
             }
           )
-          next ExecutedTool.new(result:, companion_content: [])
+          execution_result = Tool::ExecutionResult.new(content: result.content, status: :error, error: tool)
+          next ExecutedTool.new(result:, execution_result:)
         end
 
         context.check!
@@ -1542,7 +1620,8 @@ module LittleGhost
               exception: diagnostic_tool_exception(rejection, tool:)
             }
           )
-          next ExecutedTool.new(result:, companion_content: [])
+          execution_result = Tool::ExecutionResult.new(content: result.content, status: :error, error: rejection)
+          next ExecutedTool.new(result:, execution_result:)
         end
 
         execution_context = ToolExecution.new(
@@ -1555,20 +1634,36 @@ module LittleGhost
           parent_trace_context:
         )
         invoke = lambda do
-          with_tool_execution(execution_context) do
-            invoke_tool(
-              tool_use, tool, context,
-              operation_id:, parent_operation_id:
-            )
+          ExecutionState.with(tool_execution: execution_context) do
+            with_tool_execution(execution_context) do
+              invoke_tool(
+                tool_use, tool, context,
+                operation_id:, parent_operation_id:
+              )
+            end
           end
         end
-        tool_result = tool.exclusive? ? synchronize_exclusive_tools(&invoke) : invoke.call
+        tool_result = if tool.exclusive? && !code_mode_control_tool?(tool_use)
+          synchronize_exclusive_tools(&invoke)
+        else
+          invoke.call
+        end
         after_decision = run_callbacks(
           :after_tool,
           callback_payload.merge(result: tool_result),
           context: context
         )
         tool_result = replacement_value(after_decision, :result, tool_result)
+        if @artifact_lifecycle
+          tool_result = @artifact_lifecycle.prepare_tool_result(
+            tool_result,
+            tool_use:,
+            run: @run,
+            workspace:,
+            context:
+          )
+        end
+        tool_result = bound_artifact_presentation(tool_result, presentation_budget)
         result = build_tool_result(
           tool_use_id: tool_use.id,
           content: tool_result.content,
@@ -1589,7 +1684,7 @@ module LittleGhost
             exception: tool_error && diagnostic_tool_exception(tool_error, tool:)
           }.compact
         )
-        ExecutedTool.new(result:, companion_content: tool_result.companion_content)
+        ExecutedTool.new(result:, execution_result: tool_result)
       rescue ToolError => error
         result = build_tool_result(tool_use_id: tool_use.id, content: error.message, status: :error)
         finish_instrumentation(
@@ -1605,7 +1700,8 @@ module LittleGhost
             exception: diagnostic_tool_exception(error, tool:)
           }
         )
-        ExecutedTool.new(result:, companion_content: [])
+        execution_result = Tool::ExecutionResult.new(content: result.content, status: :error, error:)
+        ExecutedTool.new(result:, execution_result:)
       rescue => error
         finish_instrumentation(
           tool_handle,
@@ -1622,7 +1718,7 @@ module LittleGhost
       if tools.any?(&:exclusive?)
         pairs.map do |tool_use, tool|
           executed_tool = execution.call(tool_use, tool)
-          emit(events, :tool_stop, tool_use:, result: executed_tool.result)
+          emit(events, :tool_stop, tool_use:, result: executed_tool.result) unless code_mode_control_tool?(tool_use)
           executed_tool
         end
       else
@@ -1630,7 +1726,8 @@ module LittleGhost
           pairs,
           cancellation_token: context.cancellation_token,
           on_result: lambda do |index, executed_tool|
-            emit(events, :tool_stop, tool_use: tool_uses.fetch(index), result: executed_tool.result)
+            tool_use = tool_uses.fetch(index)
+            emit(events, :tool_stop, tool_use:, result: executed_tool.result) unless code_mode_control_tool?(tool_use)
           end
         ) do |tool_use, tool|
           execution.call(tool_use, tool)
@@ -1638,10 +1735,82 @@ module LittleGhost
       end
     end
 
+    def bound_artifact_presentation(result, budget)
+      accepted = budget.accept(result.presentation_content)
+      return result if accepted.equal?(result.presentation_content) || accepted == result.presentation_content
+
+      fallback = result.artifacts.reject do |artifact|
+        artifact.metadata[:complete_result] || artifact.metadata["complete_result"]
+      end
+      references = artifact_references(fallback)
+      content = if references.empty?
+        result.content
+      else
+        "#{result.content}\n\nArtifacts:\n#{references.join("\n")}"
+      end
+
+      Tool::ExecutionResult.new(
+        value: result.value,
+        content:,
+        status: result.status,
+        error: result.error,
+        artifacts: result.artifacts,
+        presentation_content: accepted
+      )
+    end
+
+    def artifact_references(artifacts)
+      artifacts.filter_map do |artifact|
+        next unless artifact.reference.is_a?(String) && artifact.bytes
+
+        details = [artifact.media_type, "#{artifact.bytes} bytes"].compact.join(", ")
+        "- #{artifact.reference} (#{details})"
+      end
+    end
+
+    def artifact_message_metadata(executed_tools)
+      artifacts = executed_tools.flat_map(&:artifacts).select do |artifact|
+        artifact.reference.is_a?(String) && artifact.bytes
+      end
+      return {} if artifacts.empty?
+
+      {
+        "little_ghost_artifacts" => artifacts.map do |artifact|
+          {
+            "reference" => artifact.reference,
+            "name" => artifact.name,
+            "media_type" => artifact.media_type,
+            "bytes" => artifact.bytes
+          }.compact
+        end
+      }
+    end
+
     def invoke_tool(tool_use, tool, context, operation_id:, parent_operation_id:)
       tool.execute(tool_use.input, context:)
     end
 
+    def code_mode_control_tool?(tool_use)
+      @code_mode_runtime && %w[exec wait stop].include?(tool_use.name)
+    end
+
+    def code_mode_control_event?(event, indexes)
+      return false unless @code_mode_runtime
+
+      index = event.data[:index]
+      case event.type
+      when :tool_call_start
+        indexes[index] = true if %w[exec wait stop].include?(event.data[:name])
+        indexes.key?(index)
+      when :tool_call_delta
+        indexes.key?(index)
+      when :tool_call_stop
+        indexes.delete(index)
+      else
+        false
+      end
+    end
+
     def parent_trace_attributes(trace_context)
       return {} unless trace_context.is_a?(Hash) && !trace_context.empty?
 
@@ -1938,19 +2107,39 @@ module LittleGhost
 
     def rendered_system_prompt(locals, invocation_paths)
       prompt = self.class.system_prompt
-      return prompt.call(locals) if prompt.respond_to?(:call)
-      return prompt if prompt
+      prompt = prompt.call(locals) if prompt.respond_to?(:call)
+      return append_code_mode_instructions(prompt) if prompt
       template = self.class.system_template
-      return DEFAULT_SYSTEM_PROMPT if instance_of?(Agent) && run && !template
+      return append_code_mode_instructions(DEFAULT_SYSTEM_PROMPT) if instance_of?(Agent) && run && !template
 
       template ||= "#{self.class.logical_path}/system" if run
       return nil unless template
 
-      @template_resolver.render(
+      append_code_mode_instructions(@template_resolver.render(
         template,
         locals: locals,
         invocation_paths: invocation_paths
-      )
+      ))
+    end
+
+    def initialize_code_mode
+      declaration = self.class.code_mode_configuration
+      return unless declaration
+
+      defaults = @runtime.respond_to?(:code_mode_configuration) ? @runtime.code_mode_configuration : nil
+      @code_mode_declaration = (defaults || {}).merge(declaration).transform_keys(&:to_sym).freeze
+      unknown = @code_mode_declaration.keys - %i[engine except sandbox limits]
+      raise ConfigurationError, "Unknown code-mode option: #{unknown.first.inspect}" unless unknown.empty?
+      @code_mode_runtime = CodeMode::AgentRuntime.new(agent: self, declaration: @code_mode_declaration)
+      @tool_registry.register(CodeMode::ExecTool)
+      @tool_registry.register(CodeMode::WaitTool)
+      @tool_registry.register(CodeMode::StopTool)
+    end
+
+    def append_code_mode_instructions(prompt)
+      return prompt unless @code_mode_runtime
+
+      [prompt, @code_mode_runtime.instructions].compact.reject(&:empty?).join("\n\n")
     end
 
     def default_template_resolver(paths)
@@ -1976,6 +2165,19 @@ module LittleGhost
       events << StreamEvent.build(type, **data)
     end
 
+    def agent_stream_events(events, input:, operation_id:, parent_operation_id:)
+      return events unless run&.include_agent_events?
+
+      source = AgentStreamSource.build(
+        agent_id: self.class.agent_id,
+        agent_path:,
+        operation_id:,
+        parent_operation_id:,
+        assembly_path: agent_stream_path
+      )
+      AgentStreamSink.new(destination: events, run:, source:, input:)
+    end
+
     def instrument(name, **attributes)
       attributes.delete(:diagnostic) unless self.class.capture_diagnostics
       values = correlation_attributes.merge(attributes.compact)
@@ -2086,8 +2288,8 @@ module LittleGhost
       value.respond_to?(:role) ? diagnostic_message(value) : value.to_s
     end
 
-    def tool_companion_message?(message)
-      message.metadata[:little_ghost_tool_companion] || message.metadata["little_ghost_tool_companion"]
+    def artifact_presentation_message?(message)
+      message.metadata[:little_ghost_artifact_presentation] || message.metadata["little_ghost_artifact_presentation"]
     end
 
     def diagnostic_tool_exception(error, tool:)