samagotchi 0.38.0 → 0.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35846da55e0107127da528067ad179a59cbd7a23eee66c1b770a17d1504c717b
-  data.tar.gz: e28ce71127da751668251ddfca44dc8b05a97e038f5d03045357f1cdbac26f20
+  metadata.gz: 15442c0fe342d1193ff595b31c554f886076fc4da7dac938fe319ec784e053c6
+  data.tar.gz: 37e73e8590db29ba273346191954ba96b72de468a46663bc2f8820807d95278d
 SHA512:
-  metadata.gz: b2be4346aaaa73f05518a5b62ffcfca820f94ea571b5524d1d8013224ff43ee1648951e40ee4290f80f088da6ffec4c26c4de6c8a6905ccc83340919173fe330
-  data.tar.gz: 01027d62cb5f9b423196f386c68fc4cbb46d8c73866540e1aacb9778f3a414013a059c5df99df099d528574cb1a5a5d57b0cb764002de0a4524148fd91ad66e8
+  metadata.gz: a7d252dbf3ef0eb6ea34aa61bd47e5da389bf17b5f0f4784c9c0e2bf69d22732e83db29b8652bce40ef7ac4a0593e48bc481eb63b9b86a2485ff4027dac1de5f
+  data.tar.gz: 50d569dc04ca76c690c9f4f91ffcec90d85b54445b07f63d2bab1fc6aed5a47d214d9b400faa9b3915783a10e9952613b1a0b0db6361accb514eb4aab7ad3e67

data/CHANGELOG.md

@@ -8,6 +8,38 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.39.0] - 2026-10-07
+
+### Added
+
+- `llm_context.strategy` (default `none`), and per model or host `llm_context_strategy`. `stale` sends a file read
+  that a later read of the same lines superseded as a one-line stub; the session keeps the output. With
+  `llm_context.stale_edits: true` (opt-in, experimental) a read a later edit or write of the file superseded is
+  stubbed too; on the replay bench these cost about 5x the tokens they free in re-prefill, and 26% were needed again
+  (against a 6% base rate). No read of a file edited in the last `llm_context.protect_steps` (3) steps is stubbed.
+  `llm_context.apply` (and per model or host `llm_context_apply`) says when stubs reach the prompt: `payoff` (the
+  default) sends them at a request when they free at least the tail the server reads again, else at the end of a
+  turn the model answered, which in practice is usually where they go; `next_request` and `turn_end` are the
+  others. See [docs/configuration.md](docs/configuration.md).
+- `/stats` shows the re-prefilled tokens for every session (what the server prefilled again of the previous
+  request's prompt, 128 tokens or more), and the log's `generation_completed` line has them as `reprefill=`.
+- For development: `script/llm_context_bench.rb`, a replay benchmark for the LLM context strategies over a folder of
+  stored sessions (offline; `--live` asks a model, for picks). It isn't part of the gem. See
+  [docs/internals/llm-context-bench.md](docs/internals/llm-context-bench.md).
+
+### Fixed
+
+- Answering a step-limit question with Continue and then sending a prompt runs the continue turn first, even when
+  both arrive while the worker is between turns (the prompt could run first and drop the offer). A session started
+  from another session's `execute` (`chi send`) no longer inherits that session's `SAMAGOTCHI_PARENT_SESSION` and
+  `SAMAGOTCHI_SESSION_MODEL`, so your `!chi context add` there attaches to it, not to the other one. `context_read`
+  pages within `max_tool_output_chars` whatever its header holds, so a page is never cut a second time behind its
+  "Pass offset". The mcp bundle (0.6.1): `mcp_call` with a mistyped `<server>/<tool>` waits only for that server's
+  start, and `find_mcp_tools` names a server with no `description:` or instructions by its tool count, not its first
+  tool names (a model called those without searching).
+
+Update with `chi update` (mcp 0.6.1).
+
 ## [0.38.0] - 2026-10-07
 
 ### Added
@@ -1842,7 +1874,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.38.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.39.0...HEAD
+[0.39.0]: https://github.com/dm1try/samagotchi/compare/v0.38.0...v0.39.0
 [0.38.0]: https://github.com/dm1try/samagotchi/compare/v0.37.0...v0.38.0
 [0.37.0]: https://github.com/dm1try/samagotchi/compare/v0.36.0...v0.37.0
 [0.36.0]: https://github.com/dm1try/samagotchi/compare/v0.35.0...v0.36.0

data/docs/cli.md

@@ -421,7 +421,8 @@ 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 tokens, the cache writes and the reasoning tokens when the server reports them),
+request (with the cached tokens, the cache writes, the re-prefilled tokens 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

data/docs/configuration.md

@@ -535,8 +535,10 @@ cache:
   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`.
+`prompt=` (its prompt tokens), `cached=` (read from the server's cache), `cache_write=` (written to it, when the
+server reports writes) and `reprefill=` (of the previous request's prompt on the same model, what the server
+prefilled again: an `llm_context` edit's cache break, or anything else that rewrote the prompt's middle; only when the
+server reports a cached count, and not on the first request after a warm-up); recap and side requests log theirs as `recap request_usage`.
 
 ## Llama Model Routing
 
@@ -915,6 +917,12 @@ described in their own sections.
 | `context.status` | `true` | yes | Context-usage telemetry for the model. See [context telemetry](internals/context-telemetry.md). |
 | `context.window_tokens` | server's, else 256000 | yes | Context window when the server doesn't report one. `models.<key>.window_tokens` and `hosts.<name>.window_tokens` come first; see "The context window". |
 | `models.<key>.window_tokens`, `hosts.<name>.window_tokens` | none | | A model's or host's context window when the server and its model list report none. |
+| `llm_context.strategy` | `none` | | What the model is sent of the conversation: `none` (everything, unchanged), or a list of layers (`stale`, `forget`; `"\|"`-separated or a YAML list). `stale`: a file read that a later read covering its lines superseded (a read that came back whole: not the head/tail preview of a big file, nor cut at `max_tool_output_chars`) is sent as a stub (`[read] lib/x.rb lines 1-200: superseded by a later read`). With `llm_context.stale_edits: true` (opt-in, experimental) so is a read a later successful edit or write of the file superseded (`superseded by a later edit`); on the replay bench these stubs cost about 5x the tokens they free in re-prefill, and 26% of them were needed again (against a 6% base rate). No read of a file edited or written in the last `llm_context.protect_steps` steps is stubbed. When stubs reach the prompt is `llm_context.apply`: `next_request` sends a read a later read superseded from the next request, and an edit-driven stub at the end of a turn the model answered; `turn_end` sends them all at the end of a turn the model answered (a turn that ran out of steps keeps them staged; on the native loop against a local llama.cpp the turn-end warm-up prefills the edited prompt, elsewhere the next turn's first request carries the cache break); `payoff` sends the batch at a request when the tokens it frees are at least the tail after its earliest stub (what the server reads again), or the context is in the top `context.status_thresholds` bucket (which needs `context.status` on), else at the end of a turn the model answered. A re-read's tail holds the later read, so in practice payoff usually waits for the turn's end. Each batch breaks the prompt cache from its earliest stub; `/stats` counts the re-prefilled tokens. The session keeps the outputs and the stubs it sent, so a `--resume` sends the same. `forget` isn't built yet: a list with it warns and is `none`; an unknown name warns and is `none`. `models.<key>.llm_context_strategy` and `hosts.<name>.llm_context_strategy` come first. |
+| `models.<key>.llm_context_strategy`, `hosts.<name>.llm_context_strategy` | none | | A model's or host's `llm_context.strategy` (`none` or `stale` for now). |
+| `llm_context.apply` | `payoff` | | When a layer's edits reach the prompt (each batch breaks the prompt cache from its earliest edit): `payoff`, `next_request` or `turn_end`. An unknown value warns and is `payoff`. `models.<key>.llm_context_apply` and `hosts.<name>.llm_context_apply` come first. |
+| `models.<key>.llm_context_apply`, `hosts.<name>.llm_context_apply` | none | | A model's or host's `llm_context.apply`. |
+| `llm_context.stale_edits` | `false` | | Opt-in, experimental: `stale` also stubs a read that a later successful edit or write of the file superseded. |
+| `llm_context.protect_steps` | `3` | | `stale` never stubs a read of a file edited or written in the last N steps (tool batches; counted across the whole conversation, not only the turn). `0` turns the protection off. |
 | `context.chars_per_token` | `4.0` | yes | Estimate ratio when the server reports no usage. |
 | `context.status_thresholds` | `20,40,60,80` | yes | Percentages that trigger a status. |
 | `context.status_cadence` | `0` | yes | Also every N rounds; `0` = thresholds only. |

data/docs/internals/background-tasks.md

@@ -23,6 +23,6 @@ Behavior:
 - `task_get` returns metadata and `output_path`; use `read` for output contents.
 - `task_wait` accepts `timeout`, `tail_lines` (maximum 100), and `done_pattern` (a regular expression string).
 - `task_create` accepts `env` as a JSON object string for deterministic overrides such as `PATH`; use an absolute interpreter path when that is simpler. Ruby/Bundler isolation variables remain protected.
-- `execute` and `task_create` export chi's own markers into the command, set over the model's `env` (which can't set them: `Error: env key is reserved`): `SAMAGOTCHI_PARENT_SESSION` (the session's id, `chi` without one; a chi started there answers as a parent agent) and `SAMAGOTCHI_SESSION_MODEL` (the resolved ref the session runs on, read at each call so it follows `/model`; unset when unknown). `chi self` reads the latter for its `model` row.
+- `execute` and `task_create` export chi's own markers into the command, set over the model's `env` (which can't set them: `Error: env key is reserved`): `SAMAGOTCHI_PARENT_SESSION` (the session's id, `chi` without one; a chi started there answers as a parent agent) and `SAMAGOTCHI_SESSION_MODEL` (the resolved ref the session runs on, read at each call so it follows `/model`; unset when unknown). `chi self` reads the latter for its `model` row. A session's worker never inherits them from whoever started it (a `chi send` run by another session's `execute`): its other commands (a user's `!cmd`, an MCP server, a context command) have none.
 
 Work that needs a model, not a shell command, goes to a child chi session instead: `delegate` / `delegate_result` have the same shape (start, then wait) and return only the child's final reply; see [Sessions: Delegating](../sessions.md#delegating).

data/docs/internals/llm-context-bench.md

@@ -0,0 +1,119 @@
+# The llm_context replay benchmark
+
+`script/llm_context_bench.rb` replays stored chi sessions offline and reports what an LLM context strategy
+(`llm_context.strategy`) would have changed in them. Every strategy or policy change gets a number from it before it
+becomes a default. It is a development tool: it lives under `script/`, isn't shipped with the gem, and no spec runs
+it on real sessions (the specs use small synthetic ones).
+
+```sh
+ruby script/llm_context_bench.rb [SESSIONS_DIR] [options]     # --help lists the options
+```
+
+`SESSIONS_DIR` is a folder of `<session id>.json` files: an argument, else `$LLM_CONTEXT_BENCH_SESSIONS`, else chi's
+own (`~/.local/state/samagotchi/sessions`). The benchmark only reads it. Sessions with fewer than two turns are
+skipped; `--top N` keeps the N heaviest, `--session PREFIX` picks some.
+
+It measures what chi would send: sessions load through `Session.from_h`, a native batch's joined result splits into
+its runs as `LLMContextView` splits it (calls read by chi's `ToolCallParser`), every output is named by its
+`ToolIds` id, and a strategy's edits are saved as `LLMContextEdit` records on copies of the entries and rendered
+through `LLMContextView`. Tokens are chars/4 throughout, which undercounts code-heavy prompts by about 1.25x.
+
+## What it reports
+
+**The profile (none, every session):** the resent tokens by category (tool outputs, call arguments, the system
+prompt, prose, user messages, context notes, a native session's inline thinking; stored thinking apart, since chi
+never resends it), tool outputs by tool and size, turns, how much of a turn's output a later turn refers to, and
+repeat reads.
+
+**A row per strategy × model × policy**, summed over the cases. A case is the end of a turn that has a next turn,
+scored at the next turn's first request. Cases are named `<first 8 of the session id>_t<turn>`; they come from a
+`--cases FILE` (one name per line), else from the picks given, else every turn with at least `--min-turn-tool`
+(3000) tokens of its own tool output.
+
+Each case says how its turn ends: `answer` (the model's final prose, no calls), `tool_result` (it stopped mid-task on
+a tool's output), `turn_note` (chi's note on a turn that ended without an answer), `tool_call` (calls never
+answered) or `empty`. The report's second line tallies them, `--per-case` has an `ends` column, and the JSON has
+`case_ends` (name => ending) and `ends` on each case. `--ends answer|any` picks which turns make cases: by default the
+turn-size rule keeps only `answer` ends, the point where a forget-at-turn-end offer would come (the layout check
+found a model behaves differently mid-task), and named cases (`--cases`, picks) are kept as named. `--ends answer`
+drops named cases that end otherwise and says how many; `--ends any` takes every turn.
+
+| Column | Meaning |
+|---|---|
+| forgot/outputs | outputs the strategy edits / outputs in context at the case |
+| freed/tool | what the prompt loses, stubs counted / the tool output tokens in context |
+| wrong strict (base) | edited outputs a later step needs: from the step the edit reaches through the end of the next turn, a call re-reads the file or re-runs the command. In brackets the base rate: the share of all outputs in context that are needed, what a random pick scores |
+| wrong loose (base) | the same, counting a mention of the output's path or of an identifier it brought in |
+| 1-step | edited outputs the step the edit reaches re-reads (a read of the file, not an edit) or re-runs. Offline that step is the session's own, made without the stub, so it is a floor, not the stub's effect |
+| re-prefilled | what the server prefills again because an edit broke its prompt cache: from the earliest changed entry to the end of what the previous request left cached. A case counts the breaks of its own window only (after the previous turn's case point), so a strategy that edits as the session goes isn't counted twice |
+| breaks | the requests of the case's window that an edit first reaches: one prompt-cache break each, a batch's edits together |
+
+The proxies are the context-edit spike's (lexical and lenient: a basename mention counts).
+
+## Strategies
+
+- `none`: nothing changes. The base.
+- `forget_all`: at the turn's end, forget every output in context with an empty note. The spike's base rate; about
+  what a model told "free context now" does.
+- `stale`: chi's own stale layer (`Samagotchi::LLMContextStale`) as chi runs it: each read a later read covering its
+  lines superseded is stubbed from the request after that read (chi applies it at the next request), so a case's
+  numbers count every stub since the session began. An edit or write of the file supersedes nothing, nor does a read
+  that came back as a preview or cut. A relative
+  path is taken against the session's working directory.
+- `stale_edits_next_request`, `stale_edits_turn_end`, `stale_edits_payoff`: the stale layer with edit-driven stubs
+  under an `llm_context.apply` rule, as chi runs it (`Samagotchi::LLMContextApply`, `llm_context.protect_steps`'
+  default), over each session from its start: at each request, and at the end of each turn that ends with the
+  model's answer (those stubs reach the next turn's first request, the case point). The top context bucket isn't
+  modelled (the bench has no window), so `payoff` applies at a request only when the freed tokens are at least the
+  tail. A turn-end batch's re-prefill is counted at the next turn's first request even where chi's warm-up would
+  prefill it while the user reads.
+- `forget_outputs` (P4): a slot. It prints "not built yet" until its phase adds it to
+  `LLMContextBench::Strategies`; a strategy answers `#plans(kase)` with `Plan`s of `PlannedEdit`s (the output id, the
+  edit kind, the note, the request it first reaches), and the scorer and the report take it as is.
+- `--picks LABEL=DIR`: model picks recorded as responses, one file per pick, `<case>.<variant>.json` (the spike's
+  `out/<model>/` files, or what `--live` saves). The variant is the row's policy, the label its model.
+
+```sh
+ruby script/llm_context_bench.rb "$SESSIONS" --strategy none,forget_all,stale --per-case
+ruby script/llm_context_bench.rb "$SESSIONS" --strategy none,stale,stale_edits_turn_end,stale_edits_payoff --ends any
+ruby script/llm_context_bench.rb "$SESSIONS" --picks deepseek=picks/deepseek --picks splash=picks/splash --json
+```
+
+## Live picks (the D7 tool-name A/B)
+
+The one part that calls a model, and only with `--live MODEL`: at each case it asks the model which of its tool
+outputs to forget, through chi's own chat client (the model must be on an `api: openai` host), and saves each
+answer under `--out DIR` for `--picks` to score. A saved pick is never asked for again. The request is the
+session's conversation up to the turn's end (thinking dropped, every tool result led by its id `[#tN]`), chi's
+built-in chat tools plus the forget tool, and the policy's tail line; a model that doesn't call the tool is asked
+once more with it forced (`--no-force` asks once).
+
+A pick record holds the answer (`unforced`), the forced one when it took that (`forced`) and why it was forced
+(`forced_because`: `no_call`, or `length` when the unforced reply was cut off at `max_tokens`, finish reason
+`length`, before it could call anything), how it was asked (`bench`), and `cost`: what the server reported for the
+pick's requests, summed (OpenRouter's `usage.cost`, asked for with `usage.include`; absent when the server sends
+none). The run's last line counts the picks written, the forced ones, those forced after a cut, the errors, and sums
+the cost.
+
+A request that fails is saved as an error record and the run goes on to the next case, except a payment error: a
+402, or an error that mentions credits or balance, stops the run at once (exit 1), saves nothing for that case, and
+says how many picks it wrote before it. A rerun with the same `--out` asks only for the rest.
+
+- `--tool-name forget_outputs|forget_llm_context`: the name under test; the description stays the same.
+- `--policy subtask|soft|now`: `subtask` offers the tool and puts the plan's policy line in its description;
+  `soft` and `now` are the spike's selective and "free context now" lines.
+- `--layout tail_system|tail_user|boundary`: where the tail line goes. `tail_system` (the default) is a system
+  message after the case's last entry; `tail_user` the same line as a user message; `boundary` a system message
+  worded as a stopping point. A layout other than the default names its picks `<policy>_<layout>`.
+- `--samples N`, and `--dry-run` to count the requests and prompt tokens (and the cases' endings) without calling
+  anything.
+
+Case selection matters here: at a turn that ends with the model's answer the forget offer reads as a real turn end,
+while mid-task (a `tool_result` or `turn_note` end) a model mostly carries on with the task, or, worded as a
+stopping point, forgets at the base rate. A forget-at-turn-end test should run on `answer` cases, the default for
+the turn-size rule; give `--ends answer` with a `--cases` file to hold one to that too.
+
+```sh
+ruby script/llm_context_bench.rb "$SESSIONS" --cases cases.txt --live openrouter:deepseek/deepseek-v4.1-flash \
+  --tool-name forget_llm_context --policy subtask --out picks/deepseek --dry-run
+```

data/docs/internals/prompt-caching.md

@@ -110,10 +110,11 @@ is prefilled once. The native and the chat loop use the same plan.
 ## 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
+  server's cache), `cache_write=` (written to it, where the provider reports writes) and `reprefill=` (of the last
+  request's prompt on the same model, what was prefilled again). 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.
+- `/stats`: "cached N (P%)", "cache writes" and "re-prefilled" 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.
 

data/docs/plugins.md

@@ -848,8 +848,9 @@ bundles:
     `(failed: …)`, a first-run server still starting `(starting, try
     again)`. Its description names each server on one line, never its
     tools: the server's `description:`, else the first sentence of its
-    `instructions`, else its first 6 tool names, and how many tools it has
-    (a first run's server is just its name until the next session).
+    `instructions`, and how many tools it has (`- chrome (26 tools)` with
+    neither: tool names there get called blind, without a search; a first
+    run's server is just its name until the next session).
   - `mcp_call(tool, args)` calls one: `tool` is `<server>/<tool>`, and
     `mcp_<server>_<tool>` works too (looked up, not parsed). Two tools whose
     `mcp_<server>_<tool>` comes out the same (servers `git-hub` and

data/docs/testing.md

@@ -63,3 +63,10 @@ a model that follows tool instructions: a small model may fail some of them.
 `spec/integration/omlx_spec.rb` tests oMLX's model-id resolution and runs only with
 `SAMAGOTCHI_INTEGRATION_TRANSPORT=omlx`, against an oMLX server (a short model selector in
 `SAMAGOTCHI_INTEGRATION_MODEL`).
+
+## The llm_context replay benchmark
+
+`ruby script/llm_context_bench.rb SESSIONS_DIR` replays stored sessions offline and scores the LLM context
+strategies (freed tokens, wrongly forgotten outputs, one-step re-reads, re-prefilled tokens). It is opt-in: the suite
+runs its code only on small synthetic sessions, never on yours. See
+[internals/llm-context-bench.md](internals/llm-context-bench.md).

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

@@ -1,12 +1,12 @@
 ---
 name: mcp
-version: 0.6.0
+version: 0.6.1
 scope: system
 description: "Tools from MCP servers (stdio): each server in config.yml bundles: mcp: servers: runs for the session; the model searches their tools with find_mcp_tools and calls one with mcp_call (<server>/<tool>); /mcp lists them"
 trust_level: reviewed
 files: {}
 plugin:
   file: plugin.rb
-  sha256: sha256:561dfc3a765d6a72913a7bc416ac0120e14f5747fdfc8f692e3d4dfb241ff6a6
+  sha256: sha256:7778b1a8f82a043c06c0289a191bc2847c844665de0c961edb493f787f435ad5
 # 0.37.0 (published 2026-10-07) is the release whose targets: take acts_as:, args: and label:.
 requires_chi: ">= 0.37.0"

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

@@ -59,8 +59,6 @@ class Plugin
   # A query word in a tool's name (or its server's) counts this many times
   # one in its description.
   NAME_WEIGHT = 3
-  # Tool names that stand for a server's summary when it has none.
-  SAMPLE_NAMES = 6
   # A cached tool list older than this is refreshed in the background.
   CACHE_TTL = 24 * 60 * 60
   # Restarts of a server that exited, per session.
@@ -689,16 +687,14 @@ class Plugin
   end
 
   # The server's line: its description: from config, else the first
-  # sentence of its instructions, else its first tool names.
+  # sentence of its instructions, else nothing (its line has the tool
+  # count). Never its tool names: a model that knows them calls them
+  # blind, without a search (a smoke run's Splash did).
   def server_summary(server)
     given = server.config["description"].to_s.strip
     return given unless given.empty?
-    return server.info if server.info
 
-    names = server.tools.map(&:name)
-    return nil if names.empty?
-
-    "tools #{names.take(SAMPLE_NAMES).join(", ")}#{", …" if names.size > SAMPLE_NAMES}"
+    server.info
   end
 
   # ── Search ────────────────────────────────────────────────────────────
@@ -808,7 +804,8 @@ class Plugin
   # The McpTool +name+ names: <server>/<tool>, or mcp_<server>_<tool>
   # looked up by chi_name (never parsed: server names may hold _, and long
   # names are cut). A miss while a server is starting waits for it (its
-  # tools may be the one); then a miss is the error text: a failed
+  # tools may be the one; for a <server>/ name, that server's start only);
+  # then a miss is the error text: a failed
   # server's error, else the closest tools.
   # @return [McpTool, String]
   def lookup(name, waited: false)
@@ -828,7 +825,10 @@ class Plugin
              "call one as <server>/<tool>"
     end
 
-    starting = @servers.select { |server| server.state == :starting }
+    # A name with a configured server's <server>/ waits for that server
+    # only; any other name (mcp_<server>_<tool>) for every one starting.
+    named = @servers.select { |server| name.start_with?("#{server.name}/") }
+    starting = (named.empty? ? @servers : named).select { |server| server.state == :starting }
     unless waited || starting.empty?
       starting.each { |server| wait_started(server) }
       return lookup(name, waited: true)

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

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

@@ -9,6 +9,7 @@ require_relative "config_text_edit"
 require_relative "log"
 require_relative "model_ref"
 require_relative "paths"
+require_relative "llm_context_strategy"
 
 module Samagotchi
   # Parses the thinking: levels of host and model entries (it needs Config).
@@ -154,6 +155,18 @@ module Samagotchi
       # 10 minutes, within session.max_wakes); false: it waits as a note for the next turn.
       Entry.new(key: "context.wake",             yaml_path: %w[context wake],             type: :bool,   default: true,             expose: %i[env config cli]),
 
+      # What the model is sent of the conversation (LLMContextStrategy, LLMContextView): none, or a list of layers
+      # (stale, forget; "|"-separated or a YAML list). none and stale are built: a list with forget warns and is none.
+      # models.<key>.llm_context_strategy and hosts.<name>.llm_context_strategy come first.
+      Entry.new(key: "llm_context.strategy",     yaml_path: %w[llm_context strategy],     type: :string, default: "none",           expose: %i[env config]),
+      # When a layer's edits reach the prompt (LLMContextApply): payoff, next_request or turn_end;
+      # models.<key>.llm_context_apply and hosts.<name>.llm_context_apply come first.
+      Entry.new(key: "llm_context.apply",        yaml_path: %w[llm_context apply],        type: :string, default: "payoff",         expose: %i[env config]),
+      # Whether an edit or write of a file makes its earlier reads stale too (opt-in, experimental).
+      Entry.new(key: "llm_context.stale_edits",  yaml_path: %w[llm_context stale_edits],  type: :bool,   default: false,            expose: %i[env config]),
+      # The steps (tool batches) back whose edited files' reads stale never stubs.
+      Entry.new(key: "llm_context.protect_steps", yaml_path: %w[llm_context protect_steps], type: :integer, default: 3,             expose: %i[env config]),
+
       Entry.new(key: "thinking.turn_preamble",   yaml_path: %w[thinking turn_preamble],   type: :bool,   default: true,             expose: %i[env config cli]),
       # How much models think: off|low|medium|high|default, parsed by Thinking
       # (a :string, since YAML reads an unquoted off as false). The CLI flag
@@ -241,8 +254,8 @@ module Samagotchi
     # (ConfigFile.hosts_config, ConfigFile.model_settings).
     MAP_ENTRY_KEYS = {
       "hosts" => %w[host port url transport api api_key_env profile first_token_timeout vision sampling thinking enabled
-                    remote window_tokens].freeze,
-      "models" => %w[profile vision sampling thinking window_tokens].freeze
+                    remote window_tokens llm_context_strategy llm_context_apply].freeze,
+      "models" => %w[profile vision sampling thinking window_tokens llm_context_strategy llm_context_apply].freeze
     }.freeze
     # Section keys beyond the registry's: guardrails' YAML rules (Engine#guardrail_rules).
     SECTION_EXTRA_KEYS = { "guardrails" => %w[rules disable].freeze }.freeze
@@ -826,6 +839,10 @@ module Samagotchi
                                             "hosts entry '#{name}'")
           sampling = ConfigFile.sampling_map(raw_cfg.key?("sampling") ? raw_cfg["sampling"] : raw_cfg[:sampling], "hosts entry '#{name}'")
           thinking = Thinking.level(raw_cfg.key?("thinking") ? raw_cfg["thinking"] : raw_cfg[:thinking], "hosts entry '#{name}'")
+          llm_context = LLMContextStrategy.parse(raw_cfg.key?(LLMContextStrategy::KEY) ? raw_cfg[LLMContextStrategy::KEY] : raw_cfg[:llm_context_strategy],
+                                                 "hosts entry '#{name}'")
+          llm_context_apply = LLMContextStrategy.parse_apply(raw_cfg.key?(LLMContextStrategy::APPLY_KEY) ? raw_cfg[LLMContextStrategy::APPLY_KEY] : raw_cfg[:llm_context_apply],
+                                                             "hosts entry '#{name}'")
           unless first_token_timeout.nil? || (first_token_timeout.is_a?(Numeric) && !first_token_timeout.negative?)
             warn_once "Warning: hosts entry '#{name}': first_token_timeout must be seconds (0 = off); using the default"
             first_token_timeout = nil
@@ -890,7 +907,8 @@ module Samagotchi
                                   url: url.empty? ? nil : url, api_key_env: api_key_env.empty? ? nil : api_key_env,
                                   profile: profile.empty? ? nil : profile, first_token_timeout: first_token_timeout,
                                   vision: vision, sampling: sampling, thinking: thinking, remote: remote,
-                                  window_tokens: window }
+                                  window_tokens: window, llm_context_strategy: llm_context,
+                                  llm_context_apply: llm_context_apply }
         end
       end
 
@@ -1037,7 +1055,9 @@ module Samagotchi
         location.merge("transport" => v[:transport]&.to_s, "api" => v[:api]&.to_s, "api_key_env" => v[:api_key_env],
                        "profile" => v[:profile], "first_token_timeout" => v[:first_token_timeout],
                        "vision" => v[:vision], "sampling" => v[:sampling], "thinking" => v[:thinking]&.to_s,
-                       "remote" => v[:remote], "window_tokens" => v[:window_tokens]).compact
+                       "remote" => v[:remote], "window_tokens" => v[:window_tokens],
+                       "llm_context_strategy" => v[:llm_context_strategy]&.map(&:to_s),
+                       "llm_context_apply" => v[:llm_context_apply]&.to_s).compact
       end
       # Disabled hosts travel as just that, so a worker refuses "box:x"
       # the way its parent does instead of sending it to the default host.
@@ -1129,6 +1149,12 @@ module Samagotchi
         result[key][:thinking] = thinking if thinking
         window = window_tokens(v.key?("window_tokens") ? v["window_tokens"] : v[:window_tokens], "models: #{key}")
         result[key][:window_tokens] = window if window
+        layers = LLMContextStrategy.parse(v.key?(LLMContextStrategy::KEY) ? v[LLMContextStrategy::KEY] : v[:llm_context_strategy],
+                                          "models: #{key}")
+        result[key][:llm_context_strategy] = layers if layers
+        apply = LLMContextStrategy.parse_apply(v.key?(LLMContextStrategy::APPLY_KEY) ? v[LLMContextStrategy::APPLY_KEY] : v[:llm_context_apply],
+                                               "models: #{key}")
+        result[key][:llm_context_apply] = apply if apply
       end
     rescue StandardError
       {}

data/lib/samagotchi/context_note.rb

@@ -64,9 +64,13 @@ module Samagotchi
     # (a note that arrived before the first turn, a turn note left by a
     # failed first turn) stays and the prompt goes before it.
     def with_system_head(messages, system_message)
-      first = messages.first
-      replace = first && fetch(first, :role).to_s == "system" && fetch(first, :kind).to_s.empty?
-      [system_message] + (replace ? messages.drop(1) : messages)
+      [system_message] + (system_head?(messages.first) ? messages.drop(1) : messages)
+    end
+
+    # A system prompt at a conversation's head: a system message of no kind
+    # (#with_system_head replaces it).
+    def system_head?(message)
+      message.is_a?(Hash) && fetch(message, :role).to_s == "system" && fetch(message, :kind).to_s.empty?
     end
 
     def clock(created_at)

data/lib/samagotchi/context_status.rb

@@ -85,6 +85,7 @@ module Samagotchi
       @last_bucket = self.class.last_bucket(conversation)
       @server_usage = nil
       @counted = nil
+      @edited = false
       @display = nil
       @guidance = nil
     end
@@ -95,6 +96,12 @@ module Samagotchi
 
     def enabled? = @enabled
 
+    # The status line's value is in the top configured bucket (the apply
+    # rule's payoff applies staged edits there at once).
+    def top_bucket?
+      !@display.nil? && bucket_rank(@display[:bucket]) == @thresholds.size
+    end
+
     # Before a request: estimate the usage of a prompt of +prompt_chars+
     # against +window+ (this request's ContextWindow::Resolved) and update
     # the status line's value. A rise into a bucket that asks the model for
@@ -120,6 +127,14 @@ module Samagotchi
       { status: status_message(usage: usage, bucket: bucket), usage: usage, bucket: bucket, source: usage[:source] }
     end
 
+    # An LLM context edit was applied (LLMContextApply): the prompt is
+    # shorter than the one the server's count was for. Until the next
+    # count the estimate takes what the prompt lost off that count too,
+    # instead of holding it (a shorter prompt counts as trimmed otherwise).
+    def edited!
+      @edited = true
+    end
+
     # @return [Hash, nil] the model's line from the last #observe (once)
     def take_guidance
       line = @guidance
@@ -145,6 +160,7 @@ module Samagotchi
       return unless usage
 
       @counted = { chars: prompt_chars, image_tokens: image_tokens }
+      @edited = false
       value = display_for(used_tokens: usage[:total_tokens], window_tokens: usage[:context_window_tokens] || window&.tokens)
       @display = value if value
     end
@@ -172,7 +188,7 @@ module Samagotchi
 
       if server_usage && server_usage[:prompt_tokens]
         window_tokens = server_usage[:context_window_tokens] || window.tokens
-        used_tokens = server_usage[:prompt_tokens] + appended_tokens(prompt_chars, image_tokens, counted)
+        used_tokens = [server_usage[:prompt_tokens] + appended_tokens(prompt_chars, image_tokens, counted), 0].max
         source = "server"
       else
         window_tokens = window.tokens
@@ -192,11 +208,13 @@ module Samagotchi
 
     private
 
-    # The estimate for what the prompt added since the +counted+ one.
+    # The estimate for what the prompt added since the +counted+ one;
+    # after an edit (#edited!) what it lost too, as a negative.
     def appended_tokens(prompt_chars, image_tokens, counted)
       return 0 unless counted
 
       chars = prompt_chars - counted[:chars]
+      return -(-chars / @chars_per_token).ceil if @edited && chars.negative?
       return 0 unless chars.positive?
 
       (chars / @chars_per_token).ceil + [image_tokens - counted[:image_tokens].to_i, 0].max

data/lib/samagotchi/engine.rb

@@ -1727,7 +1727,7 @@ module Samagotchi
       @turn_thinking = [thinking_level(thinking_target), thinking_target]
       announce_thinking_level(*@turn_thinking)
       LLM::TurnSettings.new(vision: vision, sampling: sampling, thinking: @turn_thinking.first, model_name: nil,
-                            window_setting: nil)
+                            window_setting: nil, llm_context: nil)
     end
     private :turn_settings
 
@@ -1754,11 +1754,14 @@ module Samagotchi
       return if reminders_due? || @turn_state.carried_steers? || @next_turn_waiting&.call
 
       messages = ContextNote.with_system_head(turn.session.messages.dup, { role: "system", content: system_prompt(target) })
-      prompt, images = @kernel.warmup_prompt(messages)
+      # Under the next turn's strategy (a /model switch may have changed it);
+      # the last turn's when it can't be resolved.
+      prompt, images = @kernel.warmup_prompt(messages, llm_context: turn_llm_context || @kernel.turn_settings&.llm_context)
       return unless prompt
 
-      @prompt_warmup.start(client: client, prompt: prompt, model: @kernel.turn_settings.model_name,
-                           slot: @kernel.last_slot, images: images)
+      started = @prompt_warmup.start(client: client, prompt: prompt, model: @kernel.turn_settings.model_name,
+                                     slot: @kernel.last_slot, images: images)
+      @kernel.warmed_up! if started
     rescue StandardError => e
       Log.warn(:model, "warmup_skipped", error: e.class.name, msg: e.message.to_s[0, 200])
     end
@@ -1816,7 +1819,8 @@ module Samagotchi
       # The turn's settings, set once here. The chat loop dispatches tools
       # through the kernel without its #run: tag those dumps with this
       # turn's model, not the last native one.
-      @kernel.turn_settings = turn.settings.with(model_name: bare_for_backend, window_setting: turn_window_setting)
+      @kernel.turn_settings = turn.settings.with(model_name: bare_for_backend, window_setting: turn_window_setting,
+                                                 llm_context: turn_llm_context)
 
       turn.limit = @no_interrupt ? IterationLimit.for(no_interrupt: true) : max_iterations || IterationLimit.for
       backend.complete(
@@ -2512,6 +2516,16 @@ module Samagotchi
       nil
     end
 
+    # The effective model's LLM context strategy (models:/hosts:
+    # llm_context_strategy, else llm_context.strategy), read per turn as
+    # the window is.
+    def turn_llm_context
+      target = @host_registry.resolve(@effective_model_name)
+      LLMContextStrategy.resolve(target, names: model_lookup_names(target))
+    rescue StandardError
+      nil
+    end
+
     # See #served_model. A report for another name (before a /model switch)
     # doesn't count. Without a target, no probe. A remote chat host has no
     # /props: nil until a turn.

data/lib/samagotchi/guardrails/targets.rb

@@ -149,11 +149,23 @@ module Samagotchi
                 end
         return name unless whose
 
-        Log.warn(:plugins, "plugin_acts_as_dropped", tool: entry.name, acts_as: name,
-                                                     msg: "#{entry.name} targets: acts_as #{name} dropped: it is #{whose}")
+        if first_drop?(registry, entry.name, name)
+          Log.warn(:plugins, "plugin_acts_as_dropped", tool: entry.name, acts_as: name,
+                                                       msg: "#{entry.name} targets: acts_as #{name} dropped: it is #{whose}")
+        end
         nil
       end
 
+      # The drops logged, per registry (a session's): each tool's acts_as
+      # once, not at every call (targets run several times a call).
+      DROPS_LOGGED = ObjectSpace::WeakKeyMap.new
+      DROPS_LOCK = Mutex.new
+
+      def self.first_drop?(registry, tool, acts_as)
+        DROPS_LOCK.synchronize { !(DROPS_LOGGED[registry] ||= Set.new).add?([tool, acts_as]).nil? }
+      end
+      private_class_method :first_drop?
+
       # The longest label: the question takes from targets:.
       LABEL_CHARS = 80
 

data/lib/samagotchi/host_registry.rb

@@ -36,10 +36,12 @@ module Samagotchi
     # sampling: the configured request parameters (SamplingSettings), nil when unset;
     # thinking: the configured level (Thinking), nil when unset;
     # remote: the configured true/false (#remote?), nil when unset;
-    # window_tokens: the configured context window (ContextWindow.setting), nil when unset.
+    # window_tokens: the configured context window (ContextWindow.setting), nil when unset;
+    # llm_context_strategy: the configured layers (LLMContextStrategy), nil when unset;
+    # llm_context_apply: the configured apply rule (LLMContextStrategy), nil when unset.
     HostEntry = Struct.new(:name, :host, :port, :transport, :client, :api, :scheme, :url, :api_key_env, :profile,
                            :first_token_timeout, :vision, :sampling, :thinking, :remote, :window_tokens,
-                           keyword_init: true) do
+                           :llm_context_strategy, :llm_context_apply, keyword_init: true) do
       # Talks the OpenAI chat API (the chat loop); nil and raw apis use the
       # raw-prompt loop.
       def chat? = api == :openai
@@ -99,7 +101,8 @@ module Samagotchi
                               api: cfg[:api]&.to_sym, scheme: cfg[:scheme], url: cfg[:url], api_key_env: cfg[:api_key_env],
                               profile: cfg[:profile], first_token_timeout: cfg[:first_token_timeout],
                               vision: cfg[:vision], sampling: cfg[:sampling], thinking: cfg[:thinking],
-                              remote: cfg[:remote], window_tokens: cfg[:window_tokens])
+                              remote: cfg[:remote], window_tokens: cfg[:window_tokens],
+                              llm_context_strategy: cfg[:llm_context_strategy], llm_context_apply: cfg[:llm_context_apply])
         entry.client = Client.new(host: cfg[:host], port: cfg[:port], transport: transport, scheme: cfg[:scheme],
                                   first_token_timeout: entry.first_token_limit, name: entry.name,
                                   api_key_env: entry.api_key_env, env: env)