samagotchi 0.3.0 → 0.4.0

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

@@ -57,8 +57,8 @@ Legacy flat keys (`SAMAGOTCHI_DEFAULT_MODEL`, `SAMAGOTCHI_N_PREDICT` etc. at top
 **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, 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).
+- `hosts:` map of `name → {host, port | url, transport, api, api_key_env, profile, first_token_timeout, vision, sampling, thinking, 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, thinking}` (`ConfigFile.model_settings`). `thinking:` (here, on a host, or `thinking.level` for every model) is `off|low|medium|high|default` (`Thinking`; unquoted `off` works, `on` is not a level; `default` = send nothing). Precedence: `--thinking`/`SAMAGOTCHI_THINKING_LEVEL` > `models:` > `hosts.<name>.thinking` > `thinking.level` in config.yml > `default`. A `sampling:` key wins over the fields a level sends (`null` drops one); `docs/configuration.md` "Thinking". `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.
 

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

@@ -1,10 +1,9 @@
 # Delegated session
 
-A parent session delegated your task and reads only your final reply; the user may be watching or not.
+Another chi session (the parent) gave you this task. It reads only your last message of each turn; the user may be watching, or not.
 
-- Do the task; put everything the parent needs in your last message (findings, paths, commands run, what is unverified). Nothing else of yours reaches it.
-- Don't delegate further, don't start other chi sessions, don't send notes to sessions other than the parent.
-- Don't write memories unless the task asks for it; put what you learned in the reply instead.
-- Don't change config, install bundles or edit managed files.
-- Stay in the working directory you were started in.
-- If you are blocked, say so in the reply with the exact question; only ask_user_question when the task says the user is watching.
+- Finish the task in this turn if you can. End with one reply the parent can act on without asking back: the result first, then evidence (paths, commands run and what they printed), then anything you could not verify or finish.
+- The parent may send follow-up messages later; each one is a new turn in this same session, with what you did so far.
+- Work in the directory you were started in. Don't change config, install bundles, edit managed files or write memories unless the task asks for it.
+- You can't delegate further. Don't start other chi sessions, and send notes only to the parent.
+- If you are blocked, stop and say so in the reply with the exact question. Use ask_user_question only when the task says the user is watching.

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.3.0
+version: 0.4.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:67eb6223728a72788fa0d75aa56affea2ca48962de2e445293bc12b15f5f70c0
-  config_modification_protocol.md: sha256:1d1047f3f99fc9ceb89ef191cbcf3d68bc996addd00d7b6eb567a63b8ff677ea
+  config_modification_protocol.md: sha256:f76ee7e2f5a8e699401e3a4c9144643ee64015efd11a266029704bf228be6a95
   memory_guide.md: sha256:6dd1ecfd6a377c4f2cfc2dc299c1ef3835f10d9f313616fd3eb23e5fd3202858
-  delegated.md: sha256:8f7965b6165c3526abb0cd39e44a8b73a8d6a26755049bdcd007baf0b0771087
+  delegated.md: sha256:0a71d5dfa7127df2d51cb5f0e7214240ed88777e36559430a8724c796d7ae561

data/lib/samagotchi/client.rb

@@ -147,15 +147,17 @@ module Samagotchi
     #   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
@@ -163,8 +165,8 @@ 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 = {}
@@ -174,7 +176,8 @@ module Samagotchi
       @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.

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
 

data/lib/samagotchi/config.rb

@@ -8,6 +8,9 @@ require "set"
 require_relative "log"
 
 module Samagotchi
+  # Parses the thinking: levels of host and model entries (it needs Config).
+  autoload :Thinking, File.expand_path("thinking", __dir__)
+
   # Unified configuration registry implementing the implicit convention:
   #   ENV    SAMAGOTCHI_ATTR            (UPPER + prefix + _ = nesting)
   #   YAML   attr: / nested: {param:}   (lower snake, dot = nesting, Option A leaf keeps _)
@@ -22,7 +25,7 @@ module Samagotchi
   # handled by ConfigFile (same file, below), which reads the *same* parsed YAML
   # through ConfigFile.read_yaml so the file is parsed once per change.
   module Config
-    Entry = Struct.new(:key, :yaml_path, :type, :default, :expose, :enum_values, :aliases, :yaml_aliases, keyword_init: true) do
+    Entry = Struct.new(:key, :yaml_path, :type, :default, :expose, :enum_values, :yaml_aliases, keyword_init: true) do
       def env_key
         "SAMAGOTCHI_" + yaml_path.map { |p| p.upcase }.join("_")
       end
@@ -118,6 +121,11 @@ module Samagotchi
       Entry.new(key: "thinking.ui",              yaml_path: %w[thinking ui],              type: :string, default: nil,              expose: %i[env config cli]),
       Entry.new(key: "thinking.render_interval", yaml_path: %w[thinking render_interval], type: :float,   default: 0.08,            expose: %i[env config cli]),
       Entry.new(key: "thinking.turn_preamble",   yaml_path: %w[thinking turn_preamble],   type: :bool,   default: true,             expose: %i[env config cli]),
+      # How much models think: off|low|medium|high|default, parsed by Thinking
+      # (a :string, since YAML reads an unquoted off as false). The CLI flag
+      # is bin/chi's own --thinking; models: and hosts: entries rank below
+      # the flag and the env, above config.yml's value.
+      Entry.new(key: "thinking.level",           yaml_path: %w[thinking level],           type: :string, default: "default",       expose: %i[env config]),
 
       Entry.new(key: "default.n_predict",        yaml_path: %w[default n_predict],        type: :integer, default: nil,              expose: %i[env config cli]),
       Entry.new(key: "max_tool_output_chars",    yaml_path: %w[max_tool_output_chars],    type: :integer, default: 10_000,          expose: %i[env config cli]),
@@ -128,6 +136,10 @@ module Samagotchi
       # Asks again in the same turn after an empty answer (EmptyAnswerRetry);
       # 0 = off, capped at 3. No CLI flag: workers get no CLI args.
       Entry.new(key: "retry.empty_answer",       yaml_path: %w[retry empty_answer],       type: :integer, default: 1,               expose: %i[env config]),
+      # What `chi update` touches; its --no-gem/--no-bundles/--no-desktop turn one off for a run.
+      Entry.new(key: "update.gem",               yaml_path: %w[update gem],               type: :bool,    default: true,            expose: %i[env config]),
+      Entry.new(key: "update.bundles",           yaml_path: %w[update bundles],           type: :bool,    default: true,            expose: %i[env config]),
+      Entry.new(key: "update.desktop",           yaml_path: %w[update desktop],           type: :bool,    default: true,            expose: %i[env config]),
 
       Entry.new(key: "read.truncate_at_bytes",        yaml_path: %w[read truncate_at_bytes],        type: :integer, default: 65_536,   expose: %i[env config cli]),
       Entry.new(key: "read.preview_bytes",            yaml_path: %w[read preview_bytes],            type: :integer, default: 12_288,   expose: %i[env config cli]),
@@ -162,8 +174,8 @@ module Samagotchi
     # Maps of named entries and the keys an entry may hold
     # (ConfigFile.hosts_config, ConfigFile.model_settings).
     MAP_ENTRY_KEYS = {
-      "hosts" => %w[host port url transport api api_key_env profile first_token_timeout vision sampling enabled].freeze,
-      "models" => %w[profile vision sampling].freeze
+      "hosts" => %w[host port url transport api api_key_env profile first_token_timeout vision sampling thinking enabled].freeze,
+      "models" => %w[profile vision sampling thinking].freeze
     }.freeze
     # Section keys beyond the registry's: guardrails' YAML rules (Engine#guardrail_rules).
     SECTION_EXTRA_KEYS = { "guardrails" => %w[rules disable].freeze }.freeze
@@ -172,13 +184,15 @@ module Samagotchi
 
     # Fast lookup maps
     BY_KEY = ENTRIES.each_with_object({}) { |e, h| h[e.key] = e }.freeze
-    BY_ENV = ENTRIES.each_with_object({}) do |e, h|
-      h[e.env_key] = e
-      Array(e.aliases).each { |a| h[a] = e }
-    end.freeze
-    BY_CLI = ENTRIES.each_with_object({}) { |e, h| h[e.cli_flag] = e if e.cli_exposed? }.freeze
+    BY_ENV = ENTRIES.each_with_object({}) { |e, h| h[e.env_key] = e }.freeze
 
     class << self
+      # The +candidates+ within edit distance 2 of +probe+, closest first
+      # (the "did you mean" of an unknown key or host).
+      def near_names(probe, candidates)
+        candidates.uniq.map { |c| [levenshtein(probe, c), c] }.select { |d, _| d <= 2 }.sort.map(&:last)
+      end
+
       def find_by_key(key)
         BY_KEY[key.to_s]
       end
@@ -187,10 +201,6 @@ module Samagotchi
         BY_ENV[env_key.to_s]
       end
 
-      def find_by_cli(flag)
-        BY_CLI[flag.to_s]
-      end
-
       def all_entries
         ENTRIES
       end
@@ -321,10 +331,10 @@ module Samagotchi
       def lookup_legacy(data, entry)
         return nil unless entry && data.is_a?(Hash)
 
-        [entry.env_key, *Array(entry.aliases)].each do |key|
-          return data[key] if data.key?(key)
-          return data[key.to_sym] if data.key?(key.to_sym)
-        end
+        key = entry.env_key
+        return data[key] if data.key?(key)
+        return data[key.to_sym] if data.key?(key.to_sym)
+
         nil
       end
 
@@ -392,6 +402,16 @@ module Samagotchi
         get_with_origin(key).first
       end
 
+      # A timeout setting (server.open_timeout, server.read_timeout) in
+      # seconds, +given+ (a caller's own value) first; one that isn't
+      # positive (0, a word) is the key's default, on every kind of host.
+      def positive_seconds(key, given = nil)
+        value = (given.nil? ? get(key) : given).to_i
+        value.positive? ? value : find_by_key(key).default
+      rescue StandardError
+        find_by_key(key)&.default
+      end
+
       # [value, origin] for the live value #get returns; origin is one of
       # :cli, :env, :file, :default.
       def get_with_origin(key)
@@ -485,7 +505,7 @@ module Samagotchi
       # share its last segment, at most three.
       def unknown_key_message(key, probe, candidates, prefix: "")
         candidates = candidates.uniq
-        near = candidates.map { |c| [levenshtein(probe, c), c] }.select { |d, _| d <= 2 }.sort.map(&:last)
+        near = near_names(probe, candidates)
         close = (near + candidates.select { |c| c.split(".").last == probe.split(".").last }).uniq.first(3)
         hint = close.empty? ? "" : " (did you mean #{close.map { |c| "'#{prefix}#{c}'" }.join(' or ')}?)"
         "config: unknown key '#{key}'#{hint}"
@@ -652,10 +672,11 @@ module Samagotchi
       # avoid polluting ENV with defaults.
       Samagotchi::Config.all_entries.each do |entry|
         next unless entry.env_exposed?
+        # The env's thinking.level outranks models:/hosts: levels, the file's doesn't (Thinking.resolve).
+        next if entry.key == "thinking.level"
         # check if file actually contained this key (including legacy flat)
         file_val = Samagotchi::Config.lookup_yaml(raw, entry.yaml_path)
         file_val ||= raw[entry.env_key] if raw.key?(entry.env_key)
-        Array(entry.aliases).each { |a| file_val ||= raw[a] if raw.key?(a) }
         next if file_val.nil?
         val = Samagotchi::Config.store[entry.key]
         next if val.nil?
@@ -726,6 +747,7 @@ module Samagotchi
           first_token_timeout = raw_cfg.key?("first_token_timeout") ? raw_cfg["first_token_timeout"] : raw_cfg[:first_token_timeout]
           vision = ConfigFile.vision_flag(raw_cfg.key?("vision") ? raw_cfg["vision"] : raw_cfg[:vision], "hosts entry '#{name}'")
           sampling = ConfigFile.sampling_map(raw_cfg.key?("sampling") ? raw_cfg["sampling"] : raw_cfg[:sampling], "hosts entry '#{name}'")
+          thinking = Thinking.level(raw_cfg.key?("thinking") ? raw_cfg["thinking"] : raw_cfg[:thinking], "hosts entry '#{name}'")
           unless first_token_timeout.nil? || (first_token_timeout.is_a?(Numeric) && !first_token_timeout.negative?)
             warn_once "Warning: hosts entry '#{name}': first_token_timeout must be seconds (0 = off); using the default"
             first_token_timeout = nil
@@ -789,7 +811,7 @@ module Samagotchi
                                   api: api_val&.to_sym, original_name: name, scheme: scheme,
                                   url: url.empty? ? nil : url, api_key_env: api_key_env.empty? ? nil : api_key_env,
                                   profile: profile.empty? ? nil : profile, first_token_timeout: first_token_timeout,
-                                  vision: vision, sampling: sampling }
+                                  vision: vision, sampling: sampling, thinking: thinking }
         end
       end
 
@@ -880,6 +902,26 @@ module Samagotchi
       [nil, value]
     end
 
+    # Hosted providers' names, which no local model family uses: as a
+    # prefix they always mean a host ("openai:gpt-4o"). "mistral" and
+    # "deepseek" are left out: Ollama has mistral:7b and deepseek-* tags.
+    PROVIDER_HOST_NAMES = %w[openrouter openai anthropic google gemini groq xai together fireworks].freeze
+
+    # The host a model ref names when that host isn't configured, or nil.
+    # A ':' in a model id is often a tag (qwen3:8b, org/model:Q4_K_M), so
+    # the prefix counts as a host only when it could be a host name and
+    # either the rest looks like a hosted provider's org/model id
+    # ("nosuch:anthropic/claude-sonnet-4"; Ollama-style tags never hold a
+    # '/') or the prefix is a provider's name (PROVIDER_HOST_NAMES).
+    def unknown_host_prefix(raw, hosts:)
+      prefix, rest = raw.to_s.strip.split(":", 2)
+      return nil if rest.to_s.strip.empty? || !prefix.match?(HOST_NAME_RE)
+      return nil unless rest.include?("/") || PROVIDER_HOST_NAMES.include?(prefix.downcase)
+
+      prefix = prefix.downcase
+      hosts.keys.map { |k| k.to_s.downcase }.include?(prefix) ? nil : prefix
+    end
+
     def hosts_json_for_env(env: ENV, path: global_path(env: env))
       hosts = hosts_config(env: env, path: path)
       # Only serialize if non-default or explicitly configured hosts:
@@ -892,7 +934,7 @@ module Samagotchi
         location = v[:url] ? { "url" => v[:url] } : { "host" => v[:host], "port" => v[:port] }
         location.merge("transport" => v[:transport]&.to_s, "api" => v[:api]&.to_s, "api_key_env" => v[:api_key_env],
                        "profile" => v[:profile], "first_token_timeout" => v[:first_token_timeout],
-                       "vision" => v[:vision], "sampling" => v[:sampling]).compact
+                       "vision" => v[:vision], "sampling" => v[:sampling], "thinking" => v[:thinking]&.to_s).compact
       end
       JSON.generate(simple)
     rescue StandardError
@@ -976,6 +1018,8 @@ module Samagotchi
         result[key][:vision] = vision unless vision.nil?
         sampling = sampling_map(v.key?("sampling") ? v["sampling"] : v[:sampling], "models: #{key}")
         result[key][:sampling] = sampling if sampling
+        thinking = Thinking.level(v.key?("thinking") ? v["thinking"] : v[:thinking], "models: #{key}")
+        result[key][:thinking] = thinking if thinking
       end
     rescue StandardError
       {}

data/lib/samagotchi/desktop/macos/App.swift

@@ -1,5 +1,6 @@
-// Chi Helper: the "Send to chi" Service opens the panel with the selection,
-// the hotkey with the clipboard. No Dock icon (LSUIElement); it stays
+// Chi Helper: the "Send to chi" Service opens the panel with the selection
+// (text, or images: files in Finder, a picture in Preview), the hotkey with
+// the clipboard (a screenshot too). No Dock icon (LSUIElement); it stays
 // running after the first launch. `ChiHelper --login on|off|status` (run
 // directly by chi desktop) manages the login item and exits.
 import AppKit
@@ -10,11 +11,12 @@ final class ServiceProvider: NSObject {
 
   // Info.plist NSServices: NSMessage = sendToChi.
   @objc func sendToChi(_ pboard: NSPasteboard, userData: String?, error: AutoreleasingUnsafeMutablePointer<NSString>) {
-    guard let text = pboard.string(forType: .string) else {
-      error.pointee = "No text in the selection" as NSString
+    let (text, images) = ImageIntake.read(pboard)
+    guard !text.isEmpty || !images.isEmpty else {
+      error.pointee = "No text or image in the selection" as NSString
       return
     }
-    app?.open(text: text)
+    app?.open(text: text, images: images)
   }
 }
 
@@ -28,6 +30,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
 
   func applicationDidFinishLaunching(_ notification: Notification) {
     provider.app = self
+    ImageIntake.sweep()
     NSApp.servicesProvider = provider
     NSUpdateDynamicServices()
     hotkey = Hotkey { [weak self] in self?.openFromClipboard() }
@@ -54,12 +57,13 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
 
   /// The hotkey doesn't activate us, so the frontmost app is the source.
   func openFromClipboard() {
-    open(text: NSPasteboard.general.string(forType: .string) ?? "")
+    let (text, images) = ImageIntake.read(NSPasteboard.general)
+    open(text: text, images: images)
   }
 
-  func open(text: String) {
+  func open(text: String, images: [PanelImage] = []) {
     let from = sourceApp
-    panel.show(text: text, source: from?.localizedName?.lowercased() ?? "desktop", returnTo: from)
+    panel.show(text: text, images: images, source: from?.localizedName?.lowercased() ?? "desktop", returnTo: from)
   }
 }
 

data/lib/samagotchi/desktop/macos/ChiRunner.swift

@@ -106,7 +106,9 @@ final class ChiRunner {
   /// Runs `chi <args>`, with stdin written from a background queue and
   /// stdout/stderr drained as they come (no pipe deadlock near the 16 KiB
   /// note cap). Calls back on the main queue.
-  func run(_ args: [String], stdin: Data? = nil, completion: @escaping (Result<ChiResult, ChiError>) -> Void) {
+  /// @param timeout this call's limit instead of the runner's
+  func run(_ args: [String], stdin: Data? = nil, timeout: TimeInterval? = nil,
+           completion: @escaping (Result<ChiResult, ChiError>) -> Void) {
     let config: LaunchConfig
     do { config = try loadLaunch() } catch let error as ChiError {
       completion(.failure(error)); return
@@ -161,7 +163,7 @@ final class ChiRunner {
         try? input.fileHandleForWriting.close()
       }
     }
-    DispatchQueue.global().asyncAfter(deadline: .now() + timeout) {
+    DispatchQueue.global().asyncAfter(deadline: .now() + (timeout ?? self.timeout)) {
       if process.isRunning {
         lock.lock(); timedOut = true; lock.unlock()
         process.terminate()

data/lib/samagotchi/desktop/macos/Images.swift

@@ -0,0 +1,113 @@
+// Images for the panel: what a pasteboard (the clipboard, the Service's,
+// a drop) carries, as files `chi send --image` can read. Image files are
+// passed as they are; image data (a ⌃⇧⌘4 screenshot, Preview, Safari's
+// Copy Image) is written to a temp file first, deleted after the send.
+import AppKit
+import UniformTypeIdentifiers
+
+/// The Bridge's cap on one turn's images.
+let maxImages = 20
+
+struct PanelImage: Identifiable, Equatable {
+  let id = UUID()
+  let url: URL
+  /// Written by the helper (image data), so the helper deletes it.
+  let temp: Bool
+  let thumbnail: NSImage?
+
+  var name: String { url.lastPathComponent }
+
+  init(url: URL, temp: Bool) {
+    self.url = url
+    self.temp = temp
+    thumbnail = NSImage(contentsOf: url)
+  }
+
+  static func == (a: PanelImage, b: PanelImage) -> Bool { a.id == b.id }
+}
+
+enum ImageIntake {
+  static let tempDir = URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent("chi-helper", isDirectory: true)
+
+  /// A pasteboard's content for the panel, in this order: image files
+  /// (Finder ⌘C, a Service on files) with no text; else its text, as before
+  /// (an office app's copy carries a picture of the cells too: the text
+  /// wins); else image data (png, then tiff). A non-image file is skipped.
+  static func read(_ pb: NSPasteboard) -> (text: String, images: [PanelImage]) {
+    let files = imageFiles(pb)
+    if !files.isEmpty { return ("", files) }
+    if let text = pb.string(forType: .string), !text.isEmpty { return (text, []) }
+    return ("", imageData(pb))
+  }
+
+  /// A drop adds images only: text dropped on the fields is theirs.
+  static func dropped(_ pb: NSPasteboard) -> [PanelImage] {
+    let files = imageFiles(pb)
+    return files.isEmpty ? imageData(pb) : files
+  }
+
+  static func imageFiles(_ pb: NSPasteboard) -> [PanelImage] {
+    let urls = pb.readObjects(forClasses: [NSURL.self], options: [.urlReadingFileURLsOnly: true]) as? [URL] ?? []
+    return urls.filter(isImage).prefix(maxImages).map { PanelImage(url: $0, temp: false) }
+  }
+
+  static func isImage(_ url: URL) -> Bool {
+    (try? url.resourceValues(forKeys: [.contentTypeKey]))?.contentType?.conforms(to: .image) == true
+  }
+
+  static func imageData(_ pb: NSPasteboard) -> [PanelImage] {
+    for (type, ext) in [(NSPasteboard.PasteboardType.png, "png"), (.tiff, "tiff")] {
+      guard let data = pb.data(forType: type) else { continue }
+      // A folder per image, so the name chi shows is "clipboard.png".
+      let dir = tempDir.appendingPathComponent(UUID().uuidString, isDirectory: true)
+      do {
+        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        let url = dir.appendingPathComponent("clipboard.\(ext)")
+        try data.write(to: url)
+        return [PanelImage(url: url, temp: true)]
+      } catch {
+        return []
+      }
+    }
+    return []
+  }
+
+  static func delete(_ images: [PanelImage]) {
+    for image in images where image.temp {
+      try? FileManager.default.removeItem(at: image.url.deletingLastPathComponent())
+    }
+  }
+
+  /// At launch: what a helper that quit mid-send left.
+  static func sweep() {
+    try? FileManager.default.removeItem(at: tempDir)
+  }
+}
+
+/// The panel's background, taking dropped images anywhere on the panel.
+final class DropEffectView: NSVisualEffectView {
+  var onDrop: (([PanelImage]) -> Void)?
+
+  override init(frame: NSRect) {
+    super.init(frame: frame)
+    registerForDraggedTypes([.fileURL, .png, .tiff])
+  }
+
+  required init?(coder: NSCoder) { fatalError("init(coder:) is not used") }
+
+  override func draggingEntered(_ sender: NSDraggingInfo) -> NSDragOperation {
+    carriesImages(sender.draggingPasteboard) ? .copy : []
+  }
+
+  override func performDragOperation(_ sender: NSDraggingInfo) -> Bool {
+    let images = ImageIntake.dropped(sender.draggingPasteboard)
+    guard !images.isEmpty else { return false }
+    onDrop?(images)
+    return true
+  }
+
+  private func carriesImages(_ pb: NSPasteboard) -> Bool {
+    let urls = pb.readObjects(forClasses: [NSURL.self], options: [.urlReadingFileURLsOnly: true]) as? [URL] ?? []
+    return urls.contains(where: ImageIntake.isImage) || pb.availableType(from: [.png, .tiff]) != nil
+  }
+}

data/lib/samagotchi/desktop/macos/Info.plist.erb

@@ -33,6 +33,12 @@
       <key>NSSendTypes</key>
       <array>
         <string>public.utf8-plain-text</string>
+        <string>public.png</string>
+        <string>public.tiff</string>
+      </array>
+      <key>NSSendFileTypes</key>
+      <array>
+        <string>public.image</string>
       </array>
       <key>NSRequiredContext</key>
       <dict/>