samagotchi 0.42.0 → 0.44.0

data/lib/samagotchi/plugin/attached_context.rb

@@ -27,27 +27,71 @@ module Samagotchi
       # +name+ and +cmd+ (+hint+, +every_seconds+). A source of that name
       # already attached stays as it is. One the user removed from the
       # session (its name, or its URL) isn't attached again (#declined?)
-      # until the user adds it again.
+      # until the user adds it again, or +force+: the user's own explicit
+      # choice (a click), which clears the declined marker (by the name,
+      # and by the URL).
       # @return [String, nil] the source's name; nil when declined
       # @raise [Error]
-      def attach(url: nil, name: nil, cmd: nil, why: nil, hint: nil, every_seconds: nil)
-        own = location or raise Error, "this session has no id yet"
+      def attach(url: nil, name: nil, cmd: nil, why: nil, hint: nil, every_seconds: nil, force: false)
+        own = own_location!
         source = url ? from_url(url, name: name, why: why) : from_cmd(name: name, cmd: cmd, why: why, hint: hint, every_seconds: every_seconds)
-        return nil if own.declined?(source.name) || (url && own.declined_hints.include?(source.hint))
+        if force
+          own.undecline(source.name, hint: url && source.hint)
+        elsif own.declined?(source.name) || (url && own.declined_hints.include?(source.hint))
+          return nil
+        end
         return source.name if own.source(source.name)
 
-        own.add(source.with(scope: own.scope))
-        source.name
+        add(own, source)
       rescue ContextSources::Invalid, ContextProviders::Invalid => e
         raise Error, e.message
       end
 
-      # Whether the user removed +name+ from this session (so #attach skips it).
-      def declined?(name)
-        own = location
-        own ? own.declined?(name) : false
+      # Marks +name+ (or +url+'s source, through its provider) declined in
+      # this session, as the user's removal does: #attach skips it until the
+      # user adds it again. An attached source stays (chi context rm).
+      # @return [String] the name
+      # @raise [Error]
+      def decline(url: nil, name: nil)
+        own = own_location!
+        if url
+          resolved = ContextProviders.resolve(url) or raise Error, "no installed bundle resolves #{url}"
+          name = name ? ContextSources.check_name!(name) : resolved.name
+          hint = resolved.hint
+        else
+          raise Error, "give url: or name:" if name.to_s.empty?
+
+          name = ContextSources.check_name!(name)
+        end
+        own.decline(name, hint)
+        name
+      rescue ContextSources::Invalid, ContextProviders::Invalid => e
+        raise Error, e.message
+      end
+
+      # Whether the user removed +name+ (or +url+) from this session (so
+      # #attach skips it).
+      def declined?(name = nil, url: nil)
+        own = location or return false
+        name_declined?(own, name) || (!url.to_s.empty? && own.declined_hints.include?(url))
+      end
+
+      # Records that this plugin offered +name+ (+hint+: its URL; +why+: the
+      # reason an attach from the offer gives) here, so a worker restart
+      # doesn't offer it again.
+      # @return [ContextSources::Offer]
+      # @raise [Error]
+      def mark_offered(name, hint, why: nil)
+        own_location!.mark_offered(name, hint, why: why)
+      rescue ContextSources::Invalid => e
+        raise Error, e.message
+      end
+
+      # @return [ContextSources::Offer, nil] the offer #mark_offered recorded
+      def offered(name)
+        location&.offered(name)
       rescue ContextSources::Invalid
-        false
+        nil
       end
 
       # This session's sources (its own, then its project's).
@@ -69,6 +113,26 @@ module Samagotchi
 
       def state_dir = @host.state_dir&.call || Session.default_state_dir
 
+      # Two attaches at once (a double click): the one that lost the race
+      # finds the source there and returns its name too.
+      def add(own, source)
+        own.add(source.with(scope: own.scope))
+        source.name
+      rescue ContextSources::Invalid
+        raise unless own.source(source.name)
+
+        source.name
+      end
+
+      # An invalid name isn't declined (and doesn't hide the URL's check).
+      def name_declined?(own, name)
+        !name.nil? && own.declined?(name)
+      rescue ContextSources::Invalid
+        false
+      end
+
+      def own_location! = location || raise(Error, "this session has no id yet")
+
       def location
         id = @host.session_id.call
         id && ContextSources.session_location(id, state_dir: state_dir)

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -1222,7 +1222,8 @@ module Samagotchi
           # hook's notice, a retry's line), as they were drawn live.
           # Questions are left out: the pending one is asked after the
           # replay, answered ones showed no line.
-          when :turn_started, :pending_input_merged, :hook_notice, :empty_answer_retry, :steer_cut then @renderer.call(event)
+          when :turn_started, :pending_input_merged, :hook_notice, :empty_answer_retry, :steer_cut, :llm_context_edited
+            @renderer.call(event)
           end
         end
         @view.resume(tail: tail, lane: lane, tool: running_tool, parts: turn[:parts])

data/lib/samagotchi/terminal_ui/event_renderer.rb

@@ -83,6 +83,9 @@ module Samagotchi
         when :steer_cut
           @view.finish_thinking_spinner
           @view.print_line(@view.format_steer_cut_line(event))
+        when :llm_context_edited
+          @view.finish_thinking_spinner
+          @view.print_line(@view.format_llm_context_line(event))
         when :turn_completed
           render_turn_summary(event[:turn_summary]) if event[:turn_summary]
         when :turn_canceled

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -83,6 +83,13 @@ module Samagotchi
         paint("↪ cut in for #{STEER_CUT_FOR.fetch(event[:source].to_s, "your message")}", 90)
       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.
+      def format_llm_context_line(event)
+        paint(event[:text].to_s.empty? ? "✂ LLM context edited" : event[:text].to_s, 90)
+      end
+
       # "no answer: the model returned nothing (after 1 retry)", dim like the
       # retry row: a turn that ended with no answer (TurnNote.empty_answer_line).
       def format_empty_answer_line(retries)

data/lib/samagotchi/terminal_ui/one_shot_sink.rb

@@ -30,6 +30,7 @@ module Samagotchi
         case event[:type]
         when :empty_answer_retry then line(format_empty_retry_line(event))
         when :steer_cut then line(format_steer_cut_line(event))
+        when :llm_context_edited then line(format_llm_context_line(event))
         when :generation_retrying then line(format_generation_retry_line(event))
         when :turn_completed, :turn_canceled then @turn_over = true
         when :hook_notice

data/lib/samagotchi/tool_declarations.rb

@@ -3,6 +3,7 @@
 require "json"
 require_relative "tools/args"
 require_relative "llm_context_strategy"
+require_relative "tools/memory"
 
 module Samagotchi
   # Tool-declaration constants, protocol constants, and guidance text.
@@ -146,7 +147,7 @@ module Samagotchi
             },
             description: {
               type: "string",
-              description: "Optional one-line description (at most 200 characters) appended to the managed index line; without content, it changes only that line"
+              description: "Optional one-line description (at most #{Tools::MemoryWrite::DESCRIPTION_LIMIT} characters) appended to the managed index line; without content, it changes only that line"
             },
             current_model_only: {
               type: "boolean",

data/lib/samagotchi/version.rb

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

data/lib/samagotchi/web/app.rb

@@ -20,6 +20,7 @@ require_relative "../session_metrics"
 require_relative "../session_commands"
 require_relative "../steer"
 require_relative "../host_registry"
+require_relative "../llm_context_override"
 require_relative "../model_catalog"
 require_relative "../model_profile"
 require_relative "../sampling_settings"
@@ -458,7 +459,8 @@ module Samagotchi
       end
 
       # Each model's configured sampling as /model words it ("temperature=0.6
-      # (hosts.work)"), on the models that have some: the picker's tooltip.
+      # (hosts.work)"), on the models that have some: the picker's tooltip;
+      # and each model's LLM context (LLMContextStrategy::Explained#summary).
       # A config that can't be read leaves the list as it is.
       def add_sampling(models, registry)
         return if registry.nil? || models.empty?
@@ -466,14 +468,23 @@ module Samagotchi
         settings = ConfigFile.model_settings
         models.each do |model|
           target = registry.resolve(model[:name])
-          summary = SamplingSettings.summary(target, names: registry.lookup_names(model[:name], target: target),
-                                                     models: settings)
+          names = registry.lookup_names(model[:name], target: target)
+          summary = SamplingSettings.summary(target, names: names, models: settings)
           model[:sampling] = summary if summary
+          add_llm_context(model, target, names, settings)
         end
       rescue StandardError
         nil
       end
 
+      # The LLM context +model+ starts under (the start page's llm ctx chip);
+      # one that can't be read leaves this model without, not the others.
+      def add_llm_context(model, target, names, settings)
+        model[:llm_context] = LLMContextStrategy.explain(target, names: names, models: settings).summary(nil)
+      rescue StandardError
+        nil
+      end
+
       # A session's LLM context strategy, apply rule and budget, each with
       # where it came from (LLMContextStrategy::Explained#summary), as its
       # worker would resolve them; nil when they can't be.
@@ -563,6 +574,12 @@ module Samagotchi
         dir, error = scope_dir(body["dir"])
         return error if error
 
+        # llm_context: the session's own LLM context values before its first
+        # turn (the start page's llm ctx chip; chi --llm-context), read
+        # before anything spawns so a bad one spawns nothing.
+        llm_context, error = request_llm_context(body["llm_context"])
+        return error if error
+
         folder = dir ? { working_directory: dir } : {}
         # model: the model the session starts on (the start page's picker,
         # spelled as GET /api/models lists it); blank means the default.
@@ -573,6 +590,7 @@ module Samagotchi
         # until that turn is saved.
         preview = idle ? body["preview"].to_s.strip : ""
         folder[:title] = preview unless preview.empty?
+        folder[:llm_context] = llm_context if llm_context
         begin
           session = @manager.spawn_session(prompt: idle ? nil : prompt.to_s, state_dir: @state_dir, **folder)
         rescue ModelProfile::MissingModel => e
@@ -588,6 +606,25 @@ module Samagotchi
         json_response(201, session_to_json(session).merge(bridge_port: port))
       end
 
+      # The create request's "llm_context" ({strategy:, apply:, budget:},
+      # each a word as /llm-context takes it, "default" for unset) as an
+      # override: [override, nil] (nil when absent or all default), or
+      # [nil, a 400 response] for anything else.
+      def request_llm_context(raw)
+        return [nil, nil] if raw.nil?
+
+        fields = LLMContextOverride::COMMAND_WORDS.invert
+        unless raw.is_a?(Hash) && raw.all? { |key, word| fields.key?(key) && word.is_a?(String) }
+          return [nil, error_response(400, "invalid_llm_context",
+                                      "llm_context is an object of #{fields.keys.join(", ")} words")]
+        end
+
+        override = LLMContextOverride.update(nil, raw.to_h { |key, word| [fields.fetch(key), word] })
+        [override.empty? ? nil : override, nil]
+      rescue ArgumentError => e
+        [nil, error_response(400, "invalid_llm_context", e.message)]
+      end
+
       def handle_show(req, id)
         # The page's light re-reads: never the whole conversation.
         return handle_cards_read(id) if req.params["cards"] == "1"
@@ -1621,6 +1658,8 @@ module Samagotchi
       def messages_for_display(msgs, parts: false, cwd: nil)
         filtered = []
         list = Array(msgs)
+        # The outputs' ✂ marks (LLM context edits), by id, for the parts.
+        marks = parts ? MessageParts.edit_marks(list) : {}
         list.each_with_index do |m, index|
           role = (m[:role] || m["role"]).to_s
           content = (m[:content] || m["content"]).to_s
@@ -1652,7 +1691,7 @@ module Samagotchi
           next if role == "tool_response"
 
           stripped = Samagotchi::OutputFormatter.strip_markup(content)
-          did = parts && %w[model assistant].include?(role) ? message_parts(list, index, cwd) : nil
+          did = parts && %w[model assistant].include?(role) ? message_parts(list, index, cwd, marks) : nil
           next if stripped.empty? && did.nil?
 
           norm_role = role == "model" ? "assistant" : role
@@ -1720,10 +1759,11 @@ module Samagotchi
       end
 
       # The parts of the assistant message at +index+, with the tool_response
-      # messages right after it.
-      def message_parts(list, index, cwd = nil)
+      # messages right after it; +marks+: the session's ✂ marks
+      # (MessageParts.edit_marks).
+      def message_parts(list, index, cwd = nil, marks = {})
         responses = list.drop(index + 1).take_while { |r| (r[:role] || r["role"]).to_s == "tool_response" }
-        MessageParts.for_message(list[index], responses, cwd: cwd)
+        MessageParts.for_message(list[index], responses, cwd: cwd, marks: marks)
       end
 
       # The last message messages_for_display shows as an answer

data/lib/samagotchi/web/message_parts.rb

@@ -7,6 +7,8 @@ require_relative "../tool_view"
 require_relative "../llm/native_tool_normalizer"
 require_relative "../tools/builtins"
 require_relative "../image_store"
+require_relative "../llm_context_edit"
+require_relative "../token_usage"
 
 module Samagotchi
   module Web
@@ -28,6 +30,10 @@ module Samagotchi
     # by the saved image_counts (older sessions without them: only a lone
     # call gets them).
     #
+    # A call's chi-owned id (ToolIds, saved as tool_ids) is the part's
+    # tool_id:, and an LLM context edit saved on its output (LLMContextEdit,
+    # under edits) the part's edit: (.edit_marks), the row's ✂ mark.
+    #
     # A plugin tool's params are what its live row showed (its preview),
     # saved with the result as tool_params (native: one per call, chat: one
     # per result); its label ("chrome: screenshot") likewise as tool_labels,
@@ -59,15 +65,17 @@ module Samagotchi
       # @param registry [Tools::Registry] the session's tools
       # @param cwd [String, nil] the session's working directory (a file
       #   tool's title is relative to it)
+      # @param marks [Hash{String => Hash}] the session's edit marks by
+      #   output id (.edit_marks)
       # @return [Hash, nil] { thinking:, tools: [{ tool:, params:, title:,
-      #   output:, output_truncated:, images: }] } with only what it found; nil for nothing
-      def for_message(message, responses, registry: Tools::Builtins.default, cwd: nil)
+      #   output:, output_truncated:, images:, tool_id:, edit: }] } with only what it found; nil for nothing
+      def for_message(message, responses, registry: Tools::Builtins.default, cwd: nil, marks: {})
         content = field(message, :content).to_s
         calls = field(message, :tool_calls)
         tools = if calls.is_a?(Array) && !calls.empty?
-                  native_tools(calls, responses, registry, cwd)
+                  native_tools(calls, responses, registry, cwd, marks)
                 else
-                  markup_tools(content, responses, registry, cwd)
+                  markup_tools(content, responses, registry, cwd, marks)
                 end
         parts = {}
         thinking = [field(message, :thinking).to_s.strip, thinking_of(content)].reject(&:empty?).join("\n\n")
@@ -87,7 +95,7 @@ module Samagotchi
         blocks.map(&:strip).reject(&:empty?).join("\n\n")
       end
 
-      def markup_tools(content, responses, registry, cwd = nil)
+      def markup_tools(content, responses, registry, cwd = nil, marks = {})
         calls = []
         calls.concat(ToolCallParser::Qwen.new(ModelProfile.qwen36).parse(content)) if content.include?("<tool_call>")
         calls.concat(ToolCallParser::Gemma.new(ModelProfile.gemma4).parse(content)) if content.include?("<|tool_call>")
@@ -98,9 +106,11 @@ module Samagotchi
         shown = saved_list(responses, :tool_params, calls.length)
         labels = saved_list(responses, :tool_labels, calls.length)
         diffs = saved_list(responses, :tool_diffs, calls.length)
+        ids = saved_list(responses, :tool_ids, calls.length)
         images = split_images(responses, calls.length)
         calls.each_with_index.map do |call, i|
-          tool_part(call, outputs[i], registry, shown[i], images[i], label: labels[i], diff: diffs[i], cwd: cwd)
+          tool_part(call, outputs[i], registry, shown[i], images[i], label: labels[i], diff: diffs[i], cwd: cwd,
+                                                                     tool_id: ids[i], marks: marks)
         end
       end
 
@@ -122,16 +132,78 @@ module Samagotchi
         counts.map { |n| images.shift(n) }
       end
 
-      def native_tools(calls, responses, registry, cwd = nil)
-        by_id = responses.to_h { |r| [field(r, :tool_call_id), r] }
+      def native_tools(calls, responses, registry, cwd = nil, marks = {})
+        # By id only for an id that names one response: a server may omit
+        # it (nil), send "" or repeat it; those pair by position.
+        ids = responses.map { |r| field(r, :tool_call_id).to_s }
+        unique = ->(id) { !id.empty? && ids.count(id) == 1 }
+        by_id = responses.each_with_index.to_h { |r, i| [ids[i], r] }.select { |id, _| unique.call(id) }
         calls.each_with_index.map do |raw, i|
           ref = CallRef.new(field(raw, :name).to_s, field(raw, :arguments))
           call = LLM::NativeToolNormalizer.normalize(ref) || { name: ref.name }
-          response = by_id[field(raw, :id)] || (field(responses[i], :tool_call_id).nil? ? responses[i] : nil)
+          response = by_id[field(raw, :id).to_s] || (responses[i] && !unique.call(ids[i]) ? responses[i] : nil)
           tool_part(call, response && field(response, :content).to_s, registry, field(response, :tool_params),
                     response && field(response, :images), label: field(response, :tool_labels),
-                                                          diff: field(response, :tool_diffs), cwd: cwd)
+                                                          diff: field(response, :tool_diffs), cwd: cwd,
+                                                          tool_id: Array(field(response, :tool_ids)).first, marks: marks)
+        end
+      end
+
+      # The ✂ mark of each output an LLM context edit is saved on, by its
+      # id, from +messages+ (a session's, symbol or string keys): {kind:
+      # "stale" | "forget", staged: true while a forget waits for the
+      # turn's end, note: (a stale stub's reason, "superseded by a later
+      # read"; the first output of a forget_outputs call's, its note), with:
+      # (the others of that call's: the first one's id), kept: ("12-40, 50",
+      # a forget's kept lines)}. A forget call's outputs share the note,
+      # author and stamp (LLMContextView's key); the first in the session's
+      # order carries the note.
+      # @return [Hash{String => Hash}]
+      def edit_marks(messages)
+        first = {}
+        Array(messages).each_with_object({}) do |entry, marks|
+          next unless field(entry, :role).to_s == "tool_response"
+
+          saved = field(entry, :edits)
+          next unless saved.is_a?(Hash)
+
+          edits = saved.filter_map { |id, hash| LLMContextEdit.from_h(id, hash) }.to_h { |edit| [edit.id, edit] }
+          order = Array(field(entry, :tool_ids)).map(&:to_s)
+          edits.sort_by { |id, _| order.index(id) || order.size }.each do |id, edit|
+            marks[id] = edit_mark(edit, first)
+          end
+        end
+      rescue StandardError
+        {}
+      end
+
+      def edit_mark(edit, first)
+        mark = { kind: edit.kind.to_s }
+        mark[:staged] = true unless edit.applied?
+        if edit.kind == :stale
+          mark[:note] = edit.note[/superseded by .*\z/] || edit.note
+        else
+          key = [edit.note, edit.by, edit.staged_at]
+          if first.key?(key)
+            mark[:with] = first[key]
+          else
+            first[key] = edit.id
+            mark[:note] = edit.note
+          end
+          kept = edit.keep.map { |from, to| from == to ? from.to_s : "#{from}-#{to}" }
+          mark[:kept] = kept.join(", ") unless kept.empty?
         end
+        mark
+      end
+
+      # +output+'s ✂ mark (+marks+ by +id+); an applied stale stub says
+      # what it frees: its output, ~chars/4.
+      def mark_of(id, marks, output)
+        mark = marks[id]
+        return nil unless mark
+        return mark unless mark[:kind] == "stale" && !mark[:staged] && output
+
+        mark.merge(tokens: (output.length / TokenUsage::CHARS_PER_TOKEN).ceil)
       end
 
       # +count+ outputs from a joined tool_response: the "[tool]"-tagged
@@ -153,7 +225,9 @@ module Samagotchi
       # +shown+ is the saved params line, when it is a String.
       # +diff+ is what an edit/write changed (EditPreview.change), saved as
       # tool_diffs. +cwd+: the session's working directory, for the title.
-      def tool_part(call, output, registry, shown = nil, images = nil, label: nil, diff: nil, cwd: nil)
+      # +tool_id+: its output's ToolIds id, with its ✂ mark in +marks+.
+      def tool_part(call, output, registry, shown = nil, images = nil, label: nil, diff: nil, cwd: nil, tool_id: nil,
+                    marks: {})
         name = call[:name].to_s
         params = shown.is_a?(String) ? shown : ToolActivity.tool_activity_params(name, call, registry: registry)
         part = { tool: name, params: params.to_s }
@@ -171,6 +245,11 @@ module Samagotchi
         refs = Array(images).select { |ref| ref.is_a?(Hash) }
         part[:images] = refs.map { |ref| ImageStore.symbolize(ref).slice(:file, :name, :width, :height) } unless refs.empty?
         part[:diff] = diff if diff.is_a?(Hash)
+        if tool_id
+          part[:tool_id] = tool_id.to_s
+          mark = mark_of(tool_id.to_s, marks, output)
+          part[:edit] = mark if mark
+        end
         part
       end