samagotchi 0.26.0 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9914119c74e2e2233fcd5931386afca4fbc95b84aa7603e2f4f14289651a12c
-  data.tar.gz: 5ba92c2703f202dffe2d4125eac11fd9d93c970a032cc56af1ce41c0827ab5ba
+  metadata.gz: 51c7c1a00eec47f70f15b04381eb6b60f5bd6c66c8dd11fbe05ef045c41d5219
+  data.tar.gz: 00cbfcba1b3b21ef54c9d54bd9de349a90a19314cb5613e9daa94ca51c8c04fe
 SHA512:
-  metadata.gz: 881df5c769cb4d5ca994253bf7cccfbbd29d033f51e9f73533cf74926d8d6fe155c8e0e92a7a6226b770dceb4e4a816b1d78dd0ff0b1502938a6e8761a26c8d3
-  data.tar.gz: 0a6c687f219568001c688d385221b239a2f285c66f17895c2202bf77098c40236a42cd3ca6b824b493260acb698bf6345e715ecaaa8e53ce6368e938c0bb155f
+  metadata.gz: 11f14c97b088efe1c1eafafb63604f44c84a7a7a79d738db5f6344191b6fa9948ceab37acd0f8daba2a85840b3f272bfcd767bd2147b0da7abbc23a04936bba4
+  data.tar.gz: e3136af1decc273b092f66756e2994ad0760a626cb9b007a4a4ad2f68ee85bdf6f37aab3f5a0bde85597f677bde3fde32826763c9b44001e941945abc39dfa5d

data/CHANGELOG.md

@@ -8,6 +8,58 @@ 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
+
+- Web: a "stop task" button on a running `task_wait` stops the background task; the turn goes on and the model is
+  told the user stopped it (Cancel still cancels the turn and leaves the task running).
+
+### Changed
+
+- `/mcp` lists each server's tools alphabetically, not in the order the server sent them (mcp bundle 0.4.3).
+
+### Fixed
+
+- A stopped background task ends as `stopped`, not `failed`, and records who stopped it (the user or the model).
+- Code blocks in the web follow the light theme too: their highlighting comes from the page's palette instead of one
+  fixed dark theme.
+
+Update with `chi update` (mcp 0.4.3).
+
 ## [0.26.0] - 2026-10-04
 
 ### Added
@@ -1419,7 +1471,9 @@ 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.26.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
 [0.24.0]: https://github.com/dm1try/samagotchi/compare/v0.23.0...v0.24.0

data/docs/architecture.md

@@ -246,6 +246,12 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   `guardrails.parent_approvals` is `403 parent_approval_refused`, the question still open.
 - `POST /session/:id/question/dismiss` — leave the question unanswered (an approval: denied);
   `200`, or `409` when it is no longer pending.
+- `POST /session/:id/tasks/stop` — `{task_id}`: stop a background task as the user
+  (`TaskRuntime.stop_task by: "user"`, the web's stop-task button on a running `task_wait`;
+  web route `POST /api/sessions/:id/tasks/:task_id/stop`). Only a task this conversation's
+  `task_create` started (the saved messages, or the running turn's accumulator); answers once the
+  task is gone: `200 {status, stop_reason, task_id}`, `404 task_not_found`, `409 not_running`.
+  The worker names it in its sidecar features (`task_stop`).
 - `POST /session/:id/relay` — the approval relay, on a delegated child's worker
   (`{action, relay_id, question_id}`): `opened` / `closed` (with a `reason`) set or clear the
   pending question's `relayed_to` mark (`QuestionDesk#annotate`, `:question_relay`); `answered`

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/hooks.md

@@ -56,7 +56,7 @@ The plugin class must respond to `#call(event)` — duck-typed, no base class re
 | `:after_generation` | After LLM returns (both loops); not after a generation a hook cut (`stop_generation`) | `{ type: :after_generation, iteration: N, response: "...", messages: [...] (the conversation as sent) }` |
 | `:generation_progress` | While the response streams, in batches (see [Watching the stream](#watching-the-stream)) | `{ type: :generation_progress, iteration: N, thinking: "..." (new since the last fire), text: "..." (new visible text), thinking_chars: N, text_chars: N (this generation so far), elapsed_ms: N }` |
 | `:before_tool_call` | Before tool dispatch (and before `tool_call_started`) | `{ type: :before_tool_call, iteration: N, call: {...}, params: "...", guardrail: Verdict, context: {...}, targets: {...}, blocked: false, block_reason: nil }` |
-| `:after_tool_call` | After tool execution | `{ type: :after_tool_call, iteration: N, tool: "read", output: "..." (capped at max_tool_output_chars), status: "ok" \| "error" \| "blocked" \| "stopped" }` |
+| `:after_tool_call` | After tool execution | `{ type: :after_tool_call, iteration: N, tool: "read", output: "..." (capped at max_tool_output_chars), status: "ok" \| "error" \| "blocked" \| "stopped" }`; `stopped` is a `task_wait` the turn's Stop ended (the task runs on) or whose task was stopped |
 | `:session_end` | After each turn `:after_turn` fires for, after it (turn-level lifecycle) | `{ type: :session_end, session_id: "..." }` |
 
 Every event also carries the hook runtime (next section): `hook:` (the label

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/bridge.rb

@@ -27,6 +27,8 @@ require_relative "version"
 require_relative "worker_sidecar"
 require_relative "relay_verifier"
 require_relative "relay_watcher"
+require_relative "tools/task_create"
+require_relative "tools/task_runtime"
 
 module Samagotchi
   # Bridge is an optional HTTP transport that lets an external web / desktop
@@ -461,7 +463,8 @@ module Samagotchi
     # sidecar (WorkerSidecar#features): a client checks a name here rather
     # than a version.
     # restart: POST /exit takes "restart": true (WorkerIdleExit#hold_for_restart).
-    FEATURES = ["restart"].freeze
+    # task_stop: POST tasks/stop (#handle_task_stop), the web's stop-task button.
+    FEATURES = %w[restart task_stop].freeze
 
     # The routes, by method and what follows /session/:id/: a handler takes
     # the session id and the request body and returns [headers, status, body].
@@ -477,6 +480,7 @@ module Samagotchi
       %w[POST recap] => :handle_recap,
       %w[POST relay] => :handle_relay,
       %w[POST relay/status] => :handle_relay_status,
+      %w[POST tasks/stop] => :handle_task_stop,
       %w[GET state] => :handle_state,
       %w[GET stats] => :handle_stats,
       %w[GET snapshot] => :handle_snapshot,
@@ -539,6 +543,38 @@ module Samagotchi
       end
     end
 
+    # POST /session/:id/tasks/stop {task_id}: stop a background task as the
+    # user (TaskRuntime.stop_task by: "user"); a task_wait on it returns, and
+    # the turn goes on. Only a task this conversation created: records in
+    # tmp/tasks are shared by every session in the cwd. Those are in the
+    # saved conversation, or, created in the running turn, only in the
+    # accumulator's task_create parts. 200 {status, stop_reason, task_id},
+    # 404 task_not_found, 409 not_running (it already ended), 400 no id.
+    # Answers once the task is gone: up to STOP_GRACE_SEC.
+    def handle_task_stop(_session_id, body)
+      parsed = parse_json(body)
+      task_id = (fetched(parsed, "task_id") if parsed.is_a?(Hash)).to_s.strip
+      return [{ "Allow" => "POST" }, 400, { error: "missing_fields", detail: "task_id required" }] if task_id.empty?
+      return [{}, 404, { error: "task_not_found", task_id: task_id }] unless own_task_ids.include?(task_id)
+
+      record, error = Tools::TaskRuntime.get_record(task_id)
+      return [{}, 404, { error: "task_not_found", task_id: task_id }] if error
+      return [{}, 409, { error: "not_running", status: record["status"], task_id: task_id }] unless record["status"] == "running"
+
+      Log.info(:bridge, "task_stop", task_id: task_id)
+      record, error = Tools::TaskRuntime.stop_task(task_id, by: "user")
+      return [{}, 500, { error: "bridge_error", detail: error }] if error
+
+      [{}, 200, { status: record["status"], stop_reason: record["stop_reason"], task_id: task_id }]
+    end
+
+    def own_task_ids
+      running = Array(@accumulator.current_turn&.dig(:parts)).filter_map do |part|
+        part[:output].to_s[/\A(?:\[task_create\]\n)?task_id: (\S+)/, 1] if part[:kind] == "tool" && part[:tool] == Tools::TaskCreate::NAME
+      end
+      Tools::TaskRuntime.created_ids_in(@engine.messages_checkpoint) | running
+    end
+
     # Answer the pending question. A past +deadline+ (see #handle_post_turn):
     # 408 deadline_passed, and the question stays open. An answer takes no
     # event hold, so it is checked right before it is recorded.

data/lib/samagotchi/bridge_client.rb

@@ -187,6 +187,15 @@ module Samagotchi
       post("cancel", { reason: reason }, read_body: true)
     end
 
+    # POST /session/:id/tasks/stop: stop a background task this session's
+    # conversation created, as the user (Bridge#handle_task_stop). 200 with
+    # its final status, 404 task_not_found, 409 not_running. Synchronous:
+    # the worker answers once the task is gone (up to its 3 s grace).
+    # @return [Response]
+    def stop_task(task_id)
+      post("tasks/stop", { task_id: task_id }, read_body: true)
+    end
+
     # How long the approval relay's calls wait for a reply: a parent's Stop
     # isn't held for READ_TIMEOUT by a child that doesn't answer.
     RELAY_TIMEOUT = 5

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

@@ -1,11 +1,11 @@
 ---
 name: mcp
-version: 0.4.2
+version: 0.4.3
 scope: system
 description: "Tools from MCP servers (stdio): each server in config.yml bundles: mcp: servers: runs for the session, its tools are mcp_<server>_<tool>; /mcp lists them"
 trust_level: reviewed
 files: {}
 plugin:
   file: plugin.rb
-  sha256: sha256:d0491b038e7f111f9f8c629729a2b0525d573fd0b17d48ea8ec59c4a2b8b821b
+  sha256: sha256:079a42892f10822115235e1ced7ccd481f80c9ef54abb094f9a1c599bb03e8e2
 requires_chi: ">= 0.8.0"

data/lib/samagotchi/bundles/mcp/plugin.rb

@@ -752,7 +752,8 @@ class Plugin
 
     @servers.map do |server|
       head = "**#{server.name}**: #{state_text(server)}"
-      tools = server.tools.map { |tool| tool["chi_name"] }.compact
+      # Sorted: a server lists its tools in its own (often grouped) order.
+      tools = server.tools.map { |tool| tool["chi_name"] }.compact.sort
       tools.empty? ? head : "#{head}\n#{tools.map { |t| "- `#{t}`" }.join("\n")}"
     end.join("\n\n")
   end

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

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.26.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