samagotchi 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9d794c2749a0f1293cb16d7afeb7e023f38dd8798532e4dcb2d0e9fcb575af1
-  data.tar.gz: 8ade3692c344214cc8cdbe90c1fb8539242639f7cbf8707c751a8d2b02f9548a
+  metadata.gz: 9019626f95da411558ec5350303433de58fd07f9db6f9e22323856e4e2ed31a0
+  data.tar.gz: 015df1a469fb64ff5556ce6f683ee23abf039865a34584fff07e3f3c32e4724e
 SHA512:
-  metadata.gz: b3eb054e3b0dd3ded63ef8de4bfff37d8d36971dbe02107ac2e30114fadc12563807d4c7bdc4d3fdf8b801a7bd8250fcb5e73a547604b0feba7382abfdff0ee7
-  data.tar.gz: 168c3cfef2a37c4f5e3f6e2782b614a546f8307793e41af0efe200b2afa8d100b725889e5bb8fcf520fa7c2a0be18faa4cedb10a9ddf573bedac162a1404f133
+  metadata.gz: 1bd652f5d5c2d549dce4eba12cc6577f34cb80ae2a95ea4d63492b4581ed510a5f4eeb8b741f86da7af39198dbfc4981e5d6e7d019dfff7d90f8c0a19722cd6b
+  data.tar.gz: fe6e4cbc412b112d157ad16a1f176fa1308ed094498eb982770b5a6b87859a89c9d544b9c0791d953e0823e51e09396f13e484eccdb240cdd0a0daad8dfe3f8e

data/CHANGELOG.md

@@ -8,6 +8,34 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.22.0] - 2026-10-04
+
+### Added
+
+- Claude models on OpenAI-compatible hosts (OpenRouter) use Anthropic's prompt cache: chat requests mark the
+  system message and the last message with `cache_control`, so each step reads the earlier prompt from the
+  cache (about a tenth of the price) instead of paying for all of it again. The log line shows `cache=on`.
+
+### Changed
+
+- An HTTP 402 is no longer a "rejected the request" bad request. OpenRouter's "would exceed your available
+  credits given your current in-flight requests" (credit reserved by another running request) is retried like a
+  429, 20s apart (about 100s with the default `retry.max`), instead of failing the turn at once; any other 402
+  fails as `out of credits on host <name>: …; add credits, then send again`, with `error_kind` `credits`.
+- `chi answer --option Continue --text "…"` is accepted: the text joins the continued turn as a steer (marked as the parent agent's for `chi answer`), instead of being refused.
+- The Continue answer's text keeps its line breaks in the continued turn's steer, and it is dropped (logged
+  `steer_dropped why=not_begun`) when the continue turn fails before it begins or a typed `/continue no` answered
+  the offer first, instead of joining whatever turn ran next.
+- `chi answer --format json` says `"answered_here": false` when the question was no longer open (answered
+  elsewhere, or another one waits now): it still waits for what comes next, but the JSON no longer reads as if
+  the given answer went in.
+- `chi send --wait` and `chi answer` with `--format json` say why a turn stopped: a failed turn adds `error_kind`
+  (the provider error's kind, e.g. `credits`, `server`) and `retryable`, a canceled one `cancel_reason` (`user`,
+  `hook`, `ctrl_c`, `manual`) and `stopped_by` (the hook, e.g. `loop-guard`), when known. The session's
+  `last_turn` records them.
+
+Update with `chi update` (no bundle versions moved). Restart `chi web` and running sessions afterwards (`chi sessions restart ID`).
+
 ## [0.21.0] - 2026-10-04
 
 ### Added
@@ -1245,7 +1273,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.21.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.22.0...HEAD
+[0.22.0]: https://github.com/dm1try/samagotchi/compare/v0.21.0...v0.22.0
 [0.21.0]: https://github.com/dm1try/samagotchi/compare/v0.20.0...v0.21.0
 [0.20.0]: https://github.com/dm1try/samagotchi/compare/v0.19.0...v0.20.0
 [0.19.0]: https://github.com/dm1try/samagotchi/compare/v0.18.1...v0.19.0

data/docs/architecture.md

@@ -392,8 +392,9 @@ output) and cancel. Cancel closes the in-flight socket from the
 `CancellationController` listener, so it works on any thread.
 
 **Errors.** A failed request raises an `LLM::ProviderError` of one kind:
-`ConnectionError` (`RetryExhausted`), `RateLimited`, `ServerError`, `AuthError`,
-`BadRequest` (`context_overflow?`) or `ProtocolError`. Engine keeps the turn's
+`ConnectionError` (`RetryExhausted`), `RateLimited` (`CreditsHeld`: a 402 about
+credit held by in-flight requests, retried after 20 s), `OutOfCredits` (any other
+402), `ServerError`, `AuthError`, `BadRequest` (`context_overflow?`) or `ProtocolError`. Engine keeps the turn's
 conversation (the prompt plus completed tool iterations) and emits
 `:turn_failed` with `error_kind:`, `retryable:`, `host:` and a one-line
 `summary:`, which the REPL, the attached TUI and the web show.

data/docs/configuration.md

@@ -513,6 +513,12 @@ Every chat request carries the session's id as a `Session-Id` header (next to `U
 gateway that spreads requests over several providers can key on it to keep one conversation on one provider, so
 prompt caches hit and every turn is answered by the same model. Servers that don't know the header ignore it.
 
+Chat requests for a Claude model (an id containing `claude`, such as `anthropic/claude-sonnet-5.5`) on a remote
+OpenAI-compatible host get two prompt-cache breakpoints (`cache_control` on the system message and on the last
+message), so each step reads the earlier prompt from Anthropic's cache instead of paying for it again; the debug
+log's line shows `cache=on`. Nothing to configure. A provider behind a gateway may still not cache: check the
+cached tokens in `/stats`.
+
 ## Llama Model Routing
 
 To explicitly route requests to a named model in llama.cpp, set:
@@ -607,6 +613,9 @@ Transient network failures are retried automatically with exponential backoff.
 - Retry scope: transient network errors (timeouts, reset connections, EOF/socket reachability failures),
   HTTP 429 and HTTP 500/502/503/504/529. A `Retry-After` header replaces the backoff delay; one longer than
   60s is not waited out and the error is reported instead.
+- An HTTP 402 about credit held by in-flight requests (OpenRouter reserves credit for each running request, so
+  one session's long request can make another's fail) is retried like a 429, 20s apart unless `Retry-After`
+  says otherwise: with the default `retry.max` that is about 100s. With `retry.max: 0` it fails at once.
 - A refused connection (nothing listening) is not retried: the turn fails at once with `can't reach host <name> at
   <address> (connection refused) — is the server running?`.
 - A stream that has already produced output is never retried (the retry would repeat it); it fails the turn.
@@ -653,6 +662,8 @@ message (before, a failed llama.cpp `/completion` ended the turn as
 |---|---|---|
 | connection | reset, timed out, dropped mid-stream; refused | yes (network retry), not mid-stream; refused: no |
 | rate limited | HTTP 429 | yes, honouring `Retry-After` |
+| credits held | HTTP 402 "… in-flight requests" | yes, after 20s (or `Retry-After`) |
+| credits | any other HTTP 402: out of credits | no |
 | server | HTTP 5xx, llama.cpp's mid-stream `error:` event | 500/502/503/504/529 only |
 | auth | HTTP 401/403 | no |
 | bad request | other 4xx; a prompt larger than the context window, whatever the status | no |

data/docs/sessions.md

@@ -172,7 +172,7 @@ chi send --wait 3fa2                                   # sends nothing: waits fo
 - `--new` prints `<full id>  started` on stdout. With `--wait` that line (and the `sent` line for an existing session) goes to stderr, so stdout is exactly the answer: the reply of the turn the message started, in full. It is the worker's `output/` file, the same one `delegate` reads; a turn that ends with only tool calls and no text has none.
 - `--wait` takes one session: `--new` or one id. A session with a running turn is refused (`busy: a turn is running; wait or attach`, exit 1): the message would run after it, and its reply would come back as the answer.
 - Exit codes with `--wait`: 0 answered; 3 the turn waits for an answer from you (a question, a hook's question, a guardrail approval, or the step-limit question: see [chi as a sub-agent](sub-agent.md#the-step-limit)), and the session keeps waiting: stderr gets the whole question (`waiting for an answer (approval): …`, its text, the numbered options, whether free text is allowed) and how to answer it (`chi answer ID --question QID --option N`, or `chi --attach ID`, the web); 4 `--timeout S` passed with the turn still running (it goes on; wait again); 1 the turn ended without a reply (canceled, failed or empty), the worker failed or vanished, or the session was stopped; 130 on Ctrl-C, which leaves the turn running (`still running: chi --attach ID`). There is no default timeout.
-- `--format json` (with `--wait`) prints one JSON object on stdout however the wait ends, for a script or a parent agent (see [chi as a sub-agent](sub-agent.md)): `{"status":"answered","session_id":…,"text":…}`; `{"status":"question",…,"question":{"id","kind","header","text","options","multi_select","allow_freeform","approval"},"answer_with":"chi answer ID --question QID --option N"}`, where `kind` is `question` (the model's), `hook` or `approval` (with the tool, command, cwd, rule, reason and offered scopes); `{"status":"running",…,"detail":…}` (exit 4, and on Ctrl-C); and `failed`, `canceled`, `no_answer`, `error`, `worker_gone` or `stopped` with a `detail` line (exit 1). A failure before the wait (no such session, a busy one) is `error` too. A usage error (exit 2) prints no JSON.
+- `--format json` (with `--wait`) prints one JSON object on stdout however the wait ends, for a script or a parent agent (see [chi as a sub-agent](sub-agent.md)): `{"status":"answered","session_id":…,"text":…}`; `{"status":"question",…,"question":{"id","kind","header","text","options","multi_select","allow_freeform","approval"},"answer_with":"chi answer ID --question QID --option N"}`, where `kind` is `question` (the model's), `hook` or `approval` (with the tool, command, cwd, rule, reason and offered scopes); `{"status":"running",…,"detail":…}` (exit 4, and on Ctrl-C); and `failed`, `canceled`, `no_answer`, `error`, `worker_gone` or `stopped` with a `detail` line (exit 1); `failed` adds `error_kind` and `retryable`, `canceled` adds `cancel_reason` and `stopped_by`, when known. A failure before the wait (no such session, a busy one) is `error` too. A usage error (exit 2) prints no JSON.
 - `--wait ID` with no message (no `-m`, nothing piped) sends nothing: it waits for the session's next reply and prints and exits as above. A running session is fine (that is the point), so after exit 3, 4 or 130 an agent waits again this way while the user answers in the web or `chi --attach`; the question pending when it starts doesn't count again. An idle session with no worker waits until something wakes one. With `--new`, or two ids, it is a usage error (exit 2).
 - The 16 KiB cap applies: `git diff | chi send --new …` on a big diff is refused; name the branch in the message instead and let the session read it.
 - A session nobody attaches to stalls at its first question or guardrail ask until someone answers it (`chi answer`, the web, `chi --attach`), and its worker stays up meanwhile: it doesn't idle-exit while a question waits (`chi sessions list` shows it as `waiting`; `chi sessions stop ID` frees it). Otherwise it idle-exits after `session.idle_exit_minutes` like any worker. These are ordinary sessions: delete them like any other.

data/docs/sub-agent.md

@@ -37,7 +37,7 @@ Exit codes, both commands:
 | 0 | `not_continued` | (`chi answer`) a Stop answered the step-limit question; the turn's work so far stays |
 | 3 | `question` | chi waits for an answer: `question`, `answer_with` |
 | 4 | `running` | `--timeout` passed; the turn goes on, wait again |
-| 1 | `failed`, `canceled`, `limit`, `no_answer`, `error`, `worker_gone`, `stopped` | `detail` says what happened (`limit`: the turn ran out of steps and nobody can be asked, e.g. an older worker; `chi send ID -m '/continue yes'` continues it) |
+| 1 | `failed`, `canceled`, `limit`, `no_answer`, `error`, `worker_gone`, `stopped` | `detail` says what happened (`limit`: the turn ran out of steps and nobody can be asked, e.g. an older worker; `chi send ID -m '/continue yes'` continues it). `failed` adds `error_kind` (the provider error's kind: `credits`, `credits_held`, `rate_limited`, `server`, `auth`, `connection`, …) and `retryable` when known; `canceled` adds `cancel_reason` (`user`: a Stop in the web or `chi sessions stop`; `hook`; `ctrl_c`; `manual`) and `stopped_by` (the hook that stopped it, e.g. `loop-guard`) when known |
 | 2 | (no JSON) | usage error, or an option the question doesn't offer |
 | 130 | `running` | Ctrl-C; the turn goes on |
 
@@ -59,8 +59,11 @@ A turn that runs out of steps (`turn.max_iterations`, default 100) before it
 answers waits as a question of kind `continue` (`"limit": 100`, options
 `Continue` and `Stop`). `answer_with` continues it:
 `chi answer ID --question QID --option Continue`, and the continued turn's
-reply (or its next question) comes back on that same wait. To stop it:
-`--option Stop`, with `--text "why"` for the model (Continue takes no text);
+reply (or its next question) comes back on that same wait. With
+`--text "…"` the text joins the continued turn as a steer (as a `chi send -m`
+into a running turn does, marked as coming from the parent agent), so one
+answer continues and redirects it. To stop it:
+`--option Stop`, with `--text "why"` for the model;
 that wait ends with `status: not_continued`, exit 0, and the turn's work so far
 stays in the session. A message instead (`chi send ID -m "…"`) drops the
 question and starts a new turn. It can't be dismissed.
@@ -132,7 +135,9 @@ answers from any local process.
 - `chi send --wait ID` with no message waits past a question already reported
   (the step-limit question too), until someone answers it.
 - An answer to a question that is no longer open (you answered it in the web
-  first) isn't sent; `chi answer` says so and waits for what comes next.
+  first) isn't sent; `chi answer` says so and waits for what comes next. Its
+  JSON then has `"answered_here": false` (absent when the answer went in), so
+  an `answered` status there is someone else's answer's turn, not yours.
 - `chi send --wait` and `chi answer` don't read stdin unless it's a pipe or a
   file. Agent shells usually pass `/dev/null`, which is fine.
 
@@ -165,7 +170,8 @@ Start a task: `chi send --new --wait --format json --timeout 500 -m "<task>"`
 - `status: running` (exit 4): still working. Wait again:
   `chi send --wait --format json --timeout 500 <session_id>`.
 - `question.kind: continue`: chi ran out of steps before it answered. If it is
-  getting somewhere, continue it (`answer_with`, `--option Continue`); if not,
+  getting somewhere, continue it (`answer_with`, `--option Continue`, with
+  `--text "…"` to steer it on the way); if not,
   stop it (`--option Stop --text "why"`, exit 0, status `not_continued`) or send
   a narrower follow-up instead. Ask your user when unsure.
 - Anything else (exit 1): report `detail` to your user. `chi --attach <session_id>`

data/lib/samagotchi/answer_command.rb

@@ -34,7 +34,8 @@ module Samagotchi
         with it), then waits for what comes next and prints it as chi send
         --wait does.
         --question QID  the question's id (chi send --wait prints it); a
-                        question no longer open is not answered
+                        question no longer open is not answered (the JSON
+                        says "answered_here": false)
         --option N|LABEL
                         an option, by number (1-based) or label; repeat
                         on a multi-select question
@@ -47,7 +48,8 @@ module Samagotchi
         An approval (a guardrail's ask) can be denied here: deny it, and
         tell your user; allowing it is the user's. With
         guardrails.parent_approvals: once, "Allow once" is let through.
-        A step-limit question (kind continue): --option Continue, or
+        A step-limit question (kind continue): --option Continue [--text
+        STEER] (the text joins the continued turn as a steer), or
         --option Stop [--text WHY] (exit 0, status not_continued); it
         can't be dismissed.
         Exit: 0 answered, 1 failed, refused or the worker is gone, 2
@@ -214,9 +216,11 @@ module Samagotchi
     end
 
     # The question was answered elsewhere (the web first), or another one
-    # waits now: said, then what comes next is waited for.
+    # waits now: said, then what comes next is waited for (the JSON says
+    # answered_here: false).
     # @return [nil]
     def not_open(qid)
+      @answered_here = false
       error_line("#{command_name}: question #{qid} is no longer open; not answered here, waiting for what comes next")
       nil
     end

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

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.21.0
+version: 0.22.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/cli/parent_wait.rb

@@ -64,10 +64,11 @@ module Samagotchi
         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,
-                                    json: @json, timeout: timeout)
+                                    json: @json, timeout: timeout, extra: report_extra)
       rescue Interrupt
         if @json
-          @stdout.puts(ParentReport.json_line(ReplyWait::Result.new(status: :canceled), session_id: id))
+          @stdout.puts(ParentReport.json_line(ReplyWait::Result.new(status: :canceled), session_id: id,
+                                                                                        extra: report_extra))
           @stdout.flush
           @reported = true
         end
@@ -77,6 +78,12 @@ module Samagotchi
         error_line("#{command_name}: the session is gone (deleted while waiting)")
         Exit::FAILED
       end
+
+      # More keys for the JSON object: answered_here: false when chi
+      # answer's answer didn't go in (the question was no longer open).
+      def report_extra
+        @answered_here == false ? { answered_here: false } : {}
+      end
     end
   end
 end

data/lib/samagotchi/continue_offer.rb

@@ -41,6 +41,9 @@ module Samagotchi
       # A question was posted since the last close (it may have been
       # answered or superseded meanwhile).
       @asked = false
+      # The text a Continue answer came with ({text:, source:}): it steers
+      # the continue turn (#run_continue_turn).
+      @continue_steer = nil
     end
 
     attr_writer :queue_command
@@ -62,6 +65,7 @@ module Samagotchi
     def drop(origin)
       return unless awaiting?
 
+      @continue_steer = nil
       close("dropped")
       @engine.synchronize_events do
         @turn_flow.drop_offer!
@@ -95,6 +99,10 @@ module Samagotchi
       close(resolved ? "answered" : "dropped") unless awaiting?
       return unless resolved
 
+      # Answered without a turn (a typed /continue no that got there before
+      # the answer's /continue yes): the answer's text steers nothing.
+      @continue_steer = nil unless result.resume
+
       # An offer answered without a turn ("no") is activity: the recap
       # written at the offer (it says the turn stopped) gets rewritten.
       @engine.record_activity unless result.resume
@@ -103,18 +111,26 @@ module Samagotchi
     # The continue offer was answered yes: resume the conversation without a
     # user message, with the iteration limit the offer's turn had. A failure
     # keeps the offer, as the REPL does ("continue prompt preserved"), and
-    # asks again.
+    # asks again. The answer's text is carried into the turn as it begins;
+    # a turn that never began (a raise before it) leaves it to no other.
     def run_continue_turn(command)
       offer = @turn_flow.offer
       close("answered")
-      @turn_flow.before_continue_turn
-      @run_turn.call(nil, continue: true, origin: { client_id: command[:client_id] }.compact,
-                          max_iterations: @max_iterations.call(offer[:no_interrupt])) do |result, error|
-        if error
-          open(offer)
-        else
-          after_turn(result, continue: true, no_interrupt: offer[:no_interrupt])
+      steer = @continue_steer
+      @continue_steer = nil
+      begin
+        @engine.steer_next_turn(steer[:text], source: steer[:source]) if steer
+        @turn_flow.before_continue_turn
+        @run_turn.call(nil, continue: true, origin: { client_id: command[:client_id] }.compact,
+                            max_iterations: @max_iterations.call(offer[:no_interrupt])) do |result, error|
+          if error
+            open(offer)
+          else
+            after_turn(result, continue: true, no_interrupt: offer[:no_interrupt])
+          end
         end
+      ensure
+        @engine.drop_carried_steers if steer
       end
     end
 
@@ -164,9 +180,18 @@ module Samagotchi
     end
 
     # The question's answer as the /continue line a typed answer would be:
-    # Continue → yes; Stop → no; a text (with Stop, or alone) → no, <text>.
+    # Continue → yes, and a text with it steers the continue turn (from the
+    # parent agent when the answer says so); Stop → no; a text (with Stop,
+    # or alone) → no, <text>.
     def answered(answer, client_id:)
+      # The /continue line takes the text on one line; the steer keeps its
+      # line breaks.
       text = answer[:freeform].to_s.gsub(/\s+/, " ").strip
+      @continue_steer = nil
+      if Array(answer[:selected]).include?(CONTINUE) && !text.empty?
+        @continue_steer = { text: answer[:freeform].to_s.strip,
+                            source: answer[:by] == "parent_agent" ? "parent_agent" : "user" }
+      end
       line = if Array(answer[:selected]).include?(CONTINUE) then "/continue yes"
              elsif text.empty? then "/continue no"
              else "/continue no, #{text}"

data/lib/samagotchi/engine.rb

@@ -325,6 +325,21 @@ module Samagotchi
       @turn_state.steer(text, source: source)
     end
 
+    # Like #steer, for the turn that begins next (a continue turn answered
+    # with a text): it joins that turn at its first boundary. Callable from
+    # any thread; a turn that never begins keeps it for the next one, unless
+    # #drop_carried_steers drops it.
+    # @return [Boolean] whether it was queued (false: blank)
+    def steer_next_turn(text, source:)
+      @turn_state.steer_next_turn(text, source: source)
+    end
+
+    # Drop the #steer_next_turn steers no turn began with (the continue turn
+    # failed before it began), logged; a no-op once a turn took them.
+    def drop_carried_steers
+      log_dropped_steers(@turn_state.drop_carried_steers, "not_begun")
+    end
+
     # The drain a turn's loop gets: the caller's lines (a UI's steering; nil
     # in a --non-interactive run) and the plugin steers. At the after-answer
     # boundary the steers are dropped: the model answered, and a nudge would
@@ -1089,7 +1104,8 @@ module Samagotchi
     # @param limit [Integer, nil] the turn ran out of iterations at this
     #   limit: "exhausted" => true, "limit" => N, so a wait with nobody to
     #   answer the continue offer says so (ReplyWait, ParentReport "limit")
-    def record_last_turn(session, outcome, seconds, origin, limit: nil)
+    # @param event [Hash] the turn's end event (#stop_facts)
+    def record_last_turn(session, outcome, seconds, origin, event, limit: nil)
       client_id = origin.is_a?(Hash) ? origin[:client_id].to_s : ""
       source = if client_id.start_with?("#{Tools::Delegate::CLIENT_PREFIX}:") then "delegate"
                elsif client_id == SessionManager::REMINDER_CLIENT_ID then "reminder"
@@ -1098,9 +1114,23 @@ module Samagotchi
       session.last_turn = { "outcome" => outcome, "ended_at" => Time.now.iso8601(3),
                             "seconds" => seconds.round(1), "origin" => source }
       session.last_turn.merge!("exhausted" => true, "limit" => limit) if limit
+      session.last_turn.merge!(stop_facts(event))
     end
     private :record_last_turn
 
+    # Why a turn stopped, from its end event, for a parent agent's wait
+    # (ReplyWait): a provider error's kind and whether a retry may help, a
+    # cancel's reason and the hook that stopped it. Only what is known.
+    def stop_facts(event)
+      case event&.dig(:type)
+      when :turn_failed then { "error_kind" => event[:error_kind]&.to_s, "retryable" => event[:retryable] }.compact
+      when :turn_canceled
+        { "cancel_reason" => event[:cancellation_reason]&.to_s, "stopped_by" => event[:cancelled_by]&.to_s }.compact
+      else {}
+      end
+    end
+    private :stop_facts
+
     # How every turn ends (completed, canceled, failed): the session gets
     # what the turn kept, goes idle and records the ending, and the end
     # event is announced, as one step of the event log (a snapshot taken
@@ -1118,7 +1148,7 @@ module Samagotchi
         kept, event = yield(seconds)
         replace_session_messages(turn.session, kept) if kept
         turn.session.status = Session::STATUS_IDLE
-        record_last_turn(turn.session, outcome, seconds, turn.origin, limit: exhausted ? turn.limit : nil)
+        record_last_turn(turn.session, outcome, seconds, turn.origin, event, limit: exhausted ? turn.limit : nil)
         emit_event(turn.on_event, turn.tag(event))
       end
       turn.ended = true

data/lib/samagotchi/llm/errors.rb

@@ -22,6 +22,9 @@ module Samagotchi
     #   ConnectionError  no answer (refused, reset, timeout); RetryExhausted,
     #                    ConnectionRefused
     #   RateLimited      429, with retry_after when the server says
+    #   CreditsHeld      402 "… in-flight requests": credit reserved by other
+    #                    requests; a RateLimited, retried after 20 s
+    #   OutOfCredits     any other 402; never retried
     #   ServerError      5xx or a server's error event mid-stream
     #   AuthError        401/403, or an API key variable that is not set
     #   BadRequest       other 4xx (a context overflow is one, whatever status;
@@ -84,6 +87,24 @@ module Samagotchi
       def default_retryable? = true
     end
 
+    # A 402 that says the account's credit is reserved by requests still in
+    # flight (OpenRouter: "This request would exceed your available credits
+    # given your current in-flight requests"): it clears once they settle,
+    # so it is retried like a 429, after CREDITS_SETTLE_DELAY unless the
+    # server says how long.
+    class CreditsHeld < RateLimited
+      def kind = :credits_held
+
+      def summary = "credits on host #{host} are held by in-flight requests (retry after #{retry_after.to_f.ceil}s)"
+    end
+
+    # Any other 402: the account has run out of credits. Never retried.
+    class OutOfCredits < ProviderError
+      def kind = :credits
+
+      def summary = "out of credits on host #{host}: #{detail}; add credits, then send again"
+    end
+
     class ServerError < ProviderError
       def kind = :server
 
@@ -238,6 +259,10 @@ module Samagotchi
       VISION_UNSUPPORTED_RE = /support image input|image input is not supported|mmproj/i
       # A 400 about the thinking fields chi sent (Thinking.chat_fields).
       REASONING_REFUSED_RE = /reasoning|thinking/i
+      # A 402 about credit held by in-flight requests (see CreditsHeld).
+      CREDITS_HELD_RE = /in-flight requests/i
+      # Seconds to wait before retrying a CreditsHeld without a Retry-After.
+      CREDITS_SETTLE_DELAY = 20.0
       RETRYABLE_SERVER_STATUSES = [500, 502, 503, 504, 529].freeze
 
       module_function
@@ -259,6 +284,12 @@ module Samagotchi
         when 401, 403 then AuthError.new(text, **options)
         when 429 then RateLimited.new(text, retry_after: parse_retry_after(retry_after), **options)
         when 408 then ServerError.new(text, retryable: true, **options)
+        when 402
+          if CREDITS_HELD_RE.match?(message) || CREDITS_HELD_RE.match?(body.to_s)
+            CreditsHeld.new(text, retry_after: parse_retry_after(retry_after) || CREDITS_SETTLE_DELAY, **options)
+          else
+            OutOfCredits.new(text, **options)
+          end
         when 400..499
           tools = TOOLS_UNSUPPORTED_RE.match?(message)
           BadRequest.new(text, tools_unsupported: tools,

data/lib/samagotchi/llm/openai_chat.rb

@@ -6,6 +6,7 @@ require_relative "../config"
 require_relative "../sampling_settings"
 require_relative "errors"
 require_relative "http"
+require_relative "prompt_cache"
 require_relative "usage"
 require_relative "utf8_scrub"
 
@@ -121,7 +122,8 @@ module Samagotchi
                session_id: nil)
         body = request_body(messages, tools, model, options)
         request = post_request("#{@base_url}/chat/completions", body, session_id: session_id)
-        log_fields = { model: model, purpose: @purpose, sampling: sampling_summary(body) }
+        log_fields = { model: model, purpose: @purpose, sampling: sampling_summary(body),
+                       cache: ("on" if PromptCache.marked?(body[:messages])) }
         return chat_once(request, cancel_controller, log_fields) unless @stream
 
         assembly = Assembly.new
@@ -204,7 +206,7 @@ module Samagotchi
       def request_body(messages, tools, model, options)
         body = {
           model: model,
-          messages: Array(messages).map { |message| wire_message(message) },
+          messages: cache_breakpoints(Array(messages).map { |message| wire_message(message) }, model),
           temperature: 0.0,
           stream: @stream
         }
@@ -217,6 +219,16 @@ module Samagotchi
         body.merge(options || {}).compact
       end
 
+      # Prompt-cache breakpoints (PromptCache) on the wire copies, for a
+      # Claude model's chat requests to a remote host: a one-shot side ask
+      # would pay for a cache write nothing reads, and a local model named
+      # after Claude must not get Array content.
+      def cache_breakpoints(messages, model)
+        return messages unless @remote && @purpose == "chat"
+
+        PromptCache.mark(messages, model: model)
+      end
+
       # The body's fields beyond the conversation and the stream, for the
       # log line: "temperature=0.6 presence_penalty=1.5".
       def sampling_summary(body)

data/lib/samagotchi/llm/prompt_cache.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module LLM
+    # Prompt-cache breakpoints for Claude models behind an OpenAI-compatible
+    # host (OpenRouter, a gateway). Anthropic caches a prompt only up to a
+    # content part marked with cache_control, in the order tools → system →
+    # messages, so two marks cover a chat request:
+    # - the first system message (with it, the tool list), and
+    # - the last non-system message with content, so the next request (the
+    #   same prefix plus new messages) reads everything up to it.
+    # Mid and tail system messages (reminders, turn notes) never take the
+    # second mark. Other models' messages pass through untouched.
+    module PromptCache
+      CONTROL = { type: "ephemeral" }.freeze
+
+      module_function
+
+      # Whether +model+ (the bare id a host is asked for) names a Claude model.
+      def claude?(model) = model.to_s.match?(/claude/i)
+
+      # +messages+ (wire messages: symbol keys, content a String or an Array
+      # of parts) with the breakpoints set when +model+ is a Claude model;
+      # the given messages as they are otherwise. The marked messages and
+      # parts are copies: the caller's are never changed.
+      # @return [Array<Hash>]
+      def mark(messages, model:)
+        return messages unless claude?(model)
+
+        indexes = [system_index(messages), last_index(messages)].compact.uniq
+        return messages if indexes.empty?
+
+        messages.each_with_index.map { |message, index| indexes.include?(index) ? marked(message) : message }
+      end
+
+      # Whether any message in +messages+ carries a breakpoint.
+      def marked?(messages)
+        Array(messages).any? do |message|
+          content = message[:content]
+          content.is_a?(Array) && content.any? { |part| part.is_a?(Hash) && control?(part) }
+        end
+      end
+
+      def system_index(messages)
+        index = messages.index { |message| message[:role].to_s == "system" }
+        index if index && content?(messages[index][:content])
+      end
+
+      # The last message that isn't a system message and has content (an
+      # assistant tool_calls message has nil or "").
+      def last_index(messages)
+        messages.rindex { |message| message[:role].to_s != "system" && content?(message[:content]) }
+      end
+
+      def content?(content)
+        case content
+        when String then !content.empty?
+        when Array then content.any? { |part| part.is_a?(Hash) }
+        else false
+        end
+      end
+
+      # A String becomes one text part; an Array gets the mark on its last
+      # text part (the last part when none is text).
+      def marked(message)
+        content = message[:content]
+        return message.merge(content: [{ type: "text", text: content, cache_control: CONTROL }]) if content.is_a?(String)
+
+        target = content.rindex { |part| part.is_a?(Hash) && (part[:type] || part["type"]).to_s == "text" } ||
+                 content.rindex { |part| part.is_a?(Hash) }
+        part = content[target]
+        key = part.key?("type") ? "cache_control" : :cache_control
+        parts = content.dup
+        parts[target] = part.merge(key => CONTROL)
+        message.merge(content: parts)
+      end
+
+      def control?(part) = part.key?(:cache_control) || part.key?("cache_control")
+
+      private_class_method :system_index, :last_index, :content?, :marked, :control?
+    end
+  end
+end

data/lib/samagotchi/parent_report.rb

@@ -70,8 +70,10 @@ module Samagotchi
 
     # @param session_id [String]
     # @param timeout [Numeric, nil] the wait's --timeout (for the running detail)
+    # @param extra [Hash] more keys for the object (chi answer's
+    #   answered_here: false)
     # @return [Hash] the --format json object
-    def json(result, session_id:, timeout: nil)
+    def json(result, session_id:, timeout: nil, extra: {})
       report = { status: status(result), session_id: session_id }
       case report[:status]
       when "answered" then report[:text] = result.text.to_s
@@ -79,24 +81,39 @@ module Samagotchi
         question = question(result.question)
         report[:question] = question
         report[:answer_with] = answer_with(session_id, question)
-      else report[:detail] = detail(result, session_id: session_id, timeout: timeout)
+      else
+        report.merge!(stop_facts(result))
+        report[:detail] = detail(result, session_id: session_id, timeout: timeout)
+      end
+      report.merge(extra)
+    end
+
+    # Why a failed or canceled turn stopped, as far as last_turn knows
+    # (ReplyWait::Result): error_kind and retryable, cancel_reason and
+    # stopped_by; absent when unknown.
+    # @return [Hash]
+    def stop_facts(result)
+      case status(result)
+      when "failed" then { error_kind: result.error_kind, retryable: result.retryable }.compact
+      when "canceled" then { cancel_reason: result.cancel_reason, stopped_by: result.stopped_by }.compact
+      else {}
       end
-      report
     end
 
     # @return [String] the JSON object as one line
-    def json_line(result, session_id:, timeout: nil)
-      JSON.generate(json(result, session_id: session_id, timeout: timeout))
+    def json_line(result, session_id:, timeout: nil, extra: {})
+      JSON.generate(json(result, session_id: session_id, timeout: timeout, extra: extra))
     end
 
     # Print a wait's end the way the commands do: the JSON object on
     # stdout, or the reply on stdout and anything else on stderr (a
     # question in full) after "chi send: ".
     # @param command [String] "chi send", "chi answer"
+    # @param extra [Hash] more keys for the JSON object (#json)
     # @return [Integer] the exit status
-    def report(result, session_id:, stdout:, stderr:, command:, json: false, timeout: nil)
+    def report(result, session_id:, stdout:, stderr:, command:, json: false, timeout: nil, extra: {})
       if json
-        stdout.puts(json_line(result, session_id: session_id, timeout: timeout))
+        stdout.puts(json_line(result, session_id: session_id, timeout: timeout, extra: extra))
       elsif result.status == :done
         stdout.puts(result.text)
       else

data/lib/samagotchi/question_desk.rb

@@ -455,7 +455,7 @@ module Samagotchi
     def settle_standing(standing, answer, client_id)
       clear_saved_question
       emit({ type: :question_answered, id: answer[:id], answer: answer })
-      standing[:on_answer].call(answer.except(:by), client_id: client_id)
+      standing[:on_answer].call(answer, client_id: client_id)
     rescue StandardError => e
       Log.warn(:turn, "standing_answer_failed", error: e.class.name, message: e.message)
     end
@@ -472,12 +472,6 @@ module Samagotchi
       raise ArgumentError, "invalid selection: #{invalid.join(', ')} (valid: #{opts.join(', ')})" unless invalid.empty?
       raise ArgumentError, "single-select question: got #{sel.size} selections" if !pending[:multi_select] && sel.size > 1
       raise ArgumentError, "selection required" if pending[:multi_select] == false && sel.empty? && fm.nil?
-      # A step-limit question: Continue resumes the turn as it was; a text
-      # goes with Stop (steering a continue is not a thing).
-      if pending[:kind].to_s == CONTINUE_KIND && sel == [CONTINUE_OPTION] && fm
-        raise ArgumentError, "Continue takes no text (a text goes with Stop)"
-      end
-
       indices = sel.map { |v| opts.index(v) }
       # The one whose answer settles the approval (Approval.settle, by index).
       if parent_setting

data/lib/samagotchi/reply_wait.rb

@@ -33,7 +33,16 @@ module Samagotchi
     #   "failed", text is the failure's summary when the turn note has one.
     # @!attribute limit [Integer, nil] the iteration limit an "exhausted"
     #   turn ran out at
-    Result = Struct.new(:status, :text, :file, :question, :outcome, :limit, keyword_init: true)
+    # @!attribute error_kind [String, nil] a "failed" turn's provider error
+    #   kind (credits, server, auth, …), from last_turn
+    # @!attribute retryable [Boolean, nil] whether that error may pass on a
+    #   retry
+    # @!attribute cancel_reason [String, nil] a "canceled" turn's reason
+    #   (user, hook, ctrl_c, manual)
+    # @!attribute stopped_by [String, nil] the hook that canceled it
+    #   (loop-guard)
+    Result = Struct.new(:status, :text, :file, :question, :outcome, :limit, :error_kind, :retryable, :cancel_reason,
+                        :stopped_by, keyword_init: true)
 
     module_function
 
@@ -151,7 +160,8 @@ module Samagotchi
       return Result.new(status: :no_reply, outcome: "exhausted", limit: last["limit"]) if fresh && last["exhausted"]
 
       text = outcome == "failed" ? failure_summary(session.messages) : nil
-      Result.new(status: :no_reply, outcome: outcome, text: text)
+      why = fresh ? last.slice("error_kind", "retryable", "cancel_reason", "stopped_by").transform_keys(&:to_sym) : {}
+      Result.new(status: :no_reply, outcome: outcome, text: text, **why)
     end
 
     # The summary in the failed-turn note at the conversation's tail, nil

data/lib/samagotchi/turn_state.rb

@@ -23,6 +23,7 @@ module Samagotchi
       @controller = nil
       @sink = nil
       @steers = []
+      @carried_steers = []
     end
 
     # ── Activity clock ──────────────────────────────────────────────────
@@ -69,6 +70,8 @@ module Samagotchi
         @running = true
         @controller = controller
         @sink = sink
+        @steers.concat(@carried_steers)
+        @carried_steers = []
       end
     end
 
@@ -118,6 +121,25 @@ module Samagotchi
       true
     end
 
+    # Queue +text+ for the next turn that begins: it is a steer of that turn
+    # from its first boundary on (a continue turn's answer text, which has
+    # no turn running yet to steer). Taken by #begin!.
+    # @return [Boolean] whether it was queued (false: blank)
+    def steer_next_turn(text, source:)
+      text = text.to_s.strip
+      return false if text.empty?
+
+      @lock.synchronize { @carried_steers << { text: text, source: source.to_s } }
+      true
+    end
+
+    # Drop what #steer_next_turn queued and no turn began with (a no-op
+    # once #begin! took it).
+    # @return [Array<Hash>] the steers dropped ({text:, source:})
+    def drop_carried_steers
+      @lock.synchronize { @carried_steers.tap { @carried_steers = [] } }
+    end
+
     # @return [Array<Hash>] the steers queued so far ({text:, source:}), taken
     def take_steers
       @lock.synchronize { @steers.tap { @steers = [] } }

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.21.0"
+  VERSION = "0.22.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samagotchi
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.22.0
 platform: ruby
 authors:
 - Dmitry Dedov
@@ -270,6 +270,7 @@ files:
 - lib/samagotchi/llm/native_backend.rb
 - lib/samagotchi/llm/native_tool_normalizer.rb
 - lib/samagotchi/llm/openai_chat.rb
+- lib/samagotchi/llm/prompt_cache.rb
 - lib/samagotchi/llm/turn_settings.rb
 - lib/samagotchi/llm/usage.rb
 - lib/samagotchi/llm/utf8_scrub.rb