samagotchi 0.24.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d6348260d3f666ffbfc0b8c3f10a51a2c64c3a30ce9cbd5a5c1280fa0325306
-  data.tar.gz: 0cad64155e27a000a49c82e89778d69804fc609526418c1e03846a32d2fb864c
+  metadata.gz: d9914119c74e2e2233fcd5931386afca4fbc95b84aa7603e2f4f14289651a12c
+  data.tar.gz: 5ba92c2703f202dffe2d4125eac11fd9d93c970a032cc56af1ce41c0827ab5ba
 SHA512:
-  metadata.gz: b9a1f022f8a225c517e3160d0d512fbb5a97750c32a6df7769bbcb91ddff5534c5b12f540c4ef80871d8e4f2f80d460c71cd56107476435a69d54cef0ef78395
-  data.tar.gz: 419a527ffca2330de67b42544f619db872c06388ded821d3bc5e7f17f07a488a7adf96ce56d55032a53c4bc21e6076d32af398c0b8aff15c48e651e6596e7873
+  metadata.gz: 881df5c769cb4d5ca994253bf7cccfbbd29d033f51e9f73533cf74926d8d6fe155c8e0e92a7a6226b770dceb4e4a816b1d78dd0ff0b1502938a6e8761a26c8d3
+  data.tar.gz: 0a6c687f219568001c688d385221b239a2f285c66f17895c2202bf77098c40236a42cd3ca6b824b493260acb698bf6345e715ecaaa8e53ce6368e938c0bb155f

data/CHANGELOG.md

@@ -8,6 +8,83 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.26.0] - 2026-10-04
+
+### Added
+
+- The web has a light theme: with the system set to light it follows (`prefers-color-scheme`). There is no
+  in-page switch yet. Native radios, inputs and scrollbars now follow the theme, so they are dark in dark mode.
+- On a local llama.cpp host, the next turn starts faster: when a turn ends, chi sends the next turn's prompt (up to
+  your next message) in the background, so the server has it ready while you read. `cache.warmup: off` turns it
+  off; remote and paid hosts never get it.
+
+### Changed
+
+- `execute`'s `description` parameter now says it is shown to the user as the step's title and asks for it on
+  every call (still optional), so models, Sonnet in particular, now label execute steps.
+- loop-guard (bundle 0.3.4) words a loop its short run or its window found by the different sentences it held,
+  `12 different sentences in 48`, instead of `12 sentences ×4`, which read as a cycle of 12.
+- `sampling:` can't set llama.cpp's `id_slot` (pinning a session to a slot made the next turn re-read the whole
+  prompt).
+
+### Fixed
+
+- `thinking_tails.jsonl` names the plugin that stopped a turn instead of "hook".
+
+Update with `chi update` (loop-guard 0.3.4).
+
+## [0.25.0] - 2026-10-04
+
+### Added
+
+- The web shows an `execute` command as the steps a person reads: `cd X &&` becomes an "in X" tag, `| head -20` a
+  chip, `echo "=== x ==="` a label, a heredoc a collapsed "EOF · N lines" chip; the collapsed row's title is the
+  first step `+N`. A `raw` toggle shows the whole command; anything the parser can't read shows as before.
+- `execute` takes an optional `description` ("what the command does, in a few words"), written by the model; it
+  becomes the tool row's title in the web and replaces the cut command in the terminal's tool line. Turn it off
+  with `execute.description: false`.
+- Every generation logs its prompt-cache counts (`prompt=`, `cached=`, `cache_write=`), and `/stats` shows cache
+  writes next to cached tokens.
+- A generation cut mid-thinking (loop-guard, a plugin's stop, a steer) or ended at the provider's output cap keeps
+  the last 20k chars of its thinking in the session's folder, `thinking_tails.jsonl`, so an archived session holds
+  the loop it was archived for. The model never sees it.
+- Turn records count `cuts` (generations a plugin cut) and `capped` (generations that hit the output cap), and
+  `/stats` shows them as "thinking cuts" and "output cap hits": `retries` counts network retries only.
+
+### Changed
+
+- On macOS, `execute`, `task_create` and `!cmd` run commands in `/bin/zsh` emulating sh (with bash's `{1..3}`,
+  `[[ =~ ]]` groups and echo escapes kept) instead of `/bin/sh`, which is bash 3.2 there and failed on an apostrophe
+  in a heredoc inside `"$( )"`: `git commit -m "$(cat <<'EOF' … it's … EOF )"` now works. Linux keeps
+  `/bin/sh`; see [background tasks](docs/internals/background-tasks.md).
+- loop-guard's cut notice (bundle 0.3.3) quotes the looping sentence: `thinking repeats itself ("Let me write the
+  tool call.", one sentence ×8, 33k chars, 63 s): cut`.
+- The system prompt puts what every session shares first and the per-session lines (model, working directory,
+  session) last, and plugin tools come in a fixed order, so a new session reuses the server's prompt cache: on a
+  local llama.cpp or Splash server its first answer starts in about 0.5 s instead of 4–6 s, and on Claude via
+  OpenRouter a new session reads the shared part from the cache (about 7× cheaper to start).
+- Chat hosts (`api: openai`) are no longer asked for `temperature: 0.0`: chi sends no temperature unless one is
+  configured, so each model runs at its provider's default (as native llama.cpp hosts already did). Greedy decoding
+  made DeepSeek v4.1-flash loop in its thinking. The idle recap and `/btw` follow suit. Set `sampling: {temperature:
+  …}` on a `hosts:` or `models:` entry to pin one; the empty-answer retry still runs at 0.6 unless one is set.
+
+### Fixed
+
+- loop-guard (bundle 0.3.3) cuts thinking that loops in a cycle of 7 or 8 short sentences, or with a longer
+  sentence ("I'll write the spec file now.") in the cycle: 48 sentences in a row with 12 or fewer different ones are
+  a loop. New settings `thinking.window_sentences` (48) and `thinking.window_distinct` (12).
+- A steer row names chi's senders in words: the web's row and trail flash and the terminal's nudged line say
+  `parent agent`, `chi send` and `plugin` instead of the raw `parent_agent` / `chi_send` / `plugin_send`.
+- Thinking off on Gemma 4 no longer warns that off wasn't honoured: its empty thought (whitespace alone) is not
+  counted as thinking.
+- An OpenRouter 402 whose `metadata.reason` is `weight_exceeds_budget` (the request alone is larger than the
+  key's credit budget) fails at once as `request too large for the credit budget on host <name>: …; lower
+  max_tokens (default.max_tokens) or raise the key's credit limit`, instead of being retried as credit held by
+  in-flight requests. Other 402s are unchanged.
+
+Update with `chi update`: loop-guard moves to 0.3.3 (the window rule and the quoted cut notice). Restart `chi web`
+and running sessions afterwards (`chi sessions restart ID`).
+
 ## [0.24.0] - 2026-10-04
 
 ### Added
@@ -1342,7 +1419,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.24.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.26.0...HEAD
+[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
 [0.23.0]: https://github.com/dm1try/samagotchi/compare/v0.22.0...v0.23.0
 [0.22.0]: https://github.com/dm1try/samagotchi/compare/v0.21.0...v0.22.0

data/docs/architecture.md

@@ -184,12 +184,18 @@ engine.system_prompt     # fully built system prompt string
 engine.session           # current session (Engine owns create/resume)
 ```
 
-The system prompt (`SystemPrompt#build`) is the base prompt, then rg guidance,
-AGENT.md, the working directory, **the model** (`Model: this session runs on
-<ref> (host …; model key …)` and a line telling the model to answer "which model
-are you" from it, not from training), the session id and log, the memory indexes,
-the identity and the preloaded memories. It is built once per loop and rebuilt only
-by a model switch (or changed tools), so the model line costs no KV churn.
+The system prompt (`SystemPrompt#build`) is the base prompt, then rg guidance, the
+identity and the preloaded memories, AGENT.md, the memory indexes, and last **the
+model** (`Model: this session runs on <ref> (host …; model key …)` and a line telling
+the model to answer "which model are you" from it, not from training), the working
+directory and the session id and log (Gemma's native tool declarations still follow).
+The order is for the servers' prompt caches, which reuse only an exact token prefix:
+what every session shares first, what changes least before what changes more, the
+per-session lines last, so a new session reuses everything above them. It is built
+once per loop and rebuilt only by a model switch (or changed tools), so the model
+line costs no KV churn.
+The full request layout, what breaks the cache and the rules for changes:
+[internals/prompt-caching.md](internals/prompt-caching.md).
 
 #### Subscribing to the live stream (and the bridge)
 
@@ -275,11 +281,12 @@ The metrics in `/state`, `/snapshot`, `/stats` and the SSE `snapshot`/`reset` fr
 newest turn the worker finished and any it hasn't saved yet (at most 20 turns), with their tool
 calls and the running turn's finished ones. The full history is the session's `analytics.json`,
 which `SessionMetrics#persist` rewrites after each turn; the web server merges the two by id.
-The totals' `tokens` block adds the cached and reasoning sums, the cost, the decode time and tokens
+The totals' `tokens` block adds the cached, cache-write and reasoning sums, the cost, the decode time and tokens
 behind the average speed (`avg_decode_tps`) and the last speeds (`last_decode_tps`,
 `last_prefill_tps`, `tps_source`: `server` or `estimate`). Each `generation_completed` event
-carries the generation's `speed` (`{decode_tps, source}`, null without one) and those running
-`tokens`: the Engine closes the generation in `SessionMetrics#finish_generation` before relaying
+carries the generation's `speed` (`{decode_tps, source}`, null without one), its own prompt-cache
+counts (`prompt_tokens`, `cached_tokens`, `cache_write_tokens`: null when the server reported no writes) and
+those running `tokens`: the Engine closes the generation in `SessionMetrics#finish_generation` before relaying
 it, so the web's info bar updates per generation without parsing chunk payloads.
 
 The page's frequent reads of `GET /api/sessions/:id` stay light too:

data/docs/cli.md

@@ -420,9 +420,10 @@ file and index line stay as they are; only this session doesn't see it.
 `/help` lists the commands this session takes, the installed bundles' too, each
 with a line on what it does. `/stats` shows the session's numbers: turns, tool
 calls (by tool, with errors), iterations, tokens in/out summed over every
-request (with the cached and reasoning tokens when the server reports them),
-the decode speed, generation latency, cancellations, retries, context used
-and window, the prompt profile and the model the server says it ran, and the
+request (with the cached tokens, the cache writes and the reasoning tokens when the server reports them),
+the decode speed, generation latency, cancellations, retries (the network's),
+thinking cuts (generations a plugin such as loop-guard cut) and output cap hits
+(generations that ended at the provider's cap), context used and window, the prompt profile and the model the server says it ran, and the
 cost when the provider reports one (OpenRouter's `usage.cost`; no prices are
 guessed). The speed line is the last generation's and the session's average
 (weighted by tokens): llama.cpp reports it exactly (`87 tok/s out, 1.9k tok/s

data/docs/configuration.md

@@ -369,9 +369,9 @@ after an idle exit) gets that process's environment, so put a lasting choice in
 
 ## Sampling
 
-chi asks chat hosts (`api: openai`) for greedy decoding (`temperature: 0.0`) and sends native hosts no sampling
-fields, so their server's defaults apply (llama.cpp: temperature 0.8). `sampling:` on a `hosts:` entry or a `models:`
-entry sets request fields for the model's turns:
+chi sends no sampling fields by default, to chat hosts (`api: openai`) or native ones, so each model runs at its
+provider's defaults (llama.cpp: temperature 0.8; vLLM takes them from the model's `generation_config.json`).
+`sampling:` on a `hosts:` entry or a `models:` entry sets request fields for the model's turns:
 
 ```yaml
 hosts:
@@ -394,15 +394,16 @@ models:
 - A `models:` entry's fields win over its host's, field by field (the host can set a penalty and the model move only
   the temperature). The entry is found the way `profile:` is (the name as typed, alias-resolved or without its host
   prefix).
-- `temperature: null` (or `~`) sends no temperature, so the provider's default applies (vLLM takes it from the
-  model's `generation_config.json`).
+- `temperature: null` (or `~`) in a model's entry takes back a host's temperature, so the provider's default applies;
+  it also keeps the empty-answer retry (below) at that default.
 - Fields chi sets itself are refused with a warning: `model`, `messages`, `prompt`, `stream`, `stream_options`,
   `tools`, `tool_choice`, `stop`, `n_predict`, `max_tokens`, `n`, `parallel_tool_calls`, `response_format`,
   `cache_prompt`. A `sampling:` that isn't a map warns and is skipped.
-- Greedy decoding can make a heavily quantized thinking model loop in its reasoning ("Let me write the reply…"
-  for minutes) or end with an empty answer. Qwen's own advice for its thinking models is `temperature: 0.6,
-  top_p: 0.95` (not greedy), with `presence_penalty` between 0 and 2 against endless repetition.
-- The idle recap and side questions keep their own short, deterministic settings.
+- Greedy decoding (`temperature: 0`) can make a thinking model loop in its reasoning ("Let me write the reply…"
+  for minutes) or end with an empty answer; set it only for a model you have watched. Qwen's own advice for its
+  thinking models is `temperature: 0.6, top_p: 0.95`, with `presence_penalty` between 0 and 2 against endless
+  repetition.
+- The idle recap and side questions don't use `sampling:`; they send their own short output cap and no temperature.
 
 `/model` shows what applies (`sampling: temperature=0.6 presence_penalty=1.5 (hosts.work)`), and each request's
 `stream` line in the debug log carries a `sampling=` field with what was sent. The fields are read every turn, so a
@@ -514,10 +515,14 @@ gateway that spreads requests over several providers can key on it to keep one c
 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
+OpenAI-compatible host get two prompt-cache breakpoints (`cache_control` on the system prompt and on the last
+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`.
+cached tokens in `/stats`. 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`.
 
 ## Llama Model Routing
 
@@ -616,6 +621,8 @@ Transient network failures are retried automatically with exponential backoff.
 - 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.
+  Not when its `metadata.reason` is `weight_exceeds_budget`: that request alone is larger than the key's credit
+  budget, so it fails at once (lower `default.max_tokens` or raise the key's limit).
 - 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.
@@ -671,7 +678,7 @@ 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 |
+| credits | any other HTTP 402: out of credits; one whose `metadata.reason` is `weight_exceeds_budget` (the request alone is over the key's budget: lower `default.max_tokens`) | 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 |
@@ -891,6 +898,7 @@ described in their own sections.
 | `models.<key>.thinking`, `hosts.<name>.thinking` | none | | A model's or host's level. See "Thinking". |
 | `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). |
 | `retry.max` | `5` | yes | See "Llama Network Retry Behavior". |
 | `retry.base_delay` | `0.5` | yes | |
 | `retry.max_delay` | `8.0` | yes | |
@@ -912,6 +920,7 @@ described in their own sections.
 | `execute.preview_bytes` | `12288` | yes | |
 | `execute.telemetry_threshold_pct` | `80` | yes | |
 | `execute.timeout_sec` | `120` | yes | Seconds one `execute` command may run before it is stopped. |
+| `execute.description` | `true` | | `execute` offers the model an optional `description` (a few words on what the command does), shown as the tool row's title in `chi web` and in place of the command in the TUI's tool line. `false`: the parameter isn't declared, and rows show the command's first step. |
 | `web.port` | `4567` | `--port` | `chi web`'s port. See [CLI](cli.md). |
 | `web.host` | `127.0.0.1` | yes | `127.0.0.1`, `::1` or `localhost`; `lan` (this machine's private IPv4 address) or one of its IPv4 addresses also opens `chi web` to the network, with an access token (`chi web --new-token` replaces it). Anything else binds `127.0.0.1` with a warning. See [CLI: chi web on your phone](cli.md#chi-web-on-your-phone). |
 | `web.markdown` | `false` | yes | Render answers as Markdown in `chi web`. |

data/docs/hooks.md

@@ -399,7 +399,7 @@ stripped of surrounding whitespace, except file text, an edit's
 
 | Tool | `content:` from | `path:` from | Own fields |
 |------|-----------------|--------------|------------|
-| `execute` | `command` | — | `cwd` |
+| `execute` | `command` | — | `description`, `cwd` |
 | `read` | `path` | — | `start_line`, `end_line` |
 | `write` | — | `path` | `content` |
 | `edit` | — | `path` | `old_text`, `new_text`, `start_line`, `end_line` |

data/docs/internals/background-tasks.md

@@ -17,6 +17,7 @@ Recommended workflow:
 
 Behavior:
 
+- `execute`, `task_create` and the `!cmd` shell bang run the command in a non-login shell: `/bin/sh -c` on Linux; on macOS, when `/bin/zsh` is there, `/bin/zsh --emulate sh +o ignore_braces +o sh_glob -o bash_rematch +o bsd_echo -c` (macOS's `/bin/sh` is bash 3.2, which can't parse an apostrophe in a heredoc inside `"$( )"`, the usual commit message shape). That mode reads no rc files and keeps POSIX word splitting, unmatched globs left as is, `{1..3}`, `[[ … =~ (…) ]]` with `BASH_REMATCH`, arrays, `$'…'`, `&>` and echo expanding `\t`. Bash-only builtins and variables (`shopt`, `BASH_VERSION`, `${!prefix*}`, `read -p`) are not there.
 - Task metadata and output are persisted under `tmp/tasks/`.
 - Task listing is workspace-scoped (current project only).
 - `task_get` returns metadata and `output_path`; use `read` for output contents.