pikuri-core 0.0.7 → 0.1.0

data/lib/pikuri/agent/synthesizer.rb

@@ -2,44 +2,24 @@
 
 module Pikuri
   class Agent
-    # Prompt builder for the step-exhaustion rescue. When an
-    # +Agent+'s {Control::StepLimit} trips with the +:synthesize+
-    # policy, +Agent#run_loop+ runs this module's prompt on a
-    # nested tools-free agent so the run still produces something
-    # useful — an 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.
-    #
-    # Salvage is the wrong move for some agents, which is why the
-    # policy lives on {Control::StepLimit} and defaults to
-    # +:raise+ — a coding agent's half-finished work can't be
-    # completed by a tools-free pass, only described. See
-    # {Control::StepLimit}'s class header.
-    #
-    # == Seam discipline
-    #
-    # This module is pure prompt construction — no chat handling,
-    # no +RubyLLM.chat+ call, no event wiring. The execution side
-    # (constructing the nested agent, sharing the parent's
-    # listener stream and cancellable, capturing the answer) is
-    # +Agent#run_synthesizer+'s job: the synth is a regular
-    # tools-free +Agent+, the same construction shape the +agent+
-    # tool from +pikuri-subagents+ uses for sub-agents. The only
-    # +RubyLLM::*+ surface read here is the value-type
-    # +RubyLLM::Message+ / +ToolCall+ passthrough (per the
-    # value-type rule in CLAUDE.md).
+    # 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.
@@ -47,10 +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
 
-      # 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]
@@ -60,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]
@@ -97,33 +72,25 @@ module Pikuri
       end
       private_class_method :format_evidence
 
-      # The +:synthesize+ arm of the step-exhaustion policy (see the
-      # class header). Runs the {Synthesizer} prompt over the
-      # exhausted chat's history on a nested tools-free +Agent+ —
-      # the same construction shape the +agent+ tool from
-      # +pikuri-subagents+ uses for sub-agents, so the synth gets
-      # listener propagation, transport / context-window-cap /
-      # streaming inheritance, and teardown via +close+ for free.
-      # The synth's answer is returned.
+      # 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 full message history, the evidence
-      #   {.build_prompt} renders
+      # @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
-      #   from the turn that exhausted
-      # @raise [Control::Cancellable::Cancelled] when a cancel
-      #   landed between the budget tripping and this rescue —
-      #   cancellation wins over salvage
+      # @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 (on the derived listener list)
-        # instead, so either way the stream sees at most one.
+        # 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(
@@ -131,27 +98,18 @@ module Pikuri
                                                  'synthesizing answer from gathered evidence'
                        ))
 
-        # Synth runs under this agent's identity but with a
-        # different system prompt, so it gets a distinct
-        # +_synthesizer+ suffix on the id — same +_+ separator the
-        # sub-agent generator uses, so main becomes +"synthesizer"+
-        # and a sub-agent +"researcher 0"+ becomes
-        # +"researcher 0_synthesizer"+. Any +TokenLog+ in the list
-        # tags the synth's prompt under that bracket so it's
-        # obvious from the log which turns were the rescue rather
-        # than the original loop.
+        # 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}
-          # now, not an +Agent.new(context_window:)+ kwarg.
+          # 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 budget with the default :raise policy: the
-          # synth has no tools so it should never tick, but a buggy
-          # provider that somehow returns a tool call must not loop
-          # forever — and a synth that needs its own synth is a bug,
-          # not a rescue.
+          # 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,