samagotchi 0.27.0 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b91f830918a3f58dac1d54820450ec90b4caa2d8f970b3fab03c8a0199b3ac2e
-  data.tar.gz: 1d1f0f1dc839247801be1462a895e8a57e189a68882fbaeb5a7707fdb4add0ab
+  metadata.gz: 51c7c1a00eec47f70f15b04381eb6b60f5bd6c66c8dd11fbe05ef045c41d5219
+  data.tar.gz: 00cbfcba1b3b21ef54c9d54bd9de349a90a19314cb5613e9daa94ca51c8c04fe
 SHA512:
-  metadata.gz: 398faa2152be479cf78093fb9c752158932a2c186bf1fa5fd1ee9a622895bf742f82f1a25c843febfb877c826cee869623ee9871c50154015fdb54d02a490054
-  data.tar.gz: 35a4b45af554dd9cfd79c87d67ed7d819d14759421f8f669ac769ddbb1b37a64f5b0c79101f15a002ebdb4a2e2e9bee1def9eead820d50f61312c9f4a8cc41c8
+  metadata.gz: 11f14c97b088efe1c1eafafb63604f44c84a7a7a79d738db5f6344191b6fa9948ceab37acd0f8daba2a85840b3f272bfcd767bd2147b0da7abbc23a04936bba4
+  data.tar.gz: e3136af1decc273b092f66756e2994ad0760a626cb9b007a4a4ad2f68ee85bdf6f37aab3f5a0bde85597f677bde3fde32826763c9b44001e941945abc39dfa5d

data/CHANGELOG.md

@@ -8,6 +8,39 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.28.0] - 2026-10-04
+
+### Added
+
+- Desktop: the panel's footer says where its text and images came from, "from clipboard" (the hotkey) or "from
+  selection" (Send to chi); run `chi desktop upgrade`.
+- `cache.ttl: 1h` keeps a Claude model's prompt-cache breakpoints for an hour instead of 5 minutes (a write costs 2×
+  the input price instead of 1.25×; off by default), and `cache.key: session` sends the session id as
+  `prompt_cache_key` to OpenAI's API and OpenRouter (off by default).
+- `chi sessions list` marks a session whose last turn loop-guard stopped with `[looped]` (another hook:
+  `[stopped by <name>]`); `--format json` carries `stopped_by`.
+
+### Changed
+
+- Past `image.max_per_request` images, the oldest are left out in batches of half the limit instead of one per new
+  image, so the earlier conversation stays a cacheable prefix; the placeholder reads "an older image (chi sends up
+  to the newest N)".
+- After loop-guard cuts a runaway reply, chi's retry note tells the model to continue the task with its next tool
+  call (or answer if it's done) instead of "answer briefly", which made models wrap up in the middle of a task.
+
+### Fixed
+
+- REPL: a line typed ahead during a turn no longer starts a turn-end warm-up that the next turn throws away.
+- Web: when one of a task's stop buttons is clicked, the other one (the stage's step list) disables too.
+- Desktop: `chi desktop install` starts the helper with a bare env, so `SAMAGOTCHI_*` settings (and anything else)
+  from the install shell no longer stick to the helper and the chi it runs until a relaunch; run `chi desktop upgrade`.
+- Desktop: ⌘⏎ on the panel's "New session" row says "A note needs a session" instead of only beeping, and the Note
+  button is off on that row; run `chi desktop upgrade`.
+- Desktop: the panel lists live sessions in the order they started, so ⌘1…⌘9 no longer shift when a session runs a
+  turn (a new session comes last); run `chi desktop upgrade`.
+
+Update with `chi update`, then `chi desktop upgrade` if you use the desktop helper.
+
 ## [0.27.0] - 2026-10-04
 
 ### Added
@@ -1438,7 +1471,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.27.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.28.0...HEAD
+[0.28.0]: https://github.com/dm1try/samagotchi/compare/v0.27.0...v0.28.0
 [0.27.0]: https://github.com/dm1try/samagotchi/compare/v0.26.0...v0.27.0
 [0.26.0]: https://github.com/dm1try/samagotchi/compare/v0.25.0...v0.26.0
 [0.25.0]: https://github.com/dm1try/samagotchi/compare/v0.24.0...v0.25.0

data/docs/cli.md

@@ -495,9 +495,12 @@ A model that can see images gets them these ways:
 Images are downscaled to a 1568 px long side (with `sips` on macOS or
 ImageMagick; without either, a larger image is refused with a hint) and stored
 next to the session in `<session>/images/`, and the session file keeps small
-references to them. Each request sends the newest 20 images of the conversation;
-older ones become a line like `[image shot.png 1280×800 not sent: only the
-newest 20 images are sent]`.
+references to them. Each request sends up to the newest 20 images of the
+conversation (`image.max_per_request`); past that the oldest are left out ten at
+a time (half the limit), so the earlier conversation stays the same between
+requests and the server's prompt cache keeps it. A left-out image becomes a line
+like `[image shot.png 1280×800 not sent: an older image (chi sends up to the
+newest 20)]`.
 
 A model that can't see images (a text-only model, llama.cpp without
 `--mmproj`, an mlx host) refuses a turn with images before sending it:

data/docs/configuration.md

@@ -519,8 +519,20 @@ OpenAI-compatible host get two prompt-cache breakpoints (`cache_control` on the
 message), so each step reads the earlier prompt from Anthropic's cache instead of paying for it again. The system
 prompt goes as two text parts, the breakpoint after the first: everything sessions share, then the model, working
 directory and session lines, so a new session reads the shared part from the cache as well; 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`. Each request's own counts are in the debug log's `generation_completed` line:
+log's line shows `cache=on`. A provider behind a gateway may still not cache: check the cached tokens in `/stats`.
+
+Anthropic drops a cache entry 5 minutes after its last read, so a session you come back to after a longer pause
+writes its prompt again. `cache.ttl: 1h` keeps the breakpoints an hour (the log shows `cache=1h`); a write then
+costs 2× the input price instead of 1.25×, so it pays off when you often pause 5–60 minutes between turns.
+`cache.key: session` sends the session id as `prompt_cache_key` (OpenAI's API and OpenRouter only; the log shows
+`cache_by=session`), which OpenAI uses to route a conversation to the machine that holds its cache:
+
+```yaml
+cache:
+  ttl: 1h        # 5m (default) or 1h
+  key: session   # off (default) or session
+```
+ Each request's own counts are in the debug log's `generation_completed` line:
 `prompt=` (its prompt tokens), `cached=` (read from the server's cache) and `cache_write=` (written to it, when the
 server reports writes); recap and side requests log theirs as `recap request_usage`.
 
@@ -784,7 +796,7 @@ downscaled first; three settings bound them (env `SAMAGOTCHI_IMAGE_*` or
 image:
   max_side: 1568          # long side in px (Claude's standard; ~1.3k tokens for 1280×800)
   max_bytes: 3750000      # larger after downscaling → re-encoded as JPEG
-  max_per_request: 20     # older images in the conversation become placeholder lines
+  max_per_request: 20     # older images become placeholder lines, dropped in batches of half this
 ```
 
 Whether a model can see images is found out before a turn with images is sent:
@@ -899,6 +911,8 @@ described in their own sections.
 | `hosts.<name>.remote` | by address | | `true`/`false`: treat the host as a remote provider or a local server. See "Remote or local". |
 | `max_tool_output_chars` | `10000` | yes | Tool output kept in the conversation; a top-level key (see below). |
 | `cache.warmup` | `auto` | | `auto`: after a turn, send the next turn's prompt (up to the next message) to a local llama.cpp host on the native loop, so the next turn prefills only its message; never a remote or `api: openai` host. `off`: never. See [prompt caching](internals/prompt-caching.md#the-turn-end-warm-up). |
+| `cache.ttl` | `5m` | | How long Anthropic keeps the prompt-cache breakpoints of a Claude model on a remote host: `5m` (Anthropic's default) or `1h`. A 1h cache write costs 2× the input price (5m: 1.25×), a read the same 0.1×. See "Remote or local". |
+| `cache.key` | `off` | | `session`: send the session id as `prompt_cache_key` to OpenAI's API and OpenRouter, which route and cache by it; no other host gets it. `off`: none. |
 | `retry.max` | `5` | yes | See "Llama Network Retry Behavior". |
 | `retry.base_delay` | `0.5` | yes | |
 | `retry.max_delay` | `8.0` | yes | |

data/docs/internals/prompt-caching.md

@@ -43,9 +43,9 @@ right-hand column happens.
  shared by every turn of this session ─────────────────────────────────────
 ┌──────────────────────────────────────────────────────────────────────────┐
 │ history      user / assistant / tool messages, APPEND-ONLY               │  !rollback, a failed or
-│              (images: the newest N, ImagePlan)                           │  cancelled turn's tail,
-│                         ◄── remote Claude: breakpoint #2 on the last     │  the image window
-│                             non-system message                           │  sliding, history
+│              (images: up to the newest N, cut in batches; ImagePlan)     │  cancelled turn's tail,
+│                         ◄── remote Claude: breakpoint #2 on the last     │  the image cut moving
+│                             non-system message                           │  a batch, history
 ├──────────────────────────────────────────────────────────────────────────┤  sanitizing (thinking
 │ tail notes   reminders, turn notes, steers (system/user messages)        │  stripped per spec)
 │ new prompt   this turn's user message                                    │
@@ -83,7 +83,39 @@ user message starts (`KernelLoop#warmup_prompt`) and sends it in a thread (`Clie
   server has since cleared skips its prompt cache and prefills everything (measured 0.5 s → 12 s). For the same
   reason `id_slot` is a reserved sampling key.
 - What breaks it (the warm-up simply misses): a system-prompt rebuild (`/thinking`, `/model`, a tool change),
-  the image window sliding, `!rollback`.
+  the image cut moving a batch, `!rollback`.
+
+## The image window
+
+A request sends at most `image.max_per_request` images (20 by default); older ones become placeholder lines
+(`[image a.png 1280×800 not sent: an older image (chi sends up to the newest 20)]`). If the window slid by one
+image per new image, every new image would turn the oldest sent one into a placeholder and rewrite history from
+there. So the cut is a pure function of the image count (`ImagePlan.dropped_count`): nothing is dropped up to
+the limit, then the oldest in whole steps of half the limit (21–30 images drop 10, 31–40 drop 20). Between two
+step boundaries the earlier messages stay byte-identical; at a boundary the history from the newly cut image on
+is prefilled once. The native and the chat loop use the same plan.
+
+## Remote caches: TTL and routing
+
+- **TTL.** Anthropic keeps a breakpoint 5 minutes after its last read; a session the user comes back to later
+  writes its prompt again. `cache.ttl: 1h` sends `cache_control: {type: "ephemeral", ttl: "1h"}` on both
+  breakpoints (the log line shows `cache=1h`). Off by default: a 1h write costs 2× the input price, a 5m write
+  1.25×, a read 0.1× either way, so 1h pays off only when pauses of 5–60 minutes are common.
+- **Routing.** Every chat request carries a `Session-Id` header, which OpenRouter uses to keep a conversation on
+  one provider. `cache.key: session` also sends the session id as `prompt_cache_key` in the body, the field
+  OpenAI's API routes and caches by (OpenRouter honours it too); the log line shows `cache_by=session`. Only
+  `api.openai.com` and OpenRouter get it, and only the session's own chat requests (not recap or `/btw`): a local
+  llama.cpp, Splash or another gateway may reject an unknown field. Off by default.
+
+## Reading the numbers
+
+- The debug log's `generation_completed` line: `prompt=` (the request's prompt tokens), `cached=` (read from the
+  server's cache) and `cache_write=` (written to it, where the provider reports writes). The `http` line of a
+  remote Claude request shows `cache=on` (or `cache=1h`) when it carried breakpoints.
+- The warm-up logs `model warmup` with `cached=`, `prefilled=` and `prefill_ms=`.
+- `/stats`: "cached N (P%)" and "cache writes" for the session.
+- A healthy session: from the second request on `cached=` is close to `prompt=`; a second fresh session in the
+  same project reads everything up to the volatile tail.
 
 ## Rules for changes
 
@@ -114,7 +146,6 @@ user message starts (`KernelLoop#warmup_prompt`) and sends it in a thread (`Clie
   a slot (`id_slot`) is the hazard. With `--cache-ram 0` or an old single-slot build, a recap does evict the
   session. `--ctx-checkpoints` controls how many restore points a hybrid model keeps. chi sends
   `cache_prompt: true` on every native request.
-- **OpenRouter / Anthropic:** the default cache TTL is 5 minutes. Provider routing (which upstream serves a
-  request) also decides whether a cache is there to hit.
+- **OpenRouter / Anthropic:** the default cache TTL is 5 minutes (`cache.ttl: 1h` for an hour, see above).
+  Provider routing (which upstream serves a request) also decides whether a cache is there to hit.
 
-Still to come: image-window batches and longer remote TTLs.

data/docs/sessions.md

@@ -56,7 +56,7 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 
 `--dry-run` is the safe preview. `--keep N` keeps the N newest sessions that stay: one that goes anyway (a leftover scratch session, one left empty, one older than `--days`) takes no place in the count. Web has no prune endpoint; use the CLI.
 
-`chi sessions list` shows each session's saved recap, its first sentence without the "The user was…" opening (as on the web cards), in place of its last prompt, cut to 60 characters; a session with no recap shows its last prompt. A delegated session's row ends with `↳ <parent's short id>` (plain and `--live`; `--format json` has `parent_id`); rows keep their `updated_at` order, so a parent may be on another page than its children. After the status, `ctx 12%` says how full the context was after the session's last counted turn (from its `analytics.json`; blank when no turn had a server count or the window is unknown; `ctx_pct` in `--format json`). The web's session cards show it quietly too (`12%`), and a session's ctx meter shows it on load, before its next turn streams.
+`chi sessions list` shows each session's saved recap, its first sentence without the "The user was…" opening (as on the web cards), in place of its last prompt, cut to 60 characters; a session with no recap shows its last prompt. A session whose last turn a hook stopped carries `[looped]` when the hook was loop-guard (the thinking watch's cut, or its stop) and `[stopped by <hook>]` for any other hook, after `[archived]` (`--format json` has it as `stopped_by`; from `Session#last_turn`, so it stays until a later turn ends differently). A delegated session's row ends with `↳ <parent's short id>` (plain and `--live`; `--format json` has `parent_id`); rows keep their `updated_at` order, so a parent may be on another page than its children. After the status, `ctx 12%` says how full the context was after the session's last counted turn (from its `analytics.json`; blank when no turn had a server count or the window is unknown; `ctx_pct` in `--format json`). The web's session cards show it quietly too (`12%`), and a session's ctx meter shows it on load, before its next turn streams.
 
 **Projects:** a session belongs to the git project it was started in: the repository, whichever worktree or subfolder of it (the same project root memories use). `chi sessions list` (with `--live` and `--format` too) and `chi web` show the current folder's project; `--scope=all` shows every session, and so does a folder in no repo (`~`). `--cwd PATH` is a folder filter instead of the project. The project is stored with the session (`project_root` in its JSON, `project` in `--format json`), so a session keeps it after its worktree is deleted; sessions older than that are placed by their folder, and one whose folder is gone shows in `--scope=all` only. Retention, `--resume`/`--attach ID`, `chi send`/`chi note ID` and `chi note --all` (every live session) are not scoped. The agent's `list_sessions` lists its own project's sessions; `cwd: "/"` lists every one.
 

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

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

data/lib/samagotchi/config.rb

@@ -142,6 +142,14 @@ module Samagotchi
       # prompt on a local llama.cpp host while the user reads; off never
       # does. A :string, since YAML reads an unquoted off as false.
       Entry.new(key: "cache.warmup",             yaml_path: %w[cache warmup],             type: :string, default: "auto",           expose: %i[env config]),
+      # How long Anthropic keeps a cache breakpoint (PromptCache): 5m, or
+      # 1h for long reading gaps (a 1h write costs 2x the input price, a 5m
+      # one 1.25x, so it's opt-in).
+      Entry.new(key: "cache.ttl",                yaml_path: %w[cache ttl],                type: :string, default: "5m",             expose: %i[env config]),
+      # session sends the session id as `prompt_cache_key` to OpenAI's API
+      # and OpenRouter (OpenAIChat), which route and cache by it; off sends
+      # none. A :string, since YAML reads an unquoted off as false.
+      Entry.new(key: "cache.key",                yaml_path: %w[cache key],                type: :string, default: "off",            expose: %i[env config]),
 
       Entry.new(key: "retry.max",                yaml_path: %w[retry max],                type: :integer, default: 5,               expose: %i[env config cli]),
       Entry.new(key: "retry.base_delay",         yaml_path: %w[retry base_delay],         type: :float,   default: 0.5,             expose: %i[env config cli]),

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

@@ -18,7 +18,7 @@ final class ServiceProvider: NSObject {
       error.pointee = "No text or image in the selection" as NSString
       return
     }
-    app?.open(text: text, images: images)
+    app?.open(text: text, images: images, origin: "selection")
   }
 }
 
@@ -60,12 +60,14 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
   /// The hotkey doesn't activate us, so the frontmost app is the source.
   func openFromClipboard() {
     let (text, images) = ImageIntake.read(NSPasteboard.general)
-    open(text: text, images: images)
+    open(text: text, images: images, origin: "clipboard")
   }
 
-  func open(text: String, images: [PanelImage] = []) {
+  /// @param origin "clipboard" (the hotkey) or "selection" (the Service)
+  func open(text: String, images: [PanelImage] = [], origin: String) {
     let from = sourceApp
-    panel.show(text: text, images: images, source: from?.localizedName?.lowercased() ?? "desktop", returnTo: from)
+    panel.show(text: text, images: images, origin: origin, source: from?.localizedName?.lowercased() ?? "desktop",
+               returnTo: from)
   }
 }
 

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

@@ -118,11 +118,13 @@ final class ChiRunner {
                       stdin: stdin, timeout: timeout ?? self.timeout, completion: completion)
   }
 
-  /// The live sessions, then up to +recentCount+ stopped ones, newest
-  /// first. A session a chi REPL holds is in neither: it takes no notes or
+  /// The live sessions, oldest started first, then up to +recentCount+
+  /// stopped ones, newest first. The live order is by creation so ⌘1…⌘9
+  /// stay on their sessions as turns update them; a new one comes last.
+  /// A session a chi REPL holds is in neither: it takes no notes or
   /// messages. A failed second call just leaves "recent" empty.
   func sessions(recentCount: Int = 3, completion: @escaping (Result<[LiveSession], ChiError>) -> Void) {
-    list(["--live"]) { result in
+    list(["--live", "--sort", "created_at", "--order", "asc"]) { result in
       guard case .success(let live) = result else { completion(result); return }
       self.list(["--limit", "20"]) { recent in
         let liveIds = Set(live.map(\.id))

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

@@ -20,6 +20,9 @@ final class PanelModel: ObservableObject {
   /// The selection or clipboard: the quoted context of a message, or a note.
   @Published var text = ""
   @Published var source = ""
+  /// The path the opening text and images took: "clipboard" (the hotkey)
+  /// or "selection" (the Service); "" when the panel opened empty.
+  @Published var origin = ""
   /// Sent as `--image` with a message; notes are text only.
   @Published var images: [PanelImage] = []
   /// The thumbnail under the pointer (shows its ✕). Kept here, not in a
@@ -74,8 +77,9 @@ final class PanelModel: ObservableObject {
   }
   var live: [LiveSession] { sessions.filter { !$0.recent } }
 
-  /// One list for rows, ⌘ numbers and selection: live sessions, then kitty
-  /// windows, then recent sessions.
+  /// One list for rows, ⌘ numbers and selection: live sessions (oldest
+  /// started first: their numbers stay put), then kitty windows, then
+  /// recent sessions.
   var targets: [Target] { live.map(Target.chi) + kittyWindows.map(Target.kitty) + recent.map(Target.chi) }
 
   /// Up to maxImages; the rest is dropped (and its temp files deleted).
@@ -534,9 +538,17 @@ struct PanelView: View {
       .padding(.horizontal, 8).padding(.vertical, 4)
       .background(Capsule().fill(Color.primary.opacity(0.07)))
 
-      Text(byteLabel)
-        .font(.system(size: 11).monospacedDigit())
-        .foregroundColor(model.bytes > noteCap ? .red : .secondary)
+      HStack(spacing: 0) {
+        if !model.origin.isEmpty {
+          Text("from \(model.origin) · ").foregroundColor(.secondary)
+            .help(model.origin == "clipboard" ? "opened with the hotkey: the text and images are the clipboard's"
+                                              : "opened with Send to chi: the text and images are the selection")
+        }
+        Text(byteLabel).foregroundColor(model.bytes > noteCap ? .red : .secondary)
+      }
+      .font(.system(size: 11).monospacedDigit())
+      .lineLimit(1)
+      .fixedSize()
 
       Text(model.message)
         .font(.system(size: 11))
@@ -554,8 +566,9 @@ struct PanelView: View {
           .help("paste it into the agent's input without Enter: add more, then press Enter there")
       } else {
         Button("Note ⌘⏎") { send(.note) }
-          .disabled(!model.sendEnabled || !model.selectedKitty.isEmpty)
-          .help("add it as background the model sees on its next turn; starts no turn")
+          .disabled(!model.sendEnabled || !model.selectedKitty.isEmpty || model.newSelected)
+          .help(model.newSelected ? "a note needs a session: pick one, or ⏎ starts a new one with the message"
+                                  : "add it as background the model sees on its next turn; starts no turn")
       }
       Button(action: { send(.message) }) {
         if model.phase == .sending { ProgressView().controlSize(.small) } else { Text("Send ⏎") }
@@ -753,8 +766,9 @@ final class PanelController: NSObject, NSWindowDelegate {
     return true
   }
 
+  /// @param origin "clipboard" or "selection": where text and images came from
   /// @param returnTo the app to give focus back to on close
-  func show(text: String, images: [PanelImage] = [], source: String, returnTo app: NSRunningApplication?) {
+  func show(text: String, images: [PanelImage] = [], origin: String, source: String, returnTo app: NSRunningApplication?) {
     returnTo = app
     // A show on an open panel resets it without a close.
     dropImages()
@@ -762,6 +776,7 @@ final class PanelController: NSObject, NSWindowDelegate {
     model.images = []
     model.add(images)
     model.text = text
+    model.origin = text.isEmpty && images.isEmpty ? "" : origin
     model.source = source
     model.message = ""
     model.newSelected = false
@@ -873,13 +888,18 @@ final class PanelController: NSObject, NSWindowDelegate {
       model.message = "Paste only is for kitty windows"
       return
     }
+    // A note into a session that doesn't exist yet makes no sense.
+    if kind == .note, new {
+      NSSound.beep()
+      model.message = "A note needs a session"
+      return
+    }
     if kind == .note, !model.images.isEmpty {
       NSSound.beep()
       model.message = "Notes are text only: ⏎ sends the image as a message"
       return
     }
-    // A note into a session that doesn't exist yet makes no sense.
-    guard model.sendEnabled, new ? kind == .message : !(ids.isEmpty && windows.isEmpty) else { NSSound.beep(); return }
+    guard model.sendEnabled, new || !(ids.isEmpty && windows.isEmpty) else { NSSound.beep(); return }
     model.phase = .sending
     model.message = ""
     if !new {

data/lib/samagotchi/desktop/macos.rb

@@ -310,7 +310,11 @@ module Samagotchi
         # type may otherwise show only after a re-login).
         @runner.run([LSREGISTER, "-f", app_path])
         @runner.run([PBS, "-update"])
-        @runner.run(["open", "-g", app_path])
+        # open hands the app its own env, so the install shell's
+        # (SAMAGOTCHI_* knobs, tokens) would stay in the helper and in every
+        # chi it runs until a relaunch. Through env -i the app gets launchd's
+        # bare env, as at login; launch.json carries what chi needs.
+        @runner.run(["/usr/bin/env", "-i", "HOME=#{@env["HOME"] || Dir.home}", "/usr/bin/open", "-g", app_path])
       end
 
       def quit

data/lib/samagotchi/engine.rb

@@ -1780,7 +1780,7 @@ module Samagotchi
     # A caller's check that the next turn starts at once (input queued for
     # it: a worker's inbox) or that none follows (a one-shot run): no
     # warm-up then. nil: neither.
-    attr_writer :next_turn_waiting
+    attr_accessor :next_turn_waiting
 
     # After a completed turn, prefill the next turn's prompt up to its user
     # message while the user reads (PromptWarmup, cache.warmup). Only on a

data/lib/samagotchi/llm/openai_chat.rb

@@ -80,6 +80,17 @@ module Samagotchi
         false
       end
 
+      # true when +url+ is OpenAI's own API (api.openai.com).
+      def self.openai?(url)
+        URI(url.to_s).host.to_s.downcase == "api.openai.com"
+      rescue URI::Error
+        false
+      end
+
+      # Whether cache.key asks for the session id as `prompt_cache_key`
+      # (session; off, the default, or anything else sends none).
+      def self.cache_key? = Samagotchi::Config.get("cache.key").to_s.strip.downcase == "session"
+
       # Tool arguments as a Hash; "" is {}, invalid JSON stays a String.
       def self.parse_arguments(raw)
         return raw if raw.is_a?(Hash)
@@ -141,10 +152,10 @@ module Samagotchi
       # @return [ChatResponse]
       def chat(messages:, model:, tools: [], cancel_controller: nil, on_delta: nil, on_retry: nil, options: {},
                session_id: nil)
-        body = request_body(messages, tools, model, options)
+        body = request_body(messages, tools, model, options, session_id)
         request = post_request("#{@base_url}/chat/completions", body, session_id: session_id)
         log_fields = { model: model, purpose: @purpose, sampling: sampling_summary(body),
-                       cache: ("on" if PromptCache.marked?(body[:messages])) }
+                       cache: cache_summary(body[:messages]), cache_by: ("session" if body.key?(:prompt_cache_key)) }
         return chat_once(request, cancel_controller, log_fields) unless @stream
 
         assembly = Assembly.new
@@ -236,7 +247,7 @@ module Samagotchi
         [[open_timeout, timeout].min, timeout]
       end
 
-      def request_body(messages, tools, model, options)
+      def request_body(messages, tools, model, options, session_id)
         body = {
           model: model,
           messages: cache_breakpoints(Array(messages).map { |message| wire_message(message) }, model),
@@ -244,6 +255,7 @@ module Samagotchi
         }
         body[:stream_options] = { include_usage: true } if @stream
         body[:max_tokens] = @default_max_tokens if @default_max_tokens
+        body[:prompt_cache_key] = session_id.to_s if prompt_cache_key?(session_id)
         unless Array(tools).empty?
           body[:tools] = tools
           body[:tool_choice] = "auto"
@@ -264,10 +276,34 @@ module Samagotchi
         PromptCache.mark(messages, model: model)
       end
 
+      # The session id as `prompt_cache_key` (cache.key: session) goes only
+      # to the APIs that document it, OpenAI's and OpenRouter's (which also
+      # routes by it), for the session's own chat requests: a local server or
+      # another gateway may reject an unknown field.
+      def prompt_cache_key?(session_id)
+        return false if session_id.to_s.empty? || !@remote || @purpose != "chat"
+        return false unless self.class.openai?(@base_url) || self.class.openrouter?(@base_url)
+
+        self.class.cache_key?
+      rescue StandardError
+        false
+      end
+
+      # The log line's cache= : on for breakpoints with Anthropic's default
+      # TTL, 1h for cache.ttl 1h, nil for none.
+      def cache_summary(messages)
+        return nil unless PromptCache.marked?(messages)
+
+        hour = Array(messages).any? do |message|
+          Array(message[:content]).any? { |part| part.is_a?(Hash) && part.dig(:cache_control, :ttl) == "1h" }
+        end
+        hour ? "1h" : "on"
+      end
+
       # The body's fields beyond the conversation and the stream, for the
       # log line: "temperature=0.6 presence_penalty=1.5", nil for none.
       def sampling_summary(body)
-        SamplingSettings.log_text(body.except(:model, :messages, :stream, :stream_options, :tools, :tool_choice))
+        SamplingSettings.log_text(body.except(:model, :messages, :stream, :stream_options, :tools, :tool_choice, :prompt_cache_key))
       end
 
       # A String stays a String, an Array of parts an Array; both scrubbed

data/lib/samagotchi/llm/prompt_cache.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "../config"
+require_relative "../log"
+
 module Samagotchi
   module LLM
     # Prompt-cache breakpoints for Claude models behind an OpenAI-compatible
@@ -17,11 +20,33 @@ module Samagotchi
     # the stable part with the mark, the per-session tail (model, location,
     # session) without, so a new session reads the stable part from the
     # cache. `cache_split:` never goes on the wire (#without_split).
+    #
+    # cache.ttl: 1h marks the breakpoints with `ttl: "1h"` (#control), so a
+    # cache outlives a long reading gap; 5m, the default, sends Anthropic's
+    # default (no ttl).
     module PromptCache
       CONTROL = { type: "ephemeral" }.freeze
+      CONTROL_1H = { type: "ephemeral", ttl: "1h" }.freeze
+      TTLS = %w[5m 1h].freeze
 
       module_function
 
+      # The cache_control a breakpoint carries under cache.ttl (an unknown
+      # value warns once and is 5m).
+      def control
+        value = Config.get("cache.ttl").to_s.strip.downcase
+        return CONTROL_1H if value == "1h"
+
+        unless value.empty? || value == "5m" || @warned_ttl
+          @warned_ttl = true
+          Log.warn(:config, "invalid_value", echo: "Warning: invalid value for cache.ttl: #{value.inspect} (allowed: 5m, 1h) — using 5m",
+                                             key: "cache.ttl")
+        end
+        CONTROL
+      rescue StandardError
+        CONTROL
+      end
+
       # Whether +model+ (the bare id a host is asked for) names a Claude model.
       def claude?(model) = model.to_s.match?(/claude/i)
 
@@ -34,8 +59,9 @@ module Samagotchi
         return without_split(messages) unless claude?(model)
 
         indexes = [system_index(messages), last_index(messages)].compact.uniq
+        breakpoint = control
         messages.each_with_index.map do |message, index|
-          next marked(message.except(:cache_split), split: message[:cache_split]) if indexes.include?(index)
+          next marked(message.except(:cache_split), breakpoint, split: message[:cache_split]) if indexes.include?(index)
 
           message.key?(:cache_split) ? message.except(:cache_split) : message
         end
@@ -80,15 +106,15 @@ module Samagotchi
       # A String becomes one text part (two at +split+, the mark on the
       # first); an Array gets the mark on its last text part (the last part
       # when none is text).
-      def marked(message, split: nil)
+      def marked(message, breakpoint, split: nil)
         content = message[:content]
         if content.is_a?(String)
           if split.is_a?(Integer) && split.positive? && split < content.length
-            return message.merge(content: [{ type: "text", text: content[0, split], cache_control: CONTROL },
+            return message.merge(content: [{ type: "text", text: content[0, split], cache_control: breakpoint },
                                            { type: "text", text: content[split..] }])
           end
 
-          return message.merge(content: [{ type: "text", text: content, cache_control: CONTROL }])
+          return message.merge(content: [{ type: "text", text: content, cache_control: breakpoint }])
         end
 
         target = content.rindex { |part| part.is_a?(Hash) && (part[:type] || part["type"]).to_s == "text" } ||
@@ -96,7 +122,7 @@ module Samagotchi
         part = content[target]
         key = part.key?("type") ? "cache_control" : :cache_control
         parts = content.dup
-        parts[target] = part.merge(key => CONTROL)
+        parts[target] = part.merge(key => breakpoint)
         message.merge(content: parts)
       end
 

data/lib/samagotchi/session.rb

@@ -62,6 +62,15 @@ module Samagotchi
     # "ended_at" => iso8601, "seconds" => Float, "origin" =>
     # "client"|"reminder"|"delegate"}; nil before the first turn.
     attr_accessor :last_turn
+
+    # The hook that stopped the last turn (stop_turn, or a cut with no retry
+    # left), e.g. "loop-guard"; nil when it ended otherwise. Both strings
+    # and symbols are read (the file's keys are strings).
+    def stopped_by
+      return nil unless @last_turn.is_a?(Hash)
+
+      (@last_turn["stopped_by"] || @last_turn[:stopped_by])&.to_s
+    end
     # Archived (ArchiveStore): hidden from the lists. Set by .list (with
     # include_archived); not saved in session.json.
     attr_accessor :archived

data/lib/samagotchi/session_manager.rb

@@ -259,12 +259,13 @@ module Samagotchi
     # @param include_archived [Boolean] archived sessions too
     # @return [Array<Hash>] {id:, short_id:, desc:, preview:, cwd:, project:,
     #   updated_at:, status:, live:, busy:, owner:, recap:, parent_id:,
-    #   parent_short_id:, archived:, scratch:, test_run:, waiting:, waiting_id:}; busy = live with
+    #   parent_short_id:, archived:, scratch:, test_run:, waiting:, waiting_id:, stopped_by:}; busy = live with
     #   a turn running, recap = the saved recap's first sentence, project =
     #   Session#project_root, waiting = the kind of question it waits on
     #   ("question", "approval", "hook"; Session#waiting_question) or nil,
     #   waiting_id = that question's id or nil, relayed_to = the parent
-    #   whose card it waits in too (the approval relay), its short id, or nil
+    #   whose card it waits in too (the approval relay), its short id, or nil,
+    #   stopped_by = the hook that stopped the last turn (Session#stopped_by)
     def self.session_summaries(live: false, cwd: nil, limit: nil, include_tests: true, exclude: nil, state_dir: nil,
                                project_root: nil, include_archived: false, sort: nil, order: nil)
       sd = state_dir || Session.default_state_dir
@@ -284,7 +285,7 @@ module Samagotchi
           owner: owner&.kind, recap: RecapStore.preview(Session.session_dir(s.id, state_dir: sd)),
           ctx_pct: SessionMetrics.saved_context_pct(Session.session_dir(s.id, state_dir: sd))&.round(1),
           parent_id: s.parent_id, parent_short_id: s.parent_id&.[](0, 8), archived: s.archived,
-          scratch: s.scratch, test_run: s.test_run }.merge(waiting_fields(s.waiting_question(live: owned)))
+          scratch: s.scratch, test_run: s.test_run, stopped_by: s.stopped_by }.merge(waiting_fields(s.waiting_question(live: owned)))
       end
       (limit ? summaries.first(limit) : summaries.to_a)
     end

data/lib/samagotchi/sessions_command.rb

@@ -112,6 +112,28 @@ module Samagotchi
       options.to_h { |key, value| [key, INTEGER_OPTIONS.include?(key) ? value.to_i : value] }
     end
 
+    # The flags a list row carries: a chi scratch session, a test run, an
+    # archived one, and the turn's stopper (see #stopped_flag).
+    def session_flag(scratch:, test_run:, archived:, stopped_by: nil)
+      flag = if scratch
+               " [scratch]"
+             else
+               (test_run ? " [test]" : "")
+             end
+      flag += " [archived]" if archived
+      flag + stopped_flag(stopped_by)
+    end
+
+    # The marker for a turn a hook stopped: "[looped]" for loop-guard (the
+    # bundle's thinking watch, and the word `chi sessions stats` uses for its
+    # cuts), "[stopped by X]" for any other hook; "" otherwise. A cut with no
+    # retry left records the same stopped_by.
+    def stopped_flag(by)
+      return "" if by.to_s.empty?
+
+      by.to_s == "loop-guard" ? " [looped]" : " [stopped by #{by}]"
+    end
+
     def list
       format, scope, cwd = @opts.values_at(:format, :scope, :cwd)
       unless format.nil? || %w[text json tsv].include?(format)
@@ -156,7 +178,7 @@ module Samagotchi
         # id, for chi answer --question; relayed_to: the parent session (short
         # id) whose card it also waits in (the approval relay), or nil
         keys = %i[id short_id desc cwd project updated_at live busy owner recap parent_id archived scratch ctx_pct waiting
-                  waiting_id relayed_to]
+                  waiting_id relayed_to stopped_by]
         @stdout.puts JSON.generate(summaries.map { |summary| summary.slice(*keys) })
       when "tsv"
         summaries.each { |summary| @stdout.puts "#{summary[:id]}\t#{summary[:desc]}" }
@@ -176,12 +198,8 @@ module Samagotchi
           end
           # A delegated session points at its parent.
           child = summary[:parent_short_id] ? "  ↳ #{summary[:parent_short_id]}" : ""
-          flag = if summary[:scratch]
-                   " [scratch]"
-                 else
-                   (summary[:test_run] ? " [test]" : "")
-                 end
-          flag += " [archived]" if summary[:archived]
+          flag = session_flag(scratch: summary[:scratch], test_run: summary[:test_run], archived: summary[:archived],
+                              stopped_by: summary[:stopped_by])
           ctx = Samagotchi::SessionMetrics.context_label(summary[:ctx_pct])
           @stdout.puts "#{summary[:id]}  #{state.ljust(8)}  #{ctx.ljust(8)}  #{summary[:updated_at]}  #{desc}#{flag}#{child}"
         end
@@ -209,12 +227,7 @@ module Samagotchi
       end
       # A delegated session points at its parent: ↳ <parent's short id>.
       row = lambda do |s|
-        flag = if s.scratch
-                 " [scratch]"
-               else
-                 (s.test_run ? " [test]" : "")
-               end
-        flag += " [archived]" if s.archived
+        flag = session_flag(scratch: s.scratch, test_run: s.test_run, archived: s.archived, stopped_by: s.stopped_by)
         child = s.parent_id ? "  ↳ #{s.parent_id[0, 8]}" : ""
         # How full the context was after the last turn: "ctx 12%", blank when unknown.
         ctx = Samagotchi::SessionMetrics.context_label(

data/lib/samagotchi/terminal_ui/repl_input.rb

@@ -94,6 +94,19 @@ module Samagotchi
       # @return [Boolean] whether it went in
       def prefill(text) = open? && @reader.prefill(text)
 
+      # What the open prompt holds, nil when none is open: a line typed
+      # ahead there is the next turn's input.
+      def typed_text = @reader&.typed_text
+
+      # Whether the next turn's input is already here: text typed ahead at
+      # the open prompt, or a line a turn took as steering but never merged
+      # (it runs as the next turn).
+      def waiting_input?
+        @lock.synchronize { return true unless @front.empty? }
+
+        !typed_text.to_s.strip.empty?
+      end
+
       # A question answered at the open prompt: the lines submitted from now
       # on go to it, at the ? prompt. What was typed at the prompt is put aside
       # and comes back once the question closes.

data/lib/samagotchi/terminal_ui.rb

@@ -175,6 +175,11 @@ module Samagotchi
       @engine.interface = @non_interactive ? :non_interactive : :repl
       # A --non-interactive run exits after its turn: no turn-end warm-up.
       @engine.next_turn_waiting = -> { true } if @non_interactive
+      # A warm-up never pays off while a line typed ahead at the open prompt
+      # (or a left-over steer) already forms the next turn: only prefill when
+      # the prompt is empty. The REPL-only check composes with the one above.
+      next_waiting = @engine.next_turn_waiting
+      @engine.next_turn_waiting = -> { @repl_input&.waiting_input? || next_waiting&.call }
       @turn_flow = TurnFlow.new(engine: @engine)
       # A recap written while a continue offer waits says the turn stopped
       # unfinished. (Answering at the prompt is typing: activity already.)

data/lib/samagotchi/turn_note.rb

@@ -143,7 +143,7 @@ module Samagotchi
     def cut_retry(by, reason)
       why = reason.to_s.strip.empty? ? "" : ": #{one_line(reason)}"
       retry_nudge(message("your last reply was cut off by #{by || "a plugin"}#{why}. Don't start the same reasoning " \
-                          "again; answer the user's last message now, briefly."))
+                          "again; continue the task with your next tool call, or answer if it is done."))
     end
 
     # A retry nudge is marked, so the spent one is found by the mark

data/lib/samagotchi/version.rb

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

data/lib/samagotchi/vision_context.rb

@@ -66,8 +66,10 @@ module Samagotchi
 
   # Which images of a conversation one request sends. Every image that is
   # not sent becomes a placeholder line: all of them when the model can't
-  # see images, the older ones past limits.max_per_request (the newest go),
-  # and any whose file is gone.
+  # see images, the oldest ones past limits.max_per_request, and any whose
+  # file is gone. Past the limit the oldest images are dropped in batches
+  # (ImagePlan.dropped_count), so the cut stays put for a few new images
+  # and the history before it stays a cacheable prefix.
   class ImagePlan
     Item = Data.define(:ref, :data, :placeholder) do
       def sent? = !data.nil?
@@ -92,7 +94,18 @@ module Samagotchi
         Array(entry[:images]).each_index { |position| occurrences << [index, position] }
       end
       @limit = vision&.limits&.max_per_request || ImageStore::Limits.from_config.max_per_request
-      @sent = occurrences.last(@limit)
+      @sent = occurrences.drop(self.class.dropped_count(occurrences.size, @limit))
+    end
+
+    # How many of +total+ images (oldest first) a request leaves out with
+    # +limit+ per request: none up to the limit, then whole steps of
+    # limit/2, so it's a pure function of the count. With limit 20, 21..30
+    # images drop the oldest 10, 31..40 the oldest 20.
+    def self.dropped_count(total, limit)
+      return 0 if total <= limit
+
+      step = [limit / 2, 1].max
+      (((total - limit) + step - 1) / step) * step
     end
 
     # The Items for conversation[+index+] (none when it has no images).
@@ -120,7 +133,7 @@ module Samagotchi
     def skip_reason(index, position)
       return "no session images here" if @vision.nil?
       return CANT_SEE unless @vision.sendable?
-      return "only the newest #{@limit} images are sent" unless @sent.include?([index, position])
+      return "an older image (chi sends up to the newest #{@limit})" unless @sent.include?([index, position])
 
       nil
     end

data/lib/samagotchi/web/public/task_stop.js

@@ -54,10 +54,24 @@ export function createTaskStopper({
   alert = (text) => globalThis.alert(text),
 }) {
   const inFlight = new Set();
+  const watchers = new Map(); // key -> Set of fn(busy)
   const keyOf = (taskId) => `${sessionId()}|${taskId}`;
+  const notify = (key, busy) => watchers.get(key)?.forEach((fn) => fn(busy));
   return {
     target: (row) => stopTarget(row, features()),
     busy: (taskId) => inFlight.has(keyOf(taskId)),
+    // Call +fn+ whenever a stop for +taskId+ starts or ends (the key enters
+    // or leaves the in-flight set) — the session's own task, on this session.
+    // Returns unwatch. A task drawn in two rows (the stage's "now" slot and
+    // the step list) so both buttons stay in step; a watcher for a button
+    // that is gone unwatches itself.
+    watch(taskId, fn) {
+      const key = keyOf(taskId);
+      let set = watchers.get(key);
+      if (!set) watchers.set(key, (set = new Set()));
+      set.add(fn);
+      return () => set.delete(fn);
+    },
     // true once the worker stopped it. A stop that went through stays in
     // flight: the button goes with its row's completion a moment later.
     async stop(taskId, command = null) {
@@ -65,11 +79,13 @@ export function createTaskStopper({
       const key = keyOf(taskId);
       if (!id || inFlight.has(key) || !confirm(confirmText(taskId, command))) return false;
       inFlight.add(key);
+      notify(key, true);
       try {
         await stopTask(id, taskId);
         return true;
       } catch (e) {
         inFlight.delete(key);
+        notify(key, false);
         if (!quietFailure(e)) alert(e.message);
         return false;
       }
@@ -79,7 +95,10 @@ export function createTaskStopper({
 
 // The button itself (the one DOM part): a click asks, posts, and keeps it
 // disabled while the stop is in flight. +command+ is read at the click;
-// +onChange+ lets a view redraw (the stage's slot).
+// +onChange+ lets a view redraw (the stage's slot). It also watches the
+// task's in-flight state, so a stop started from a second button of the
+// same row (the stage draws one in the "now" slot and one in the step
+// list) disables this one too — a button that is gone unwatched.
 export function taskStopButton(stopper, taskId, { command = () => null, onChange = () => {} } = {}) {
   const btn = document.createElement("button");
   btn.type = "button";
@@ -87,6 +106,10 @@ export function taskStopButton(stopper, taskId, { command = () => null, onChange
   btn.textContent = "stop task";
   btn.title = "Kill this background task; the model is told you stopped it";
   btn.disabled = stopper.busy(taskId);
+  const unwatch = stopper.watch?.(taskId, (busy) => {
+    if (!btn.isConnected) { unwatch(); return; }
+    btn.disabled = busy;
+  });
   btn.addEventListener("click", (e) => {
     e.stopPropagation();
     const pending = stopper.stop(taskId, command());

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samagotchi
 version: !ruby/object:Gem::Version
-  version: 0.27.0
+  version: 0.28.0
 platform: ruby
 authors:
 - Dmitry Dedov