samagotchi 0.110.0 → 0.111.1

data/lib/samagotchi/reply_wait.rb

@@ -63,8 +63,31 @@ module Samagotchi
     # @!attribute origin [String, nil] "command" for a :no_reply that a
     #   file-delivered session command settled (no turn ran:
     #   TurnCheckpoint.record_command_outcome); nil otherwise
+    # @!attribute running_look [RunningLook, nil] on a :timeout, the turn
+    #   this wait saw running (call's running_look:, for a wait that goes
+    #   on in a next call: chi web's 30 s slices of a remote wait)
     Result = Struct.new(:status, :text, :file, :question, :outcome, :limit, :error_kind, :retryable, :cancel_reason,
-                        :stopped_by, :kept_steps, :session, :turn_id, :origin, keyword_init: true)
+                        :stopped_by, :kept_steps, :session, :turn_id, :origin, :running_look, keyword_init: true)
+
+    # A turn a wait with no turn: saw running with its checkpoint mark:
+    # last_turn's ended_at then and the names of the input files claimed
+    # then (*.json.processing), so its settle by a next worker tells from
+    # a turn that ended or an input that runs next (Poll#settled_running).
+    # Plain strings, so a remote wait carries it from one slice to the next.
+    RunningLook = Data.define(:last_end, :claimed) do
+      # @return [RunningLook, nil] nil unless +raw+ is {last_end: String or
+      #   nil, claimed: [file names]} (string keys, as JSON parsed it)
+      def self.from_h(raw)
+        return nil unless raw.is_a?(Hash) && raw.keys.sort == %w[claimed last_end]
+
+        last_end = raw["last_end"]
+        claimed = raw["claimed"]
+        return nil unless (last_end.nil? || last_end.is_a?(String)) && claimed.is_a?(Array) &&
+                          claimed.all? { |name| name.is_a?(String) && File.basename(name) == name }
+
+        new(last_end: last_end, claimed: claimed.sort.freeze)
+      end
+    end
 
     # The session as it was before a message went in (call's baseline:,
     # #baseline_of): its message count, the question pending then, and when
@@ -133,13 +156,17 @@ module Samagotchi
     #   sorts at the cursor, not past it, and its end precedes the
     #   baseline, so without it the wait would time out "running" again.
     #   Not for a turn: wait (chi answer) whose own end it waits for.
+    # @param running_look [RunningLook, nil] the running turn an earlier
+    #   call of the same wait saw (its :timeout result's running_look): its
+    #   settle ends this call too, as if this call had seen it running
     # @return [Result]
     # @raise [ArgumentError] no such session
     def call(id, state_dir:, cursor:, timeout: nil, poll_interval: POLL_INTERVAL, cancelled: -> { false },
-             baseline: nil, owner_grace: nil, interject: nil, turn: nil, queued: false, ended_before: false)
+             baseline: nil, owner_grace: nil, interject: nil, turn: nil, queued: false, ended_before: false,
+             running_look: nil)
       Poll.new(id, state_dir: state_dir, cursor: cursor, timeout: timeout, poll_interval: poll_interval,
                    cancelled: cancelled, baseline: baseline, owner_grace: owner_grace, interject: interject, turn: turn,
-                   queued: queued, ended_before: ended_before).run
+                   queued: queued, ended_before: ended_before, running_look: running_look).run
     end
 
     # The session as it was before a message went in (call's baseline:):

data/lib/samagotchi/send_command/wait_target.rb

@@ -19,11 +19,18 @@ module Samagotchi
       # settle end the wait (TurnCheckpoint.settled_turn). A message merged
       # into a turn starting then falls back to that turn's reply
       # (ReplyWait's turn: without queued:); no id (an older worker), the
-      # next reply.
+      # next reply. A prompt the session was created with has no delivery:
+      # its turn is the id the create gave it (+direct_turn+,
+      # Session#first_turn_id), and nothing can merge into it, so the wait
+      # is for that turn alone (ReplyWait's queued:).
       # @param delivered [SessionManager::DeliverResult, nil] nil when the
       #   message started the session itself (no delivery)
-      def self.first_message(delivered)
-        return new unless delivered
+      # @param direct_turn [String, nil] that first turn's id, for a direct
+      #   start
+      def self.first_message(delivered, direct_turn: nil)
+        return new unless delivered || !direct_turn.to_s.strip.empty?
+
+        return new(turn: direct_turn, report_turn_id: direct_turn, queued: true) if delivered.nil?
 
         new(turn: delivered.enqueued_id, report_turn_id: delivered.enqueued_id)
       end

data/lib/samagotchi/send_command.rb

@@ -521,7 +521,8 @@ module Samagotchi
 
       start = @access.prepare_wait(session.id, session: session, created: true)
       wait_for_reply(session.id, cursor: start.cursor, baseline: start.baseline,
-                                 timeout: options[:timeout], **WaitTarget.first_message(@delivered).to_h)
+                                 timeout: options[:timeout],
+                                 **WaitTarget.first_message(@delivered, direct_turn: session.first_turn_id).to_h)
     end
 
     # What chi send --new asks to create: through the worker (images, a

data/lib/samagotchi/session.rb

@@ -54,6 +54,13 @@ module Samagotchi
     attr_accessor :id, :metadata_version, :mode, :model_name, :working_directory, :messages,
                   :created_at, :updated_at, :status, :last_prompt, :first_preview, :test_run,
                   :used_memory_names
+    # The id the prompt a session is created with gets (SessionManager
+    # .spawn_session), so its first turn is a turn with an id like one sent
+    # later: the worker's first turn takes it as its origin, its reply file
+    # and last_turn carry it, and a wait for it (`chi send --new --wait`,
+    # chi web's create) can name it (`--wait --turn T ID`). nil for a
+    # session created idle, and for one saved before the field existed.
+    attr_accessor :first_turn_id
     # Memories the session was started with (--memory) and memories hidden
     # from it (--mute): the worker rebuilds the same prompt on a respawn.
     # Names as given; the engine normalizes them.
@@ -310,7 +317,7 @@ module Samagotchi
 
     def initialize(id:, mode:, model_name:, working_directory:, messages:, created_at:, updated_at:,
                    metadata_version: METADATA_VERSION, status: STATUS_IDLE, last_prompt: "",
-                   first_preview: "", test_run: false, pending_question: nil,
+                   first_preview: "", first_turn_id: nil, test_run: false, pending_question: nil,
                    used_memory_names: [], project_root: nil,
                    preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, scratch: false,
                    last_turn: nil, model_typed: nil, delegate: false, llm_context: nil, prompt_notes: [],
@@ -329,6 +336,7 @@ module Samagotchi
       @status = status
       @last_prompt = last_prompt
       @first_preview = first_preview
+      @first_turn_id = first_turn_id
       @title = title
       @test_run = !!test_run
       self.pending_question = pending_question
@@ -525,12 +533,13 @@ module Samagotchi
       "interrupted_turn" => nil,
       "parent_answers" => nil,
       "working_set_pins" => [],
-      "review" => nil
+      "review" => nil,
+      "first_turn_id" => nil
     }.freeze
 
     # FIELDS a session file has only when set: a session without them saves
     # as it did before they existed.
-    OPTIONAL_FIELDS = %w[review].freeze
+    OPTIONAL_FIELDS = %w[review first_turn_id].freeze
 
     # A session from a parsed session file. +messages+ false leaves the
     # conversation out (the lists' lightweight summaries).

data/lib/samagotchi/session_access/remote.rb

@@ -179,7 +179,8 @@ module Samagotchi
 
         json = reply.json
         Created.new(id: json.fetch("id"), model_warning: json["model_warning"], continues: json["continues"],
-                    moved_children: json["moved"] || [], parent_answers_warning: json["parent_answers_warning"])
+                    moved_children: json["moved"] || [], parent_answers_warning: json["parent_answers_warning"],
+                    first_turn_id: json["first_turn_id"])
       end
 
       # Whether a just-created session's worker came up within +timeout+
@@ -332,7 +333,9 @@ module Samagotchi
       end
 
       # ReplyWait on the server, asked again each WAIT_SLICE until it ends
-      # or +timeout+ passes.
+      # or +timeout+ passes. Each slice is a fresh ReplyWait there: the
+      # running turn a slice saw (its timeout's running_look) goes into the
+      # next, so a settle between two slices ends the wait as it would here.
       # @return [ReplyWait::Result]
       # @raise [ArgumentError] the session is gone
       def wait_reply(id, cursor:, timeout:, baseline:, owner_grace: nil, turn: nil, queued: false, ended_before: false,
@@ -355,6 +358,8 @@ module Samagotchi
           @strategies[id] = strategy_of(reply.json["parent_strategy"])
           result = result_of(reply.json)
           return result unless result.status == :timeout
+
+          body[:running_look] = reply.json["running_look"]
         end
       end
 

data/lib/samagotchi/session_access.rb

@@ -160,9 +160,13 @@ module Samagotchi
 
     # What chi send --new created (Remote; Local gives the Session): its
     # id, a model warning, the session it continues, the delegates it took
-    # over, and the server's word on a --parent-answers looser than its
-    # config.yml's (capped).
-    Created = Data.define(:id, :model_warning, :continues, :moved_children, :parent_answers_warning)
+    # over, the server's word on a --parent-answers looser than its
+    # config.yml's (capped), and the id the prompt it started with gets for
+    # its first turn (nil for one created idle).
+    Created = Data.define(:id, :model_warning, :continues, :moved_children, :parent_answers_warning, :first_turn_id) do
+      def initialize(id:, model_warning: nil, continues: nil, moved_children: [], parent_answers_warning: nil,
+                     first_turn_id: nil) = super
+    end
 
     # A session's worker as an attach finds it (Local#worker, chi web's GET
     # …/worker): +sidecar+ the live worker's WorkerSidecar (port, version,

data/lib/samagotchi/session_manager.rb

@@ -197,6 +197,11 @@ module Samagotchi
       # the prompts), so the session starts idle.
       session.status = prompt.to_s.strip.empty? ? Session::STATUS_IDLE : Session::STATUS_RUNNING
       session.last_prompt = prompt
+      # The first prompt's turn gets an id like a sent message's, so a wait
+      # for it can name it (chi send --new --wait, chi web's create): the
+      # worker runs it with that origin, and its reply file and last_turn
+      # carry the id.
+      session.first_turn_id = SecureRandom.uuid unless prompt.to_s.strip.empty?
       # The worker takes last_prompt and clears it, and messages are saved at
       # the turn's end: until then this is the only preview a list has.
       session.first_preview = Session.preview_of(preview.to_s.strip.empty? ? prompt : preview)

data/lib/samagotchi/turn_endings.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative "llm/errors"
+require_relative "tools/task_runtime"
+require_relative "turn_note"
+
+module Samagotchi
+  # What each of an Engine's turn endings keeps and announces: pure builders
+  # over the turn, its result or its error. The kept messages and their
+  # TurnNote (#kept_messages, #ctrl_c_messages, #failed_messages), the end
+  # event (#failed_event), the turn summary and the stop facts. The Engine
+  # forwards each here and keeps the steps that hold the event lock or save
+  # (end_turn, complete_turn, store_answer_display, record_last_turn).
+  class TurnEndings
+    # @param failure_summary [#call] (error) → a failed turn's one line (Engine#failure_summary)
+    def initialize(failure_summary:)
+      @failure_summary = failure_summary
+    end
+
+    # Why a turn stopped, from its end event (LastTurn::STOP_FACTS), for a
+    # parent agent's wait (ReplyWait): a provider error's kind and whether
+    # a retry may help, a cancel's reason and the hook that stopped it.
+    # Only what is known.
+    def stop_facts(event)
+      case event&.dig(:type)
+      # kept_steps: the turn's work stayed (a parent must not send the task again).
+      when :turn_failed
+        { error_kind: event[:error_kind]&.to_s, retryable: event[:retryable], kept_steps: event[:kept_steps] }
+      when :turn_canceled
+        { cancel_reason: event[:cancellation_reason]&.to_s, stopped_by: event[:cancelled_by]&.to_s }
+      else {}
+      end
+    end
+
+    # What the session keeps of a turn that ended normally (nil: nothing to
+    # replace). Runs under the event lock: it also adds the turn's note to
+    # result.conversation, which the REPL keeps as-is.
+    # A turn that ran out of iterations ends at its tool results, so a
+    # continue resumes from them rather than after a made-up reply (and a
+    # step-limit Continue from its run's start: ModelResult#run_start).
+    def kept_messages(turn, result, seconds)
+      conversation = result.conversation if result.conversation.is_a?(Array)
+      # Nothing visible (no text) is a turn the model should know ended
+      # that way: the note, and nothing made up as its answer. The note's
+      # marker is for the UIs (the notice, and the empty steps after a
+      # reload); it goes on the result's conversation too (the REPL keeps it).
+      # A retry's nudge at the tail goes: this note says it all. An earlier
+      # turn's note stays: it says why that turn ended.
+      if result.empty_answer?
+        note = TurnNote.empty(retries: result.empty_retries, steps: result.empty_steps, refusal: result.refusal)
+        conversation&.replace(TurnNote.without_trailing_nudge(conversation))
+        saved = TurnNote.without_trailing_nudge(conversation || turn.session.messages)
+        conversation << note if conversation
+        saved + [note]
+      elsif result.canceled? && conversation
+        conversation << TurnNote.cancelled(result.cancellation_reason, seconds: seconds,
+                                                                      stopped_by: turn.controller.detail,
+                                                                      shown: TurnNote.interrupted_tail?(conversation),
+                                                                      running_tasks: Tools::TaskRuntime.running_created_in(conversation))
+      else
+        conversation
+      end
+    end
+
+    # A Ctrl-C keeps the loop's conversation so far, as a Stop does (its
+    # finished tool iterations, every call answered: ToolResponse.run_batch),
+    # else the turn's messages so far (it came before the loop), with a
+    # cancel note naming the tasks still running; nil before there are any.
+    def ctrl_c_messages(turn, interrupt, seconds)
+      kept = loop_conversation(interrupt) || turn.messages
+      return nil unless kept
+
+      note = TurnNote.cancelled(:ctrl_c, seconds: seconds, running_tasks: Tools::TaskRuntime.running_created_in(kept))
+      TurnNote.replace_trailing(kept, note)
+    end
+
+    # The conversation the loop had built when +error+ ended the turn
+    # (LLM::FailedTurn), or nil.
+    def loop_conversation(error)
+      error.partial_conversation if error.respond_to?(:partial_conversation) && error.partial_conversation.is_a?(Array)
+    end
+
+    # A failure keeps the loop's partial conversation (else the turn's
+    # messages so far) with a failed note; nil when the turn never reached
+    # the model. The model reads why on its next turn. A turn that got to
+    # tool results (LLM::FailedTurn.progress) says so in the note; on the
+    # error (kept_steps) too unless it failed in a way that rolls back
+    # (FailedTurn.keeps_work?: a context overflow). The UIs keep a marked
+    # turn (TurnFlow#prompt_turn_failed), and roll back the others, with a
+    # note of their own; -p --non-interactive keeps what this keeps.
+    def failed_messages(turn, error)
+      kept = loop_conversation(error) || turn.messages
+      return nil unless kept
+
+      steps = LLM::FailedTurn.progress(turn.session.messages, kept)
+      error.kept_steps = steps if steps && error.is_a?(LLM::FailedTurn) && LLM::FailedTurn.keeps_work?(error)
+      summary = error.respond_to?(:summary) ? error.summary : error.message
+      TurnNote.replace_trailing(kept, TurnNote.failed(summary, continued: turn.continue, steps: steps))
+    end
+
+    # Called after #failed_messages, which marks the error's kept steps.
+    def failed_event(error, seconds)
+      failed = { type: :turn_failed, error_class: error.class.name, message: error.message,
+                 duration_ms: (seconds * 1000).round }
+      # Its work stays: the UIs say so, as after a cancel.
+      steps = LLM::FailedTurn.kept_steps(error)
+      failed[:kept_steps] = steps if steps
+      # A provider error says what kind it is, for one line per kind in the UIs.
+      if error.is_a?(LLM::ProviderError)
+        failed.merge!(error_kind: error.kind, retryable: error.retryable?, host: error.host, summary: failure_summary(error))
+      end
+      failed
+    end
+
+    # JSON-safe digest of a finished turn for renderers (in-process or over the
+    # Bridge): the bits of the native loop's result a UI needs beyond `result:`.
+    # @param result [LLM::ModelResult]
+    # @return [Hash]
+    def turn_summary(result)
+      summary = {
+        output: result.output.to_s,
+        exhausted: result.exhausted?,
+        resumable: result.resumable?,
+        pending_tool_calls: result.pending_tool_calls?,
+        tool_activity: Array(result.tool_activity).map(&:dup),
+        context_status: result.context_status&.dup
+      }
+      # No answer: every UI shows its notice (TurnNote.empty_answer_line).
+      summary[:empty_answer] = { retries: result.empty_retries.to_i, refusal: result.refusal }.compact if result.empty_answer?
+      summary
+    end
+
+    private
+
+    def failure_summary(error) = @failure_summary.call(error)
+  end
+end

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.110.0"
+  VERSION = "0.111.1"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end