samagotchi 0.53.0 → 0.55.0

data/lib/samagotchi/engine.rb

@@ -21,6 +21,7 @@ require_relative "tools/builtins"
 require_relative "tools/task_runtime"
 require_relative "session_commands"
 require_relative "plugin/loader"
+require_relative "extension_load"
 require_relative "log"
 require_relative "log_subscriber"
 require_relative "thinking_tails"
@@ -89,6 +90,9 @@ module Samagotchi
       new(profile: profile, plugins: false).assist_system_prompt
     end
 
+    # What memory_write answers in a scratch session.
+    SCRATCH_MEMORY_WRITE = "Error: scratch session: nothing is saved"
+
     # @param client             [Client, nil] defaults to Client.new
     # @param profile            [ModelProfile, Symbol, String, nil]
     # @param session_id         [String, nil] resume an existing session
@@ -100,8 +104,6 @@ module Samagotchi
     # @param memories           [Array<String>] explicit --memory preload list (merged with the config.yml `memories:` baseline)
     # @param muted_memories     [Array<String>] --mute list: memories hidden from this session (not in the
     #   prompt's index, dropped from the preloads, refused by memory_read); a mute wins over a preload
-    # What memory_write answers in a scratch session.
-    SCRATCH_MEMORY_WRITE = "Error: scratch session: nothing is saved"
     # @param plugins            [Boolean] false: load no bundle plugins (a throwaway Engine for a prompt)
     # @param scratch            [Boolean] a `chi scratch` session: memory writes are refused, and there is no
     #   delegate (a child would outlive it) nor plugin fork
@@ -144,17 +146,7 @@ module Samagotchi
       # Load hooks from config (plugins) and create the registry; what fails
       # to load is announced, and a required guardrail's failure denies
       # every tool call. Rules load now too, so their errors are announced.
-      @guardrail_wiring = GuardrailWiring.new(
-        scratch: @scratch,
-        hooks: -> { @hooks },
-        tools: -> { @tools },
-        session: -> { @session },
-        model_key: -> { @model_key },
-        model_name: -> { guardrail_model_name },
-        cancelled: -> { !!active_cancel_controller&.cancelled? },
-        ask: ->(fields) { open_question(fields) },
-        notify: ->(message) { guardrail_notify(message) }
-      )
+      @guardrail_wiring = build_guardrail_wiring
       @guardrail_failures = @guardrail_wiring.failures
       # Plugins that failed to load: announced apart, as plugins (not
       # guardrails: no tool call is denied for them).
@@ -163,30 +155,17 @@ module Samagotchi
       # approvals). Built before the hooks and plugins load: a plugin can ask
       # during its load (answered nil then: the interface is still
       # :non_interactive).
-      @question_desk = QuestionDesk.new(
-        session: -> { @session },
-        state_dir: -> { session_state_dir },
-        emit: ->(event) { emit_event(nil, event) },
-        cancel_controller: -> { active_cancel_controller },
-        interface: -> { interface },
-        user_input: ->(sid) { ArchiveStore.user_input(sid, state_dir: session_state_dir) }
-      )
+      @question_desk = build_question_desk
       # Built here, not on first use: the turn thread and the Bridge's read it.
       @relay_desk = RelayDesk.new
-      @hooks = load_hooks_from_config
-      load_hooks_from_bundles
+      @extension_load = ExtensionLoad.new(hook_failures: @guardrail_failures)
+      @hooks = @extension_load.hooks
       # The tools this session offers (the prompts' declarations and the
       # kernel's dispatch): the built-ins, per Engine. execute.description
       # off: execute offers no description parameter.
       @tools = Tools::Builtins.registry(command_description: Config.get("execute.description") != false,
                                         policy: Config.get(LLMContextStrategy::POLICY_SETTING))
-      if @scratch
-        # A scratch session's children would outlive it, and so would a
-        # note it left in a peer; its memories would too (write and edit
-        # into the memories: ScratchWrites).
-        [Tools::Delegate::NAME, Tools::DelegateResult::NAME, Tools::SendNote::NAME].each { |name| @tools.unregister(name) }
-        @tools[Tools::MemoryWrite::NAME].handler = ->(_call, _kctx) { SCRATCH_MEMORY_WRITE }
-      end
+      restrict_scratch_tools! if @scratch
       # Likewise the slash commands its SessionCommands run.
       @command_registry = SessionCommands.register_builtins(Commands::Registry.new)
       # Installed bundles' plugins add commands, tools and hooks to these
@@ -199,16 +178,7 @@ module Samagotchi
       # chi.init tasks (#add_init_task), started by #start_init_tasks!, and
       # plugins' tool sets from chi.replace_tools until the turn thread
       # applies them (#apply_staged_tools!). Built before the plugins load.
-      @plugin_tasks = PluginTasks.new(
-        clock: -> { monotonic_now },
-        synchronize_events: ->(&block) { synchronize_events(&block) },
-        announce: ->(event) { announce(event) },
-        emit: ->(sink, event) { emit_event(sink, event) },
-        show_card: ->(**card) { show_card(**card) },
-        tools: -> { @tools },
-        notify: ->(text, level, source, fallback_for: nil) { hook_notify(text, level, source, fallback_for: fallback_for) },
-        tools_changed: -> { tools_changed! }
-      )
+      @plugin_tasks = build_plugin_tasks
       @lifecycle_mutex = Mutex.new
       @shut_down = false
       load_plugins if plugins
@@ -225,36 +195,9 @@ module Samagotchi
       @reminders = build_reminders(auto_turn_callback: callback)
       # Track whether this is the first turn in the session (for session_start event)
       @first_turn = true
-      # A given kernel (specs) gets the Engine's store, hooks and tools, as
-      # the one built here does.
-      @kernel = kernel || KernelLoop.new(client: @client, profile: @given_profile, hooks: @hooks, reminder_store: @reminder_store,
-                                         tools: @tools)
-      @kernel.reminder_store = @reminder_store
-      @kernel.hooks = @hooks
-      @kernel.tools = @tools
-      sync_kernel_client!
-      sync_model_key!
-      # The mutes never change during a session, so no re-sync: the kernel's
-      # memory_read guard reads the same list for every turn.
-      @muted_memory_names = MutedMemories.normalize_list(muted_memories)
-      @kernel.muted_memory_names = @muted_memory_names
-      # ask_user_question blocks on the Engine's question flow (TUI/Web answer it).
-      @kernel.question_handler = proc { |payload| request_question(payload) }
-      # Every tool call asks this gate first. The kernel is never rebuilt, so
-      # it holds across model switches.
-      self.guardrail_state_dir = Session.default_state_dir
-      # list_sessions and send_note speak for whichever session runs now.
-      @kernel.peers = PeerView.new(self)
-      @kernel.guardrail_gate = @guardrail_wiring.gate
-      # The turn-end warm-up; the kernel asks it for a slot pin per request.
-      @prompt_warmup = PromptWarmup.new
-      @kernel.warmup = @prompt_warmup
-      # What a hook can do beyond reading its event (event[:notify],
-      # event[:ask_user], event[:stop_turn]): the Engine's routes to the UIs.
-      @hooks.runtime = hook_runtime
-      # The loop follows the effective model's host (its api:): the raw-prompt
-      # NativeBackend, or the chat backend for openai hosts.
-      @native_backend = LLM::NativeBackend.new(kernel: @kernel)
+      # The kernel (built here, or a spec's) and what it reads of the Engine;
+      # then the native backend over it.
+      wire_kernel(kernel, muted_memories)
       Log.debug(:model, "backend", provider: backend.provider) if Log.level?(:debug)
       @resume_session = session_id ? Session.load(session_id) : nil
       @prompt_builder = SystemPrompt.new(profile: -> { self.profile }, tools: -> { @tools }, session: -> { @session },
@@ -286,6 +229,23 @@ module Samagotchi
         engine: self,
         jobs: [@reminders, @recap].compact
       )
+      subscribe_session_observers
+    end
+
+    # ── initialize's collaborators ──────────────────────────────────────────
+
+    # The tools a scratch session doesn't offer, and its memory_write.
+    def restrict_scratch_tools!
+      # A scratch session's children would outlive it, and so would a
+      # note it left in a peer; its memories would too (write and edit
+      # into the memories: ScratchWrites).
+      [Tools::Delegate::NAME, Tools::DelegateResult::NAME, Tools::SendNote::NAME].each { |name| @tools.unregister(name) }
+      @tools[Tools::MemoryWrite::NAME].handler = ->(_call, _kctx) { SCRATCH_MEMORY_WRITE }
+    end
+    private :restrict_scratch_tools!
+
+    # The persistent observers of every turn's events.
+    def subscribe_session_observers
       # The metrics collector is a persistent observer so every run_turn event
       # (the REPL, -p/--non-interactive/--resume and SessionManager workers)
       # feeds it automatically.
@@ -297,6 +257,88 @@ module Samagotchi
         @session&.id && Session.session_dir(@session.id, state_dir: session_state_dir)
       }))
     end
+    private :subscribe_session_observers
+
+    # The kernel and what it holds of the Engine (stores, hooks, tools, the
+    # mutes, the question flow, the gate, peers, warm-up, the hook runtime),
+    # and the native backend over it. After the plugins load.
+    def wire_kernel(kernel, muted_memories)
+      # A given kernel (specs) gets the Engine's store, hooks and tools, as
+      # the one built here does.
+      @kernel = kernel || KernelLoop.new(client: @client, profile: @given_profile, hooks: @hooks, reminder_store: @reminder_store,
+                                         tools: @tools)
+      @kernel.reminder_store = @reminder_store
+      @kernel.hooks = @hooks
+      @kernel.tools = @tools
+      sync_kernel_client!
+      sync_model_key!
+      # The mutes never change during a session, so no re-sync: the kernel's
+      # memory_read guard reads the same list for every turn.
+      @muted_memory_names = MutedMemories.normalize_list(muted_memories)
+      @kernel.muted_memory_names = @muted_memory_names
+      # ask_user_question blocks on the Engine's question flow (TUI/Web answer it).
+      @kernel.question_handler = proc { |payload| request_question(payload) }
+      # Every tool call asks this gate first. The kernel is never rebuilt, so
+      # it holds across model switches.
+      self.guardrail_state_dir = Session.default_state_dir
+      # list_sessions and send_note speak for whichever session runs now.
+      @kernel.peers = PeerView.new(self)
+      @kernel.guardrail_gate = @guardrail_wiring.gate
+      # The turn-end warm-up; the kernel asks it for a slot pin per request.
+      @prompt_warmup = PromptWarmup.new
+      @kernel.warmup = @prompt_warmup
+      # What a hook can do beyond reading its event (event[:notify],
+      # event[:ask_user], event[:stop_turn]): the Engine's routes to the UIs.
+      @hooks.runtime = hook_runtime
+      # The loop follows the effective model's host (its api:): the raw-prompt
+      # NativeBackend, or the chat backend for openai hosts.
+      @native_backend = LLM::NativeBackend.new(kernel: @kernel)
+    end
+    private :wire_kernel
+
+    # The tool guardrails (see #initialize for when).
+    def build_guardrail_wiring
+      GuardrailWiring.new(
+        scratch: @scratch,
+        hooks: -> { @hooks },
+        tools: -> { @tools },
+        session: -> { @session },
+        model_key: -> { @model_key },
+        model_name: -> { guardrail_model_name },
+        cancelled: -> { !!active_cancel_controller&.cancelled? },
+        ask: ->(fields) { open_question(fields) },
+        notify: ->(message) { guardrail_notify(message) }
+      )
+    end
+    private :build_guardrail_wiring
+
+    # The question flow (see #initialize for when).
+    def build_question_desk
+      QuestionDesk.new(
+        session: -> { @session },
+        state_dir: -> { session_state_dir },
+        emit: ->(event) { emit_event(nil, event) },
+        cancel_controller: -> { active_cancel_controller },
+        interface: -> { interface },
+        user_input: ->(sid) { ArchiveStore.user_input(sid, state_dir: session_state_dir) }
+      )
+    end
+    private :build_question_desk
+
+    # The plugins' init tasks and staged tool sets (see #initialize for when).
+    def build_plugin_tasks
+      PluginTasks.new(
+        clock: -> { monotonic_now },
+        synchronize_events: ->(&block) { synchronize_events(&block) },
+        announce: ->(event) { announce(event) },
+        emit: ->(sink, event) { emit_event(sink, event) },
+        show_card: ->(**card) { show_card(**card) },
+        tools: -> { @tools },
+        notify: ->(text, level, source, fallback_for: nil) { hook_notify(text, level, source, fallback_for: fallback_for) },
+        tools_changed: -> { tools_changed! }
+      )
+    end
+    private :build_plugin_tasks
 
     # A monotonically-increasing clock (wall clock can jump backwards; the idle
     # detector must never treat a jump as "activity"). Injectable for specs.
@@ -680,7 +722,7 @@ module Samagotchi
     # @raise [ArgumentError] a card without a title, or a bad action
     def show_card(source:, title:, body: "", actions: [], level: :info, id: nil)
       card = build_card(source: source, title: title, body: body, actions: actions, level: level, id: id)
-      return hold_load_event(card.merge(in_turn: true))[:id] if @loading_plugins
+      return @extension_load.hold(card.merge(in_turn: true))[:id] if @extension_load.loading?
       return announce_anytime(card.merge(in_turn: false))[:id] if anytime_thread?
       # A plugin's init task (chi.init): never a running turn's event.
       return announce(card.merge(in_turn: false)) && card[:id] if current_init_task
@@ -781,7 +823,7 @@ module Samagotchi
         announce({ type: :guardrail_warning, message: message }) if message
         plugins = @plugin_failures.message
         announce({ type: :guardrail_warning, message: plugins, label: "plugins" }) if plugins
-        Array(@plugin_load_events).each do |event|
+        @extension_load.held_events.each do |event|
           announce(event[:type] == :card ? event.merge(in_turn: false) : event.merge(between_turns: true))
         end
       end
@@ -1242,7 +1284,7 @@ module Samagotchi
       emit_event(on_event, { type: :guardrail_warning, message: message }) if message
       plugins = @plugin_failures.message
       emit_event(on_event, { type: :guardrail_warning, message: plugins, label: "plugins" }) if plugins
-      Array(@plugin_load_events).each { |event| emit_event(on_event, event) }
+      @extension_load.held_events.each { |event| emit_event(on_event, event) }
     end
     private :announce_guardrail_failures
 
@@ -1402,7 +1444,7 @@ module Samagotchi
       level = :info unless %i[info warn].include?(level)
       notice = { type: :hook_notice, hook: hook.to_s, text: text.to_s, level: level,
                  fallback_for: notice_fallback(fallback_for, hook) }.compact
-      return hold_load_event(notice) && nil if @loading_plugins
+      return @extension_load.hold(notice) && nil if @extension_load.loading?
 
       in_turn, sink = @turn_state.in_turn_sink
       if anytime_thread?
@@ -2394,48 +2436,6 @@ module Samagotchi
       end
     end
 
-    # Load hooks from the global config file using the Hooks::Loader.
-    # Returns a Registry with all plugins registered (or an empty Registry if
-    # no hooks config is present).
-    def load_hooks_from_config
-      config_path = Samagotchi::ConfigFile.global_path
-      data = Samagotchi::ConfigFile.read_yaml(path: config_path)
-      return Hooks::Loader.load(data, failures: @guardrail_failures) if data.is_a?(Hash)
-
-      Hooks::Registry.new
-    end
-
-    def load_hooks_from_bundles
-      require_relative "memory_bundle/provenance"
-      settings = bundle_settings
-      MemoryBundle::Provenance.each_installed(holding: :hooks) do |bundle_name, data|
-        if data[:error]
-          Log.warn(:hooks, "bundle_manifest_invalid", echo: "[samagotchi:hooks] bundle '#{bundle_name}': #{data[:error]}; its hooks are not loaded",
-                                                      bundle: bundle_name)
-          @guardrail_failures.add("hooks (bundle #{bundle_name})", data[:error], required: false)
-          next
-        end
-        bundle_dir = File.join(MemoryBundle::Provenance.bundles_dir, bundle_name)
-        hooks_dir = File.join(bundle_dir, "hooks")
-        if (data[:trust_level] || "experimental").to_s == "experimental"
-          Log.info(:hooks, "experimental_bundle", echo: "[hooks] Bundle '#{bundle_name}' is experimental — its hooks may change or misbehave.", bundle: bundle_name)
-        end
-        begin
-          Hooks::BundleLoader.load(bundle_name: bundle_name, hooks_dir: hooks_dir, metadata: data[:hooks], registry: @hooks,
-                                   failures: @guardrail_failures, settings: settings[bundle_name.to_s] || {},
-                                   requires_chi: data[:requires_chi])
-        rescue Exception => e # rubocop:disable Lint/RescueException -- a hook's SyntaxError or exit must not stop chi
-          raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
-
-          Log.error(:hooks, "bundle_load_failed", echo: "[samagotchi:hooks] bundle '#{bundle_name}' failed to load hooks: #{e.class}: #{e.message}", bundle: bundle_name, error: e.class.name)
-        end
-      end
-    rescue Exception => e # rubocop:disable Lint/RescueException -- a hook's SyntaxError or exit must not stop chi
-      raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
-
-      Log.error(:hooks, "bundles_load_failed", echo: "[samagotchi:hooks] failed to load bundle hooks: #{e.class}: #{e.message}", error: e.class.name)
-    end
-
     def load_plugins
       host = plugin_host
       registries = Plugin::Registries.new(
@@ -2454,17 +2454,7 @@ module Samagotchi
       # What plugins show while they load (an MCP server that didn't
       # start) waits for the first turn, beside the load warnings: no UI
       # is there yet, and the Engine isn't built.
-      @plugin_load_events = []
-      @loading_plugins = true
-      Plugin::Loader.load_installed(registries, failures: @plugin_failures, settings: bundle_settings)
-    ensure
-      @loading_plugins = false
-    end
-
-    # Keep a notice or card a plugin showed while loading (#load_plugins).
-    def hold_load_event(event)
-      @plugin_load_events << event
-      event
+      @extension_load.load_plugins(registries, failures: @plugin_failures)
     end
 
     # Keep a plugin's new tool set (chi.replace_tools, from any thread)
@@ -2550,13 +2540,6 @@ module Samagotchi
     end
     private :ask_side_model
 
-    # config.yml `bundles:` (ConfigFile.bundle_settings), read once: the
-    # bundle hooks and the plugins both want it.
-    def bundle_settings
-      @bundle_settings ||= Samagotchi::ConfigFile.bundle_settings
-    end
-    private :bundle_settings
-
     # The session's current model as a recap target: its host's OpenAI API
     # (native llama.cpp hosts serve /v1/chat/completions too), key variable
     # and bare model name, as a turn resolves them.

data/lib/samagotchi/extension_load.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "log"
+require_relative "hooks"
+require_relative "plugin/loader"
+
+module Samagotchi
+  # What an Engine loads from outside chi as it starts: config.yml's hooks,
+  # installed bundles' hooks and plugins, and config.yml `bundles:` (their
+  # settings). It holds what plugins showed while they loaded (notices,
+  # cards): no UI is there yet, so the Engine announces them on the first
+  # turn (Engine#announce_load_events!).
+  class ExtensionLoad
+    # @param hook_failures [Guardrails::LoadFailures] where hooks that fail to load go
+    def initialize(hook_failures:)
+      @hook_failures = hook_failures
+      @loading = false
+      @held_events = []
+    end
+
+    # @return [Array<Hash>] the notices and cards plugins showed while loading
+    attr_reader :held_events
+
+    # Whether the plugins are loading now (#load_plugins): what they show
+    # then is held (#hold), not shown.
+    def loading? = @loading
+
+    # Keep a notice or card a plugin showed while loading.
+    # @return [Hash] the event
+    def hold(event)
+      @held_events << event
+      event
+    end
+
+    # The hooks: config.yml's (Hooks::Loader; an empty Registry without a
+    # hooks config), then the installed bundles' added to them.
+    # @return [Hooks::Registry]
+    def hooks
+      registry = hooks_from_config
+      add_bundle_hooks(registry)
+      registry
+    end
+
+    # Load the installed bundles' plugins into +registries+; one that fails
+    # goes to +failures+, and the rest still load.
+    def load_plugins(registries, failures:)
+      @held_events = []
+      @loading = true
+      Plugin::Loader.load_installed(registries, failures: failures, settings: bundle_settings)
+    ensure
+      @loading = false
+    end
+
+    # config.yml `bundles:` (ConfigFile.bundle_settings), read once: the
+    # bundle hooks and the plugins both want it.
+    def bundle_settings
+      @bundle_settings ||= Samagotchi::ConfigFile.bundle_settings
+    end
+
+    private
+
+    def hooks_from_config
+      config_path = Samagotchi::ConfigFile.global_path
+      data = Samagotchi::ConfigFile.read_yaml(path: config_path)
+      return Hooks::Loader.load(data, failures: @hook_failures) if data.is_a?(Hash)
+
+      Hooks::Registry.new
+    end
+
+    def add_bundle_hooks(registry)
+      require_relative "memory_bundle/provenance"
+      settings = bundle_settings
+      MemoryBundle::Provenance.each_installed(holding: :hooks) do |bundle_name, bundle|
+        if bundle.error?
+          Log.warn(:hooks, "bundle_manifest_invalid", echo: "[samagotchi:hooks] bundle '#{bundle_name}': #{bundle.error}; its hooks are not loaded",
+                                                      bundle: bundle_name)
+          @hook_failures.add("hooks (bundle #{bundle_name})", bundle.error, required: false)
+          next
+        end
+        bundle_dir = File.join(MemoryBundle::Provenance.bundles_dir, bundle_name)
+        hooks_dir = File.join(bundle_dir, "hooks")
+        if bundle.experimental?
+          Log.info(:hooks, "experimental_bundle", echo: "[hooks] Bundle '#{bundle_name}' is experimental — its hooks may change or misbehave.", bundle: bundle_name)
+        end
+        begin
+          Hooks::BundleLoader.load(bundle_name: bundle_name, hooks_dir: hooks_dir, metadata: bundle.hooks, registry: registry,
+                                   failures: @hook_failures, settings: settings[bundle_name.to_s] || {},
+                                   requires_chi: bundle.requires_chi)
+        rescue Exception => e # rubocop:disable Lint/RescueException -- a hook's SyntaxError or exit must not stop chi
+          raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
+
+          Log.error(:hooks, "bundle_load_failed", echo: "[samagotchi:hooks] bundle '#{bundle_name}' failed to load hooks: #{e.class}: #{e.message}", bundle: bundle_name, error: e.class.name)
+        end
+      end
+    rescue Exception => e # rubocop:disable Lint/RescueException -- a hook's SyntaxError or exit must not stop chi
+      raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
+
+      Log.error(:hooks, "bundles_load_failed", echo: "[samagotchi:hooks] failed to load bundle hooks: #{e.class}: #{e.message}", error: e.class.name)
+    end
+  end
+end

data/lib/samagotchi/file_ref.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "tools/read"
+require_relative "tools/write"
+require_relative "tools/edit"
+
+module Samagotchi
+  # A ref to the file a read/write/edit call touched, for a UI to trace it
+  # (the web opens it in this machine's editor): its absolute path (the
+  # call's path against the session's cwd) and the lines the call named (a
+  # range read or a range edit). A ref is a kind and a target; what a click
+  # does is the UI's (refs.js keeps the actions per kind), so nothing here
+  # names an editor.
+  FileRef = Data.define(:path, :line, :end_line) do
+    # @return [Hash] {kind: "file", path:, line:, end_line:}, the lines only
+    #   when there are some
+    def to_h = { kind: FileRef::KIND, **super.compact }
+  end
+
+  class FileRef
+    KIND = "file"
+
+    TOOLS = [Tools::Read::NAME, Tools::Write::NAME, Tools::Edit::NAME].freeze
+
+    # @param cwd [String, nil] the session's working directory; without one
+    #   a relative path gets no ref (an absolute or ~ path still does)
+    # @return [FileRef, nil] nil for a tool that isn't a file tool and for a
+    #   path it can't place. +line+: the call's start_line when positive;
+    #   +end_line+: its end_line, only when past +line+.
+    def self.for(tool_name, call, cwd:)
+      return nil unless TOOLS.include?(tool_name) && call.is_a?(Hash)
+
+      path = absolute((tool_name == Tools::Read::NAME ? call[:content] : call[:path]).to_s.strip, cwd)
+      return nil unless path
+
+      line = positive(call[:start_line])
+      end_line = line && positive(call[:end_line])
+      new(path: path, line: line, end_line: end_line && end_line > line ? end_line : nil)
+    end
+
+    def self.absolute(raw, cwd)
+      return nil if raw.empty?
+      return File.expand_path(raw) if raw.start_with?("/", "~")
+      return nil if cwd.to_s.empty?
+
+      File.expand_path(raw, cwd)
+    rescue ArgumentError
+      # ~user for a user that doesn't exist.
+      nil
+    end
+    private_class_method :absolute
+
+    def self.positive(value)
+      number = Integer(value.to_s.strip, exception: false)
+      number&.positive? ? number : nil
+    end
+    private_class_method :positive
+  end
+end

data/lib/samagotchi/guardrail_wiring.rb

@@ -151,26 +151,26 @@ module Samagotchi
     def bundle_rules
       require_relative "memory_bundle/provenance"
       rules = []
-      MemoryBundle::Provenance.each_installed(holding: :guardrails) do |bundle_name, data|
-        if data[:error]
-          Log.warn(:guardrails, "bundle_rules_invalid", echo: "[samagotchi:guardrails] bundle #{bundle_name}: #{data[:error]}", bundle: bundle_name)
-          @failures.add("rules (bundle #{bundle_name})", data[:error], required: true, group: :rules)
+      MemoryBundle::Provenance.each_installed(holding: :guardrails) do |bundle_name, bundle|
+        if bundle.error?
+          Log.warn(:guardrails, "bundle_rules_invalid", echo: "[samagotchi:guardrails] bundle #{bundle_name}: #{bundle.error}", bundle: bundle_name)
+          @failures.add("rules (bundle #{bundle_name})", bundle.error, required: true, group: :rules)
           next
         end
-        if (too_new = MemoryBundle::Manifest.requires_chi_failure(data[:requires_chi], Samagotchi::VERSION))
-          rules.concat(too_new_bundle_rules(bundle_name, data, too_new))
+        if (too_new = MemoryBundle::Manifest.requires_chi_failure(bundle.requires_chi, Samagotchi::VERSION))
+          rules.concat(too_new_bundle_rules(bundle_name, bundle, too_new))
           next
         end
         dir = MemoryBundle::Provenance.new(name: bundle_name).guardrails_dir
         loaded = []
         whole = true
-        data[:guardrails].sort_by { |k, _| k.to_s }.each do |basename, meta|
+        bundle.guardrails.sort.each do |basename, sha|
           what = "rules #{basename} (bundle #{bundle_name})"
-          path = File.join(dir, basename.to_s)
+          path = File.join(dir, basename)
           begin
             raise Guardrails::Rules::ParseError, "the file is missing" unless File.file?(path)
 
-            unless MemoryBundle::Provenance.sha_matches?(path, meta.is_a?(Hash) ? meta[:sha256] : nil)
+            unless MemoryBundle::Provenance.sha_matches?(path, sha)
               raise Guardrails::Rules::ParseError, "its sha256 differs from the installed one (edited after install? reinstall the bundle)"
             end
 
@@ -256,7 +256,7 @@ module Samagotchi
     # load the new ones). Never loaded (a chi older than the bundle it
     # starts with): none, and a required load failure, as the hook loader
     # does for a guardrail hook, so the calls aren't quietly unguarded.
-    def too_new_bundle_rules(bundle_name, data, reason)
+    def too_new_bundle_rules(bundle_name, bundle, reason)
       kept = @loaded_bundle_rules[bundle_name]
       unless kept
         Log.warn(:guardrails, "bundle_rules_requires_chi", echo: "[samagotchi:guardrails] bundle #{bundle_name}: its rules are not loaded: #{reason}",
@@ -266,19 +266,19 @@ module Samagotchi
         return []
       end
 
-      key = [bundle_name, data[:version].to_s]
+      key = [bundle_name, bundle.version.to_s]
       return kept if @kept_noticed[key]
 
       @kept_noticed[key] = true
-      Log.warn(:guardrails, "bundle_rules_kept", bundle: bundle_name, version: data[:version].to_s,
-                                                 requires_chi: data[:requires_chi].to_s)
-      @notify.call(kept_notice(bundle_name, data))
+      Log.warn(:guardrails, "bundle_rules_kept", bundle: bundle_name, version: bundle.version.to_s,
+                                                 requires_chi: bundle.requires_chi.to_s)
+      @notify.call(kept_notice(bundle_name, bundle))
       kept
     end
 
-    def kept_notice(bundle_name, data)
+    def kept_notice(bundle_name, bundle)
       id = @session_lookup.call&.id || "ID"
-      "bundle #{bundle_name} #{data[:version]} needs chi #{data[:requires_chi]} and this session runs chi #{Samagotchi::VERSION}: " \
+      "bundle #{bundle_name} #{bundle.version} needs chi #{bundle.requires_chi} and this session runs chi #{Samagotchi::VERSION}: " \
         "its new rules are not loaded, the ones loaded before still apply. Restart the session to load them " \
         "(chi sessions stop #{id}, then chi --resume #{id})"
     end

data/lib/samagotchi/kernel_loop.rb

@@ -726,9 +726,11 @@ module Samagotchi
     end
 
     # Estimate context usage for this iteration's prompt (ContextStatus#observe)
-    # and, when the emit gate fires, surface it to stream consumers as a
-    # :context_status event. The telemetry is not for the model (it used to
-    # be injected as a synthetic system message).
+    # and surface it to stream consumers as a :context_status event, on every
+    # request (observe returns the estimate each time it is enabled), so the
+    # web and the attached TUI get a fresh number per request. The telemetry
+    # is not for the model (it used to be injected as a synthetic system
+    # message); the model's own line is still left only on a rise.
     def emit_context_status_event(on_stream_event, context, prompt, iteration_index:, window:, image_tokens: 0)
       event = context.observe(prompt.length, iteration_index: iteration_index, window: window, image_tokens: image_tokens)
       return unless event

data/lib/samagotchi/llm/chat_loop.rb

@@ -651,10 +651,11 @@ module Samagotchi
 
         # Before a request, as the native loop: estimate how full the window
         # is (the server's last count plus what the turn appended since),
-        # emit :context_status on a bucket change, and put the model's own
-        # line on the tail on a rise that asks it for a change. The estimate
-        # counts the conversation's text and tool calls, not the tool
-        # schemas (the server's count does).
+        # emit :context_status on every request (observe returns the estimate
+        # each time it is enabled), and put the model's own line on the tail
+        # on a rise that asks it for a change. The estimate counts the
+        # conversation's text and tool calls, not the tool schemas (the
+        # server's count does).
         def observe_context(iteration, window)
           return unless window