samagotchi 0.17.0 → 0.18.0

data/lib/samagotchi/continue_offer.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Samagotchi
+  # A session worker's continue offer: what it announces when a turn runs out
+  # of iterations, when a prompt or a reminder drops the offer, when a
+  # /continue answers it, and the continue turn a yes runs. TurnFlow keeps
+  # the offer itself (its checkpoint and context); this is the worker's side
+  # of it, which every UI hears about.
+  #
+  # The offer is also a question (kind "continue", the step-limit
+  # question), standing on the Engine's question desk between turns, so
+  # everything built on a pending question sees it: chi send --wait (exit
+  # 3), chi answer, the lists' waiting, the web's badge and bell. Its
+  # answer becomes the matching /continue line on the worker's command
+  # queue, which runs it as a typed one (#run_command's path).
+  class ContinueOffer
+    KIND = "continue"
+    HEADER = "Step limit"
+    CONTINUE = "Continue"
+    STOP = "Stop"
+    PROMPT_PREVIEW = 200
+    # last_turn's outcome after a Stop: no turn ran, but the wait of
+    # whoever answered (chi answer) ends on it.
+    NOT_CONTINUED = "not_continued"
+
+    # @param engine [Engine] announces, records activity, holds the question
+    # @param turn_flow [TurnFlow] owns the offer
+    # @param run_turn [#call] (prompt, **turn_args, &block) the worker's
+    #   run_engine_turn
+    # @param max_iterations [#call] (no_interrupt) → Integer
+    # @param queue_command [#call] (line, client_id:) queues a session
+    #   command as a card's (Bridge#queue_command, card: true)
+    def initialize(engine:, turn_flow:, run_turn:, max_iterations:, queue_command: nil)
+      @engine = engine
+      @turn_flow = turn_flow
+      @run_turn = run_turn
+      @max_iterations = max_iterations
+      @queue_command = queue_command
+      # A question was posted since the last close (it may have been
+      # answered or superseded meanwhile).
+      @asked = false
+    end
+
+    attr_writer :queue_command
+
+    def awaiting? = @turn_flow.awaiting_continue?
+
+    # TurnFlow keeps the checkpoint (a cancelled turn's, for !rollback) and
+    # the continue offer of a turn that ran out of iterations; an offer made
+    # (or kept, after a cancelled continue turn) is announced and asked.
+    def after_turn(result, continue: false, no_interrupt: false)
+      outcome = @turn_flow.after_turn(result, continue: continue, no_interrupt: no_interrupt)
+      return unless outcome == :continue_offered || outcome == :continue_cancelled
+
+      open
+    end
+
+    # A prompt (or a reminder turn) taken while a continue is offered
+    # replaces the answer (D2): the offer goes, the partial turn stays.
+    def drop(origin)
+      return unless awaiting?
+
+      close("dropped")
+      @engine.synchronize_events do
+        @turn_flow.drop_offer!
+        @engine.announce(type: :continue_resolved, decision: "dropped", client_id: origin&.dig(:client_id))
+      end
+      @engine.record_activity
+    end
+
+    # Whether a command's +result+ answered the offer that was pending
+    # (+awaiting+) as it started.
+    def resolved?(awaiting, result)
+      awaiting && result.decision && result.decision != :invalid ? true : false
+    end
+
+    # Called with the event log held, before the command's command_ran. A
+    # Stop runs no turn: last_turn says so (not_continued), so a wait on
+    # it ends (chi answer --option Stop).
+    def announce_resolved(result, command)
+      @engine.announce(type: :continue_resolved, decision: result.decision.to_s, client_id: command[:client_id])
+      return if result.resume
+
+      session = @engine.session
+      session.last_turn = { "outcome" => NOT_CONTINUED, "ended_at" => Time.now.iso8601(3) } if session
+    end
+
+    # After a command's command_ran and save: a /continue that answered the
+    # offer closes its question; a command that dropped the offer
+    # otherwise (!rollback) too.
+    # @param resolved [Boolean] it answered the offer (#resolved?)
+    def after_command(result, resolved:)
+      close(resolved ? "answered" : "dropped") unless awaiting?
+      return unless resolved
+
+      # An offer answered without a turn ("no") is activity: the recap
+      # written at the offer (it says the turn stopped) gets rewritten.
+      @engine.record_activity unless result.resume
+    end
+
+    # The continue offer was answered yes: resume the conversation without a
+    # user message, with the iteration limit the offer's turn had. A failure
+    # keeps the offer, as the REPL does ("continue prompt preserved"), and
+    # asks again.
+    def run_continue_turn(command)
+      offer = @turn_flow.offer
+      close("answered")
+      @turn_flow.before_continue_turn
+      @run_turn.call(nil, continue: true, origin: { client_id: command[:client_id] }.compact,
+                          max_iterations: @max_iterations.call(offer[:no_interrupt])) do |result, error|
+        if error
+          open(offer)
+        else
+          after_turn(result, continue: true, no_interrupt: offer[:no_interrupt])
+        end
+      end
+    end
+
+    # The question goes (the offer went, or was answered).
+    # @param reason [String] dropped, answered
+    def close(reason)
+      return unless @asked
+
+      @asked = false
+      @engine.withdraw_question(reason)
+    end
+
+    private
+
+    def open(offer = @turn_flow.offer)
+      @engine.announce(type: :continue_offered, context: offer[:context], no_interrupt: offer[:no_interrupt])
+      ask
+    end
+
+    # Post the step-limit question while the offer stands (again, after a
+    # question that superseded it closed).
+    def ask
+      return unless awaiting?
+
+      @asked = true
+      @engine.post_question(question_fields(@turn_flow.offer), on_answer: method(:answered),
+                                                               on_superseded_close: method(:ask))
+    end
+
+    def question_fields(offer)
+      limit = limit_of_last_turn
+      context = offer[:context] || {}
+      text = "The turn ran out of iterations#{" (#{limit} steps)" if limit} before it answered. Continue it?"
+      prompt = context[:original_prompt].to_s.strip
+      unless prompt.empty?
+        prompt = "#{prompt[0, PROMPT_PREVIEW].rstrip}..." if prompt.length > PROMPT_PREVIEW
+        text += "\nPrompt: #{prompt}"
+      end
+      { kind: KIND, header: HEADER, question: text, options: [CONTINUE, STOP], multi_select: false,
+        allow_freeform: true, limit: limit, context: context }.compact
+    end
+
+    # The limit the offer's turn ran out at (Engine's last_turn marker).
+    def limit_of_last_turn
+      last = @engine.session&.last_turn
+      last.is_a?(Hash) && last["exhausted"] ? last["limit"] : nil
+    end
+
+    # The question's answer as the /continue line a typed answer would be:
+    # Continue → yes; Stop → no; a text (with Stop, or alone) → no, <text>.
+    def answered(answer, client_id:)
+      text = answer[:freeform].to_s.gsub(/\s+/, " ").strip
+      line = if Array(answer[:selected]).include?(CONTINUE) then "/continue yes"
+             elsif text.empty? then "/continue no"
+             else "/continue no, #{text}"
+             end
+      @queue_command&.call(line, client_id: client_id)
+    end
+  end
+end

data/lib/samagotchi/engine.rb

@@ -6,6 +6,7 @@ require "securerandom"
 require "time"
 require "yaml"
 
+require_relative "iteration_limit"
 require_relative "config"
 require_relative "context_note"
 require_relative "context_status"
@@ -27,6 +28,7 @@ require_relative "llm/backend"
 require_relative "llm/openai_chat"
 require_relative "llm/turn_settings"
 require_relative "session"
+require_relative "answer_tail"
 require_relative "archive_store"
 require_relative "session_observer"
 require_relative "tool_declarations"
@@ -83,7 +85,7 @@ module Samagotchi
     # @param profile            [ModelProfile, Symbol, String, nil]
     # @param session_id         [String, nil] resume an existing session
     # @param no_interrupt       [Boolean] --no-interrupt: every turn runs with
-    #   NO_INTERRUPT_MAX_ITERATIONS, whichever loop runs it
+    #   IterationLimit.for(no_interrupt: true), whichever loop runs it
     # @param model_name         [String, nil] defaults from SAMAGOTCHI_DEFAULT_MODEL
     # @param model_typed        [String, nil] the name the model was given as (a session's
     #   model_typed: an alias), for the models: lookup; model_name by default
@@ -92,10 +94,6 @@ module Samagotchi
     #   prompt's index, dropped from the preloads, refused by memory_read); a mute wins over a preload
     # What memory_write answers in a scratch session.
     SCRATCH_MEMORY_WRITE = "Error: scratch session: nothing is saved"
-    # A turn's iteration limit with no_interrupt (the worker's own
-    # --no-interrupt turns pass the same).
-    NO_INTERRUPT_MAX_ITERATIONS = 1000
-
     # @param plugins            [Boolean] false: load no bundle plugins (a throwaway Engine for a prompt)
     # @param scratch            [Boolean] a `chi scratch` session: memory writes are refused, and there is no
     #   delegate (a child would outlive it) nor plugin fork
@@ -1081,7 +1079,10 @@ module Samagotchi
 
     # How the turn ended, on the session (Session#last_turn): the caller's
     # save puts it in the file the session hub watches.
-    def record_last_turn(session, outcome, seconds, origin)
+    # @param limit [Integer, nil] the turn ran out of iterations at this
+    #   limit: "exhausted" => true, "limit" => N, so a wait with nobody to
+    #   answer the continue offer says so (ReplyWait, ParentReport "limit")
+    def record_last_turn(session, outcome, seconds, origin, limit: nil)
       client_id = origin.is_a?(Hash) ? origin[:client_id].to_s : ""
       source = if client_id.start_with?("#{Tools::Delegate::CLIENT_PREFIX}:") then "delegate"
                elsif client_id == SessionManager::REMINDER_CLIENT_ID then "reminder"
@@ -1089,6 +1090,7 @@ module Samagotchi
                end
       session.last_turn = { "outcome" => outcome, "ended_at" => Time.now.iso8601(3),
                             "seconds" => seconds.round(1), "origin" => source }
+      session.last_turn.merge!("exhausted" => true, "limit" => limit) if limit
     end
     private :record_last_turn
 
@@ -1101,14 +1103,15 @@ module Samagotchi
     # returns [the messages to keep (nil: leave the session's), the end
     # event]. +save:+ also saves the session (a failed turn: a worker exits
     # after it). The disk writes come after the step: every emitter waits
-    # for the event lock.
-    def end_turn(turn, outcome, save: false)
+    # for the event lock. +exhausted:+ the turn ran out of iterations
+    # (its limit goes in last_turn).
+    def end_turn(turn, outcome, save: false, exhausted: false)
       seconds = turn.elapsed
       synchronize_events do
         kept, event = yield(seconds)
         replace_session_messages(turn.session, kept) if kept
         turn.session.status = Session::STATUS_IDLE
-        record_last_turn(turn.session, outcome, seconds, turn.origin)
+        record_last_turn(turn.session, outcome, seconds, turn.origin, limit: exhausted ? turn.limit : nil)
         emit_event(turn.on_event, turn.tag(event))
       end
       turn.ended = true
@@ -1254,6 +1257,19 @@ module Samagotchi
       @question_desk.open_question({ **fields.to_h, **more }, watch: watch)
     end
 
+    # Publish a standing question that blocks nobody (QuestionDesk#post: a
+    # worker's step-limit question).
+    # @return [Hash, nil] the pending question, nil while another is open
+    def post_question(fields, on_answer:, on_superseded_close: nil)
+      @question_desk.post(fields, on_answer: on_answer, on_superseded_close: on_superseded_close)
+    end
+
+    # Withdraw the standing question (QuestionDesk#withdraw).
+    # @return [Boolean]
+    def withdraw_question(reason, id: nil)
+      @question_desk.withdraw(reason, id: id)
+    end
+
     # Answer the pending question (called from UI thread; QuestionDesk#answer).
     # @return [Hash] normalized answer
     def answer_question(id:, selected:, freeform: nil, client_id: nil, parent_agent: nil)
@@ -1274,6 +1290,7 @@ module Samagotchi
 
     # Cancel the pending question (QuestionDesk#cancel).
     # @return [Boolean] whether it was cancelled
+    # @raise [QuestionDesk::NotDismissable] +id+ names a standing question
     def cancel_question(reason = "user", id: nil)
       @question_desk.cancel(reason, id: id)
     end
@@ -1414,8 +1431,9 @@ module Samagotchi
     # set on the kernel in #generate.
     # +id+: names the turn on :turn_started (its metrics record's id) and on
     # its saved prompt, so a UI pairs the two whatever left the conversation.
+    # +limit+: the iteration limit #generate ran it with.
     Turn = Struct.new(:session, :prompt, :continue, :on_event, :controller, :origin, :started_at, :messages, :ended,
-                      :settings, :id) do
+                      :settings, :id, :limit) do
       # The turn's boundary events carry the origin only when there is one,
       # so payloads stay unchanged for callers that don't pass it.
       def tag(event) = origin ? event.merge(origin: origin) : event
@@ -1433,7 +1451,7 @@ module Samagotchi
     # @param session  [Session] the session to operate on
     # @param prompt   [String] user input
     # @param on_event [Proc, nil] receives event hashes
-    # @param max_iterations [Integer] max kernel iterations
+    # @param max_iterations [Integer, nil] max kernel iterations (nil: IterationLimit.for)
     # @param cancel_controller [CancellationController, nil]
     # @param max_tool_output_chars [Integer, nil] per-output char cap for the
     #   :tool_call_completed event's `output:` (nil → max_tool_output_chars)
@@ -1462,7 +1480,7 @@ module Samagotchi
     # other error (e.g. an LLM::ProviderError) emits :turn_failed and
     # re-raises; a provider error adds error_kind:, retryable:, host: and a
     # one-line summary:.
-    def run_turn(session, prompt, on_event: nil, max_iterations: 100, cancel_controller: nil, max_tool_output_chars: nil, pending_input: nil, continue: false, origin: nil,
+    def run_turn(session, prompt, on_event: nil, max_iterations: nil, cancel_controller: nil, max_tool_output_chars: nil, pending_input: nil, continue: false, origin: nil,
                  images: [])
       turn = begin_turn(session, prompt, on_event: on_event, cancel_controller: cancel_controller, origin: origin,
                                          continue: continue)
@@ -1666,9 +1684,10 @@ module Samagotchi
       # turn's model, not the last native one.
       @kernel.turn_settings = turn.settings.with(model_name: bare_for_backend, window_setting: turn_window_setting)
 
+      turn.limit = @no_interrupt ? IterationLimit.for(no_interrupt: true) : max_iterations || IterationLimit.for
       backend.complete(
         messages: turn.messages,
-        max_iterations: @no_interrupt ? NO_INTERRUPT_MAX_ITERATIONS : max_iterations,
+        max_iterations: turn.limit,
         on_stream_event: build_stream_event_handler(turn.on_event, cancel_controller: turn.controller),
         cancel_controller: turn.controller,
         model_name: bare_for_backend,
@@ -1705,7 +1724,7 @@ module Samagotchi
       # after_turn hooks run below and may present the answer (the web
       # holds its pop until it knows).
       display_pending = !canceled && @hooks.any?(:after_turn)
-      end_turn(turn, canceled ? "canceled" : "completed") do |seconds|
+      end_turn(turn, canceled ? "canceled" : "completed", exhausted: !canceled && result.exhausted?) do |seconds|
         kept = kept_messages(turn, result, seconds)
         if canceled
           [kept, { type: :turn_canceled, cancellation_reason: result.cancellation_reason,
@@ -1968,6 +1987,15 @@ module Samagotchi
     # rollback after Ctrl-C). Each replaces the array rather than mutating it,
     # so the recap's lock-free snapshot never sees a half-applied edit.
 
+    # The answer a UI shows last (AnswerTail), a copy of that one message
+    # only: walked back from the end, never a #messages_checkpoint of the
+    # whole conversation (the Bridge's GET tail). +turn_id+: that turn's
+    # answer (AnswerTail.find); unknown or nil: the newest.
+    # @return [Hash, nil]
+    def last_answer_message(turn_id: nil)
+      AnswerTail.find(@session&.messages, turn_id: turn_id)&.dup
+    end
+
     # @return [Array<Hash>] a copy of the current session's messages to hand
     #   back to #rollback_to later
     def messages_checkpoint

data/lib/samagotchi/guardrails/outside.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require_relative "protected_paths"
+require_relative "../memory_bundle/index_sync"
+
+module Samagotchi
+  module Guardrails
+    # What `outside_repo` means (a rule's path: and git:): a path is outside
+    # when it isn't in the session's repo root (the cwd outside a repo),
+    # with symlinks resolved on both sides. Never outside:
+    # - a memory's file (MemoryBundle::IndexSync.memory_scope): write/edit
+    #   there is what memory_write does; index.md, the bundles dir and the
+    #   rest of chi's config dir still count;
+    # - a tmp dir (Dir.tmpdir, /tmp, /var/tmp), unless the session's root
+    #   is itself in that tmp dir (a sandbox there still gets the check
+    #   between its siblings).
+    # chi's state dir is not special: nothing there is the model's to write.
+    module Outside
+      TMP_DIRS = %w[/tmp /var/tmp].freeze
+
+      # @param path [String] absolute
+      # @param root [String] the session's repo root (or cwd)
+      def self.outside?(path, root:)
+        real = ProtectedPaths.real(path)
+        session = ProtectedPaths.real(root)
+        return false if within?(real, session)
+        return false if MemoryBundle::IndexSync.memory_scope(path)
+        return false if tmp_roots.any? { |tmp| within?(real, tmp) && !within?(session, tmp) }
+
+        true
+      end
+
+      # The tmp dirs that exist, resolved.
+      def self.tmp_roots
+        [Dir.tmpdir, *TMP_DIRS].filter_map do |dir|
+          File.realpath(dir) if File.directory?(dir)
+        rescue SystemCallError
+          nil
+        end.uniq
+      end
+
+      def self.within?(path, root) = path == root || path.start_with?(File.join(root, ""))
+    end
+  end
+end

data/lib/samagotchi/guardrails/parent_approvals.rb

@@ -5,6 +5,7 @@ require_relative "../paths"
 require_relative "../hooks/loader"
 require_relative "approval"
 require_relative "protected_paths"
+require_relative "parent_continue"
 
 module Samagotchi
   module Guardrails
@@ -115,6 +116,7 @@ module Samagotchi
       def message(reason, typed: false)
         deny = typed ? "deny it (n; WHY), and tell your user" : "deny it (--option Deny --text WHY), and tell your user"
         case reason
+        when :stop_only then ParentContinue.message
         when :protected then "this call changes chi's own config, hooks or guardrails, and only the user can allow it: #{deny}"
         when :off then "allowing a tool call is up to the user: #{deny}"
         else "only Allow once (#{KEY}: once) can be given here: #{deny}"

data/lib/samagotchi/guardrails/parent_continue.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "../config"
+
+module Samagotchi
+  module Guardrails
+    # Whether a parent agent may answer Continue to a session's step-limit
+    # question (kind "continue", ContinueOffer): turn.parent_continue,
+    # config.yml only, default true. Continue grants no permission (every
+    # tool call still meets the guardrails), it spends time and tokens;
+    # false makes parents stop-only. Checked by `chi answer` before it posts
+    # and by the worker's question desk for an answer marked as chi
+    # answer's, the way ParentApprovals is.
+    module ParentContinue
+      KEY = "turn.parent_continue"
+      KIND = "continue"
+      CONTINUE = "Continue"
+
+      module_function
+
+      # @return [Boolean] this process's setting
+      def allowed?
+        Config.get(KEY) != false
+      end
+
+      # Why a parent may not give this answer, or nil.
+      # @param pending [Hash] the pending question (symbol or string keys)
+      # @param selected [Array<String>] the selected labels
+      # @return [Symbol, nil] :stop_only
+      def refusal(pending, selected, allowed: allowed?)
+        return nil if allowed
+        return nil unless (pending[:kind] || pending["kind"]).to_s == KIND
+
+        Array(selected).map(&:to_s).include?(CONTINUE) ? :stop_only : nil
+      end
+
+      def message
+        "a parent agent may only stop this turn here (#{KEY}: false): answer Stop " \
+          "(--option Stop --text WHY), or tell your user it waits"
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/rules.rb

@@ -14,6 +14,8 @@ module Samagotchi
     #   path:    "outside_repo", or a glob on the resolved paths (absolute
     #            or "**/…" globs match the absolute path; others the path
     #            relative to the repo root, the cwd outside one)
+    #   git:     "outside_repo": a shell call runs a mutating git
+    #            subcommand outside the session's repo (ShellGitDirs)
     #   models:  "small" (Guardrails::ModelSize, guardrails.small_models),
     #            or a glob on the bare model name or the model key, or a
     #            list of them: the rule only votes for a model that matches
@@ -26,17 +28,19 @@ module Samagotchi
     class Rules
       class ParseError < StandardError; end
 
-      KEYS = %w[id tool command path models verdict reason scopes].freeze
+      KEYS = %w[id tool command path git models verdict reason scopes].freeze
+      MATCH_KEYS = %w[tool command path git].freeze
       VERDICTS = %w[ask deny].freeze
       GLOB_FLAGS = File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB
 
-      Rule = Struct.new(:id, :tools, :command, :path, :models, :verdict, :reason, :scopes, :source, keyword_init: true) do
+      Rule = Struct.new(:id, :tools, :command, :path, :git, :models, :verdict, :reason, :scopes, :source, keyword_init: true) do
         def matches?(targets)
           return false unless targets
           return false unless for_model?(targets.model_name, targets.model_key, -> { targets.small_model? })
           return false if tools && !tool_matches?(targets.tool)
           return false if command && !(targets.command && command.match?(targets.command))
           return false if path && !path_matches?(targets)
+          return false if git && !targets.git_outside_repo?
 
           true
         end
@@ -99,12 +103,12 @@ module Samagotchi
 
         verdict = raw["verdict"].to_s
         raise ParseError, "#{label}: verdict must be ask or deny (got #{verdict.inspect})" unless VERDICTS.include?(verdict)
-        unless %w[tool command path].any? { |k| raw.key?(k) }
-          raise ParseError, "#{label}: give at least one of tool, command, path"
+        unless MATCH_KEYS.any? { |k| raw.key?(k) }
+          raise ParseError, "#{label}: give at least one of #{MATCH_KEYS.join(", ")}"
         end
 
         Rule.new(id: id, tools: tools_of(raw["tool"], label), command: regex_of(raw["command"], label),
-                 path: path_of(raw["path"], label), models: models_of(raw["models"], label), verdict: verdict.to_sym,
+                 path: path_of(raw["path"], label), git: git_of(raw["git"], label), models: models_of(raw["models"], label), verdict: verdict.to_sym,
                  reason: (raw["reason"] || "rule #{id}").to_s, scopes: scopes_of(raw["scopes"], label), source: source)
       end
 
@@ -135,6 +139,14 @@ module Samagotchi
         value
       end
 
+      # Only "outside_repo" for now (room for globs later).
+      def self.git_of(value, label)
+        return nil if value.nil?
+        raise ParseError, "#{label}: git must be outside_repo" unless value == "outside_repo"
+
+        value
+      end
+
       def self.models_of(value, label)
         return nil if value.nil?