samagotchi 0.130.1 → 0.132.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +76 -1
  3. data/bin/chi +3 -1
  4. data/docs/architecture.md +32 -1
  5. data/docs/cli.md +32 -9
  6. data/docs/configuration.md +67 -8
  7. data/docs/desktop.md +15 -6
  8. data/docs/guardrails.md +3 -3
  9. data/docs/internals/anthropic.md +3 -2
  10. data/docs/internals/engine.md +4 -4
  11. data/docs/internals/participants.md +23 -6
  12. data/docs/internals/prompt-caching.md +29 -6
  13. data/docs/memory.md +16 -2
  14. data/docs/plugins.md +68 -1
  15. data/lib/samagotchi/bootstrap_command.rb +35 -6
  16. data/lib/samagotchi/bundles/model-notes/manifest.yml +4 -1
  17. data/lib/samagotchi/bundles/model-notes/model_notes_tone.md +3 -0
  18. data/lib/samagotchi/bundles/model-notes/notes/README.md +14 -0
  19. data/lib/samagotchi/bundles/system/manifest.yml +1 -1
  20. data/lib/samagotchi/cache_confirm.rb +47 -9
  21. data/lib/samagotchi/chi_home.rb +311 -0
  22. data/lib/samagotchi/desktop/macos.rb +75 -19
  23. data/lib/samagotchi/engine.rb +66 -6
  24. data/lib/samagotchi/engine_snapshots.rb +5 -0
  25. data/lib/samagotchi/gem_update.rb +19 -10
  26. data/lib/samagotchi/guardrail_wiring.rb +3 -1
  27. data/lib/samagotchi/guardrails/protected_paths.rb +6 -3
  28. data/lib/samagotchi/guardrails/verdict.rb +1 -1
  29. data/lib/samagotchi/home_command.rb +149 -0
  30. data/lib/samagotchi/installed_versions.rb +5 -3
  31. data/lib/samagotchi/level_setting_command.rb +3 -2
  32. data/lib/samagotchi/llm_context_command.rb +53 -7
  33. data/lib/samagotchi/llm_context_override.rb +3 -2
  34. data/lib/samagotchi/plugin/api.rb +45 -1
  35. data/lib/samagotchi/plugin/context.rb +34 -1
  36. data/lib/samagotchi/plugin/loader.rb +5 -2
  37. data/lib/samagotchi/plugin/prompt_sections.rb +124 -0
  38. data/lib/samagotchi/run_options.rb +1 -0
  39. data/lib/samagotchi/session_access/contract.rb +1 -1
  40. data/lib/samagotchi/session_commands.rb +68 -21
  41. data/lib/samagotchi/session_manager.rb +36 -1
  42. data/lib/samagotchi/session_model_settings.rb +5 -2
  43. data/lib/samagotchi/system_prompt.rb +34 -3
  44. data/lib/samagotchi/terminal_ui/attach_launcher.rb +3 -2
  45. data/lib/samagotchi/terminal_ui/formatting.rb +3 -0
  46. data/lib/samagotchi/testing/bundle.rb +22 -3
  47. data/lib/samagotchi/testing/host.rb +22 -1
  48. data/lib/samagotchi/testing/recorder.rb +6 -1
  49. data/lib/samagotchi/testing/recording_api.rb +1 -1
  50. data/lib/samagotchi/toolkit_command.rb +2 -2
  51. data/lib/samagotchi/update_command.rb +65 -7
  52. data/lib/samagotchi/version.rb +1 -1
  53. data/lib/samagotchi/web/app.rb +11 -1
  54. data/lib/samagotchi/web/participant_view.rb +22 -6
  55. data/lib/samagotchi/web/public/annotate_bar.js +6 -1
  56. data/lib/samagotchi/web/public/app.js +14 -5
  57. data/lib/samagotchi/web/public/index.html +6 -2
  58. data/lib/samagotchi/web/public/llm_context_chip.js +4 -3
  59. data/lib/samagotchi/web/public/model_pick.js +26 -0
  60. data/lib/samagotchi/web/public/model_picker.js +3 -1
  61. data/lib/samagotchi/web/public/participant.js +24 -6
  62. data/lib/samagotchi/web/public/start_page.js +14 -2
  63. data/lib/samagotchi/web/public/verdict_card.js +48 -4
  64. data/lib/samagotchi/web/public/verdict_fresh.js +8 -4
  65. data/lib/samagotchi/web/public/verify_target.js +73 -0
  66. data/lib/samagotchi/web/server.rb +27 -8
  67. data/lib/samagotchi/web/update_check.rb +3 -2
  68. metadata +6 -1
@@ -40,6 +40,7 @@ right-hand column happens.
40
40
  │ AGENTS.md (root → cwd) │ (picked up by a new
41
41
  │ appended files (append_system_prompt:, --append-system-prompt) │ process or a rebuild)
42
42
  │ kit prompt (per toolkit: its kit's prompt: text, only when it has one) │
43
+ │ plugin prompt sections (chi.prompt_section, by (bundle, name)) │ chi.prompt_changed!
43
44
  │ project + system memory indexes │
44
45
  │ ◄── remote Claude / Messages: cache_control breakpoint #1 │
45
46
  ├──────────────────────────────────────────────────────────────────────────┤
@@ -65,8 +66,8 @@ right-hand column happens.
65
66
  - The system prompt is built **once per key** and kept (`SystemPrompt#build`, keyed by `[chat, thinking, layers]`:
66
67
  the loop, the thinking level, the turn's LLM context layers; a `/thinking` change builds under another key). All
67
68
  of them are dropped only on `@prompt_builder.reset!`: a model switch (`Engine#switch_model!`), a plugin's
68
- `tools_changed!`, a profile change, or a toolkit change (`Engine#apply_toolkit!`). A per-turn rebuild would break
69
- everything below it.
69
+ `tools_changed!` or `prompt_changed!` (`Engine#prompt_changed!`), a profile change, or a toolkit change
70
+ (`Engine#apply_toolkit!`). A per-turn rebuild would break everything below it.
70
71
  - The tools layer is shared **per toolkit** (configuration.md, "Toolkits"): sessions on the same toolkit share it,
71
72
  and a chain's links keep theirs. A session's toolkit is saved when it is created and never resolved again from
72
73
  config. A change (`/toolkit`, `ctx.use_toolkit`) is applied only at a turn's start (`Engine#apply_toolkit!`,
@@ -88,6 +89,15 @@ right-hand column happens.
88
89
  sessions on the kit share it; a memory write (the indexes after it) doesn't move it. It is part of the
89
90
  `Toolkit::Resolved` the Registry holds, so a switch that changes only the text is a toolkit change
90
91
  (`apply_toolkit!` → `reset!`). `full` and kits without one send the bytes they sent before.
92
+ - A plugin's prompt sections (`chi.prompt_section`, `Plugin::PromptSections`) sit after the kit prompt and before
93
+ the memory indexes (`SystemPrompt#plugin_prompt_section`), sorted by (bundle, name), each
94
+ `From <bundle> (<name>):\n<text>`; with none (every block nil) the bytes are what they were before. A block runs
95
+ only inside a build, never per request, so its text changes the prompt only at a rebuild: `/model` (a block
96
+ reading `ctx.model` re-resolves for free) or the plugin's `chi.prompt_changed!`, which its command calls only
97
+ after asking (`ctx.cache_confirm`, rule 6); a running turn keeps the prompt it started with (`turn_messages` puts
98
+ it in the turn's messages once). A block that raises, returns a non-String or text over 2000 characters keeps
99
+ the section's last good text for the session: a skip on a transient error would break the cache twice (and on
100
+ Claude 5.x cost the preserved thinking each time).
91
101
  - find_tools' description is a function of the toolkit and the source groups **at load**: `ToolIndex#declare`
92
102
  snapshots source group names and description lines (name, summary, callable count). `ToolIndex#refresh!` (from
93
103
  `ToolkitBinding#apply!`) filters that snapshot by the new toolkit and rebuilds the `chi` line from the built-ins
@@ -221,7 +231,9 @@ is prefilled once. The native and the chat loop use the same plan.
221
231
  3. **Deterministic order.** Tools, memory lists and anything else that's rendered from a hash or a set needs a
222
232
  fixed sort. Plugin tools are sorted by (bundle, name) whatever order their plugins finished starting in
223
233
  (R5a).
224
- 4. **Don't rebuild the system prompt per turn.** Rebuild only when its content really changed (`reset!`).
234
+ 4. **Don't rebuild the system prompt per turn.** Rebuild only when its content really changed (`reset!`). A
235
+ plugin's prompt section is the same text for the same inputs, and its `chi.prompt_changed!` is called only when
236
+ its text changed.
225
237
  5. **Measure.** Every generation logs `prompt=`, `cached=` and, where the provider reports it, `cache_write=`
226
238
  on its `generation_completed` log line. `/stats` shows "cached N (P%)" and "cache writes". A change that
227
239
  drops `cached=` on the second fresh session is a regression. Update the prompt snapshot fixtures with
@@ -230,10 +242,21 @@ is prefilled once. The native and the chat loop use the same plan.
230
242
  the conversation again asks a person at a web tab or a TUI first (`CacheConfirm`: the reply carries the
231
243
  `--yes` line, `SessionCommands::Result#confirm` and the `command_ran` event's `confirm`). Each setting has a
232
244
  classifier: `Thinking.cache_cost` (`:full` for Gemma, `:provider` for a remote chat host, `:tail` otherwise) and
233
- `ReasoningHistory.cache_cost` (`:history` for a change to or from `all` once an earlier reply has thinking).
245
+ `ReasoningHistory.cache_cost` (`:history` for a change to or from `all` once an earlier reply has thinking),
246
+ `/model` (`SessionCommands#model_ask`: `:full` for any other resolved ref, `Engine#model_switch_ref` checking
247
+ the name first, so a typo errors instead of asking; every switching branch, `--default`, `--alias`, `clear`), and `LLMContextCommand#cache_cost` (`:full` for forget
248
+ on or off, `:history` for a layer with applied stubs turned off; stale on, the apply rule and the budget only
249
+ decide when a batch's break comes, so they don't ask).
234
250
  `CacheConfirm.needed?` asks only for `:full`, `:provider` and `:history`, when the effective level changes and
235
- the session has a model reply. A new setting with a cost (a `/model` across templates, `/llm-context` turning
236
- forget on) adds its classifier and goes through the same step.
251
+ the session has a model reply. The confirmation estimates the reread size from the latest known context count:
252
+ the whole conversation for `:full` / `:provider`, or up to the first changed reply for `:history`; it omits the
253
+ estimate when no count is known. On `api: anthropic`, a `:full` / `:provider` change also warns that preserved
254
+ thinking in replies is dropped from then on. A new setting with a cost adds its classifier and goes through
255
+ the same step. A launch flag (`chi --model`, `--llm-context`, `--thinking` on an attached or resumed session,
256
+ `LLMContextOverride.command_line`) and a chip whose form states the cost (`level_chip.js`, `llm_context_chip.js`)
257
+ send their line with `--yes`: typing the flag, or the Set, is the choice. A plugin command asks
258
+ through `ctx.cache_confirm(line, changed:)` (cost `:full`: its prompt section is in the stable part), with the
259
+ sender's flag `SessionCommands#run` gives it (`CacheConfirm.asking`), and returns `[text, confirm]`.
237
260
  7. **No wall-clock time rendered at wire time.** A history entry's `at` (`MessageTime::KEY`, when it happened) is
238
261
  display-only: no wire format reads it, and a guard spec checks that `ChatLoop#wire_messages` and
239
262
  `Prompt.format_with_images` give the same bytes with and without it (`spec/message_time_history_spec.rb`). A
data/docs/memory.md CHANGED
@@ -164,9 +164,23 @@ Working habits for this model:
164
164
  longest run without an edit and the Continues and steers each needed; run a
165
165
  note on and muted for the same kind of task. See
166
166
  [testing.md](testing.md) ("The model notes report").
167
+ - **A note for every model**: `models: *` matches any id, so one note sets a
168
+ house style for all of them. The model-notes bundle ships one,
169
+ `model_notes_tone`:
170
+
171
+ ```markdown
172
+ models: *
173
+ How to write answers:
174
+ - Answer first, in plain words. Skip preambles, restating the question and closing offers. Use a list only for steps or several parallel items.
175
+ ```
176
+
177
+ It stacks with a family's note. Off for one session: `chi --mute
178
+ model_notes_tone` (at launch); everywhere: `chi memory rm model_notes_tone
179
+ --scope system`, or keep your own text under that name (yours wins).
167
180
  - **Shipped notes: the model-notes bundle.** `chi bundle install model-notes`
168
- (or the `dev` profile) installs reviewed notes into the system scope; for
169
- now `model_notes_deepseek` (`models: *deepseek-v4*`). Each note's provenance
181
+ (or the `dev` profile) installs reviewed notes into the system scope:
182
+ `model_notes_deepseek` (`models: *deepseek-v4*`) and `model_notes_tone`
183
+ (`models: *`, concise answers for every model). Each note's provenance
170
184
  and evidence is in the bundle's `notes/README.md`, and its spec pins which
171
185
  model ids load which note ([Plugins](plugins.md#the-model-notes-bundle)).
172
186
  - **Your own note of the same name wins.** The install skips a
data/docs/plugins.md CHANGED
@@ -150,6 +150,34 @@ chi.command "/hello-slow", "greet after 2 s, even mid-turn", anytime: true do |a
150
150
  end
151
151
  ```
152
152
 
153
+ #### Commands that ask: `ctx.cache_confirm`
154
+
155
+ A command whose change restarts the model server's prompt cache (one that changes the text of a
156
+ [prompt section](#chiprompt_sectionname--ctx---and-chiprompt_changed)) asks first, as `/thinking` and `/toolkit` do:
157
+ `ctx.cache_confirm(line, changed:)` returns nil when it may apply now, or a confirm to return with the command's
158
+ text, `[text, confirm]`, changing nothing. `line` is the command line that applies it (without `--yes`), `changed:`
159
+ whether your text would change. chi decides the rest: it asks only a person at a web tab or a TUI (never `chi send`,
160
+ a delegate or `chi -p`), only once the session has a model reply, never for a line with `--yes` (or `-y`), and
161
+ writes the confirm's text (the conversation's size to read again; on an `api: anthropic` host, that preserved
162
+ thinking is dropped). The TUI prefills `line --yes`, the web shows an Apply button that sends it, and the command
163
+ then runs again with `--yes` in `args` (drop it from your words). Outside a command (a hook, an init task, your
164
+ own thread) it is always nil. A plain String or nil return is unchanged.
165
+
166
+ A command that asks must not be `anytime: true`: the REPL shows only an anytime command's text, so its Apply would
167
+ be lost. Needs chi 0.132.0.
168
+
169
+ ```ruby
170
+ chi.command "/tone", "show or set this session's tone" do |args, ctx|
171
+ word = (args.split - %w[--yes -y]).join(" ")
172
+ ask = ctx.cache_confirm("/tone #{word}", changed: word != current_tone)
173
+ next ["Switching to #{word} restarts the prompt cache.", ask] if ask
174
+
175
+ save_tone(word)
176
+ @chi.prompt_changed!
177
+ "tone: #{word} from the next turn"
178
+ end
179
+ ```
180
+
153
181
  #### `/help`
154
182
 
155
183
  `/help` (itself an anytime command) lists every command the session knows:
@@ -607,6 +635,38 @@ chi.toolkit "coding", base: "child", prompt: "- Be concise in your responses"
607
635
  chi.toolkit "web", base: "lean", groups: %w[chrome db*]
608
636
  ```
609
637
 
638
+ ### `chi.prompt_section(name) { |ctx| … }` and `chi.prompt_changed!`
639
+
640
+ Text the session's system prompt carries, from a plugin: the block gets the Context and returns a String (at most
641
+ 2000 characters, stripped) or nil for no section. Each goes into the prompt's stable part right after the
642
+ toolkit's prompt text and before the memory indexes, as `From <bundle> (<name>):` and the text, sorted by
643
+ (bundle, name). With no section (every block nil, or no plugin uses it) the prompt is exactly what it was without.
644
+ `name` is `a-z`, `0-9`, `_` and `-` (at most 32), once per bundle.
645
+
646
+ The block runs when the prompt is built: a session's first turn, after `/model` (so `ctx.model` and
647
+ `ctx.model_key` are the new model's), after `chi.prompt_changed!` or a tools change. Never per request, and on
648
+ whatever thread builds, so keep it quick and thread-safe (no I/O beyond reading a small file). **Same inputs, same
649
+ text**: anything that differs (a time, a random pick, a count) breaks the model server's prompt cache at the next
650
+ build. A block that raises, returns something other than a String or nil, or text over the limit keeps that
651
+ section's last good text for the session (one warn in the debug log, `prompt_section_failed`); with none yet the
652
+ section is left out. A deliberate nil removes it.
653
+
654
+ `chi.prompt_changed!` says your section would give other text now (the user picked another setting): the prompt is
655
+ built again at its next build, the next turn's start (a running turn keeps the prompt it started with). That
656
+ restarts the prompt cache for the whole conversation, so a command that changes it asks first
657
+ ([Commands that ask](#commands-that-ask-ctxcache_confirm)) and calls `chi.prompt_changed!` only once it applies.
658
+ Keep `chi` from `register` for that (`@chi = chi`). `/stats` names the sections the prompt holds
659
+ (`prompt sections: tone (tone)`). The test kit runs them as a build does (`bundle.prompt_text`,
660
+ `bundle.prompt_sections`) and counts `chi.prompt_changed!` (`bundle.prompt_changes`). Needs chi
661
+ 0.132.0: a bundle using it sets `requires_chi`.
662
+
663
+ ```ruby
664
+ def register(chi)
665
+ @chi = chi
666
+ chi.prompt_section("tone") { |ctx| preset_text(ctx.model_key) } # nil: no section
667
+ end
668
+ ```
669
+
610
670
  ### `chi.tool_source(call:, acts_as:, label:, wait:, prefix:)`
611
671
 
612
672
  Tools the model reaches through a search instead of declaring them one by
@@ -764,6 +824,7 @@ full label, `plugin.rb (bundle my-bundle)`.
764
824
  | `ctx.fork?` | whether the session is a fork (`ctx.sessions.fork`): it has a parent but isn't a delegate child, and started from a conversation, so its first prompt isn't its first user message |
765
825
  | `ctx.model` | the model the session runs on now: its resolved ref (`host:id`), right after `/model` too |
766
826
  | `ctx.model_key` | that model's memory overlay key (`<name>.<key>.md`, what `memory_write current_model_only` writes) |
827
+ | `ctx.model_names` | the names chi's own per-model config looks that model up under (a `models:` map in config.yml): as typed (an alias), the alias's target, the resolved ref, without the host, the bare id; deduped, most specific first, frozen (`[]` when it doesn't resolve). Match a map of yours over them downcased, first hit, as chi does. Needs chi 0.132.0 |
767
828
  | `ctx.cost` | the session's spend so far, read now, as a frozen value: `total` (USD, reported + estimated, side requests included; 0.0 before any), `reported` (by providers, `usage.cost`), `estimated` (from `hosts.<name>.models` prices; a generation is one or the other, never both), `side` (recap, `/btw`, `ask_model`: their share of `total`) and `known?` (false while generations or side requests ran but none was reported or priced, so a limit on it can't be enforced; a session with some priced generations reads known, the unpriced ones counting 0). It includes the running turn's finished generations and what earlier workers of the session spent. Use its methods, not its class. Needs chi 0.83.0 |
768
829
  | `ctx.usage` | the session's work so far, read now, as a frozen value: `turns` (finished ones and the running one), `tool_calls` and `tool_calls_by_tool` (every call, running ones included; canonical names: an alias counts under its tool, a `call_tool` call under the inner tool), `steps` (the loop rounds that dispatched tools, `/stats`' iterations) and `active_ms` (`active_minutes` too): work time, the generations' time plus the finished tool calls' time, never the waits between them (a question, an approval, the user's answer to `ask_user_question`), with `tool_ms_by_tool` its tool part by tool, so a waiting tool's time (`task_wait`) can be left out. Its counts are the ones `/stats` and `chi sessions stats` show, earlier workers' included. Use its methods, not its class. Needs chi 0.100.0 (guard it with `ctx.respond_to?(:usage)`) |
769
830
  | `ctx.turn_author` | who wrote the running turn when it isn't the session's owner: a participant's `"p:<id>"` (`chi share`); nil for the owner's turns and between turns. Every hook event of such a turn carries the same as `author:`. The handler runs with the owner's power whatever the author ([hooks](hooks.md#participants-turns)). Needs chi 0.105.0 (guard it with `ctx.respond_to?(:turn_author)`) |
@@ -788,6 +849,7 @@ full label, `plugin.rb (bundle my-bundle)`.
788
849
  | `ctx.use_toolkit(name)` | put the session on toolkit `name` (yours from `chi.toolkit`, or chi's): saved, applied at the next turn's start and announced (`toolkit> toolkit: NAME from the next turn's start`, the web's tools chip follows). Only before the session's first model reply and outside a turn (the declared tools start every request, and a plugin doesn't ask first); otherwise it returns false and changes nothing: tell the user to run `/toolkit NAME`. An unknown name raises ArgumentError. Needs chi 0.66.0 |
789
850
  | `ctx.load_tools(names)` | load tools the session reaches but doesn't declare, so the model calls them by name: built-ins (`"delegate"`, `"chi/delegate"`), MCP tools (`"mcp_fs_read"`, `"fs/read"`). Returns the names it staged (the wire names); a declared tool, one loaded before, a removed or unknown one is skipped (an unknown one logged), so calling it every turn is fine. From a `before_turn` hook it loads for that turn; anywhere else (mid-turn too) from the next turn's start. Call it from a hook: before the session's first turn its toolkit isn't applied yet and nothing resolves. **A hint, not access**: the tools keep their guardrails and approvals, and only a host that takes tool changes (`api: anthropic`, not Fireworks) gets one, as a system message after the user's (`[tools loaded: delegate (your-bundle)]` in the session, a notice line live); elsewhere nothing is sent or saved, and the tools stay reachable with `call_tool`. A hook may switch the model after you call it, so the return value can't promise delivery. Raises ArgumentError for anything but an Array. Needs chi 0.99.0 |
790
851
  | `ctx.context` | attach outside text to this session and list it: see [Attached context](#attached-context-ctxcontext) |
852
+ | `ctx.cache_confirm(line, changed:)` | inside a command: nil to apply a prompt-cache-restarting change now, or a confirm to return as `[text, confirm]`: see [Commands that ask](#commands-that-ask-ctxcache_confirm). Needs chi 0.132.0 |
791
853
 
792
854
  The Engine itself is never handed to a plugin.
793
855
 
@@ -1211,6 +1273,10 @@ bundle.fire(:after_turn, status: "completed") # → the event, after
1211
1273
  bundle.question_asked("Fix JIRA-1?", question: { question: "Go?" }) # → the refs, as chi's seams fire it
1212
1274
  event = bundle.before_tool_call_event({ name: "read", path: "a.txt" }, params: "read a.txt")
1213
1275
  bundle.command("/mine stop") # → what the command returned
1276
+ bundle.command("/tone x", confirm: true) # sent from a web tab or a TUI: ctx.cache_confirm may ask
1277
+ bundle.set(history: true, context_tokens: 900) # a model reply to restart (ctx.cache_confirm), its size
1278
+ bundle.set(model_names: %w[tiny box:gemma gemma]) # ctx.model_names (default: model_name and its id)
1279
+ bundle.prompt_text # the prompt sections' text, as a build runs them
1214
1280
  bundle.tool("my_tool", path: "a.txt") # → the text the model reads
1215
1281
  verdict = bundle.tool_call({ name: "execute", content: "rm -rf /" })
1216
1282
  verdict.deny? # a real Guardrails::Verdict (votes: verdict.votes)
@@ -2510,11 +2576,12 @@ gem.
2510
2576
  `chi bundle install model-notes` (or the `dev` profile) installs reviewed
2511
2577
  [model notes](memory.md#model-notes) into the system scope: working habits
2512
2578
  for one model family, loaded into the prompt only for the models a note's
2513
- `models:` line names. It has no plugin or hook. It ships one note:
2579
+ `models:` line names. It has no plugin or hook. It ships two notes:
2514
2580
 
2515
2581
  | note | models | for |
2516
2582
  |---|---|---|
2517
2583
  | `model_notes_deepseek` | `*deepseek-v4*` | DeepSeek V4 / V4.1: explore briefly then act, commit one item at a time, stop digging, `memory_read` for memories, file tools rather than heredocs that guardrail rules ask about |
2584
+ | `model_notes_tone` | `*` | every model: answer first, in plain words; no preambles, restated questions or closing offers; lists only for steps or parallel items |
2518
2585
 
2519
2586
  - **Reviewed before it ships.** A note is generic (no repo or machine facts),
2520
2587
  says nothing the harness already does (a tool's description, an alias),
@@ -5,7 +5,9 @@ require_relative "config"
5
5
  require_relative "model_profile"
6
6
  require_relative "host_registry"
7
7
  require_relative "host_keys"
8
+ require_relative "chi_home"
8
9
  require_relative "gem_update"
10
+ require_relative "installed_gem"
9
11
  require_relative "bootstrap/probe"
10
12
  require_relative "bootstrap/config_writer"
11
13
  require_relative "bootstrap/bundles"
@@ -87,8 +89,10 @@ module Samagotchi
87
89
  # the process ENV points, not +env+)
88
90
  # @param gem_runner [#run] runs `gem install commonmarker` (GemUpdate::Runner)
89
91
  # @param gem_present [#call, nil] → whether commonmarker is installed
92
+ # @param home [#current, #record_first!] the chi home (ChiHome)
90
93
  def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, env: ENV, probe: nil, config_path: nil,
91
- platform: RbConfig::CONFIG["host_os"], bundles: nil, gem_runner: GemUpdate::Runner.new, gem_present: nil)
94
+ platform: RbConfig::CONFIG["host_os"], bundles: nil, gem_runner: GemUpdate::Runner.new, gem_present: nil,
95
+ gem_spec: InstalledGem.spec, home: ChiHome)
92
96
  @argv = argv.dup
93
97
  @stdin = stdin
94
98
  @stdout = stdout
@@ -99,8 +103,14 @@ module Samagotchi
99
103
  @platform = platform
100
104
  @bundles = bundles || Bootstrap::Bundles.new
101
105
  @gem_runner = gem_runner
102
- # Installed, without loading its native extension into this process.
103
- @gem_present = gem_present || -> { Gem::Specification.find_all_by_name(MARKDOWN_GEM).any? }
106
+ @gem_spec = gem_spec
107
+ @home = home
108
+ # Installed (in the chi home's gems when there is one: chi web runs
109
+ # there), without loading its native extension into this process.
110
+ @gem_present = gem_present || lambda {
111
+ home = @home.current(gem_spec: @gem_spec)
112
+ home ? home.gem?(MARKDOWN_GEM) : Gem::Specification.find_all_by_name(MARKDOWN_GEM).any?
113
+ }
104
114
  end
105
115
 
106
116
  # @return [Integer] 0 written (or already there), 1 failed (a failed
@@ -371,6 +381,7 @@ module Samagotchi
371
381
  # each. Then Markdown in chi web (#offer_markdown). 1 when a bundle
372
382
  # failed; the Markdown step never changes it.
373
383
  def install_bundles(dry_run: false)
384
+ record_home unless dry_run
374
385
  ok = system_bundle_line(@bundles.sync_system(dry_run: dry_run), dry_run)
375
386
  ok = install_profile(CORE, dry_run) && ok
376
387
  unless dry_run || !tty? || (members = dev_to_install).empty?
@@ -409,13 +420,31 @@ module Samagotchi
409
420
  false
410
421
  end
411
422
 
412
- # true when commonmarker is there or `gem install` (this Ruby's own gem
413
- # command) put it there; else one line with gem's last word on it.
423
+ # The first chi home (ChiHome.record_first!: the helper's Ruby, else
424
+ # this one), one line; nothing when one is recorded already.
425
+ def record_home
426
+ recorded = @home.record_first!(gem_spec: @gem_spec, launch_path: helper_launch_path)
427
+ @stdout.puts("chi home: #{recorded.ruby} (chi home set to change)") if recorded
428
+ end
429
+
430
+ def helper_launch_path
431
+ return nil unless @platform.to_s.include?("darwin")
432
+
433
+ require_relative "desktop/macos"
434
+ Desktop::MacOS.new(env: @env, register: false).launch_path
435
+ end
436
+
437
+ # true when commonmarker is there or `gem install` (the chi home's gem
438
+ # command, else this Ruby's own) put it there; else one line with gem's
439
+ # last word on it.
414
440
  def install_markdown_gem
415
441
  return true if @gem_present.call
416
442
 
417
443
  @stdout.puts("#{MARKDOWN_GEM}: installing…")
418
- output, ok = @gem_runner.run([GemUpdate.gem_bin, "install", MARKDOWN_GEM, "--no-document"])
444
+ home = @home.current(gem_spec: @gem_spec)
445
+ argv = [ChiHome.gem_bin(home), "install", MARKDOWN_GEM, "--no-document"]
446
+ env = ChiHome.install_env(home, env: @env)
447
+ output, ok = env.empty? ? @gem_runner.run(argv) : @gem_runner.run(argv, env: env)
419
448
  return true if ok
420
449
 
421
450
  last = output.to_s.lines.map(&:strip).reject(&:empty?).last || "no output"
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: model-notes
3
- version: 0.1.0
3
+ version: 0.2.0
4
4
  scope: system
5
5
  description: "Reviewed model notes: working habits a model family needs, loaded into the prompt only for the models each note's models: line names"
6
6
  trust_level: reviewed
@@ -9,3 +9,6 @@ files:
9
9
  model_notes_deepseek.md:
10
10
  sha256: sha256:0b07e40edc1a3d4a3ad6bea08d9b338913f78cab19a5809bcf4593f459f9bc5e
11
11
  description: "DeepSeek V4 working habits: explore briefly then act, commit per item, stop digging, memory_read for memories, file tools over heredocs"
12
+ model_notes_tone.md:
13
+ sha256: sha256:e47a93dc3b3cb78a9bd3eb7f04ef1c4d2a30b4a7c0110a66e1e3a26e363827ca
14
+ description: "Concise answers for every model (models: *): answer first, no preambles or closing offers"
@@ -0,0 +1,3 @@
1
+ models: *
2
+ How to write answers:
3
+ - Answer first, in plain words. Skip preambles, restating the question and closing offers. Use a list only for steps or several parallel items.
@@ -35,3 +35,17 @@ bundle itself.
35
35
  The dates and tasks differ, so this is a hint, not an A/B: an A/B is the same kind of task with the note on and
36
36
  muted (`chi send --new --mute model_notes_deepseek`). The shipped text is shorter than the one measured (795
37
37
  characters against 1,519) and keeps its habits.
38
+
39
+ ## model_notes_tone
40
+
41
+ - **models:** `*`: every model. It stacks on a family's note (`spec/model_ids.yml` `expected_overlaps`).
42
+ - **Origin, 2026-10-29:** chi's prompt has no style guidance, so each model talks in its own voice and answers run
43
+ long. A `/tone` bundle (presets, a session command) was built and parked; the user chose the lighter way, a model
44
+ note, with the gentlest text: only the anti-padding part of the concise preset ("leave out what went as expected"
45
+ was dropped: it can hide useful confirmations).
46
+ - **Approved:** the text as shipped, by the user, 2026-10-29 (after the check below); ships in model-notes (the `dev`
47
+ profile) first, `core` later only after more evidence (other model families, a week of the user's own use).
48
+ - **Evidence:** a with/without check on the local Qwen3.8 Flash Next (Splash), 5 tasks (4 questions about this repo,
49
+ 1 small code edit), one run each, `chi --non-interactive` with isolated state: answers 12.5k → 10.1k characters
50
+ (−19%), 4 of 5 shorter; openings more direct, closing summaries gone; nothing a task needed was lost (dropped: one
51
+ worked glob example, one aside about the model's own fixed mistake). N=1 per task: a direction, not a measurement.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: samagotchi-system
3
- version: 0.130.1
3
+ version: 0.132.0
4
4
  scope: system
5
5
  description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
6
6
  files:
@@ -1,9 +1,8 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Samagotchi
4
- # The confirm step before a session setting change that restarts the
5
- # prompt cache (/thinking, /reasoning-history): such a change, sent
6
- # without --yes from a person at a web tab or a chi TUI, changes nothing
4
+ # The confirm step before a command that restarts the prompt cache: sent
5
+ # without --yes by a person at a web tab or a chi TUI, it changes nothing
7
6
  # and replies with what it costs and the line that applies it. Two steps,
8
7
  # no stored state: the reply carries a Confirm (SessionCommands::Result,
9
8
  # the worker's command_ran), the TUI prefills its line, the web draws an
@@ -13,6 +12,9 @@ module Samagotchi
13
12
  # The costs worth asking about (Thinking.cache_cost,
14
13
  # ReasoningHistory.cache_cost); :tail and nil are not.
15
14
  COSTLY = %i[full provider history].freeze
15
+ # Thread.current key: whether the plugin command running on this
16
+ # thread may ask (#asking).
17
+ ASKING = :samagotchi_cache_confirm_asking
16
18
 
17
19
  # The line that applies a change, and the question the reply ends with.
18
20
  Confirm = Data.define(:line, :text) do
@@ -43,12 +45,48 @@ module Samagotchi
43
45
  changed && history && COSTLY.include?(cost)
44
46
  end
45
47
 
46
- # The Confirm for +name+ set to +word+: the line with --yes, and the
47
- # question naming it.
48
- # @return [Confirm]
49
- def confirm(name, word)
50
- line = "#{name} #{word} --yes"
51
- Confirm.new(line: line, text: "Nothing changed yet: send `#{line}` to apply.")
48
+ # Run +block+ as a plugin command whose sender can answer a confirm
49
+ # (+flag+: SessionCommands#run's confirm, false once the line has
50
+ # --yes): Plugin::Context#cache_confirm asks only inside it, on this
51
+ # thread. Nests; threads the block starts don't inherit it.
52
+ def asking(flag)
53
+ previous = Thread.current[ASKING]
54
+ Thread.current[ASKING] = flag ? true : false
55
+ yield
56
+ ensure
57
+ Thread.current[ASKING] = previous
58
+ end
59
+
60
+ # Whether the plugin command on this thread may ask (#asking).
61
+ def asking? = Thread.current[ASKING] == true
62
+
63
+ # Whether a cache-changing command should ask, and its reply line.
64
+ # Kept independent of any UI so commands and plugins can share it.
65
+ # @param line [String] the full command line without --yes
66
+ # @param cost [Symbol, nil] the change's cache cost
67
+ # @param changed [Boolean] whether the effective setting changes
68
+ # @param engine [Engine] supplies history, used tokens and model host
69
+ # @return [Confirm, nil]
70
+ def ask(line:, cost:, changed:, engine:)
71
+ return nil unless needed?(cost: cost, history: engine.history?, changed: changed)
72
+
73
+ apply_line = "#{line.to_s.strip} --yes"
74
+ notes = []
75
+ tokens = engine.cache_restart_tokens
76
+ if tokens
77
+ size = tokens >= 1000 ? "#{format("%.1f", tokens / 1000.0).delete_suffix(".0")}k" : tokens.to_s
78
+ notes << case cost
79
+ when :full, :provider
80
+ "The next request reads the whole conversation again (about #{size} tokens)."
81
+ when :history
82
+ "The next request reads again from the first changed reply (up to about #{size} tokens)."
83
+ end
84
+ end
85
+ if %i[full provider].include?(cost) && engine.cache_restart_anthropic?
86
+ notes << "On an `api: anthropic` host, preserved thinking in replies is dropped from then on."
87
+ end
88
+ notes << "Nothing changed yet: send `#{apply_line}` to apply."
89
+ Confirm.new(line: apply_line, text: notes.compact.join("\n"))
52
90
  end
53
91
  end
54
92
  end