samagotchi 0.63.0 → 0.64.0

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

@@ -57,7 +57,7 @@ Only the nested form is read. An env name used as a top-level key (`SAMAGOTCHI_D
 **Excluded maps** (YAML-only, not part of the flat registry; skipped by scalar loader):
 
 - `model_aliases:` map of alias → model id (`ModelRef.parse`, through `HostRegistry#resolve`). Keys lowercased on write (`ConfigFile.write_model_alias!`). Values may be bare `model` or qualified `host:model` (hybrid; only `:` names a host, `org/model` is an id). Aliases apply once: never point an alias at another alias.
-- `hosts:` map of `name → {host, port | url, transport, api, api_key_env, profile, first_token_timeout, vision, sampling, thinking, enabled, models}` (`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; `models:` (a map of model ids, or a plain list) declares ids the host serves whatever its `/v1/models` lists: no "doesn't list" warning, and a bare id routes there as if listed (`HostModel`); an entry may hold `price: {input, output, cache_read?, cache_write?}` in USD per 1M tokens (`ModelPrice`; an unset cache rate is the input rate), which estimates a cost the provider doesn't report or reports as 0 (`cost_estimate`, shown as `~$`), and `served: [ids] | any`, the models a gateway may answer that id with (no served-model warning for them); model settings stay in the root `models:`; workers inherit via `SAMAGOTCHI_HOSTS_JSON` (`hosts_json_for_env`, `session_manager.rb`).
+- `hosts:` map of `name → {host, port | url, transport, api, api_key_env, profile, first_token_timeout, vision, sampling, thinking, enabled, models}` (`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; `models:` (a map of model ids, or a plain list) declares ids the host serves whatever its `/v1/models` lists: no "doesn't list" warning, and a bare id routes there as if listed (`HostModel`); an entry may hold `price: {input, output, cache_read?, cache_write?}` in USD per 1M tokens (`ModelPrice`; an unset cache rate is the input rate), which estimates a cost the provider doesn't report or reports as 0 (`cost_estimate`, shown as `~$`), and `served: [ids] | any`, the models a gateway may answer that id with (no served-model warning for them); model settings stay in the root `models:`; a worker reads `hosts:` from the file as it starts (`SAMAGOTCHI_HOSTS_JSON` replaces it for a process it is set on; `SessionManager.spawn_options` unsets it for workers).
 - `models:` map of model id or alias → `{profile, vision, sampling, thinking, reasoning_history}` (`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: the session's own level (`/thinking LEVEL`, saved in the session; `chi --thinking` on a session run, `chi send --new --thinking`) > `chi web --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". `reasoning_history:` (here or on a host) is `drop|turn|all`, which of its reasoning a chat host's model gets back. Precedence: the session's own level (`/reasoning-history LEVEL`, saved in the session) > `SAMAGOTCHI_REASONING_HISTORY` > `models:` > `hosts.<name>.reasoning_history` > `turn`; `docs/configuration.md` "Reasoning history". `/thinking` and `/reasoning-history` ask before a change that restarts the prompt cache; `--yes` applies it (`chi send` commands apply directly). `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; config.yml only, like every `guardrails` setting: no env variable), `parent_approvals` (`off`, the default: a parent agent's `chi answer` can only deny an approval; `once`: it may give "Allow once" too; a convention for an honest parent, not a security boundary, and the user's choice: set it only when the user asks), `rules:` (list), `disable:` (a rule id or a list of them, `id` or `bundle:id`, switching off a bundle's or config rule without editing it), `small_models` (`auto`, the default: small = 32B or less read from the name; a glob or list of globs; `[]` for none). A rule takes only `id`, `tool`, `command`, `path`, `git`, `models`, `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`: outside the session's repo, tmp folders and memory files excepted), `git` (only `outside_repo`: a shell call runs commit/add/reset/… in another checkout); `models` (optional: `small`, a model-name glob, or a list; without it the rule is for every model); `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 are read again on the next tool call after config.yml or a bundle's rules change: no restart needed. Installed bundles' rule files (`chi bundle install guardrails`) add to them; `/guardrails` lists what loaded.

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.63.0
+version: 0.64.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
   self_map.md: sha256:dfc19266259a9af1e0d769b7e0f67996b740b0c9921fdf3dadad973f6e5c144a
-  config_modification_protocol.md: sha256:16403da5dd97a335e19d9d15bb1ba4390237bf9f4869e35d63c172a8828b5ae0
+  config_modification_protocol.md: sha256:99ad8a596cc0f5129caf82cc00314d597f0ec309be96e2d48ca4fa936b4ae343
   memory_guide.md: sha256:b0a1ba42c5334d4117b5733c8c26d7477364baca9169b0c0a711de6ac7fc7f3c
   delegated.md: sha256:aedaa1e756a244904c5560fff0424e06fb468bbdcb0358bccefe321d67cd2614

data/lib/samagotchi/child_reports.rb

@@ -231,11 +231,16 @@ module Samagotchi
       return nil unless child.parent_id == @session_id
 
       before = @taken[child_id]&.after || Tools::DelegateCursors.get(@session_id, child_id, state_dir: @state_dir)
+      # A follow-up's turn (DelegateCursor#turn) is reported by its own
+      # reply, as delegate_result takes it, not a newer queued turn's.
       wait = ReplyWait.call(child_id, state_dir: @state_dir, cursor: before.reply_file, baseline: before.baseline,
-                                      timeout: 0)
+                                      timeout: 0, turn: before.turn)
       return nil unless reportable?(wait)
 
-      after = before.with(reply_file: wait.status == :done ? wait.file : before.reply_file)
+      # A reported end is the follow-up turn's too (DelegateCursor#turn):
+      # a later wait on it would repeat its reply.
+      after = before.with(reply_file: wait.status == :done ? wait.file : before.reply_file,
+                          turn: wait.status == :waiting_for_answer ? before.turn : nil)
                     .with_baseline(ReplyWait.baseline_of(wait.session))
       text = Tools::DelegateWait.finish(wait, child_id, timeout: 0, report: true)
       Report.new(child_id: child_id, text: text, before: before, after: after, rings: rings)

data/lib/samagotchi/cli/parent_wait.rb

@@ -57,10 +57,17 @@ module Samagotchi
       # report it. Ctrl-C leaves the turn running (130).
       # @param owner_grace [Numeric, nil] seconds with no live worker before
       #   it counts as gone; nil waits for whatever wakes one
+      # @param turn [String, nil] the enqueued_id of the turn waited for
+      #   (ReplyWait's turn:): a queued message's, or the turn an answer or
+      #   a --wait with no message is about (ReplyWait.own_turn)
+      # @param queued [Boolean] +turn+ is a queued message's (ReplyWait's
+      #   queued:)
       # @return [Integer] the exit status
-      def wait_for_reply(id, cursor:, baseline:, timeout:, owner_grace: self.class::WORKER_GONE_AFTER)
+      def wait_for_reply(id, cursor:, baseline:, timeout:, owner_grace: self.class::WORKER_GONE_AFTER, turn: nil,
+                         queued: false)
         result = ReplyWait.call(id, state_dir: @state_dir, cursor: cursor, timeout: timeout, baseline: baseline,
-                                    owner_grace: owner_grace, poll_interval: self.class::POLL_INTERVAL)
+                                    owner_grace: owner_grace, poll_interval: self.class::POLL_INTERVAL, turn: turn,
+                                    queued: queued)
         result.text = result.text&.dup&.force_encoding(Encoding::UTF_8)&.scrub
         @reported = true
         ParentReport.report(result, session_id: id, stdout: @stdout, stderr: @stderr, command: command_name,

data/lib/samagotchi/composer_route.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "delivery"
+
+module Samagotchi
+  # Where a line typed at a terminal's prompt goes, for both terminals (the
+  # REPL's TerminalUI#steer_line / #run_input_line, the attached
+  # AttachedLoop#submit). It only classifies; each UI keeps what it does
+  # with the answer (the REPL's mid-turn command policy and image lines, the
+  # attached TUI's continue offer and question). The web's composer.js
+  # routeComposerLine decides the same; spec/fixtures/composer_routes.json
+  # holds the cases both answer (docs/testing.md).
+  #
+  # In order:
+  #   1. /cut TEXT, /queue TEXT (.steer_choice), before every command check:
+  #      the bare word is :usage. While a turn runs TEXT is a :deliver with
+  #      its delivery (Delivery::CUT, Delivery::QUEUE); whether the worker
+  #      can queue is the UI's to check. With none running TEXT is routed
+  #      on as a line (step 2), its own /cut not read again.
+  #   2. A line: :empty; a terminal's own word (:local, the registry's
+  #      lookup_local id: :exit, :archive, :detach, :stats, :recap…); a
+  #      session command (:command); a typo of one (:typo, the hint in
+  #      +reply+); else :prompt. A line with images (+images+) is a message:
+  #      no command or typo check.
+  module ComposerRoute
+    CUT_COMMAND = "/cut"
+    QUEUE_COMMAND = "/queue"
+    # The word, then any whitespace and the text (as the registry's
+    # entries match them, so a line Tab or /help knows is never a prompt).
+    STEER_CHOICE = /\A(#{CUT_COMMAND}|#{QUEUE_COMMAND})(?:\s+(.*))?\z/m
+
+    KINDS = %i[empty usage deliver local command typo prompt].freeze
+
+    # @!attribute kind [Symbol] one of KINDS
+    # @!attribute text [String, nil] the line stripped: a /cut's or
+    #   /queue's own text, not the word
+    # @!attribute delivery [String, nil] a :deliver's Delivery value
+    # @!attribute reply [String, nil] a :typo's hint
+    # @!attribute local [Symbol, nil] a :local's registry id
+    # @!attribute choice [Symbol, nil] :cut or :queue when the line was
+    #   typed with that word (an idle one's text routed on keeps it)
+    Route = Data.define(:kind, :text, :delivery, :reply, :local, :choice) do
+      def initialize(kind:, text: nil, delivery: nil, reply: nil, local: nil, choice: nil)
+        super
+      end
+    end
+
+    # @param line [String, nil] as typed
+    # @param running [Boolean] a turn runs
+    # @param registry [Commands::Registry] the session's commands
+    # @param images [Integer] the attachments not in the text (the web's
+    #   chips); a terminal's @path images are its own to handle (0)
+    # @return [Route]
+    def self.call(line, running:, registry:, images: 0)
+      text = line.to_s.strip
+      choice, message = steer_choice(text)
+      return line_route(text, registry: registry, images: images) unless choice
+      return Route.new(kind: :usage, choice: choice) if message.empty?
+      return line_route(message, registry: registry, images: images).with(choice: choice) unless running
+
+      Route.new(kind: :deliver, text: message, delivery: choice == :cut ? Delivery::CUT : Delivery::QUEUE, choice: choice)
+    end
+
+    # The choice a line carries, as [:cut, "TEXT"] or [:queue, "TEXT"]; nil
+    # for any other line. The text is "" when the line named the choice
+    # without one.
+    # @param line [String, nil]
+    # @return [Array(Symbol, String), nil]
+    def self.steer_choice(line)
+      match = STEER_CHOICE.match(line.to_s.strip) or return nil
+
+      [match[1] == CUT_COMMAND ? :cut : :queue, match[2].to_s.strip]
+    end
+
+    def self.line_route(text, registry:, images:)
+      return Route.new(kind: :empty, text: text) if text.empty?
+
+      if images.zero?
+        local = registry.lookup_local(text)&.id
+        return Route.new(kind: :local, text: text, local: local) if local
+        return Route.new(kind: :command, text: text) if registry.command?(text)
+
+        hint = registry.unknown_command_hint(text)
+        return Route.new(kind: :typo, text: text, reply: hint) if hint
+      end
+      Route.new(kind: :prompt, text: text)
+    end
+    private_class_method :line_route
+  end
+end

data/lib/samagotchi/config.rb

@@ -857,7 +857,7 @@ module Samagotchi
     HOST_NAME_RE = /\A[a-z0-9][a-z0-9._-]*\z/i
     ENV_NAME_RE = /\A[A-Za-z_][A-Za-z0-9_]*\z/
 
-    # config.yml's hosts: (or a worker's SAMAGOTCHI_HOSTS_JSON) by lowercased
+    # config.yml's hosts: (or a SAMAGOTCHI_HOSTS_JSON override) by lowercased
     # name; an entry that is disabled or invalid (warned) is left out. No
     # entry left: "default", from server.host/port/transport.
     # @return [Hash{String => HostConfig}]
@@ -914,7 +914,7 @@ module Samagotchi
 
     # The names (lowercased) of the hosts entries with enabled: false, which
     # hosts_config leaves out. Read from the same source: config.yml's
-    # hosts:, or SAMAGOTCHI_HOSTS_JSON in a worker.
+    # hosts:, or a SAMAGOTCHI_HOSTS_JSON override.
     # @return [Array<String>]
     def disabled_host_names(env: ENV, path: global_path(env: env))
       raw = hosts_source(read_yaml(env: env, path: path), env)
@@ -926,7 +926,8 @@ module Samagotchi
     end
 
     # config.yml's hosts: as written, or the SAMAGOTCHI_HOSTS_JSON override
-    # a worker inherits from its parent.
+    # set on this process (specs; SessionManager.spawn_options unsets it for
+    # a worker, which reads the file).
     def hosts_source(data, env)
       raw = data[HOSTS_KEY] if data.is_a?(Hash)
       env_json = env["SAMAGOTCHI_HOSTS_JSON"].to_s.strip
@@ -1041,6 +1042,8 @@ module Samagotchi
       hosts.keys.map { |k| k.to_s.downcase }.include?(prefix) ? nil : prefix
     end
 
+    # hosts_config as a SAMAGOTCHI_HOSTS_JSON override (workers no longer
+    # get one: they read config.yml).
     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:

data/lib/samagotchi/continue_offer.rb

@@ -85,12 +85,17 @@ module Samagotchi
     # Called with the event log held, before the command's command_ran. A
     # Stop runs no turn: last_turn says so (not_continued), so a wait on
     # it ends (chi answer --option Stop).
+    # It carries the offer turn's enqueued_id, so a wait on that turn
+    # (ReplyWait's turn:) ends on it too.
     def announce_resolved(result, command)
       @engine.announce(type: :continue_resolved, decision: result.decision.to_s, client_id: command.client_id)
       return if result.resume
 
       session = @engine.session
-      session.last_turn = LastTurn.new(outcome: NOT_CONTINUED, ended_at: Time.now.iso8601(3)) if session
+      return unless session
+
+      session.last_turn = LastTurn.new(outcome: NOT_CONTINUED, ended_at: Time.now.iso8601(3),
+                                       enqueued_id: offer_turn_id)
     end
 
     # After a command's command_ran and save: a /continue that answered the
@@ -117,9 +122,13 @@ module Samagotchi
     # asks again, one before the turn began too (logged, no :turn_failed).
     # The answer's text is carried into the turn as it begins; a turn that
     # never began leaves it to no other.
+    # The continue turn is the offer turn's: its origin carries that turn's
+    # enqueued_id, so its last_turn, its reply file and its checkpoint mark
+    # do too, and a wait on that turn (chi answer) gets its reply.
     def run_continue_turn(command)
       offer = @turn_flow.offer
       resume_from = @turn_flow.resume_from
+      enqueued_id = offer_turn_id
       close("answered")
       steer = @continue_steer
       @continue_steer = nil
@@ -131,8 +140,8 @@ module Samagotchi
           Log.warn(:worker, "turn_not_begun", continue: true, error: e.class.name, msg: e.message)
           return announce_offer(offer)
         end
-        @run_turn.call(nil, continue: true, origin: { client_id: command.client_id }.compact, resumed: true,
-                            resume_from: resume_from,
+        origin = { client_id: command.client_id, enqueued_id: enqueued_id }.compact
+        @run_turn.call(nil, continue: true, origin: origin, resumed: true, resume_from: resume_from,
                             max_iterations: @max_iterations.call(offer[:no_interrupt])) do |result, error|
           if error
             announce_offer(offer)
@@ -156,6 +165,11 @@ module Samagotchi
 
     private
 
+    # The enqueued_id of the turn the offer stands for: the exhausted
+    # turn's last_turn (a canceled continue turn's carries the same id);
+    # nil when it ran no input (a reminder turn, a delegate's first).
+    def offer_turn_id = @engine.session&.last_turn&.enqueued_id
+
     def announce_offer(offer = @turn_flow.offer)
       @engine.announce(type: :continue_offered, context: offer[:context], no_interrupt: offer[:no_interrupt])
       ask

data/lib/samagotchi/delivery.rb

@@ -23,25 +23,30 @@ module Samagotchi
     # Why a request body's delivery field can't be taken, as {error:,
     # detail:} for a 400, or nil when it can. The Bridge and the web's
     # POST /turn both ask this, so they refuse the same values. A missing
-    # or unknown string is not refused: it is the default (#parse). QUEUE
-    # is refused until a worker runs it (no worker reads it yet, so it
-    # would merge at the next step while the ack said queue).
+    # or unknown string is not refused: it is the default (#parse).
     # @param raw [Object] the wire value
     # @return [Hash, nil]
     def self.refusal(raw)
       return nil if raw.nil?
       return { error: "bad_delivery", detail: "delivery must be a string" } unless raw.is_a?(String)
-      return QUEUE_UNAVAILABLE if raw == QUEUE
 
       nil
     end
 
+    # The worker sidecar feature (Bridge::FEATURES) of a worker that runs
+    # all three values. One without it (before 0.64) ignores QUEUE, or
+    # refuses it with a 400 delivery_unavailable, so a sender checks it
+    # before sending a queue (SessionManager.deliver_turn, the attached TUI).
+    QUEUE_FEATURE = "delivery"
+
+    # The refusal for a queue a worker without QUEUE_FEATURE would steer
+    # (SessionManager.deliver_turn answers it as a 409). P0-P2 workers
+    # answer the same error code for a queue, with their own detail.
     QUEUE_UNAVAILABLE = {
-      error: "delivery_unavailable",
-      detail: "delivery queue isn't available yet; without it the message goes in at the running turn's next step " \
-              "(or runs as a turn when none runs)"
+      "error" => "delivery_unavailable",
+      "detail" => "this session's worker predates queueing, so the message would steer the running turn; " \
+                  "restart it (chi sessions restart ID, or the web's update badge) and send again"
     }.freeze
-    private_constant :QUEUE_UNAVAILABLE
 
     # Whether it is the one every sender defaulting to a step boundary uses.
     def self.next_step?(value) = parse(value) == NEXT_STEP

data/lib/samagotchi/engine.rb

@@ -1433,8 +1433,10 @@ module Samagotchi
                elsif client_id == ClientId::REMINDER then "reminder"
                else "client"
                end
+      enqueued_id = origin.is_a?(Hash) ? origin[:enqueued_id] : nil
       session.last_turn = LastTurn.new(outcome: outcome, ended_at: Time.now.iso8601(3), seconds: seconds.round(1),
                                        origin: source, exhausted: limit ? true : nil, limit: limit,
+                                       enqueued_id: enqueued_id.to_s.empty? ? nil : enqueued_id.to_s,
                                        **stop_facts(event))
     end
 

data/lib/samagotchi/host_config.rb

@@ -9,9 +9,9 @@ require_relative "reasoning_history"
 module Samagotchi
   # One config.yml hosts: entry, parsed and checked (ConfigFile.hosts_config
   # holds them by lowercased name; HostRegistry builds its HostEntry from
-  # one). A worker gets its parent's hosts back through
-  # SAMAGOTCHI_HOSTS_JSON: #to_env_h writes every field, and .parse reads
-  # it back to an equal HostConfig.
+  # one). #to_env_h writes every field in the shape of the
+  # SAMAGOTCHI_HOSTS_JSON override (ConfigFile.hosts_json_for_env), and
+  # .parse reads it back to an equal HostConfig.
   #
   # name: the lowercased entry name; host, port, scheme: where it is (from
   # url: when given); url: the configured url, nil when host/port; transport,
@@ -26,7 +26,7 @@ module Samagotchi
       super(**members.to_h { |m| [m, nil] }, models: {}, **fields)
     end
 
-    # A hosts: entry as written (YAML, or a worker's SAMAGOTCHI_HOSTS_JSON),
+    # A hosts: entry as written (YAML, or a SAMAGOTCHI_HOSTS_JSON override),
     # or nil when it is disabled (enabled: false) or invalid. An invalid
     # one warns once, naming the entry, the way each reader of a setting
     # does for a bad value (that value is then unset).
@@ -160,10 +160,10 @@ module Samagotchi
     end
     private_class_method :invalid
 
-    # The entry as a worker's SAMAGOTCHI_HOSTS_JSON carries it (string keys,
+    # The entry as a SAMAGOTCHI_HOSTS_JSON override carries it (string keys,
     # unset fields left out); .parse(name, to_env_h) gives it back. A url
     # entry travels as its url (host/port come from it); the API key stays
-    # in the environment, which workers inherit.
+    # in the environment.
     # @return [Hash{String => Object}]
     def to_env_h
       location = url ? { "url" => url } : { "host" => host, "port" => port }

data/lib/samagotchi/host_model.rb

@@ -104,8 +104,8 @@ module Samagotchi
       end
     end
 
-    # The entry as written back to config (SAMAGOTCHI_HOSTS_JSON for
-    # workers): nil for a bare id.
+    # The entry as written back to config (HostConfig#to_env_h): nil for a
+    # bare id.
     def to_config
       config = { "price" => price&.to_config, "served" => served }.compact
       config unless config.empty?

data/lib/samagotchi/interrupted_turn.rb

@@ -9,9 +9,13 @@ module Samagotchi
   #
   # id: the turn's id (nil when unknown); started_at / at: iso8601, when the
   # turn began and when this checkpoint was taken; iteration: the loop
-  # boundaries it had passed (Integer).
-  InterruptedTurn = Data.define(:id, :started_at, :at, :iteration) do
-    def initialize(id: nil, started_at: nil, at: nil, iteration: nil) = super
+  # boundaries it had passed (Integer); enqueued_id: the input the turn
+  # runs (its ack's id, LastTurn#enqueued_id once it ends; a Continue turn
+  # carries its offer turn's), so any process that loads the session can
+  # tell which turn is running (ReplyWait.own_turn); nil when it ran none,
+  # or a worker from before it wrote one.
+  InterruptedTurn = Data.define(:id, :started_at, :at, :iteration, :enqueued_id) do
+    def initialize(id: nil, started_at: nil, at: nil, iteration: nil, enqueued_id: nil) = super
 
     # A saved record (string or symbol keys), an InterruptedTurn as it is;
     # nil for anything else.

data/lib/samagotchi/last_turn.rb

@@ -12,9 +12,12 @@ module Samagotchi
   # children's reports) or "context" (one an attached context source's
   # change started); exhausted/limit: the turn ran out of iterations at
   # limit. The rest are its stop facts (LastTurn::STOP_FACTS), only what is
-  # known. A field may be nil (unset; left out of the file).
+  # known. enqueued_id: the input's id when the turn ran one (a POST /turn
+  # ack's, an input file's), so a wait for a queued message (`chi send
+  # --queue --wait`, ReplyWait's turn:) tells its own turn's end from
+  # another's. A field may be nil (unset; left out of the file).
   LastTurn = Data.define(:outcome, :ended_at, :seconds, :origin, :exhausted, :limit,
-                         :error_kind, :retryable, :kept_steps, :cancel_reason, :stopped_by) do
+                         :error_kind, :retryable, :kept_steps, :cancel_reason, :stopped_by, :enqueued_id) do
     def initialize(**fields)
       super(**members.to_h { |m| [m, nil] }, **fields)
     end

data/lib/samagotchi/pending_input_queue.rb

@@ -19,17 +19,24 @@ module Samagotchi
     end
 
     # Append a message to the queue. Nil/empty strings are ignored.
-    def push(text)
+    # +seq+ is the sender's own order number for it (the REPL numbers every
+    # line it takes during a turn, so its leftovers keep send order across
+    # this queue and its after-turn list: #drain_entries).
+    def push(text, seq: nil)
       text = text.to_s
       return if text.empty?
 
-      @mutex.synchronize { @messages << text }
+      @mutex.synchronize { @messages << [seq, text] }
       nil
     end
 
     # Remove and return all queued messages in FIFO order. Non-blocking.
     # @return [Array<String>]
-    def drain
+    def drain = drain_entries.map(&:last)
+
+    # #drain with each message's +seq+ (nil when pushed without one).
+    # @return [Array(Integer|nil, String)]
+    def drain_entries
       @mutex.synchronize do
         drained = @messages
         @messages = []

data/lib/samagotchi/plugin/sessions.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../client_id"
+require_relative "../delivery"
 require_relative "../session"
 require_relative "../bridge_client"
 require_relative "../bridge/turn_accumulator"
@@ -62,18 +63,28 @@ module Samagotchi
       # Send +text+ to session +id+ as a user message (it runs as a turn;
       # a stopped session is woken). Waits up to 5 s for its worker, so call
       # it from an anytime command or your own thread, never a tool or hook
-      # of a running turn.
+      # of a running turn. A running turn takes it at its next step; with
+      # +delivery: :queue+ it runs as a turn of its own after that one
+      # instead. A plugin never cuts the running turn's thinking.
+      # @param delivery [Symbol, String, nil] nil or :next_step (default),
+      #   :queue
       # @return [String] the id of the session it went to
-      # @raise [Error] no such session, a REPL owns it, or it wasn't taken
-      def send(id, text)
+      # @raise [Error] no such session, a REPL owns it, it wasn't taken
+      #   (a worker older than queueing refuses a queue), or delivery is
+      #   :cut or unknown
+      def send(id, text, delivery: nil)
         raise Error, "nothing to send" if text.to_s.strip.empty?
 
+        wire = plugin_delivery(delivery)
         state_dir = self.state_dir
         sid = resolve(id, state_dir)
-        delivered = SessionManager.deliver_turn(sid, prompt: text.to_s, client_id: ClientId::PLUGIN, state_dir: state_dir)
+        delivered = SessionManager.deliver_turn(sid, prompt: text.to_s, client_id: ClientId::PLUGIN, state_dir: state_dir,
+                                                     delivery: wire)
         case delivered[:status]
         when :accepted then sid
-        when :refused then raise Error, "session #{sid[0, 8]} refused the message (#{delivered.dig(:ack, "error")})"
+        when :refused
+          ack = delivered[:ack] || {}
+          raise Error, "session #{sid[0, 8]} refused the message (#{ack["error"]}#{": #{ack["detail"]}" if ack["detail"]})"
         when :timeout then raise Error, "session #{sid[0, 8]}'s worker did not answer in time; the message was not sent"
         else raise Error, "the message to session #{sid[0, 8]} could not be written"
         end
@@ -81,6 +92,17 @@ module Samagotchi
         raise Error, "session #{sid[0, 8]} is open in a chi REPL, which takes no messages from others"
       end
 
+      # The wire value for send's delivery: (nil for the default).
+      def plugin_delivery(delivery)
+        case delivery&.to_s
+        when nil, "", Delivery::NEXT_STEP then nil
+        when Delivery::QUEUE then Delivery::QUEUE
+        when Delivery::CUT then raise Error, "plugins never cut: send it plain (the next step) or delivery: :queue"
+        else raise Error, "delivery takes :next_step or :queue, not #{delivery.inspect}"
+        end
+      end
+      private :plugin_delivery
+
       # Session +id+ now: from its worker when one runs (with a running turn
       # so far), else as saved.
       # @return [Hash] {id:, title:, status:, parent_id:, running:, messages:}