samagotchi 0.2.0 → 0.3.0

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

@@ -18,7 +18,7 @@ Single registry `Samagotchi::Config` (`Config::ENTRIES` in `lib/samagotchi/confi
 
 Sections forbid `_`/`-` (`SECTION_RE` `/\A[a-z0-9]+\z/`); leaves keep `snake_case` in YAML (`base_url`) and become kebab in CLI (`base-url`) via registry derivation — no generic string split, registry lookup avoids flat vs nested collision.
 
-**Universal entries** (`expose: [:env,:config,:cli]`): `default.model`, `server.host/port/transport/open_timeout/read_timeout`, `server.first_token_timeout` (env and config only), `recap.model/base_url/host_ref/inactivity/timeout/min_user_turns/sentences`, `session.retention_days/max_count/keep_status/sweep_interval_hours/idle_exit_minutes`, `session.shared/keep_empty/max_children` (env and config only), `log.file/disable`, `status.line/width_mode/max_width/fixed_width`, `context.status/window_tokens/chars_per_token/status_thresholds/status_cadence`, `thinking.ui/preview_lines/render_interval`, `n_predict`, `max_tool_output_chars`, `retry.max/base_delay/max_delay`, `read.*`, `execute.*`, `web.port/host`, `no_interrupt`, `no_default_input` etc. (`Config::ENTRIES`; `expose` says which of env/config/cli each takes). Precedence is `CLI > ENV > file > default`.
+**Universal entries** (`expose: [:env,:config,:cli]`): `default.model`, `server.host/port/transport/open_timeout/read_timeout`, `server.first_token_timeout` (env and config only), `recap.model/base_url/host_ref/inactivity/timeout/min_user_turns/sentences`, `session.retention_days/max_count/keep_status/sweep_interval_hours/idle_exit_minutes`, `session.shared/keep_empty/max_children` (env and config only), `log.file/disable`, `status.line/width_mode/max_width/fixed_width`, `context.status/window_tokens/chars_per_token/status_thresholds/status_cadence`, `thinking.ui/render_interval/turn_preamble`, `default.n_predict`, `max_tool_output_chars`, `retry.max/base_delay/max_delay`, `read.*`, `execute.*`, `web.port/host`, `no_interrupt`, `no_default_input` etc. (`Config::ENTRIES`; `expose` says which of env/config/cli each takes). Precedence is `CLI > ENV > file > default`.
 
 Example `config.yml` (new nested form, preferred):
 
@@ -52,13 +52,13 @@ log:
   disable: false
 ```
 
-Legacy flat keys (`SAMAGOTCHI_DEFAULT_MODEL`, `SAMAGOTCHI_N_PREDICT` etc. at top-level) are still read via fallback in `Config.lookup_yaml` but warn `Warning: config key 'SAMAGOTCHI_DEFAULT_MODEL' is legacy UPPER — use 'default.model'` (`ConfigFile.load_global_env!`). Migrate them to nested form and remove the flat entry. The old `LLAMA_HOST`/`LLAMA_PORT` aliases were removed; use `server.host`/`server.port` (nested) or `SAMAGOTCHI_SERVER_HOST`/`SAMAGOTCHI_SERVER_PORT`.
+Legacy flat keys (`SAMAGOTCHI_DEFAULT_MODEL`, `SAMAGOTCHI_N_PREDICT` etc. at top-level) are still read via fallback in `Config.lookup_yaml` but warn `Warning: config key 'SAMAGOTCHI_DEFAULT_MODEL' is legacy UPPER — use 'default.model'` (`ConfigFile.load_global_env!`). When a file has both, the nested key wins and the warning names both. Migrate them to nested form and remove the flat entry. The old `LLAMA_HOST`/`LLAMA_PORT` aliases were removed; use `server.host`/`server.port` (nested) or `SAMAGOTCHI_SERVER_HOST`/`SAMAGOTCHI_SERVER_PORT`.
 
 **Excluded maps** (YAML-only, not part of the flat registry; skipped by scalar loader):
 
 - `model_aliases:` map of alias → model id (`ConfigFile.resolve_model_alias`). Keys lowercased on write (`ConfigFile.write_model_alias!`). Values may be bare `model` or qualified `host:model` (hybrid).
-- `hosts:` map of `name → {host, port | url, transport, api, api_key_env, profile, first_token_timeout, enabled}` (`ConfigFile.hosts_config`, `host_registry.rb` `HostEntry`). Names lowercased; `url:` (http/https, optional path) replaces host/port, never both; `api_key_env:` names the env var holding the API key (never write a key into config.yml); `transport` overrides `server.transport`; `first_token_timeout` (seconds, `0` = off; a negative or non-number warns and is ignored) overrides `server.first_token_timeout` for that host; workers inherit via `SAMAGOTCHI_HOSTS_JSON` (`hosts_json_for_env`, `session_manager.rb`).
-- `models:` map of model id or alias → `{profile}` (`ConfigFile.model_settings`). Keys match case-insensitively. `profile` (here or on a host) is `qwen36|gemma4`: the raw prompt format for native hosts. Precedence: `--profile`/`SAMAGOTCHI_MODEL_PROFILE` > `models:` > `hosts.<name>.profile` > the llama.cpp server's chat template > the name (`qwen`/`gemma`) > `qwen36` (`ModelProfile.resolve`). Set one when a model's name hides its family (e.g. a Qwen fine-tune under another name on mlx, which has no template to read).
+- `hosts:` map of `name → {host, port | url, transport, api, api_key_env, profile, first_token_timeout, vision, sampling, enabled}` (`ConfigFile.hosts_config`, `host_registry.rb` `HostEntry`). Names lowercased; `url:` (http/https, optional path) replaces host/port, never both; `api_key_env:` names the env var holding the API key (never write a key into config.yml); `transport` overrides `server.transport`; `first_token_timeout` (seconds, `0` = off; a negative or non-number warns and is ignored) overrides `server.first_token_timeout` for that host; workers inherit via `SAMAGOTCHI_HOSTS_JSON` (`hosts_json_for_env`, `session_manager.rb`).
+- `models:` map of model id or alias → `{profile, vision, sampling}` (`ConfigFile.model_settings`). `sampling:` (here or on a host) is a map of request fields passed to the provider as written (`temperature`, `top_p`, `presence_penalty`, `repeat_penalty`, …; a model's fields win over its host's per field; `null` = don't send; chi's own fields like `max_tokens`/`stream` are refused with a warning; `docs/configuration.md` "Sampling"). Keys match case-insensitively. `profile` (here or on a host) is `qwen36|gemma4`: the raw prompt format for native hosts. Precedence: `--profile`/`SAMAGOTCHI_MODEL_PROFILE` > `models:` > `hosts.<name>.profile` > the llama.cpp server's chat template > the name (`qwen`/`gemma`) > `qwen36` (`ModelProfile.resolve`). Set one when a model's name hides its family (e.g. a Qwen fine-tune under another name on mlx, which has no template to read).
 - `hooks:` map of `hooks_dir` + per-event lists `{path, on_error}` (`Hooks::Loader.load`). `hooks_dir` may start with `~`.
 - `guardrails:` tool-call rules (`docs/guardrails.md`; read in `Engine#guardrail_rules`, parsed by `Guardrails::Rules.parse`): `enabled` (bool, default true; `false` drops rules and hooks' asks, a deny still applies; env `SAMAGOTCHI_GUARDRAILS_ENABLED`), `rules:` (list), `disable:` (list of rule ids, `id` or `bundle:id`, switching off a bundle's or config rule without editing it). A rule takes only `id`, `tool`, `command`, `path`, `verdict`, `reason`, `scopes`: `id` required; at least one of `tool` (a name, `shell` = execute + task_create, a `File.fnmatch` glob like `"mcp_*"`, or a list), `command` (a Ruby regex on the shell command), `path` (a glob, or `outside_repo`); `verdict` `ask|deny`; `scopes` (for `ask`) a subset of `once, session, repo, rule`. **Any parse error (an unknown key, a bad regex, no verdict) makes chi deny every tool call** until fixed, so validate with `YAML.safe_load` and keep the list shape. Rules load when a session starts: restart the worker/REPL after an edit. Installed bundles' rule files (`chi bundle install guardrails`) add to them; `/guardrails` lists what loaded.
 
@@ -92,6 +92,10 @@ bundles:
     deny_after: 2              # same call + same result N times in a turn -> deny the next
     stop_after: 4              # stop the turn at this many denies
     mode: deny                 # deny | notify (warn only); ignore_tools: [task_wait, ...]
+  check-in:
+    after: 50                  # tool calls in one turn with no answer before the first check
+    every: 50                  # then again every N more
+    mode: ask                  # ask (a card) | nudge (nudge the model by itself) | notify; message:, ignore_tools: [...]
   mcp:                         # tools become mcp_<server>_<tool>; /mcp lists them
     timeout: 60                # per call, seconds; startup_timeout: 10
     servers:
@@ -113,7 +117,7 @@ A guardrail rule's `tool:` may be a glob (`tool: "mcp_*"`, verdict `ask`) to cov
 1. **Read** the current file via `read` tool (or `ConfigFile.global_path`). If `File.file?` false, start from `{}`.
 2. `YAML.safe_load` (permitted_classes: [], aliases: false). If data nil or not Hash, treat as `{}` or raise with path.
 3. Mutate the intended **nested** key in the raw hash. Preserve all other keys byte-for-byte where possible. Example for default model: `raw_data["default"] ||= {}; raw_data["default"]["model"] = "new-model"; raw_data.delete("SAMAGOTCHI_DEFAULT_MODEL")` to migrate legacy.
-4. **Validate** (see below) before writing. Also run `Samagotchi::Config.validate_yaml_sections` — it rejects top-level `_` (suggest `default.model`) and warns on legacy flat keys.
+4. **Validate** (see below) before writing. Also run `Samagotchi::Config.validate_yaml_sections` — it returns one `config: unknown key '…' (did you mean '…'?)` per key chi doesn't read (every config-exposed `Config::ENTRIES` key is known as written, including the section-less `max_tool_output_chars` and `skip_agent_md`; names under `hosts:`/`models:`/`model_aliases:`/`hooks:`/`bundles:`/`memories:` are free-form, host and model entries are checked against `Config::MAP_ENTRY_KEYS`). An empty list means no warning at start.
 5. **Write atomically**: `FileUtils.mkdir_p(File.dirname(path))`, `File.write("#{path}.tmp", YAML.dump(raw_data))`, `File.rename("#{path}.tmp", path)`.
 6. Update in-process state: `write_default_model!` sets `ENV["SAMAGOTCHI_DEFAULT_MODEL"]` and `Samagotchi::Config.reload!`; otherwise the harness picks it up on next `Config.get` (live resolve) or restart. CLI overrides (`--default-model`) win over file until process exit.
 
@@ -132,7 +136,7 @@ A guardrail rule's `tool:` may be a glob (`tool: "mcp_*"`, verdict `ask`) to cov
 - **Hosts**: each entry needs `host`, `port` 1-65535, `transport` and `api` optional (a raw `api` must match `transport`), name must match `/\A[a-z0-9][a-z0-9._-]*\z/i`.
 - **Hooks**: each entry must have `path` (relative to `hooks_dir`), `on_error` is `skip` (default) or `log`. Class name must match file basename snake→Pascal.
 - **Scalars via registry**: `Config.coerce` validates `String/Numeric/true/false` per `type: :string/:integer/:float/:bool/:enum`; invalid values warn and fall back to entry `default`.
-- **Sections**: `validate_yaml_sections` rejects top-level keys containing `_` (suggest dotted) and section names containing `_`/`-`.
+- **Keys**: `validate_yaml_sections` flags unknown keys (with a suggestion), a registry section that isn't a mapping, and env/CLI-only keys (`model.profile`).
 
 ## Tools to use
 

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.2.0
+version: 0.3.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:8b594100bee4797b563bd6425dc6f3ff93e1bdfbe9fc5fa1d66b42093c4795e2
-  self_map.md: sha256:d42481b930ef6e59deb1e5c989a9a171e834569b42be9a8d3dda6b2379b0a5ff
-  config_modification_protocol.md: sha256:c67e5fc1611a09203e3ebb1af2c14cacc2878b42a9fb0eb3d190c3b2daddafc3
+  self_map.md: sha256:67eb6223728a72788fa0d75aa56affea2ca48962de2e445293bc12b15f5f70c0
+  config_modification_protocol.md: sha256:1d1047f3f99fc9ceb89ef191cbcf3d68bc996addd00d7b6eb567a63b8ff677ea
   memory_guide.md: sha256:6dd1ecfd6a377c4f2cfc2dc299c1ef3835f10d9f313616fd3eb23e5fd3202858
   delegated.md: sha256:8f7965b6165c3526abb0cd39e44a8b73a8d6a26755049bdcd007baf0b0771087

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,6 +126,21 @@ 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
@@ -148,6 +168,7 @@ module Samagotchi
       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
@@ -182,11 +203,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 +220,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 +229,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 +246,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 +257,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 +293,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 +303,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 +332,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 +390,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