samagotchi 0.2.0 → 0.4.0

data/lib/samagotchi/bundles/system/self_map.md

@@ -13,11 +13,15 @@
 - Sessions: each is one file, `<sessions dir>/<id>.json`. A `<id>/` dir beside it exists only
   for background/web workers (input/, notes/, output/, pid). List them with `chi sessions list`
   (`--live` for the ones a worker runs now); delete one with `chi sessions delete ID` (never by hand).
+  An archived session (`chi sessions archive ID`, a marker file `<id>/archived`) is hidden from
+  every list and kept for good; `chi sessions list --archived` shows it.
 - `[CONTEXT NOTE from …]` messages are context notes (`chi note`, or another session's
   `send_note`): background, not requests. `list_sessions` + `send_note` tell another session
   something without starting a turn there; see `docs/sessions.md` "Context notes".
 - `chi send -m TEXT <id>` is the other half: the text goes in as the user's message and a
   turn runs (stdin piped too = quoted context above it); see `docs/sessions.md` "Sending a message".
+  `chi send --new --wait -m TEXT` starts a session the user can watch in the web and prints its
+  answer (exit 3: it waits for the user's answer); see "Starting a session".
 - `delegate` hands a task to a child session that runs in parallel and returns only its final
   reply (`delegate_result` waits for it; `session:` sends a follow-up to a child). A child is a
   normal session: it shows in `chi sessions list` with `↳ <parent>`, and the user can steer it
@@ -26,8 +30,10 @@
   commands (`anytime:` ones run mid-turn), model tools (they can return images I see), hooks,
   cards, side answers (`ask_model`),
   child sessions and services (e.g. MCP server processes). Shipped: `btw` (`/btw` side question),
-  `mcp` (MCP server tools; a screenshot comes as a picture), `guardrails` (rules), `known-names` (typo guard), `loop-guard`
-  (denies a repeated tool call with the same result, stops the turn after a few). `chi bundle list`
+  `mcp` (MCP server tools; a screenshot comes as a picture), `guardrails` (rules), `known-names` (typo guard), `source-links`
+  (turns source refs like JIRA-123 in an answer into links in the web, and a one-line note), `loop-guard`
+  (denies a repeated tool call with the same result, stops the turn after a few), `check-in` (after N tool
+  calls with no answer, a card asks the user to nudge me, let me go on or stop; `/checkin`). `chi bundle list`
   shows installed + available; `chi bundle install <name>`. Settings: config.yml `bundles: <name>:`
   (`config_modification_protocol`), read at session start: after an install or a settings change,
   tell the user to restart the session. API and bundle docs: `docs/plugins.md`.

data/lib/samagotchi/client.rb

@@ -8,6 +8,7 @@ require_relative "cancellation_controller"
 require_relative "llm/http"
 require_relative "vision_context"
 require_relative "vision_support"
+require_relative "sampling_settings"
 
 module Samagotchi
   # Thin HTTP client for llama.cpp's native /completion endpoint, or an
@@ -27,6 +28,10 @@ module Samagotchi
     # budget and no retry (see #server_props).
     CONTEXT_WINDOW_PROBE_OPEN_TIMEOUT = 1
     CONTEXT_WINDOW_PROBE_READ_TIMEOUT = 2
+    # Seconds a probe that got no answer (refused, timed out) is remembered:
+    # a down or hung server then costs one probe per window, not one per
+    # generation, and a new turn doesn't ask again at once.
+    PROPS_FAILURE_TTL = 30
 
     SERVER_TRANSPORT_ENV = "SAMAGOTCHI_SERVER_TRANSPORT"
     DEFAULT_TRANSPORT = :llama_cpp
@@ -109,7 +114,7 @@ module Samagotchi
     end
 
     # One /props probe's outcome. `answered?` is false when the probe failed:
-    # a network error, a timeout or any non-200 (llama.cpp answers 503 while
+    # a network error, a timeout, a turn's cancel or any non-200 (llama.cpp answers 503 while
     # it loads a model). `body` is the parsed JSON of a 200, or nil when it
     # isn't JSON.
     ServerProps = Data.define(:body, :status) do
@@ -121,21 +126,38 @@ module Samagotchi
     # Moved to its own file; the old name keeps working.
     CancellationController = Samagotchi::CancellationController
 
+    PROBE_CANCEL_KEY = :samagotchi_probe_cancel
+
+    # The cancel a /props probe made on this thread listens to: a turn sets
+    # its own (Engine#run_turn), so a Stop cuts the probes it makes before
+    # its first request. Probes on other threads (chi self, /model, a
+    # status snapshot) have none and run to their timeout.
+    def self.probe_cancel = Thread.current[PROBE_CANCEL_KEY]
+
+    # Sets this thread's probe cancel; returns the one it replaces.
+    def self.swap_probe_cancel(controller)
+      previous = Thread.current[PROBE_CANCEL_KEY]
+      Thread.current[PROBE_CANCEL_KEY] = controller
+      previous
+    end
+
     # @param sleeper [#call, nil] waits between retries (specs pass a no-op)
     # @param scheme [String, nil] "https" for a TLS server (default http)
     # @param first_token_timeout [Numeric, nil] seconds a completion may take
     #   to stream its first text (LLM::HTTP); nil: no limit
     # @param name [String, nil] the host's config name, for error lines
     #   (default: the transport's label)
+    # @param api_key_env [String, nil] the variable holding the host's API
+    #   key (llama.cpp's --api-key), sent as a bearer token on every request;
+    #   nil sends no Authorization header
+    # @param env [Hash] where the key variable is read
     def initialize(host: nil, port: nil, open_timeout: nil, read_timeout: nil, transport: nil, sleeper: nil, scheme: nil,
-                   first_token_timeout: nil, name: nil)
+                   first_token_timeout: nil, name: nil, api_key_env: nil, env: ENV)
       # Unified config precedence: CLI > ENV > file > default (via Samagotchi::Config)
       cfg_host = nil; cfg_port = nil; cfg_transport_raw = nil
       begin
         cfg_host       = Samagotchi::Config.get("server.host")
         cfg_port       = Samagotchi::Config.get("server.port")
-        cfg_open_timeout = Samagotchi::Config.get("server.open_timeout")
-        cfg_read_timeout = Samagotchi::Config.get("server.read_timeout")
         cfg_transport_raw = Samagotchi::Config.get("server.transport")
       rescue StandardError
         nil
@@ -143,17 +165,19 @@ module Samagotchi
       @host          = host || cfg_host
       @port          = (port || cfg_port).to_i
       @scheme        = scheme || "http"
-      @open_timeout  = (open_timeout || cfg_open_timeout).to_i
-      @read_timeout  = (read_timeout || cfg_read_timeout).to_i
+      @open_timeout  = Samagotchi::Config.positive_seconds("server.open_timeout", open_timeout)
+      @read_timeout  = Samagotchi::Config.positive_seconds("server.read_timeout", read_timeout)
       transport_fallback = cfg_transport_raw || ENV.fetch(SERVER_TRANSPORT_ENV, DEFAULT_TRANSPORT.to_s)
       @transport = build_transport(resolve_transport(transport || transport_fallback))
       @props_cache = {}
+      @props_failures = {}
       @props_mutex = Mutex.new
       @first_token_timeout = first_token_timeout
       @host_name = name
       @label = name.to_s.empty? ? @transport.label : name.to_s
       @http = LLM::HTTP.new(label: @label, open_timeout: @open_timeout, read_timeout: @read_timeout,
-                            sleeper: sleeper, first_token_timeout: first_token_timeout)
+                            sleeper: sleeper, first_token_timeout: first_token_timeout,
+                            api_key: LLM::ApiKey.for(api_key_env, host: @label, env: env))
     end
 
     # Seconds a completion may take to stream its first text, or nil.
@@ -182,11 +206,14 @@ module Samagotchi
     # @param on_retry    [Proc, nil]     optional callback before retry sleep
     # @param images      [Array<String>] base64 images, one per
     #   ImagePlan::NATIVE_PLACEHOLDER in the prompt (llama.cpp only)
+    # @param sampling    [Hash]          request fields to add (SamplingSettings):
+    #   temperature, penalties, …; they can't replace the fields above
     # @return [String] the generated text
     def complete(prompt, stop: ["<end_of_turn>", "<|tool_response>"], n_predict: nil, model: nil, on_chunk: nil, cancel_controller: nil, on_retry: nil,
-                 images: [])
+                 images: [], sampling: {})
       images = Array(images)
-      return stream_completion(scrub_utf8(prompt), stop, n_predict, model, on_chunk, cancel_controller, on_retry) if images.empty?
+      request = { stop: stop, n_predict: n_predict, model: model, sampling: sampling }
+      return stream_completion(scrub_utf8(prompt), request, on_chunk, cancel_controller, on_retry) if images.empty?
 
       # The media marker is random per server process: a restart between the
       # /props read and the request makes the prompt fail to tokenize, so
@@ -196,7 +223,7 @@ module Samagotchi
         attempts += 1
         payload_prompt = { prompt_string: scrub_utf8(prompt.gsub(ImagePlan::NATIVE_PLACEHOLDER, media_marker!(model))),
                            multimodal_data: images }
-        stream_completion(payload_prompt, stop, n_predict, model, on_chunk, cancel_controller, on_retry)
+        stream_completion(payload_prompt, request, on_chunk, cancel_controller, on_retry)
       rescue LLM::BadRequest => e
         raise unless attempts == 1 && e.message.include?("Failed to tokenize prompt")
 
@@ -205,11 +232,14 @@ module Samagotchi
       end
     end
 
-    private def stream_completion(prompt, stop, n_predict, model, on_chunk, cancel_controller, on_retry)
+    OPENAI_API_HINT = "does this host speak the OpenAI API? set `api: openai` on it"
+
+    private def stream_completion(prompt, fields, on_chunk, cancel_controller, on_retry)
       uri = completion_uri
       request = Net::HTTP::Post.new(uri)
       request["Content-Type"] = "application/json"
-      request.body = completion_payload(prompt, stop: stop, n_predict: n_predict, model: model).to_json
+      request.body = completion_payload(prompt, **fields).to_json
+      model = fields[:model]
 
       result = +""
       reset_on_retry = lambda do |event|
@@ -219,7 +249,8 @@ module Samagotchi
       end
       @http.stream_lines(uri, request, cancel_controller: cancel_controller, on_retry: reset_on_retry,
                                        on_network_error: ->(_error) { invalidate_context_window! },
-                                       log_fields: { model: model, purpose: "chat" }) do |line, shown|
+                                       log_fields: { model: model, purpose: "chat",
+                                                     sampling: SamplingSettings.log_text(sendable_sampling(fields[:sampling])) }) do |line, shown|
         parsed_chunk = parse_stream_line(line)
         next unless parsed_chunk
 
@@ -229,6 +260,11 @@ module Samagotchi
         on_chunk&.call(content: content, payload: payload)
       end
       result
+    rescue LLM::BadRequest => e
+      raise unless e.status == 404 && @transport.name == :llama_cpp
+
+      # No native /completion here: likely an OpenAI-compatible server.
+      raise LLM::BadRequest.new(e.message, host: e.host, status: e.status, attempts: e.attempts, hint: OPENAI_API_HINT)
     rescue RequestCancelled, LLM::ProviderError
       raise
     rescue StandardError => e
@@ -260,7 +296,9 @@ module Samagotchi
     # a turn. The probe names the model (`?model=`): a llama.cpp router
     # answers a stub without it, and a single-model server ignores it.
     # Whatever the server answers (a non-200 too) is cached per model; a
-    # network failure is not, so the next call asks again.
+    # network failure for PROPS_FAILURE_TTL seconds, then the next call asks
+    # again. A probe cut by this thread's Client.probe_cancel answers
+    # :cancelled, uncached, and the turn's next request ends it.
     def server_props(model: nil)
       path = @transport.props_path
       return nil unless path
@@ -268,10 +306,21 @@ module Samagotchi
       key = model.to_s
       @props_mutex.synchronize do
         return @props_cache[key] if @props_cache.key?(key)
+
+        failed, failed_at = @props_failures[key]
+        return failed if failed && monotonic_now - failed_at < PROPS_FAILURE_TTL
       end
 
       props = probe_props(path, key)
-      @props_mutex.synchronize { @props_cache[key] = props } unless props.status == :network_error
+      @props_mutex.synchronize do
+        case props.status
+        when :cancelled then nil
+        when :network_error then @props_failures[key] = [props, monotonic_now]
+        else
+          @props_cache[key] = props
+          @props_failures.delete(key)
+        end
+      end
       props
     end
 
@@ -286,23 +335,30 @@ module Samagotchi
 
     # Forget cached /props answers: the server may have restarted with
     # another -c, or a model switch may have loaded one with a different
-    # window.
+    # window. A recent failure stays until its PROPS_FAILURE_TTL ends: it
+    # holds no stale window, and asking a hung server again at every turn's
+    # start is what it saves.
     def invalidate_context_window!
       @props_mutex.synchronize { @props_cache.clear }
     end
 
     private
 
+    def monotonic_now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
     def probe_props(path, model)
       query = model.empty? ? "" : "?#{URI.encode_www_form(model: model)}"
       uri = URI("#{@scheme}://#{@host}:#{@port}#{path}#{query}")
       response = @http.fetch(uri, Net::HTTP::Get.new(uri), retries: false, check_status: false,
                                   log_fields: { model: model.empty? ? nil : model, purpose: "probe" },
                                   open_timeout: CONTEXT_WINDOW_PROBE_OPEN_TIMEOUT,
-                                  read_timeout: CONTEXT_WINDOW_PROBE_READ_TIMEOUT)
+                                  read_timeout: CONTEXT_WINDOW_PROBE_READ_TIMEOUT,
+                                  cancel_controller: Client.probe_cancel)
       return ServerProps.new(body: nil, status: :http_error) unless response.code.to_s == "200"
 
       ServerProps.new(body: parse_props(response.body), status: :ok)
+    rescue RequestCancelled
+      ServerProps.new(body: nil, status: :cancelled)
     rescue StandardError
       ServerProps.new(body: nil, status: :network_error)
     end
@@ -337,12 +393,18 @@ module Samagotchi
       URI("#{@scheme}://#{@host}:#{@port}#{@transport.completion_path}")
     end
 
-    def completion_payload(prompt, stop:, n_predict:, model:)
+    def completion_payload(prompt, stop:, n_predict:, model:, sampling: {})
       payload = { prompt: prompt, stop: stop, stream: true }
       payload[@transport.token_limit_key] = n_predict if n_predict && n_predict.to_i.positive?
       model_name = @transport.model_for_payload(model)
       payload[:model] = model_name if model_name
-      payload
+      sendable_sampling(sampling).merge(payload)
+    end
+
+    # The sampling fields that go out: no nil (nothing to drop here: the
+    # server's defaults apply) and none of the reserved request fields.
+    def sendable_sampling(sampling)
+      (sampling || {}).reject { |key, value| value.nil? || ConfigFile::SAMPLING_RESERVED_KEYS.include?(key.to_s) }
     end
 
     # Conversation content (system prompt + tool responses + model output) can

data/lib/samagotchi/commands/registry.rb

@@ -74,6 +74,14 @@ module Samagotchi
 
       def command?(line) = !lookup(line).nil?
 
+      # @return [Entry, nil] the first entry the UI runs itself (local) that
+      #   matches +line+, whatever its uis (a UI answers the others' too:
+      #   the REPL's /detach note)
+      def lookup_local(line)
+        text = line.to_s.strip
+        @entries.find { |entry| entry.local && entry.match?(text) }
+      end
+
       # @return [Array<Entry>] every entry, in registration order
       def entries = @entries.dup