samagotchi 0.49.0 → 0.51.0

data/lib/samagotchi/sessions_command.rb

@@ -9,19 +9,22 @@ require_relative "session_metrics"
 require_relative "recap_store"
 require_relative "session_delete_command"
 require_relative "session_archive_command"
+require_relative "bridge_client"
+require_relative "terminal_ui/formatting"
+require_relative "terminal_ui/event_renderer"
 require_relative "cli/command"
 require_relative "cli/flags"
 
 module Samagotchi
-  # `chi sessions`: list, stop, restart, archive/unarchive, delete, prune and clean
-  # sessions from the shell (bin/chi dispatches here before OptionParser;
-  # the subcommands have their own flags). Not SessionCommands, the REPL's
-  # slash commands for sessions (session_commands.rb).
+  # `chi sessions`: list, stop, restart, archive/unarchive, delete, prune,
+  # clean and stats sessions from the shell (bin/chi dispatches here before
+  # OptionParser; the subcommands have their own flags). Not SessionCommands,
+  # the REPL's slash commands for sessions (session_commands.rb).
   class SessionsCommand
     include CLI::Command
 
     USAGE = <<~TEXT
-      Usage: chi sessions <list|stop|restart|archive|unarchive|delete|prune|clean> [options]
+      Usage: chi sessions <list|stop|restart|archive|unarchive|delete|prune|clean|stats> [options]
         list [--sort updated_at|created_at] [--order desc|asc] [--limit N]
              [--live] [--cwd PATH] [--format text|json|tsv] [--archived]
              --live: sessions a worker runs now (the ones chi note reaches), 10 unless --limit
@@ -34,12 +37,18 @@ module Samagotchi
         delete [--force] ID...   # delete sessions for good (IDs or unique prefixes); --force stops a live worker first
         prune [--dry-run] [--days N] [--keep N] [--keep-status running,...] [--test-only]
         clean [--dry-run] [--days N]   # test sessions (SAMAGOTCHI_ENV=test, CI) and leftover chi scratch ones: all of them, or those older than N days
+        stats ID [--format text|json]   # a session's cost, tokens and progress, without running a model turn:
+             a live worker's GET stats, else the snapshot its saved analytics.json rebuilds (never starts a worker)
       Defaults: days=14 keep=500 keep_status=none (config: session.retention_days, session.max_count, session.keep_status)
     TEXT
 
     STOP_USAGE = "Usage: chi sessions stop ID...\n"
     RESTART_USAGE = "Usage: chi sessions restart ID...\n"
-    SUBCOMMANDS = %w[list stop restart archive unarchive delete prune clean].freeze
+    STATS_USAGE = "Usage: chi sessions stats ID [--format text|json]\n"
+    # How long `stats` waits for a live worker's GET stats before reading the
+    # saved analytics.json instead (a stuck worker must not hold a driver).
+    STATS_TIMEOUT = 3
+    SUBCOMMANDS = %w[list stop restart archive unarchive delete prune clean stats].freeze
 
     # Each subcommand's flags ("--flag V" or "--flag=V" for a value): an
     # unknown flag, a value flag with nothing after it or an argument where
@@ -53,6 +62,9 @@ module Samagotchi
       end,
       "stop" => CLI::Flags.new,
       "restart" => CLI::Flags.new,
+      "stats" => CLI::Flags.new do |f|
+        f.value "--format"
+      end,
       "prune" => CLI::Flags.new(args: false) do |f|
         %w[--days --keep --keep-status].each { |name| f.value name }
         f.switch "--dry-run"
@@ -98,6 +110,7 @@ module Samagotchi
       when "list" then list
       when "stop" then stop(parsed.args)
       when "restart" then restart(parsed.args)
+      when "stats" then stats(parsed.args)
       else prune(@sub)
       end
     end
@@ -105,7 +118,7 @@ module Samagotchi
     private
 
     def command_name = @sub && SUBCOMMANDS.include?(@sub) ? "chi sessions #{@sub}" : "chi sessions"
-    def usage_text = { "stop" => STOP_USAGE, "restart" => RESTART_USAGE }.fetch(@sub, USAGE)
+    def usage_text = { "stop" => STOP_USAGE, "restart" => RESTART_USAGE, "stats" => STATS_USAGE }.fetch(@sub, USAGE)
 
     # quirk: a number that isn't one is 0 (--days=abc turns the age limit off)
     def integers(options)
@@ -269,6 +282,70 @@ module Samagotchi
       0
     end
 
+    # One session's cost, tokens and progress, for a script or an agent that
+    # drives sessions (chi send --wait): a live worker's GET stats, else the
+    # snapshot its saved analytics.json rebuilds. Never starts a worker, and
+    # never sends the model anything.
+    def stats(ids)
+      return usage_error("give a session id") if ids.empty?
+      return usage_error("stats takes one session id") if ids.size > 1
+
+      format = @opts[:format]
+      unless format.nil? || %w[text json].include?(format)
+        return usage_error("unknown format #{format.inspect}: use --format text|json")
+      end
+
+      id = begin
+        Samagotchi::Session.resolve_id(ids.first)
+      rescue Samagotchi::Session::AmbiguousId => e
+        @stdout.flush
+        @stderr.puts e.message
+        return 1
+      end
+      session = begin
+        Samagotchi::Session.load(id)
+      rescue ArgumentError => e
+        @stdout.flush
+        @stderr.puts e.message
+        return 1
+      end
+
+      metrics, live, note = stats_snapshot_for(session)
+      if format == "json"
+        @stdout.puts JSON.generate({ session_id: session.id, status: session.status, live: live, metrics: metrics })
+      else
+        @stdout.puts "#{session.id[0, 8]}  #{session.status.ljust(7)} #{session.model_name}"
+        @stdout.puts TerminalUI::Formatting.format_session_metrics(metrics)
+        @stdout.puts note if note
+      end
+      0
+    end
+
+    # [snapshot, live, note]: a live worker answers GET stats (no model call);
+    # without one — or one that does not answer in time — the snapshot comes
+    # from the session's saved analytics.json, rebuilt by SessionMetrics (the
+    # same collector a worker runs, loaded from disk). The note says when the
+    # worker did not answer. nil when the session has no analytics.json yet.
+    # Never starts a worker.
+    # @return [Array(Hash, nil, Boolean, String, nil)]
+    def stats_snapshot_for(session)
+      dir = Samagotchi::Session.session_dir(session.id)
+      if (port = Samagotchi::BridgeClient.sidecar_port(dir))
+        client = Samagotchi::BridgeClient.new(session_id: session.id, port: port, read_timeout: STATS_TIMEOUT)
+        body = client.get_json("stats")&.dig("metrics")
+        if body.is_a?(Hash)
+          return [TerminalUI::EventRenderer.deep_symbolize_keys(body), true, nil]
+        end
+      end
+      return [nil, false, nil] unless File.file?(File.join(dir, "analytics.json"))
+
+      snapshot = Samagotchi::SessionMetrics.new.tap { |m| m.session_id = session.id }.saved_snapshot
+      note = live_worker?(session.id) ? "(no live worker answered; from the saved analytics.json)" : nil
+      [snapshot, false, note]
+    end
+
+    def live_worker?(session_id) = Samagotchi::SessionManager.worker_live?(session_id)
+
     def stop(ids)
       return usage_error("give session ids") if ids.empty?
 

data/lib/samagotchi/steer_cut.rb

@@ -44,21 +44,25 @@ module Samagotchi
     # Call it after the message is queued, with the #input_epoch read
     # before queueing it. Outside any lock; a cut that lands just after the
     # generation ended is harmless (the loop re-asks).
-    # @return [Boolean] whether a generation was cut now
+    # @return [Symbol] :now (a generation was cut now), :waits (the message
+    #   waits for the thinking to pass steer.cut_after), or :off (cutting
+    #   off for this source: a plugin, no turn, cut_after 0, a generation
+    #   that isn't thinking-only, or a drain already took the message)
     def cut_for_steer(source, epoch: nil)
-      return false unless Steer.cuts?(source)
+      return :off unless Steer.cuts?(source)
 
       after = Config.get("steer.cut_after").to_i
-      return false unless after.positive?
+      return :off unless after.positive?
 
       ctrl = @controller.call
-      return false unless ctrl
-      return cut!(ctrl, source.to_s) if @phase.cuttable?(after)
+      return :off unless ctrl
+      return cut!(ctrl, source.to_s) ? :now : :off if @phase.cuttable?(after)
 
-      Log.info(:turn, "steer_cut_waits", source: source.to_s) if @waiting.wait!(source, epoch: epoch)
-      false
+      waited = @waiting.wait!(source, epoch: epoch)
+      Log.info(:turn, "steer_cut_waits", source: source.to_s) if waited
+      waited ? :waits : :off
     rescue StandardError
-      false
+      :off
     end
 
     # The drains that took input so far (WaitingSteer#epoch): read it before

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -14,6 +14,7 @@ require_relative "reline_seam"
 require_relative "version_lines"
 require_relative "../bridge/turn_accumulator"
 require_relative "../bridge_client"
+require_relative "../delivery"
 require_relative "../log"
 require_relative "../context_note"
 require_relative "../steer"
@@ -380,6 +381,14 @@ module Samagotchi
           return answer_question(text)
         end
 
+        # /cut TEXT and /queue TEXT are this UI's own deliveries, read before
+        # every command check (SessionCommands registers them for Tab and
+        # /help only). A plain line sends no delivery: it goes in at the
+        # running turn's next step, and never cuts.
+        if (choice = steer_choice(text))
+          return submit_delivery(*choice)
+        end
+
         # The terminal's own commands (SessionCommands registers them, the
         # REPL reads the same words). Before the continue offer: the
         # leaving ones are no answer to it.
@@ -414,6 +423,20 @@ module Samagotchi
         nil
       end
 
+      # /cut TEXT and /queue TEXT while a turn runs. Only /cut goes in P1:
+      # the worker's drain doesn't skip queued files yet, so a queued
+      # message would steer the running turn; /queue says so and sends
+      # nothing. At the prompt both run the text as a normal turn.
+      # @return [nil]
+      def submit_delivery(choice, text)
+        return @screen.commit(STEER_CHOICE_USAGE) if text.empty?
+        return @screen.commit(QUEUE_UNAVAILABLE) if choice == :queue
+
+        # To an idle session it is an ordinary prompt: no delivery to send.
+        send_prompt(text, delivery: @running ? Delivery::CUT : nil)
+        nil
+      end
+
       # @return [Symbol] :detach
       def detach(line)
         @view.finish_thinking_spinner
@@ -573,6 +596,9 @@ module Samagotchi
       end
 
       QUEUED_NOTE = "(queued: runs after this turn)"
+      # /queue needs a worker whose drain skips queued input files (P3):
+      # until then a queued message would steer the running turn.
+      QUEUE_UNAVAILABLE = "(/queue isn't available in an attached session yet)"
 
       # A command queued for after the running turn (command_queued with
       # waits): its line now (another client's) and a note; its command_ran
@@ -661,19 +687,40 @@ module Samagotchi
         end
       end
 
-      def send_prompt(text)
+      # What a prompt's 202 says became of it, or nil when there is nothing
+      # to say: the dim line both TUIs print for a delivery. A plain line
+      # for a running turn goes in at its next step; a cut's outcome comes
+      # from the ack (the worker knows whether cutting is on for its model).
+      # An idle session's prompt simply runs, and a prompt with images runs
+      # as its own next turn (never merging mid-turn), so nothing is said.
+      # @param ack [Hash, nil] the Bridge's 202 body
+      # @param delivery [String, nil] what was asked for
+      # @return [String, nil]
+      def sent_note(ack, delivery: nil, images: [], running: false)
+        return nil unless running && images.empty? && ack.is_a?(Hash)
+
+        return NEXT_STEP_NOTE unless delivery == Delivery::CUT
+
+        steer_cut_note(ack["cut"].to_s.to_sym)
+      end
+
+      def send_prompt(text, delivery: nil)
         persist_recent_history(text)
         images = attach_images(text)
         return own_prompt_failed if images.nil?
 
+        running = @running
         options = { prompt: text, client_id: @client_id }
         options[:no_interrupt] = true if @no_interrupt
         options[:images] = images unless images.empty?
+        options[:delivery] = delivery if delivery
         reply = @client.post_turn(**options)
         if reply.status == 202
           enqueued_id = reply.json&.fetch("enqueued_id", nil)
           @sent_ids << enqueued_id if enqueued_id
           @open_ids << enqueued_id if enqueued_id && @wait_at_eof
+          note = sent_note(reply.json, delivery: delivery, images: images, running: running)
+          @screen.commit(note) if note
           return
         end
 
@@ -1226,7 +1273,7 @@ module Samagotchi
                      params: part[:params], status: status,
                      description: ToolView.description_title(part[:view] || {}) }
         "#{format_tool_activity_line(activity, duration_ms: duration_ms)}" \
-          "#{format_tool_image_suffix(part[:images])}#{format_tool_diff_suffix(part[:diff])}"
+          "#{format_tool_image_suffix(part[:images])}#{format_tool_diff_suffix(part[:diff])}#{format_tool_cut_suffix(part[:output_truncated])}"
       end
 
       # The context notes that came since the last prompt (all of them in a
@@ -1320,7 +1367,7 @@ module Samagotchi
 
         activity = EventRenderer.described(event) || {}
         @screen.commit(snapshot_tool_line({ tool: event[:tool], params: activity[:params], status: activity[:status],
-                                            description: activity[:description],
+                                            description: activity[:description], output_truncated: event[:output_truncated],
                                             images: event[:images], diff: event[:diff] }))
       end
 

data/lib/samagotchi/terminal_ui/event_renderer.rb

@@ -72,7 +72,8 @@ module Samagotchi
           # A replayed row (a join) carries its duration (nil: unknown).
           measured = tool_duration_ms(event)
           render_streamed_tool_activity(self.class.described(event), duration_ms: event.fetch(:duration_ms, measured),
-                                                                     images: event[:images], diff: event[:diff])
+                                                                     images: event[:images], diff: event[:diff],
+                                                                     output_truncated: event[:output_truncated])
         when :generation_completed, :generation_cancelled, :tool_dispatch_started
           @view.generation_feedback_finished
         when :pending_input_merged
@@ -211,13 +212,14 @@ module Samagotchi
 
       private
 
-      def render_streamed_tool_activity(activity, duration_ms:, images: nil, diff: nil)
+      def render_streamed_tool_activity(activity, duration_ms:, images: nil, diff: nil, output_truncated: nil)
         return if activity.nil?
 
         @streamed_tool_activity[tool_activity_key(activity)] += 1
         line = @view.format_tool_activity_line(activity, duration_ms: duration_ms)
         line += @view.format_tool_image_suffix(images) if images&.any?
         line += @view.format_tool_diff_suffix(diff) if diff
+        line += @view.format_tool_cut_suffix(output_truncated) if output_truncated
         @view.print_line(line)
       end
 

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -14,6 +14,14 @@ module Samagotchi
     # `tool>` line, elapsed durations. Pure apart from reading whether
     # $stdout is a colour terminal.
     module Formatting
+      # The /stats text for a metrics snapshot, for the REPL and attached
+      # views (an instance includes the module) and for `chi sessions stats`
+      # (no UI: the same text from the CLI).
+      # @return [String] "(no metrics yet)" without a snapshot
+      def self.format_session_metrics(snapshot)
+        (@formatter ||= Object.new.extend(Formatting)).send(:format_session_metrics, snapshot)
+      end
+
       def format_tool_activity_line(activity, duration_ms: nil)
         status = activity[:status].to_s
         elapsed_suffix = duration_ms.nil? ? "" : " (#{format_elapsed_duration(duration_ms)})"
@@ -23,13 +31,17 @@ module Samagotchi
 
       # What a tool line says the call did: the model's description of a
       # command (": List the specs") in place of its cut params, else the
-      # params, dim.
+      # params, dim; then, dim, the name the model called it by when that was
+      # an alias's (" (called as bash)").
       def tool_params_suffix(activity)
         description = activity[:description].to_s.strip
-        return ": #{description}" unless description.empty?
-
         params = activity[:params].to_s.strip
-        params.empty? ? "" : " #{paint(params, 90)}"
+        suffix = if !description.empty? then ": #{description}"
+                 elsif !params.empty? then " #{paint(params, 90)}"
+                 else ""
+                 end
+        called_as = activity[:called_as].to_s
+        called_as.empty? ? suffix : "#{suffix}#{paint(" (called as #{called_as})", 90)}"
       end
 
       # Green ok, yellow stopped (a wait the user's Stop ended), red the rest.
@@ -83,6 +95,45 @@ module Samagotchi
         paint("↪ cut in for #{STEER_CUT_FOR.fetch(event[:source].to_s, "your message")}", 90)
       end
 
+      # What a line submitted at the open prompt says became of it: a plain
+      # line goes in at the running turn's next step boundary (nothing cuts
+      # unless the message asked for it), /cut's cutting now or once the
+      # thinking passes steer.cut_after, and /queue's waiting for the end.
+      # Both TUIs print the same words (SteerCut#cut_for_steer's answer).
+      NEXT_STEP_NOTE = "(goes in at the next step)"
+      CUT_NOW_NOTE = "(cut in now)"
+      CUT_WAITS_NOTE = "(cuts in once the thinking passes %d s)"
+      CUT_OFF_NOTE = "(cutting is off; goes in at the next step)"
+      STEER_CHOICE_USAGE = "(/cut and /queue need a message: /cut TEXT, /queue TEXT)"
+      # The UIs' own words for a delivery, listed for Tab and /help only
+      # (a local: entry, so no command or bundle may use the names).
+      CUT_COMMAND = "/cut"
+      QUEUE_COMMAND = "/queue"
+      # The word, then any whitespace and the text (as the registry's
+      # entries match them, so a line Tab or /help knows is never a prompt).
+      STEER_CHOICE = /\A(#{CUT_COMMAND}|#{QUEUE_COMMAND})(?:\s+(.*))?\z/m
+
+      # @param outcome [Symbol] SteerCut#cut_for_steer's answer: :now, :waits or :off
+      # @return [String] the dim line to show for a /cut
+      def steer_cut_note(outcome)
+        case outcome
+        when :now then CUT_NOW_NOTE
+        when :waits then format(CUT_WAITS_NOTE, Config.get("steer.cut_after").to_i)
+        else CUT_OFF_NOTE
+        end
+      end
+
+      # The choice a mid-turn line carries, as [:cut, "TEXT"] or
+      # [:queue, "TEXT"]; nil for any other line. The text is "" when the
+      # line named the choice without one.
+      # @param line [String, nil]
+      # @return [Array(Symbol, String), nil]
+      def steer_choice(line)
+        match = STEER_CHOICE.match(line.to_s.strip) or return nil
+
+        [match[1] == CUT_COMMAND ? :cut : :queue, match[2].to_s.strip]
+      end
+
       # "✂ forgot 2 outputs, stubbed 1 stale read · frees ~4.1k tokens (paid
       # off)": a batch of LLM context edits went in (LLMContextNotice builds
       # the line; the web prints the same), dim like the retry row.
@@ -138,6 +189,12 @@ module Samagotchi
         " #{paint("+#{get.call(:added).to_i}", 32)} #{paint("\u2212#{get.call(:removed).to_i}", 31)}"
       end
 
+      # A row whose output the runner cut (max_tool_output_chars): " [cut]",
+      # dim, beside the diff one.
+      def format_tool_cut_suffix(output_truncated)
+        output_truncated ? " #{paint("[cut]", 90)}" : ""
+      end
+
       # Prompt labels by the sender's client_id: a whole id, or a prefix
       # (ending in ":") it starts with (turn_events.js CLIENT_LABELS;
       # spec/shared/labels_matrix.json).
@@ -212,7 +269,7 @@ module Samagotchi
       def snapshot_tool_line(part)
         status = part[:status].to_s
         "#{paint("tool>", 36)} #{part[:tool]}#{tool_params_suffix(part)}: #{paint(status, status_color(status))}" \
-          "#{format_tool_image_suffix(part[:images])}#{format_tool_diff_suffix(part[:diff])}"
+          "#{format_tool_image_suffix(part[:images])}#{format_tool_diff_suffix(part[:diff])}#{format_tool_cut_suffix(part[:output_truncated])}"
       end
 
       # A card (Engine#show_card) as a framed block: the title and its
@@ -482,7 +539,8 @@ module Samagotchi
       end
 
       # Render the analytics snapshot as a compact, user-facing report. Raw event
-      # logs (debug-only) are intentionally excluded; this surface is for the REPL.
+      # logs (debug-only) are intentionally excluded; this surface is for the REPL
+      # and `chi sessions stats` (the module function above).
       def format_session_metrics(snapshot)
         return "(no metrics yet)" unless snapshot.is_a?(Hash)
 
@@ -501,6 +559,10 @@ module Samagotchi
           by_tool = snapshot[:tool_calls_by_tool].sort_by { |_k, v| -v }
           lines << "  by tool:        #{by_tool.map { |k, v| "#{k}=#{v}" }.join(", ")}"
         end
+        unless snapshot[:tool_calls_aliased].to_a.empty?
+          aliased = snapshot[:tool_calls_aliased].sort_by { |_k, v| -v }
+          lines << "  called as:      #{aliased.map { |k, v| "#{k}=#{v}" }.join(", ")}"
+        end
         lines << "iterations:       #{snapshot[:iterations_total]}"
         # Summed over every request: each prompt is sent in full again.
         lines << "tokens in/out:    #{tokens[:prompt_sum].to_i}/#{tokens[:completion_sum].to_i} (all requests, #{token_src_label})" \

data/lib/samagotchi/terminal_ui.rb

@@ -752,6 +752,14 @@ module Samagotchi
     def run_input_line(session, input)
       return if input.empty?
 
+      # /cut TEXT and /queue TEXT are deliveries only while a turn runs; at
+      # the prompt both run the text as a normal turn, as their usage says.
+      if (choice = steer_choice(input))
+        return @surface.commit(STEER_CHOICE_USAGE) if choice.last.empty?
+
+        input = choice.last
+      end
+
       # /model, /models, !rollback, !cmd, /continue (shared with workers);
       # an anytime command's cards print as it shows them (btw's
       # "thinking…" before the answer).
@@ -1083,6 +1091,10 @@ module Samagotchi
     # plugin's /btw, /model alone) starts now on its own thread; one that
     # runs after the turn (/model X, !cmd) waits in the queue, in arrival
     # order with the other lines that wait; others go back in the prompt.
+    #
+    # A plain line goes in at the running turn's next step boundary and
+    # never cuts; /cut TEXT asks for a cut, /queue TEXT waits for the turn
+    # to end and runs as a turn of its own.
     # @return [Boolean, :back] whether the turn took it, :back to put it back
     def steer_line(line)
       local = local_command(line) unless line.nil?
@@ -1091,6 +1103,12 @@ module Samagotchi
       return detach_note if local == :detach
       return false if @active_cancel_controller&.cancelled?
 
+      # Before every command check: /cut and /queue are the UIs' own words
+      # for a delivery (they are listed for Tab and /help, never run).
+      if (choice = steer_choice(line))
+        return submit_steer_choice(*choice)
+      end
+
       policy = command_registry.mid_turn(line)
       return start_anytime_command(line) if policy == :anytime
       return command_queued(line) if policy == :queue
@@ -1108,12 +1126,37 @@ module Samagotchi
       # Behind a command that waits for the turn's end, a line waits too.
       return wait_for_turn_end(line) if @command_waits
 
-      epoch = @engine.input_epoch
       @pending_input_queue.push(line.strip)
-      # The user's line cuts a generation that has streamed only thinking
-      # for long (steer.cut_after), now or once it has: the model starts the
-      # step again with it.
-      @engine.cut_for_steer(nil, epoch: epoch)
+      @surface.commit(NEXT_STEP_NOTE)
+      true
+    end
+
+    # /cut TEXT and /queue TEXT during a turn, which the REPL would
+    # otherwise read as prompts (SessionCommands registers them for Tab and
+    # help only). A cut asks the engine to cut the generation only thinking
+    # too long; a queue waits for the turn's end (the REPL's own after-turn
+    # list). Empty text gets the usage line. A line with images never steers
+    # (as a plain one doesn't).
+    # @return [Boolean] whether the turn took it
+    def submit_steer_choice(choice, text)
+      if text.empty?
+        @surface.commit(STEER_CHOICE_USAGE)
+        return true
+      end
+      return image_line_waits(text) if ImageInput.extract(text).any?
+
+      # A /queue waits for the turn's end; a /cut behind a command that
+      # already waits there goes after it too.
+      if choice == :queue || @command_waits
+        @surface.commit(COMMAND_QUEUED)
+        return wait_for_turn_end(text)
+      end
+
+      epoch = @engine.input_epoch
+      @pending_input_queue.push(text)
+      # With no session running the cut is :off; the text still waits for
+      # the running turn's next step.
+      @surface.commit(steer_cut_note(@engine.cut_for_steer(nil, epoch: epoch)))
       true
     end
 

data/lib/samagotchi/tool_activity.rb

@@ -47,6 +47,9 @@ module Samagotchi
       }
       title = tool_title(tool_name, call, cwd: cwd)
       event[:title] = title if title
+      # The name the model used when an alias ran a built-in (called_as: "bash"
+      # for an execute), for a UI that shows it.
+      event[:called_as] = call[:called_as] if call.is_a?(Hash) && call[:called_as]
       # The model's own words for a command, which the TUI's tool line
       # shows in place of the cut params.
       description = command_description(tool_name, call)

data/lib/samagotchi/tool_runner.rb

@@ -57,6 +57,8 @@ module Samagotchi
       # The worker runs in its session's working directory.
       title = ToolActivity.tool_title(call[:name], call, cwd: Dir.pwd)
       started[:title] = title if title
+      # The name the model called it by when that was an alias's (bash).
+      started[:called_as] = call[:called_as] if call[:called_as]
       # The full command for a richer UI (params stays cut at 80).
       view = ToolView.for(call[:name], call)&.to_h
       started[:view] = view if view

data/lib/samagotchi/tools/builtin_calls.rb

@@ -56,6 +56,13 @@ module Samagotchi
         "forget_outputs" => { content: "note", also: %w[note], verbatim: %w[ids keep restore] }
       }.freeze
 
+      # A name the model uses for a built-in, mapped to that built-in (a model
+      # that keeps calling `bash` with execute's arguments; before this such a
+      # call died as an unknown tool). It only takes effect when the
+      # arguments really are the target's shape; the call then carries
+      # called_as: with the model's own spelling.
+      ALIASES = { "bash" => "execute" }.freeze
+
       # One built-in's mapping, resolved from its schema and OVERRIDES.
       Row = Data.define(:name, :content_keys, :path_key, :fields, :aliases, :verbatim, :fallback, :fallback_key,
                         :options) do
@@ -109,6 +116,14 @@ module Samagotchi
       def build(name, args, raw: nil)
         name = name.to_s
         args = args.is_a?(Hash) ? args.transform_keys(&:to_s) : {}
+        # An alias runs its target (bash → execute); the row is the target's,
+        # and the call keeps the model's own spelling on called_as:.
+        # Not the target's shape (a String main argument, only its keys) and
+        # the alias doesn't take: the call passes through as an unknown tool.
+        if (target = ALIASES[name.downcase])
+          return aliasable?(row(target), args) ? aliased(name, target, args, raw) : passthrough(name, args, raw)
+        end
+
         row = row(name)
         return passthrough(name, args, raw) unless row
 
@@ -120,6 +135,24 @@ module Samagotchi
         call
       end
 
+      # An execute-shaped call the model spelled +name+: built as its +target+,
+      # tagged with the model's spelling for the activity event and the log.
+      def aliased(name, target, args, raw)
+        call = build(target, args, raw: raw)
+        call[:called_as] = name
+        call
+      end
+
+      # The alias gate: a String main argument, and every key one the target's
+      # schema knows (its aliases included). More, or differently shaped, the
+      # call is the model's own and passes through as an unknown tool.
+      def aliasable?(row, args)
+        return false unless row
+
+        row.content_keys.map { |key| value(row, args, key) }.any?(String) &&
+          (args.keys - (row.content_keys + [row.path_key].compact + row.fields + row.aliases.keys)).empty?
+      end
+
       def content_value(row, args)
         found = row.content_keys.lazy.map { |key| value(row, args, key) }.find { |v| !v.nil? }
         found.nil? ? "" : found.to_s

data/lib/samagotchi/version.rb

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

data/lib/samagotchi/web/app.rb

@@ -1065,8 +1065,12 @@ module Samagotchi
         images = turn_images(id, body["images"])
         return error_response(400, "bad_images", images) if images.is_a?(String)
 
-        result = SessionManager.deliver_turn(id, prompt: prompt.to_s, client_id: client_id, images: images, state_dir: @state_dir,
-                                             manager: @manager, bridge: -> { live_bridge_client(id) })
+        delivery = body["delivery"] || body[:delivery]
+        return error_response(400, "bad_delivery", "delivery must be a string") unless delivery.nil? || delivery.is_a?(String)
+
+        result = SessionManager.deliver_turn(id, prompt: prompt.to_s, client_id: client_id, images: images,
+                                                 delivery: delivery, state_dir: @state_dir, manager: @manager,
+                                                 bridge: -> { live_bridge_client(id) })
         case result[:status]
         when :accepted
           record_history(body, prompt)

data/lib/samagotchi/web/message_parts.rb

@@ -233,6 +233,9 @@ module Samagotchi
         part = { tool: name, params: params.to_s }
         title = ToolActivity.tool_title(name, call, cwd: cwd)
         part[:title] = title if title
+        # The name the model called it by when that was an alias's (the
+        # saved call is rebuilt by BuiltinCalls, which sets it again).
+        part[:called_as] = call[:called_as] if call[:called_as]
         # Built from the saved call (never saved itself), so older sessions
         # get it too.
         view = ToolView.for(name, call)&.to_h