samagotchi 0.58.0 → 0.60.0

data/lib/samagotchi/system_prompt.rb

@@ -11,12 +11,13 @@ require_relative "model_notes"
 require_relative "bundle_needs"
 require_relative "memory_bundle/index_size"
 require_relative "thinking"
+require_relative "prompt_files"
 
 module Samagotchi
   # The system prompt an Engine gives its model: the base prompt (tool
   # declarations and call syntax for the raw-prompt loop, none for the chat
   # loop, the shared guidance) and around it the thinking token, rg
-  # guidance, the identity memory, the model notes, the preloaded memories, AGENT.md, the
+  # guidance, the identity memory, the model notes, the preloaded memories, AGENTS.md, the
   # memory indexes and, last, the model, where the session runs and the
   # session (#system_prompt_with_index has the order and why).
   #
@@ -24,8 +25,6 @@ module Samagotchi
   # tools a plugin replaces, the attached session, the thinking level) is
   # read at build time through the lookups; the memory lists are fixed.
   class SystemPrompt
-    AGENT_DESCRIPTION_FILE = "AGENT.md"
-
     # The model a session runs on, as the prompt names it: the resolved
     # ref, its host ("name, host:port" or url), the memory overlay key, and
     # what a llama.cpp server says it serves when that differs (else nil).
@@ -51,8 +50,10 @@ module Samagotchi
     #   model's (none: the section is left out)
     # @param memories [Array<String>] the --memory list
     # @param muted_memory_names [Array<String>] normalized (MutedMemories)
+    # @param appended_files [Array<String>] chi --append-system-prompt's
+    #   files (absolute paths), after config.yml's append_system_prompt:
     def initialize(profile:, tools:, session:, thinking:, model: -> {}, model_notes: -> { [] }, memories: [],
-                   muted_memory_names: [])
+                   muted_memory_names: [], appended_files: [])
       @profile_lookup = profile
       @model_lookup = model
       @model_notes_lookup = model_notes
@@ -61,6 +62,14 @@ module Samagotchi
       @thinking_lookup = thinking
       @muted_memory_names = muted_memory_names
       @requested_memories = effective_preload_list(preload_memory_list(memories))
+      # Read once, as the memories: list is: a config edit is picked up by
+      # a new process. The files' text is read at each build.
+      @config_appended = begin
+        ConfigFile.appended_prompt_files
+      rescue StandardError
+        []
+      end
+      @cli_appended = Array(appended_files).map { |path| File.expand_path(path.to_s) }
     end
 
     # @return [Array<String>] the names the session preloads, known before
@@ -81,16 +90,20 @@ module Samagotchi
       @built ||= {}
       @index_sizes ||= {}
       @notes_loaded ||= {}
+      @files_loaded ||= {}
       unless @built.key?(key)
         @section_notes = nil
+        @section_files = []
         @built[key] = system_prompt_with_index(
           assist_system_prompt(chat: chat, thinking: thinking, layers: layers), chat: chat, thinking: thinking, layers: layers
         )
         @index_sizes[key] = @measured_index
         @notes_loaded[key] = @section_notes || []
+        @files_loaded[key] = @section_files.freeze
       end
       @memory_index = @index_sizes[key]
       @prompt_notes = @notes_loaded[key]
+      @prompt_files = @files_loaded[key]
       @built[key]
     end
 
@@ -108,6 +121,14 @@ module Samagotchi
     # @return [Array<ModelNotes::Note>, nil]
     attr_reader :prompt_notes
 
+    # The files whose text the prompt #build returned last holds, as
+    # absolute paths in prompt order: the AGENTS.md chain, then the
+    # appended files (append_system_prompt:, --append-system-prompt). [] before a
+    # build and after #reset!. Read when the prompt is built, as the
+    # sections are.
+    # @return [Array<String>]
+    def prompt_files = @prompt_files || []
+
     # Drops the built prompts: the next #build reads the profile, tools,
     # indexes and memories again (a model or profile switch, changed tools).
     def reset!
@@ -115,6 +136,8 @@ module Samagotchi
       @index_sizes = nil
       @notes_loaded = nil
       @prompt_notes = nil
+      @files_loaded = nil
+      @prompt_files = nil
       @stable_lengths = nil
     end
 
@@ -282,7 +305,7 @@ module Samagotchi
     # Ordered for the servers' prompt caches (they reuse only an exact token
     # prefix): what every session shares first, what changes least before
     # what changes more, and the per-session lines last. The global parts
-    # (identity, preloads) come before the project's AGENT.md, the memory
+    # (identity, preloads) come before the project's AGENTS.md, the memory
     # indexes (a memory write changes them) after both; the model, the
     # location and the session close the prompt (Gemma's tool declarations
     # still follow them).
@@ -295,7 +318,7 @@ module Samagotchi
         "System memories:\n#{indexes[:system]}"
       ].join("\n\n")
       stable = [thinking_token + base, rg_guidance, system_identity_section, model_notes_section, explicit_memory_section,
-                project_specific_description, memory_sections]
+                project_specific_description, appended_section, memory_sections]
       stable_text = stable.compact.join("\n")
       volatile = [current_model, project_location, current_session].compact
       return with_tail_declarations(stable_text, chat: chat, layers: layers) if volatile.empty?
@@ -464,26 +487,59 @@ module Samagotchi
 
     # ── Project / rg helpers ───────────────────────────────────────────────────
 
-    # AGENT.md in the cwd, else at the top of its git work tree.
+    # The AGENTS.md chain from the top of the git work tree down to the cwd
+    # (PromptFiles.agents_sections), one section per file with text.
     def project_specific_description
       return nil if skip_agent_description?
 
-      path = agent_description_path
-      return nil unless path
-
-      content = File.read(path, encoding: "UTF-8").strip
-      return nil if content.empty?
+      sections = PromptFiles.agents_sections(Dir.pwd)
+      return nil if sections.empty?
 
-      "Project specific description:\n#{content}"
+      @section_files&.concat(sections.map(&:path))
+      sections.map(&:text).join("\n\n")
     rescue StandardError
       nil
     end
 
-    def agent_description_path
+    # The appended files' text, right after AGENTS.md (the stable, cached
+    # part): config.yml's append_system_prompt: entries first (a relative
+    # one against the cwd, as AGENTS.md is found; a missing one is skipped),
+    # then --append-system-prompt's. A file the AGENTS.md chain holds, a
+    # repeat and an empty or vanished file are left out.
+    def appended_section
       cwd = Dir.pwd
-      [cwd, MemoryPaths.work_tree_root(cwd)].compact.uniq
-        .map { |dir| File.join(dir, AGENT_DESCRIPTION_FILE) }
-        .find { |path| File.file?(path) }
+      top = MemoryPaths.work_tree_root(cwd)
+      seen = Set.new((skip_agent_description? ? [] : PromptFiles.agents_paths(cwd)).map { |path| canonical_path(path) })
+      sections = []
+      appended_candidates(cwd).each do |path, source|
+        next unless seen.add?(canonical_path(path))
+
+        unless File.file?(path)
+          Log.debug(:config, "appended_prompt_file_missing", path: path, source: source)
+          next
+        end
+        text = PromptFiles.section(path, "Appended from #{PromptFiles.display_path(path, top: top)}:")
+        next unless text
+
+        @section_files&.push(path)
+        sections << text
+      end
+      sections.empty? ? nil : sections.join("\n\n")
+    rescue StandardError
+      nil
+    end
+
+    # [absolute path, "config" | "cli"], in prompt order.
+    def appended_candidates(cwd)
+      @config_appended.map { |entry| [File.expand_path(entry, cwd), "config"] } +
+        @cli_appended.map { |path| [path, "cli"] }
+    end
+
+    # The same file however it's spelled (/tmp vs /private/tmp on macOS).
+    def canonical_path(path)
+      File.realpath(path)
+    rescue SystemCallError
+      File.expand_path(path)
     end
 
     # Where the session runs and which project memory folder it uses. Only
@@ -566,7 +622,7 @@ module Samagotchi
     end
 
     def skip_agent_description?
-      Config.get("skip_agent_md") == true
+      Config.get("skip_agents_md") == true
     end
 
     def rg_available?

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -37,6 +37,8 @@ module Samagotchi
       # @param memories [Array<String>] --memory: a new session's worker
       #   preloads them (an existing session keeps its own list)
       # @param muted_memories [Array<String>] --mute: hidden from a new session
+      # @param appended_prompt_files [Array<String>] --append-system-prompt's
+      #   files (absolute): a new session's setup carries them
       # @param llm_context [Hash{Symbol => String}] --llm-context* as typed
       #   (LLMContextOverride.update): a new session starts with them; a
       #   resumed or attached one's worker gets a /llm-context, after the
@@ -48,9 +50,10 @@ module Samagotchi
       #   :failed when the --model switch didn't go through, or (input from a
       #   pipe) :turn_failed / :empty_answer / :unanswered (AttachedLoop#run)
       def run(attach: nil, shared: false, resume: nil, prompt: nil, model: nil, no_interrupt: false, default_input: true,
-              memories: [], muted_memories: [], llm_context: {}, thinking: nil)
+              memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [])
         client = connect(attach: attach, shared: shared, resume: resume, model: model,
-                         memories: memories, muted_memories: muted_memories, llm_context: llm_context, thinking: thinking)
+                         memories: memories, muted_memories: muted_memories, llm_context: llm_context, thinking: thinking,
+                         appended_prompt_files: appended_prompt_files)
         commands = []
         commands << "/model #{model}" if model && (attach || resume)
         commands << LLMContextOverride.command_line(llm_context) if (attach || resume) && !llm_context.empty?
@@ -117,9 +120,11 @@ module Samagotchi
       # @return [BridgeClient] a client for the live Bridge of the session
       # @raise [Error]
       def connect(attach: nil, shared: false, resume: nil, model: nil, state_dir: nil, wait: BRIDGE_WAIT,
-                  memories: [], muted_memories: [], llm_context: {}, thinking: nil, err: $stderr)
+                  memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], err: $stderr)
         sd = state_dir || Session.default_state_dir
-        warn_memory_flags_ignored(attach || resume, memories, muted_memories, err) if attach || resume
+        if attach || resume
+          warn_memory_flags_ignored(attach || resume, memories, muted_memories, err, appended_prompt_files: appended_prompt_files)
+        end
         if attach
           live = connect_existing(attach, sd)
           return live if live
@@ -134,7 +139,8 @@ module Samagotchi
                     SessionManager.spawn_session(prompt: nil, model_name: model && model_ref(model), state_dir: sd,
                                                  memories: memories, muted_memories: muted_memories,
                                                  setup: SessionSetup.new(llm_context: llm_context.empty? ? nil : LLMContextOverride.update(nil, llm_context),
-                                                                         thinking: Thinking.session_level(thinking)))
+                                                                         thinking: Thinking.session_level(thinking),
+                                                                         appended_prompt_files: appended_prompt_files))
                   end
         client = BridgeClient.wait_for(session.id, session_dir: Session.session_dir(session.id, state_dir: sd), timeout: wait)
         client || raise(Error, "the worker for session #{session.id} did not start its Bridge in time")
@@ -150,16 +156,19 @@ module Samagotchi
       end
 
       # An existing session's prompt is built from its own session fields:
-      # --memory/--mute given with --attach or --resume are ignored, with a
-      # line saying so (printed before the live region opens).
-      def warn_memory_flags_ignored(session_id, memories, muted_memories, err)
+      # --memory/--mute/--append-system-prompt given with --attach or
+      # --resume are ignored, with a line saying so (printed before the live
+      # region opens).
+      def warn_memory_flags_ignored(session_id, memories, muted_memories, err, appended_prompt_files: [])
         flags = []
         flags << "--memory" unless Array(memories).empty?
         flags << "--mute" unless Array(muted_memories).empty?
+        flags << "--append-system-prompt" unless Array(appended_prompt_files).empty?
         return if flags.empty?
 
         verb = flags.size == 1 ? "applies" : "apply"
-        err.puts "(#{flags.join(" and ")} #{verb} to a new session; #{session_id}'s prompt is already built)"
+        names = flags.size > 2 ? "#{flags[0..-2].join(", ")} and #{flags.last}" : flags.join(" and ")
+        err.puts "(#{names} #{verb} to a new session; #{session_id}'s prompt is already built)"
       end
 
       # @return [BridgeClient, nil] the running worker's, or nil when none runs

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -712,7 +712,7 @@ module Samagotchi
 
         return NEXT_STEP_NOTE unless delivery == Delivery::CUT
 
-        steer_cut_note(ack["cut"].to_s.to_sym)
+        steer_cut_note(ack["cut"].to_s.to_sym, ack["cut_after"])
       end
 
       def send_prompt(text, delivery: nil)

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -8,6 +8,7 @@ require_relative "../steer"
 require_relative "../steer_cut"
 require_relative "../memory_bundle/index_size"
 require_relative "../prompt_note"
+require_relative "../prompt_files"
 
 module Samagotchi
   class TerminalUI
@@ -99,8 +100,9 @@ module Samagotchi
       # 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 and chi send --cut print the same words
+      # thinking passes the model's cut wait (the run's cut_after; the global
+      # steer.cut_after when the worker didn't say), and /queue's waiting for
+      # the end. Both TUIs and chi send --cut 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)"
@@ -116,17 +118,20 @@ module Samagotchi
       STEER_CHOICE = /\A(#{CUT_COMMAND}|#{QUEUE_COMMAND})(?:\s+(.*))?\z/m
 
       # @param outcome [Symbol] SteerCut#cut_for_steer's answer: :now, :waits or :off
+      # @param after [Integer, nil] the run's cut wait (the model's own
+      #   SteerCutAfter): the seconds a :waits waits for; the global
+      #   steer.cut_after when not given.
       # @return [String] the dim line to show for a /cut
-      def self.steer_cut_note(outcome)
+      def self.steer_cut_note(outcome, after = nil)
         case outcome
         when :now then CUT_NOW_NOTE
-        when :waits then format(CUT_WAITS_NOTE, SteerCut.cut_after)
+        when :waits then format(CUT_WAITS_NOTE, after || SteerCut.cut_after)
         else CUT_OFF_NOTE
         end
       end
 
       # The same words, for a UI that includes the module.
-      def steer_cut_note(outcome) = Formatting.steer_cut_note(outcome)
+      def steer_cut_note(outcome, after = nil) = Formatting.steer_cut_note(outcome, after)
 
       # The choice a mid-turn line carries, as [:cut, "TEXT"] or
       # [:queue, "TEXT"]; nil for any other line. The text is "" when the
@@ -400,6 +405,16 @@ module Samagotchi
         "#{"~" if source.to_s == "estimate"}#{number} tok/s"
       end
 
+      # The prompt files (absolute paths) named as the prompt names them:
+      # relative to this checkout's top, else with ~; nil with none.
+      def prompt_files_text(paths)
+        list = Array(paths).map(&:to_s).reject(&:empty?)
+        return nil if list.empty?
+
+        top = MemoryPaths.work_tree_root(Dir.pwd)
+        list.map { |path| PromptFiles.display_path(path, top: top) }.join(", ")
+      end
+
       # "~3.4k tokens in this session's prompt (system 2.0k, project 1.4k)":
       # the memory indexes the session's prompt holds (the snapshot's
       # memory_index, symbol or string keys); "" without one. As ctx.js
@@ -596,6 +611,9 @@ module Samagotchi
         # The model notes the session's prompt carried (Engine#prompt_notes).
         notes = PromptNote.text(snapshot[:prompt_notes])
         lines << "model notes:      #{notes}" unless notes.empty?
+        # The files whose text is in the prompt (SystemPrompt#prompt_files).
+        files = prompt_files_text(snapshot[:prompt_files])
+        lines << "prompt files:     #{files}" if files
         llm_context = llm_context_stats_text(snapshot[:llm_context])
         lines << "llm context:      #{llm_context}" if llm_context
         thinking = setting_stats_text(snapshot[:thinking])

data/lib/samagotchi/terminal_ui.rb

@@ -92,8 +92,12 @@ module Samagotchi
     #   (LLMContextOverride.update): set on the new or resumed session
     # @param thinking [String, nil] --thinking as typed: the new or resumed
     #   session's own level (default unsets it)
+    # @param appended_prompt_files [Array<String>] --append-system-prompt's
+    #   files (absolute): a new session saves them; a resumed one's own come
+    #   first, and the merge goes only to the Engine (as --memory's does)
     def initialize(prompt: nil, client: nil, host_registry: nil, profile: nil, session_id: nil, no_interrupt: false, no_default_input: false, model_name: nil, memories: [], muted_memories: [], non_interactive: false, surface: nil,
-                   spinner_tick_interval: AttachedView::TICK_INTERVAL, spinner_clock: nil, scratch: false, llm_context: {}, thinking: nil)
+                   spinner_tick_interval: AttachedView::TICK_INTERVAL, spinner_clock: nil, scratch: false, llm_context: {}, thinking: nil,
+                   appended_prompt_files: [])
       @scratch        = scratch
       @thinking_word  = thinking
       @prompt         = prompt
@@ -142,9 +146,11 @@ module Samagotchi
       # session started attached with mutes keeps them here.
       @requested_memories = Array(memories)
       @muted_memory_names = Array(muted_memories)
+      @appended_prompt_files = Array(appended_prompt_files)
       if @resume_session
         @requested_memories = (@resume_session.preloaded_memory_names + @requested_memories).uniq
         @muted_memory_names = (@resume_session.muted_memory_names + @muted_memory_names).uniq
+        @appended_prompt_files = (@resume_session.appended_prompt_files + @appended_prompt_files).uniq
       end
       # Every terminal write goes through the surface. The REPL swaps in a
       # live region when the terminal can show one (#assist_loop), unless it
@@ -178,6 +184,7 @@ module Samagotchi
         model_typed: no_default ? @resumed_model_typed : nil,
         memories: @requested_memories,
         muted_memories: @muted_memory_names,
+        appended_prompt_files: @appended_prompt_files,
         recap: scratch ? nil : recap_config,
         scratch: scratch,
         reminders: {
@@ -258,7 +265,8 @@ module Samagotchi
         working_directory: Dir.pwd,
         preloaded_memory_names: @requested_memories,
         muted_memory_names: @muted_memory_names,
-        scratch: @scratch
+        scratch: @scratch,
+        setup: SessionSetup.new(appended_prompt_files: @appended_prompt_files)
       ))
       # --llm-context*: the session's own values, over a resumed one's.
       # Saved at once on a resumed one: leaving before a turn keeps them.
@@ -628,7 +636,7 @@ module Samagotchi
     # Run one REPL turn (a prompt, or a continue/reminder turn with nil) through
     # Engine#run_turn, rendering via @renderer.
     # @param images [Array<Hash>] the prompt's `@path` images ({path:})
-    def run_engine_turn(session, prompt, continue: false, max_iterations: IterationLimit.for, images: [])
+    def run_engine_turn(session, prompt, continue: false, max_iterations: IterationLimit.for, images: [], resumed: false, resume_from: nil)
       cancellation_controller = CancellationController.new
       @active_cancel_controller = cancellation_controller
       @renderer.begin_turn
@@ -646,7 +654,9 @@ module Samagotchi
           cancel_controller: cancellation_controller,
           pending_input: method(:drain_steering),
           continue: continue,
-          images: images
+          images: images,
+          resumed: resumed,
+          resume_from: resume_from
         )
       end
     rescue Interrupt
@@ -774,9 +784,11 @@ module Samagotchi
       end
       return show_command_result(answer) unless answer.resume
 
+      # The run the offer's turn started: the Continue keeps its reasoning.
+      resume_from = @turn_flow.resume_from
       @turn_flow.before_continue_turn
       begin
-        result = run_engine_turn(session, nil, continue: true)
+        result = run_engine_turn(session, nil, continue: true, resumed: true, resume_from: resume_from)
       rescue LLM::ProviderError
         # The renderer showed the failure (:turn_failed).
         @surface.commit(turn_end_hint("continue prompt preserved"))
@@ -1199,7 +1211,7 @@ module Samagotchi
       @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)))
+      @surface.commit(steer_cut_note(@engine.cut_for_steer(nil, epoch: epoch), @engine.steer_cut_after))
       true
     end
 

data/lib/samagotchi/tool_activity.rb

@@ -46,7 +46,11 @@ module Samagotchi
         status: tool_activity_status(result, tool_name, command: call.is_a?(Hash) ? call[:content] : nil)
       }
       # A grep that found nothing: ok, and the web row says "no match".
-      event[:no_match] = true if event[:status] == "ok" && tool_name == Tools::Execute::NAME && execute_failed?(result.to_s)
+      # Not a hand-over: an "exit: 1" in its output tail is the command's.
+      if event[:status] == "ok" && tool_name == Tools::Execute::NAME && !handed_over?(tool_name, result) &&
+         execute_failed?(result.to_s)
+        event[:no_match] = true
+      end
       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"
@@ -214,6 +218,8 @@ module Samagotchi
       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:")
+      # Still running, as a task: its output tail may hold any "exit: N".
+      return "ok" if handed_over?(tool_name, text)
       if tool_name == Tools::Execute::NAME && execute_failed?(text)
         return no_match?(text, command) ? "ok" : "error"
       end
@@ -222,6 +228,17 @@ module Samagotchi
       "ok"
     end
 
+    # An execute still running at its limit, handed over as a task
+    # (Tools::Execute::HANDED_OVER).
+    def handed_over?(tool_name, text)
+      return false unless tool_name == Tools::Execute::NAME && text.to_s.start_with?(Tools::Execute::HANDED_OVER)
+
+      # The first line only, scrubbed: a regexp raises on bytes that aren't UTF-8.
+      text.to_s.each_line.first.to_s.scrub.match?(HANDED_OVER_START)
+    end
+
+    HANDED_OVER_START = /\A#{Regexp.escape(Tools::Execute::HANDED_OVER)} \d+s limit:/
+
     def execute_failed?(text)
       code = execute_exit_code(text)
       !code.nil? && code != "0"

data/lib/samagotchi/tool_declarations.rb

@@ -20,7 +20,7 @@ module Samagotchi
     TOOL_SCHEMAS = [
       {
         name: "execute",
-        description: "Run any shell command in a working directory (defaults to the project root) and see stdout, stderr, and exit code. Large output may be truncated to a head+tail preview with metadata. Don't background with &; use task_create.",
+        description: "Run any shell command in a working directory (defaults to the project root) and see stdout, stderr, and exit code. Large output may be truncated to a head+tail preview with metadata. A command still running at the time limit keeps running as a background task (by default): the result gives its task_id, and task_wait waits for it. Don't background with &; use task_create.",
         parameters: {
           type: "object",
           properties: {