pikuri-core 0.0.6 → 0.1.0

data/lib/pikuri/agent/synthesizer.rb

@@ -2,36 +2,24 @@
 
 module Pikuri
   class Agent
-    # Step-exhaustion rescue. When an +Agent+'s
-    # {Control::StepLimit} trips, +Agent#run_loop+ catches the
-    # +Exceeded+ exception and hands off to {Synthesizer.run} so
-    # the run still produces something useful — a tools-free
-    # assistant turn that answers the user's question from
-    # whatever evidence the failed agent collected before running
-    # out of budget.
+    # Prompt builder for the step-exhaustion rescue. When an +Agent+'s
+    # {Control::StepLimit} trips with the +:synthesize+ policy, +Agent#run_loop+
+    # runs this prompt on a nested tools-free agent so the run still produces an
+    # answer from whatever evidence the failed agent gathered before running out
+    # of budget.
     #
-    # == Why this exists
+    # The failure mode it salvages is the "wait, but what about X?" death-loop:
+    # the agent collects sound evidence in the first few rounds, then burns the
+    # rest of the budget second-guessing — by the cap, the answer is largely in
+    # the messages and just needs a tools-free pass to synthesize. Salvage is
+    # wrong for some agents (a coding agent's half-finished work can only be
+    # described, not completed), which is why the policy lives on
+    # {Control::StepLimit} and defaults to +:raise+.
     #
-    # Without a rescue, a step-exhausted run just raises a stack
-    # trace past +bin/pikuri-chat+ and the user gets nothing
-    # despite the agent having gathered useful information in the
-    # first N-1 steps. The observed failure mode is the "wait,
-    # but what about X?" death-loop: the agent collects sound
-    # evidence in the first few rounds, then spends the rest of
-    # the budget second-guessing. By the time the cap trips, the
-    # answer is largely in the messages — it just needs a
-    # tools-free pass to synthesize.
-    #
-    # == Seam discipline
-    #
-    # {Synthesizer.run} does not reference +RubyLLM::*+. +Agent+
-    # constructs the synth chat itself (the one +RubyLLM.chat+
-    # call lives in +lib/agent.rb+, same as the parent chat) and
-    # passes it in. +Synthesizer+ only calls instance methods on
-    # whatever +chat+ it receives — +#with_instructions+,
-    # +#ask+, +#messages+ — and uses {Agent.wire_chat} for the
-    # event-stream wiring so the synth chat emits events with
-    # the same shape as the main chat.
+    # Pure prompt construction — no chat handling or +RubyLLM.chat+ call.
+    # {.run_synthesizer} owns the execution (a regular tools-free +Agent+, the
+    # same shape sub-agents use). The only +RubyLLM::*+ surface read here is the
+    # +RubyLLM::Message+/+ToolCall+ value-type passthrough.
     module Synthesizer
       # The synthesizer's system prompt. Strict and short: use
       # the evidence, don't apologize, admit gaps when present.
@@ -39,62 +27,8 @@ module Pikuri
         You are given evidence another agent collected before running out of steps. Answer the user's question using only this evidence. You have no tools. If the evidence is insufficient, state plainly what's missing and what partial answer you can give. Do not apologize or comment on the previous agent.
       PROMPT
 
-      # Configure +chat+ for synthesis, run one turn against it,
-      # and return the final assistant content. The chat is wired
-      # for the event stream via {Agent.wire_chat} so the synth's
-      # reasoning and answer flow through the same listener
-      # surface the parent agent uses — terminal renders them
-      # inline (padded under sub-agent), an in-memory recorder
-      # picks them up, a TokenLog tags them with the synth id.
-      #
-      # @param chat [RubyLLM::Chat] a *fresh* chat with no tools.
-      #   The caller is responsible for constructing it with the
-      #   same model/provider configuration the parent used.
-      # @param parent_messages [Array<RubyLLM::Message>] the
-      #   parent chat's full message history at the moment of
-      #   step exhaustion. Used to build the evidence transcript.
-      # @param user_message [String] the user's original question
-      #   from the parent turn that exhausted.
-      # @param listeners [Agent::ListenerList] listeners to wire
-      #   the synth chat into. Typically the parent agent's list
-      #   run through {ListenerList#for_sub_agent} with the
-      #   synth's +id:+ so any +TokenLog+ tags its lines with
-      #   the synth bracket and any +Terminal+ pads its output.
-      # @param step_limit [Control::StepLimit, nil] defensive
-      #   step budget. The synth has no tools so it should never
-      #   trip +before_tool_call+, but a buggy provider that
-      #   somehow returned a tool call would loop without one.
-      #   Pass +nil+ to skip.
-      # @param cancellable [Control::Cancellable, nil]
-      #   cancellation control. Typically the parent's instance,
-      #   shared by reference so a user cancel during synthesis
-      #   still works. Pass +nil+ to skip.
-      # @param streaming [Boolean] mirror the parent agent's
-      #   +streaming+ flag. When +true+, {Agent.streaming_block}
-      #   is passed to +chat.ask+ so the synth's reasoning and
-      #   answer flow through the listener stream as deltas in
-      #   addition to the final {Event::Thinking} / {Event::Assistant}
-      #   bookends.
-      # @return [String, nil] the synth's final assistant
-      #   content, or +nil+ if the synth somehow produced no
-      #   assistant message
-      def self.run(chat:, parent_messages:, user_message:, listeners:,
-                   step_limit: nil, cancellable: nil, streaming: false)
-        chat.with_instructions(SYSTEM_PROMPT)
-        Agent.wire_chat(chat, listeners: listeners, step_limit: step_limit, cancellable: cancellable)
-        prompt = build_prompt(parent_messages: parent_messages, user_message: user_message)
-        if streaming
-          chat.ask(prompt, &Agent.streaming_block(listeners: listeners, cancellable: cancellable))
-        else
-          chat.ask(prompt)
-        end
-        chat.messages.reverse.find { |m| m.role == :assistant }&.content
-      end
-
-      # Render the user's question plus an "Evidence gathered"
-      # section built from +parent_messages+ as a single prompt
-      # string. Pure function — no I/O, safe to test directly
-      # with fixture messages.
+      # Render the question plus an "Evidence gathered" section from
+      # +parent_messages+. Pure — no I/O.
       #
       # @param parent_messages [Array<RubyLLM::Message>]
       # @param user_message [String]
@@ -104,14 +38,11 @@ module Pikuri
         "Question: #{user_message}\n\nEvidence gathered:\n#{transcript}"
       end
 
-      # Walk the parent's message history and produce a paired
-      # "Tool call:" / "Tool result:" log, preserving order. Tool
-      # calls that have no matching +:tool+ message are dropped —
-      # the call that tripped the step limit never executed, so
-      # including it would mislead the synth into citing
-      # nonexistent results. Non-empty assistant text content is
-      # preserved as a "Note:" line, since the parent may have
-      # summarized progress between tool calls.
+      # Walk the parent's history into a paired "Tool call:" / "Tool result:"
+      # log, in order. Tool calls with no matching +:tool+ message are dropped —
+      # the call that tripped the limit never executed, so citing its
+      # nonexistent result would mislead the synth. Non-empty assistant text
+      # becomes a "Note:" line.
       #
       # @param messages [Array<RubyLLM::Message>]
       # @return [String]
@@ -140,6 +71,59 @@ module Pikuri
         lines.join("\n").rstrip
       end
       private_class_method :format_evidence
+
+      # The +:synthesize+ arm of the step-exhaustion policy. Runs the
+      # {Synthesizer} prompt over the exhausted chat's history on a nested
+      # tools-free +Agent+ (the sub-agent construction shape, so it inherits
+      # listener propagation, transport/cap/streaming, and +close+ teardown).
+      #
+      # @param ctx [ExtensionContext]
+      # @param chat_messages [Array<RubyLLM::Message>] the exhausted chat's
+      #   history, the evidence {.build_prompt} renders
+      # @param user_message [String] the user's original question
+      # @raise [Control::Cancellable::Cancelled] when a cancel landed between
+      #   the budget tripping and this rescue — cancellation wins over salvage
+      # @return [String] the synth answer
+      def self.run_synthesizer(ctx, chat_messages, user_message)
+        # Check the cancel flag *before* constructing the synth: the nested
+        # run_loop resets the shared cancellable at its turn boundary, which
+        # would erase a cancel requested in this window. The raise propagates
+        # without a parent-side {Event::Cancelled} — a cancel *during* synthesis
+        # emits it from the synth's own rescue instead, so the stream sees at
+        # most one.
+        ctx.agent.cancellable&.check!
+
+        ctx.emit_event(Event::FallbackNotice.new(
+                         reason: "agent exhausted #{ctx.agent.step_limit.max} steps; " \
+                                                 'synthesizing answer from gathered evidence'
+                       ))
+
+        # Synth runs under this agent's identity with a distinct +_synthesizer+
+        # id suffix (same +_+ separator the sub-agent generator uses), so a
+        # +TokenLog+ tags its turns as the rescue, not the loop.
+        synth_id = ctx.agent.id.empty? ? 'synthesizer' : "#{ctx.agent.id}_synthesizer"
+        synth = Agent.new(
+          # Carry the parent's resolved cap on the transport so the synth reuses
+          # it without a re-probe (the cap rides {ChatTransport}).
+          transport: ctx.agent.transport.with(context_window: ctx.agent.context_window_cap),
+          system_prompt: Synthesizer::SYSTEM_PROMPT,
+          # Defensive :raise budget: the synth has no tools so should never
+          # tick, but a buggy provider returning a tool call must not loop — a
+          # synth that needs its own synth is a bug, not a rescue.
+          step_limit: Control::StepLimit.new(max: 1),
+          cancellable: ctx.agent.cancellable,
+          id: synth_id,
+          streaming: ctx.agent.streaming
+        ) { |c| c.add_listeners(ctx.sub_agent_listeners(id: synth_id)) }
+        begin
+          synth.run_loop(user_message: Synthesizer.build_prompt(
+            parent_messages: chat_messages, user_message: user_message
+          ))
+          synth.last_assistant_content
+        ensure
+          synth.close
+        end
+      end
     end
   end
 end