samagotchi 0.29.0 → 0.31.0

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -3,6 +3,7 @@
 require_relative "../served_model"
 require_relative "../image_store"
 require_relative "../turn_note"
+require_relative "../steer"
 
 module Samagotchi
   class TerminalUI
@@ -43,7 +44,8 @@ module Samagotchi
       # Who a steer names as its sender: a plugin's own label, chi's sender
       # ids in words (the web's format.js steerSender agrees;
       # spec/shared/labels_matrix.json). "": no one named.
-      STEER_SENDERS = { "parent_agent" => "parent agent", "chi_send" => "chi send", "plugin_send" => "plugin" }.freeze
+      STEER_SENDERS = { "parent_agent" => "parent agent", "chi_send" => "chi send", "plugin_send" => "plugin",
+                        "delegate_report" => "delegate report" }.freeze
 
       def steer_sender(source)
         STEER_SENDERS.fetch(source.to_s, source.to_s)
@@ -59,9 +61,13 @@ module Samagotchi
       end
 
       # "↻ empty answer, asking again (1/1)": the loop retries an empty answer;
-      # "↻ cut by loop-guard, asking again (1/1)" after a plugin cut it.
+      # "↻ cut by loop-guard, asking again (1/1)" after a plugin cut it;
+      # "↻ malformed answer, …" after a corrupt native generation.
       def format_empty_retry_line(event)
-        what = event[:stopped_by] ? "cut by #{event[:stopped_by]}" : "empty answer"
+        what = if event[:stopped_by] then "cut by #{event[:stopped_by]}"
+               elsif event[:malformed] then "malformed answer"
+               else "empty answer"
+               end
         paint("↻ #{what}, asking again (#{event[:attempt]}/#{event[:of]})", 90)
       end
 
@@ -109,7 +115,8 @@ module Samagotchi
 
       # Prompt labels by the sender's client_id prefix (turn_events.js
       # CLIENT_LABELS; spec/shared/labels_matrix.json).
-      CLIENT_LABELS = { "web" => "web", "tui" => "tui", "system" => "reminder", "delegate" => "delegate" }.freeze
+      CLIENT_LABELS = { "web" => "web", "tui" => "tui", "system" => "reminder", "delegate" => "delegate",
+                        "child" => "delegate report" }.freeze
 
       # "web> <prompt>": a prompt, labelled by who sent it.
       def prompt_line(client_id, prompt)
@@ -117,6 +124,26 @@ module Samagotchi
         "#{paint("#{label}>", 35)} #{prompt}"
       end
 
+      # "delegate report> 3f2a1c9e answered: <the reply's first line>": a
+      # delegate child's report (ChildReports) merged into the turn.
+      def report_line(report)
+        id = report[/\Asession: (\S+)/, 1].to_s[0, 8]
+        status = report[/^status: (.*)$/, 1]
+        rest = report.split("\n").drop(2).reject { |line| line.strip.empty? || line == "---" }.first.to_s
+        rest = "#{rest[0, STEER_PREVIEW - 1]}…" if rest.length > STEER_PREVIEW
+        "#{paint("#{CLIENT_LABELS["child"]}>", 35)} #{[id, status].compact.join(" ")}#{": #{rest}" unless rest.empty?}"
+      end
+
+      # The last prompt as a join shows it: a delegate report (a wake
+      # turn's) as the child's lines, anything else as the user's.
+      def join_prompt_line(message)
+        source = (message[:source] || message["source"]).to_s
+        content = (message[:content] || message["content"]).to_s
+        return prompt_line(nil, content) unless source == Steer::DELEGATE_REPORT
+
+        content.split(/\n\n(?=session: )/).map { |report| report_line(report) }.join("\n")
+      end
+
       # "reminder: a, b": the reminders a turn runs for (names or hashes).
       def reminder_line(reminders)
         names = Array(reminders).filter_map { |r| r.is_a?(Hash) ? r[:name] : r }
@@ -226,19 +253,22 @@ module Samagotchi
       # A cancel's reason as the UIs name it (anything else as it is);
       # spec/shared/labels_matrix.json pins it for both.
       CANCEL_REASONS = { "ctrl_c" => "Ctrl-C", "user" => "stopped", "hook" => "by a hook" }.freeze
+      # A canceled turn's mark: a stop someone chose (Ctrl-C, Stop, a hook),
+      # not an error's ✕ (timing.js STOP_MARK; the labels matrix pins it).
+      STOP_MARK = "■"
       # Under a canceled prompt turn (a canceled continue is back where it
       # started): its partial progress stays in the conversation.
       ROLLBACK_HINT = "partial progress kept; !rollback restores the pre-turn state"
 
-      # "✕ turn canceled (Ctrl-C) · 3.1s"; a hook's stop that names who
-      # (+by+, turn_canceled's cancelled_by): "✕ turn stopped by loop-guard"
+      # "■ turn canceled (Ctrl-C) · 3.1s"; a hook's stop that names who
+      # (+by+, turn_canceled's cancelled_by): "■ turn stopped by loop-guard"
       def turn_canceled_line(reason, duration_ms, by: nil)
         if reason.to_s == "hook" && !by.to_s.empty?
-          return "#{paint("✕", 33)} turn stopped by #{by}#{turn_duration_suffix(duration_ms)}"
+          return "#{paint(STOP_MARK, 33)} turn stopped by #{by}#{turn_duration_suffix(duration_ms)}"
         end
 
         label = reason.to_s.empty? ? nil : CANCEL_REASONS.fetch(reason.to_s, reason.to_s)
-        "#{paint("✕", 33)} turn canceled#{" (#{label})" if label}#{turn_duration_suffix(duration_ms)}"
+        "#{paint(STOP_MARK, 33)} turn canceled#{" (#{label})" if label}#{turn_duration_suffix(duration_ms)}"
       end
 
       # "✕ turn failed: <summary> · 2.0s"

data/lib/samagotchi/terminal_ui.rb

@@ -16,6 +16,7 @@ require_relative "host_registry"
 require_relative "session"
 require_relative "owner_lock"
 require_relative "bridge/card_store"
+require_relative "bridge/pending_card"
 require_relative "engine"
 require_relative "guardrails/parent_approvals"
 require_relative "tools/memory"
@@ -253,6 +254,7 @@ module Samagotchi
         ArchiveStore.user_input(session.id, state_dir: Session.default_state_dir)
         # Retry lines and hook notices on stderr; stdout gets the answer below.
         sink = OneShotSink.new
+        save_before_first_turn(session)
         begin
           result = @engine.run_turn(
             session,
@@ -298,7 +300,10 @@ module Samagotchi
     ensure
       # However it ends (the early returns too; the Engine was built in
       # #initialize): the anytime commands finish, the plugins' services
-      # stop (a server process).
+      # stop (a server process). Nothing resolves an open card any more, so
+      # its pending_card.json goes (a scratch session's folder is deleted
+      # below anyway; the others stay).
+      clear_pending_card
       @engine&.shutdown
       # A scratch session goes on every way out: /exit, Ctrl-D, an error,
       # SIGTERM or SIGHUP (Ruby raises those here). Only kill -9 leaves it
@@ -308,6 +313,17 @@ module Samagotchi
 
     EMPTY_ANSWER_ERROR = "chi: the model gave an empty answer"
 
+    # The session is over for this process (its exits and the ensure below):
+    # nothing will resolve the open card any more, so its pending_card.json
+    # goes (the Engine's TURN_END would clear it, but the REPL may end
+    # mid-turn).
+    def clear_pending_card
+      return unless @pending_card_handle
+
+      @pending_card_handle.observer.clear
+      @pending_card_handle = nil
+    end
+
     # A -p --non-interactive turn that failed (bin/chi exits 1): the error,
     # then how to go on. The Engine saved the failed turn with its prompt,
     # so the session is kept and `chi --resume` takes it up again.
@@ -415,13 +431,28 @@ module Samagotchi
       @surface.commit("Session #{session.id} was not archived (#{e.message}): chi sessions archive #{session.id}")
     end
 
-    # The session's cards.json, kept as a worker's Bridge keeps it (it owns
-    # the session as a worker would): this REPL's kept turns count on from
-    # the saved count, so a card an earlier worker showed stays that many
-    # turns back, and its own cards and notices are saved for the next.
+    # The session's cards.json and pending_card.json, kept as a worker's
+    # Bridge keeps them (it owns the session as a worker would): this REPL's
+    # kept turns count on from the saved count, so a card an earlier worker
+    # showed stays that many turns back, and its own cards and notices are
+    # saved for the next; an open card with actions is on disk, where
+    # `chi web`'s session hub reads it to mark the session as waiting.
     def keep_cards(session)
       path = File.join(Session.session_dir(session.id), Bridge::CardStore::FILE)
       @cards_handle ||= @engine.subscribe(observer: Bridge::CardStore.new(path: path))
+      keep_pending_card(session)
+    end
+
+    # A card a worker that died left isn't open: the file goes before the
+    # observer takes over, as Bridge#start does. Subscribed once: the REPL
+    # keeps one session, and a second observer would fold every card twice
+    # and clear the file at the first turn's end.
+    def keep_pending_card(session)
+      return if @pending_card_handle
+
+      pending = Bridge::PendingCard.new(Session.session_dir(session.id))
+      pending.clear
+      @pending_card_handle = @engine.subscribe(observer: pending)
     end
 
     # Take the session's OwnerLock for this process's lifetime: the TUI runs
@@ -552,6 +583,7 @@ module Samagotchi
       refresh_status_row
       # A prompt the user typed brings an archived session back to the lists.
       ArchiveStore.user_input(session.id, state_dir: Session.default_state_dir) if prompt && !continue
+      save_before_first_turn(session)
       with_steering do
         @engine.run_turn(
           session,
@@ -779,6 +811,13 @@ module Samagotchi
       session.save
     end
 
+    # A fresh session reaches the disk before its first turn: a tool in that
+    # turn reads it from there (delegate loads its parent to start a child,
+    # "Session not found" otherwise). Later turns find it saved already.
+    def save_before_first_turn(session)
+      session.save unless Session.exist?(session.id)
+    end
+
     # A !cmd shows its own output; everything else is the model> line.
     def show_command_result(result)
       if result.shell

data/lib/samagotchi/tool_activity.rb

@@ -176,10 +176,14 @@ module Samagotchi
     # "error" for an "Error:" result, and for an execute whose command
     # exited non-zero (its last "exit: N" line; no number: killed by a
     # signal), so the turn tally's "(N failed)" counts it. "stopped" for a
-    # task_wait the user's Stop ended (the task itself runs on), and for one
-    # whose task was stopped (the stop-task button, or the model's task_stop).
+    # task_wait the user's Stop ended (the task itself runs on), for one
+    # whose task was stopped (the stop-task button, or the model's task_stop),
+    # and for a command the user's Stop killed or kept from starting: a
+    # cancel, not a failure (its text still starts "Error:" for the model).
     def tool_activity_status(result, tool_name = nil)
       text = result.to_s
+      return "stopped" if text == Tools::Execute::NOT_RUN_ON_STOP
+      return "stopped" if tool_name == Tools::Execute::NAME && text.start_with?(Tools::Execute::STOPPED_BY_USER)
       return "error" if text.start_with?("Error:")
       return "error" if tool_name == Tools::Execute::NAME && execute_failed?(text)
       return "stopped" if tool_name == Tools::TaskWait::NAME && text.match?(/^(wait_result: canceled|status: stopped)$/)

data/lib/samagotchi/tool_call_parser.rb

@@ -40,6 +40,8 @@ module Samagotchi
       TOOL_CALL_BODY_RE = /\Acall:([a-z_][a-z0-9_]{0,49})\{/
       THOUGHT_CHANNEL_OPEN  = ModelProfile::GEMMA_THOUGHT_CHANNEL_OPEN
       THOUGHT_CHANNEL_CLOSE = ModelProfile::GEMMA_THOUGHT_CHANNEL_CLOSE
+      # Any channel's header (a thought's is THOUGHT_CHANNEL_OPEN).
+      THOUGHT_CHANNEL_HEADER = "<|channel>"
       CONTROL_TOKEN_START = "<|"
 
       def initialize(profile)
@@ -120,8 +122,43 @@ module Samagotchi
         [parse(response.to_s), nil]
       end
 
+      # Why +text+ (one generation) is corrupt, or nil. A Gemma 4
+      # generation ends a tool call with its close (the stop then comes at
+      # <|tool_response>), and thinks once, before the answer. A poisoned
+      # llama.cpp prompt cache (ggml-org/llama.cpp#27148) broke both: a
+      # call left open, then a fresh thought header and another
+      # conversation's answer.
+      def malformed(text)
+        text = text.to_s
+        return "unclosed tool call" if unclosed_tool_call?(text)
+
+        "thought header after the answer" if thought_after_answer?(strip_tool_calls(text))
+      end
+
       private
 
+      def unclosed_tool_call?(text)
+        pos = 0
+        while (open_pos = text.index(@tool_call_open, pos))
+          close_pos = text.index(@tool_call_close, open_pos + @tool_call_open.length)
+          return true unless close_pos
+
+          pos = close_pos + @tool_call_close.length
+        end
+        false
+      end
+
+      # A <|channel> header with visible text before it.
+      def thought_after_answer?(text)
+        pos = 0
+        while (header = text.index(THOUGHT_CHANNEL_HEADER, pos))
+          return true unless strip_thought(text[0...header]).strip.empty?
+
+          pos = header + THOUGHT_CHANNEL_HEADER.length
+        end
+        false
+      end
+
       # Scan forward from +start+ for the next <| sequence that is NOT the Gemma
       # string delimiter <|"|>.  Returns the position of that <| or nil if none.
       def next_real_control_token(text, start)
@@ -307,6 +344,9 @@ module Samagotchi
         read(text).map { |call| Tools::BuiltinCalls.build(call[:name], call[:args]) }
       end
 
+      # An open <tool_call> has its own recovery (#parse_with_recovery).
+      def malformed(_text) = nil
+
       # Each <tool_call> block as {name:, args:}: its <parameter=…>
       # (or <arg_key>/<arg_value>) text by lowercased key, unbuilt.
       def read(text)

data/lib/samagotchi/tool_declarations.rb

@@ -179,13 +179,13 @@ module Samagotchi
       },
       {
         name: "task_get",
-        description: "Get full metadata for a task by id. Use read on output_path to inspect command output.",
+        description: "Get a background task's metadata by its task id (from task_create or task_list; not a session id). Use read on output_path to inspect command output.",
         parameters: {
           type: "object",
           properties: {
             id: {
               type: "string",
-              description: "Task id returned by task_create"
+              description: "Task id from task_create/task_list, e.g. 20261005093000-1a2b3c4d"
             }
           },
           required: ["id"]
@@ -201,13 +201,13 @@ module Samagotchi
       },
       {
         name: "task_stop",
-        description: "Stop a running background task by id.",
+        description: "Stop a running background task by its task id (from task_create or task_list). Session ids don't work here.",
         parameters: {
           type: "object",
           properties: {
             id: {
               type: "string",
-              description: "Task id to stop"
+              description: "Task id from task_create/task_list, e.g. 20261005093000-1a2b3c4d"
             }
           },
           required: ["id"]
@@ -221,7 +221,7 @@ module Samagotchi
           properties: {
             task_id: {
               type: "string",
-              description: "Task id returned by task_create"
+              description: "Task id from task_create/task_list, e.g. 20261005093000-1a2b3c4d"
             },
             timeout: {
               type: "integer",
@@ -330,7 +330,7 @@ module Samagotchi
       },
       {
         name: "delegate",
-        description: "Hand a task to a child chi session that runs in parallel in this folder and returns only its final reply (its trace stays out of this context). The child is a normal session: it shows in the lists as a child of this one and the user can attach to it. With session, send a follow-up to one of this session's children instead. A tool call the child needs approved goes to your user as one of your own approvals; you only see how it was answered, as a line in the result. Children keep running if this turn is canceled; delegate_result waits for them later. A child stays until stopped: once its work is done, stop it with execute `chi sessions stop ID` (a follow-up with session wakes it again).",
+        description: "Hand a task to a child chi session that runs in parallel in this folder and returns only its final reply (its trace stays out of this context). The child is a normal session: it shows in the lists as a child of this one and the user can attach to it. With session, send a follow-up to one of this session's children instead. A tool call the child needs approved goes to your user as one of your own approvals; you only see how it was answered, as a line in the result. Children keep running if this turn is canceled. With wait false, chi brings each child's reply to you by itself when the child ends its turn (a delegate report, also when you are idle): don't poll it with delegate_result. To retry or redirect a child, use delegate with its session (task_* tools are for background commands, not sessions). A child stays until stopped: once its work is done, stop it with execute `chi sessions stop ID` (a follow-up with session wakes it again).",
         parameters: {
           type: "object",
           properties: {
@@ -360,7 +360,7 @@ module Samagotchi
       },
       {
         name: "delegate_result",
-        description: "Wait for a delegated child session's next reply: the child named, or this session's newest running child. Returns early if the child waits for a question the user must answer. A tool call the child needs approved goes to your user while this waits; the result says how it was answered.",
+        description: "Wait for a delegated child session's next reply: the child named, or this session's newest running child (name the child when a delegate report is about it). A delegate report already carries the reply: don't call this for it. Returns early if the child waits for a question the user must answer. A tool call the child needs approved goes to your user while this waits; the result says how it was answered.",
         parameters: {
           type: "object",
           properties: {

data/lib/samagotchi/tools/delegate.rb

@@ -5,6 +5,7 @@ require_relative "../config"
 require_relative "../model_profile"
 require_relative "peers"
 require_relative "delegate_wait"
+require_relative "../child_reports"
 
 module Samagotchi
   # Loaded on first use: session_manager requires terminal_ui, which
@@ -30,7 +31,7 @@ module Samagotchi
       STARTING_GRACE_SECONDS = 15
       # The memory every child starts with, scoped so a project memory of
       # the same name cannot shadow it.
-      CHILD_MEMORIES = ["system/delegated"].freeze
+      CHILD_MEMORIES = [Session::DELEGATE_MEMORY].freeze
 
       def self.name = NAME
 
@@ -51,21 +52,31 @@ module Samagotchi
         wait = parse_wait(wait)
         timeout = parse_timeout(timeout)
 
-        child_id = if session.to_s.strip.empty?
-                     start_child(task, parent: parent, model: model, state_dir: sd)
-                   else
-                     follow_up(task, session: session.to_s.strip, parent: parent, state_dir: sd)
-                   end
+        child_id, warning = if session.to_s.strip.empty?
+                              start_child(task, parent: parent, model: model, state_dir: sd)
+                            else
+                              follow_up(task, session: session.to_s.strip, parent: parent, state_dir: sd)
+                            end
         return child_id if child_id.start_with?("Error:")
-        return DelegateWait.call(child_id, peers: peers, timeout: timeout) if wait
+
+        note = warning ? "Warning: #{warning}\n" : ""
+        return note + DelegateWait.call(child_id, peers: peers, timeout: timeout) if wait
 
         started = session.to_s.strip.empty? ? "Started a delegate session" : "Sent the follow-up to delegate #{child_id[0, 8]}"
-        "session: #{child_id}\nstatus: running\n#{started}; delegate_result waits for its reply. " \
+        "#{note}session: #{child_id}\nstatus: running\n#{started}; #{running_hint} " \
           "It shows in chi sessions list and the web as a child of this session; the user can attach to it."
       rescue ArgumentError => e
         "Error: #{e.message}"
       end
 
+      # How the reply of a child left running comes back.
+      def self.running_hint
+        return "delegate_result waits for its reply." if ChildRing.mode == "off"
+
+        "chi brings its reply to you by itself when it ends its turn (a delegate report); don't poll with delegate_result."
+      end
+      private_class_method :running_hint
+
       # @return [String] the new child's id, or an Error: line
       def self.start_child(task, parent:, model:, state_dir:)
         if parent.parent_id
@@ -82,9 +93,9 @@ module Samagotchi
 
         child = SessionManager.spawn_session(prompt: task, working_directory: parent.working_directory,
                                              model_name: child_model(model, parent), memories: CHILD_MEMORIES,
-                                             parent_id: parent.id, state_dir: state_dir)
-        DelegateWait.mark_started(parent.id, child)
-        child.id
+                                             parent_id: parent.id, delegate: true, state_dir: state_dir)
+        DelegateWait.mark_started(parent.id, child, state_dir: state_dir)
+        [child.id, child.model_warning]
       end
       private_class_method :start_child
 
@@ -118,8 +129,10 @@ module Samagotchi
       private_class_method :follow_up
 
       # The model as typed (spawn_session stores its resolved ref), else the
-      # parent's. No existence check: an unknown model fails the child's
-      # first turn.
+      # parent's. No existence check here: spawn_session checks the host
+      # (check_host!, its UnknownHost comes back as this tool's Error: line)
+      # and warns about an id the host's saved model list doesn't have
+      # (ModelProfile.model_warning, added to this tool's result).
       def self.child_model(model, parent)
         return parent.model_name if model.to_s.strip.empty?
 

data/lib/samagotchi/tools/delegate_cursor.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require_relative "../atomic_file"
+require_relative "../session"
+
+module Samagotchi
+  module Tools
+    # What a parent was already told about one delegate child: the newest
+    # reply it was given (+reply_file+, ReplyWait's cursor) and the child as
+    # it was then (+messages+, +question_id+, +last_turn+: ReplyWait's
+    # baseline). nil +messages+ means no baseline.
+    DelegateCursor = Data.define(:reply_file, :last_turn, :question_id, :messages) do
+      def self.empty = new(reply_file: nil, last_turn: nil, question_id: nil, messages: nil)
+
+      # @param baseline [Hash, nil] ReplyWait.baseline_of's
+      def with_baseline(baseline)
+        b = baseline || {}
+        with(messages: b[:messages], question_id: b[:question_id], last_turn: b[:last_turn])
+      end
+
+      # @return [Hash, nil] ReplyWait's baseline:, nil when none was taken
+      def baseline
+        return nil if messages.nil?
+
+        { messages: messages, question_id: question_id, last_turn: last_turn }
+      end
+
+      def to_json_hash = to_h.transform_keys(&:to_s).compact
+    end
+
+    # The parent's cursors, one per child, in <parent dir>/delegates.json, so
+    # a respawned worker (or a REPL resuming the session) doesn't hand the
+    # model a reply it already had. Written by whoever owns the parent (its
+    # worker, or the REPL its kernel runs in), so a Mutex is enough for its
+    # turn thread vs its loop thread; the file is replaced whole.
+    module DelegateCursors
+      FILE = "delegates.json"
+      LOCK = Mutex.new
+
+      module_function
+
+      # @return [DelegateCursor] the child's cursor, empty when none
+      def get(parent_id, child_id, state_dir:)
+        get_from(read(parent_id, state_dir: state_dir), child_id)
+      end
+
+      # Read, change and write one child's cursor under the lock.
+      # @yieldparam cursor [DelegateCursor]
+      # @yieldreturn [DelegateCursor]
+      # @return [DelegateCursor] the new cursor
+      def update(parent_id, child_id, state_dir:)
+        LOCK.synchronize do
+          all = read(parent_id, state_dir: state_dir)
+          cursor = yield get_from(all, child_id)
+          all[child_id] = cursor.to_json_hash
+          write(parent_id, all, state_dir: state_dir)
+          cursor
+        end
+      end
+
+      def get_from(all, child_id)
+        data = all[child_id]
+        return DelegateCursor.empty unless data.is_a?(Hash)
+
+        DelegateCursor.new(reply_file: data["reply_file"], last_turn: data["last_turn"],
+                           question_id: data["question_id"], messages: data["messages"])
+      end
+
+      def path(parent_id, state_dir:)
+        File.join(Session.session_dir(parent_id, state_dir: state_dir), FILE)
+      end
+
+      # @return [Hash{String => Hash}] child id → cursor fields; {} when none
+      #   or unreadable
+      def read(parent_id, state_dir:)
+        data = JSON.parse(File.read(path(parent_id, state_dir: state_dir)))
+        data.is_a?(Hash) ? data : {}
+      rescue Errno::ENOENT, JSON::ParserError
+        {}
+      end
+
+      def write(parent_id, all, state_dir:)
+        file = path(parent_id, state_dir: state_dir)
+        FileUtils.mkdir_p(File.dirname(file))
+        AtomicFile.write(file, JSON.generate(all))
+      end
+    end
+  end
+end