samagotchi 0.80.0 → 0.81.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e8f390119025dcb6df095574fb9e59e94952c709a69ae6bc6e02ffa037e1a0d
-  data.tar.gz: c67e91b18d0ef7ac8916b03045c214c12ebcf98b469f84b0ae355bb41491388e
+  metadata.gz: e0e5c6acd4a2774291e421b71b7b5729b0e3031c9afaa46715f40a1d976ebed2
+  data.tar.gz: 6390322560ddd65a847ea4d3a122b3751be778c40eb573d457c617880daa0e06
 SHA512:
-  metadata.gz: 4c936b332ee7cafb74cb4e09b7f3b80acac7ba1247988e755078c61e72c201489b1a48f8970c6c3d70d88b7cedc31cf432d01c5b14018073a517b65f76e45de6
-  data.tar.gz: dc77457ac7bf6a0018966bef40ccaa67da732a43edbe21e0fbcef1193583a3e00934c70c4230d3fcf14f5dd23012730f9c41bb16be8d7a64754f361ff3c2ab4a
+  metadata.gz: c1d209965a45e687b89280cbcecfe0b51798dcff1a418837b3604f4b3b1e69e8d0f210d8b4972c84912e274c7f738c322a2270af36833fe17049e999081a2705
+  data.tar.gz: 9c5d2a4e2205da68d70d99db385ab3f79ebec1f83f8762baaf36d3ae466fc98204c68bcd93ab1868127e703f5d50eaed0dd363ac910541849298c3bbc72bb931

data/CHANGELOG.md

@@ -8,6 +8,34 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.81.0] - 2026-10-18
+
+### Added
+
+- Stats: side requests (the idle recap, `/btw` and plugins' `ctx.ask_model`) are counted on their own
+  `side requests:` line in `/stats` and the web's ctx tooltip, with their tokens and cost; the session's totals stay
+  its turns'.
+
+### Fixed
+
+- Guardrails: a `command:` rule no longer matches the text of a heredoc its command only reads as data
+  (`git commit -F -`, `gh pr create --body-file -`, `cat` to stdout, a `"$(cat <<'EOF' …)"` commit message); a
+  heredoc fed to a shell or an interpreter, or piped on (also from a `( … )` or `{ … }` group), is still
+  matched. The bundle's `chi-answer-piped` (guardrails bundle 0.9.1) no longer asks about stdin from
+  `/dev/null`.
+- Guardrails: the `rm` and `touches` checks now see a heredoc that bash runs after all — piped on from a `( … )` or
+  `{ … }` group, fed through `<( … )` / `>( … )`, or written with `&>` / `>& file` and then run — which they used to
+  read as plain data.
+- Plugins: a `chi.service` that starts lazily from a tool or hook handler runs its start block outside the handler,
+  so Stop no longer cancels the service's startup `ctx.http` calls (as docs/plugins.md says).
+- Bundles: the test kit's sandbox also points `XDG_DATA_HOME` and `XDG_CACHE_HOME` at its temp folder, so a bundle
+  test no longer writes to your own data or cache home when you set them.
+- `chi bootstrap`: re-running it against a server the config already has says so, without the misleading "saved as …"
+  line before it.
+
+Update with `chi update` (the system bundle 0.81.0, `guardrails` 0.9.1, `slow-commands` 0.2.3), then restart
+`chi web`.
+
 ## [0.80.0] - 2026-10-17
 
 ### Added
@@ -3310,7 +3338,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.80.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.81.0...HEAD
+[0.81.0]: https://github.com/dm1try/samagotchi/compare/v0.80.0...v0.81.0
 [0.80.0]: https://github.com/dm1try/samagotchi/compare/v0.79.0...v0.80.0
 [0.79.0]: https://github.com/dm1try/samagotchi/compare/v0.78.0...v0.79.0
 [0.78.0]: https://github.com/dm1try/samagotchi/compare/v0.77.0...v0.78.0

data/docs/architecture.md

@@ -338,6 +338,14 @@ carries the generation's `speed` (`{decode_tps, source}`, null without one), its
 counts (`prompt_tokens`, `cached_tokens`, `cache_write_tokens`: null when the server reported no writes) and
 those running `tokens` and `model_segments`: 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.
+Side requests (the idle recap, a plugin's `ctx.ask_model` such as `/btw`) are counted apart, in a `side` block
+(only when there were any; `SessionMetrics::SideTotals`: requests, token sums, `cost_sum` null until reported,
+`cost_estimate_sum` from the target host's price, `by_kind`): `IdleClient` hands each reply's usage to its
+`on_usage:` callback, `Engine#note_side_usage`, which folds it (`SessionMetrics#add_side`) and announces
+`:side_usage` (`kind`, the whole `side` block) under the event lock, so the blocks arrive in fold order, then saves
+`analytics.json` between turns (a running turn's end saves it). `tokens`, `model_segments` and the turn records
+stay the turns' only. `SessionMetrics#persist` is serialized (its own mutex, taken before the metrics one), so two
+threads' saves land in snapshot order.
 
 The page's frequent reads of `GET /api/sessions/:id` stay light too:
 - `?tail=1&recent=1` (each turn's end, a cancel, an answer display): `{tail, session: {id, status,
@@ -523,7 +531,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Attached context | `context_sources.rb` (`ContextSources`), `context_poller.rb`, `context_absorber.rb`, `peer_sources.rb` (`PeerSources`: the sources peer bundles declare) | External sources a session keeps fresh, and the peer loop's wakes ([context.md](context.md)). |
 | LLM context strategies | `llm_context_strategy.rb`, `llm_context_view.rb`, `llm_context_stale.rb`, `llm_context_forget.rb` | What a request sends of the history (none, stale, forget) ([internals/llm-context-forget.md](internals/llm-context-forget.md)). |
 | Session chains | `session_continue.rb` (`SessionContinue`), `session_chain.rb` (`SessionChain`) | A session that continues an earlier one. `SessionChain.opener_for` gives the text web `continue →` prefills in the new link: the previous link's own first typed message when that link continues one itself, else nil (the 201's `opener`; not saved) ([sessions.md](sessions.md)). |
-| Analytics | `analytics_file.rb` (`AnalyticsFile`), `session_metrics/totals.rb` (`SessionMetrics::Totals`), `session_metrics/model_segment.rb` (`SessionMetrics::ModelSegment`) | A session's `analytics.json` (`SessionMetrics#persist`); the sums over its turn records (`Totals`: tokens, cost, speeds, kept as running counters) and their split per model after a `/model` switch (`ModelSegment`: a run of turns on one model, the `model_segments` rows). |
+| Analytics | `analytics_file.rb` (`AnalyticsFile`), `session_metrics/totals.rb` (`SessionMetrics::Totals`), `session_metrics/model_segment.rb` (`SessionMetrics::ModelSegment`) | A session's `analytics.json` (`SessionMetrics#persist`); the sums over its turn records (`Totals`: tokens, cost, speeds, kept as running counters) and their split per model after a `/model` switch (`ModelSegment`: a run of turns on one model, the `model_segments` rows). `session_metrics/side_totals.rb` (`SessionMetrics::SideTotals`) and `side_usage.rb` (`SideUsage`): the side requests' sums, apart from the turns'. |
 | Images / vision | `image_store.rb` (`ImageStore`), `vision_support.rb`, `vision_context.rb` | Stored prompt images and whether a model takes them. |
 | Toolkits | `toolkit.rb` (`Toolkit`), `toolkit_binding.rb` (`ToolkitBinding`, the Engine's seam), `toolkit_command.rb` (`/toolkit`), `tools/registry.rb` (`Registry#toolkit`, `#left_out_names`), `web/public/toolkit_chip.js` | Which registered tools a session's prompts declare: saved in the session, resolved at a turn's start (`Engine#apply_toolkit!`), named in the prompt's not-loaded line, a kit's prompt text after the appended files; `chi.toolkit` and `ctx.use_toolkit` for plugins ([configuration.md](configuration.md#toolkits)). |
 | Tool index | `tools/tool_index.rb` (`Tools::ToolIndex`) | `find_tools` and `call_tool`: the tools a session knows but doesn't declare one by one (an mcp bundle's servers through `chi.tool_source`, the built-ins its toolkit leaves out), searched and called by name ([plugins.md](plugins.md)). |

data/docs/cli.md

@@ -486,6 +486,14 @@ Generations under 8 tokens or 100 ms get no speed of their own, nor does a
 reply without server token counts or a non-streamed one. A delegated child
 keeps its own numbers: a parent's tokens and cost leave them out.
 
+Side requests have their own line, right after `cost:` (in its place without one), only when the session made any:
+`side requests:    3 (recap 2, btw 1) · 14.2k in / 380 out · $0.0012 + ~$0.0009 (not in the totals above)`. It
+counts the idle recap (`recap`), `/btw` and every other plugin's `ctx.ask_model` (under the asking bundle's name),
+with their tokens and cost: a reported cost as is, else estimated from the price of the model they asked, on its
+host (as a turn's, `~`). They are never in the tokens, `models:` or `cost:` lines above it, which stay the turns'.
+A recap thrown away (stale, overdue) still counts: it was billed. `chi sessions stats` shows the line too (saved
+between turns), and the web's ctx tooltip has the same words.
+
 After a `/model` switch (or a hook's) the tokens line becomes a `models:` block, a row per run of turns on one
 model, in order (A → B → A is three rows): the model (`host:model` as asked), when (`10:43–now` while it runs; with
 the day when the rows span several), turns, tokens in/out, its average speed and cost. Under the row of the model

data/docs/configuration.md

@@ -573,6 +573,9 @@ hosts:
 - The estimate is saved apart from the reported cost (`cost_estimate` per turn, `cost_estimate_sum` in the
   session's totals in `analytics.json`) and shows with a `~`.
 - A server that sends no cached counts has its whole prompt priced at `input`: an overestimate.
+- Side requests (the idle recap, `/btw`, a plugin's `ctx.ask_model`) are priced by the same rule from the price of
+  the model they asked on its host: the recap's host and model (`recap.*`, else the session's), `ask_model(model:)`'s
+  host. They count on `/stats`' own `side requests:` line, never in the session's `cost:`.
 
 ## Thinking
 

data/docs/guardrails.md

@@ -230,7 +230,7 @@ guardrails:
   rules:
     - id: git-push
       tool: shell            # execute + task_create; or a tool name, a glob, or a list
-      command: '\bgit\s+push\b'   # Ruby regex on the command
+      command: '\bgit\s+push\b'   # Ruby regex on the command (data heredoc bodies left out)
       verdict: ask           # ask | deny
       reason: git push publishes commits
       scopes: [once, session, repo]   # optional; default all four
@@ -248,6 +248,23 @@ guardrails:
 
 A rule gives at least one of `tool`, `command`, `path`, `git`, `touches`, `rm` and `memory`.
 
+`command:` reads the command without the body of a heredoc its command
+only reads as data: `cat` or `tee` to stdout, `git commit`/`git tag` with
+`-F -`/`--file -`, `gh pr|issue`/`gh release` with `--body-file -`/
+`--notes-file -`, and a `"$(cat <<'EOF' … EOF)"` given to `-m`, `--body`
+or another message option. Each counts only when its command ends at a
+newline, `;`, `&&` or `||` and sits outside any `( … )` or `{ … }` group;
+the `<<TAG` word and the terminator line stay in the text, so a rule on
+`<<` or on what follows the terminator still matches. A heredoc fed to
+anything else (`bash`, an interpreter, `ssh`, a wrapper), an unquoted one
+whose body holds `$(…)` or backticks, a piped one, a file-writing
+`cat`/`tee` (a `>&2` or `>&-` writes no file; `>& file` does), a
+here-string and an unterminated heredoc all stay in it. An fd opened
+earlier and written to by number (`exec 3>r.sh; cat <<E >&3`) isn't
+followed, so that body counts as data: out of scope here, which is
+chi-nah's job for a model that goes looking. Approvals, the approval
+question and hooks see the whole command.
+
 `memory: remove` matches a `memory_write` with `remove: true` (it moves a
 memory into the bundle trash). Nothing else asks about it: a memory's file is
 never outside the repo (below), so without such a rule any session, a delegate
@@ -493,7 +510,7 @@ only by the user: these change a model's system prompt for later sessions (see
 [Model notes](memory.md#model-notes); a shell command reaches them only under
 `shell-touches-chi`'s text heuristic); and answering chi's
 questions around `chi answer`: `chi --attach` or `chi -p` with stdin from a
-pipe, a here-string or a file (`chi-answer-piped`), and `curl`/`wget` to a
+pipe, a here-string or a file, not `/dev/null` (`chi-answer-piped`), and `curl`/`wget` to a
 session's `/answer` route (`chi-answer-http`), both once or for the session.
 `chi answer` itself isn't asked about. It denies writes into `.git/hooks`.
 
@@ -591,7 +608,13 @@ else goes to chi's own rules. It needs nah installed; see its README for the set
 
 Text matching on shell commands stops accidents, not a model set on getting
 around it: `sh -c`, base64, a script written earlier, `git -C` variants and
-aliases can get past a regex. `outside_repo` covers the file tools and git
+aliases can get past a regex, and these rules are built for trusted models (a
+model set on getting around them is chi-nah's job). A heredoc counts as data
+only for the consumers listed under [Rules in config.yml](#rules-in-configyml)
+(`cat`/`tee` to stdout, `git commit`/`git tag` `-F -`, `gh`'s body and notes
+files, a `"$(cat <<'EOF' … EOF)"` message): anything else keeps its body in
+the text a rule sees, and a function or alias shadowing a reader in the same
+command isn't seen at all. `outside_repo` covers the file tools and git
 only: `sed -i`, `cp` or `cat > file` into another folder from the shell aren't
 asked about, and neither is git run through `sh -c`, a script, an alias, `make`
 or a folder in a variable. `!cmd` lines typed by you are not checked. The only

data/docs/plugins.md

@@ -858,6 +858,10 @@ next turn never see it, and no hook fires. It returns the answer text.
 It goes through the host's OpenAI API (`/v1/chat/completions`), which
 llama.cpp serves on a native host too.
 
+Each call counts in the session's side requests, under the bundle's name: `/stats`' `side requests:` line and the
+web's ctx tooltip (`2 (btw 1, recap 1) · …`), with its tokens and its cost (reported, else estimated from the target
+model's price), never in the session's own totals.
+
 ## Calling services: `ctx.http`
 
 ```ruby
@@ -923,7 +927,8 @@ Every call also takes `cancel:`, a `Samagotchi::CancellationController`, which r
 - **Stop.** A call made for the turn (a tool, a hook's handler) stops when the turn is stopped, and a call inside an
   init task when chi shuts down; a call from your own thread, a `chi.service` or an anytime command has only its
   timeout unless you pass `cancel:`. After the turn has ended (an `:after_turn` or `:session_end` hook of a
-  stopped turn) a call is not cancelled by that stop.
+  stopped turn) a call is not cancelled by that stop. A service's start block counts as the service's even when its
+  first `value` comes from a handler.
 - **The log.** Each call writes one `http` line to the debug log: INFO (ERROR when it fails) with `bundle=`,
   `purpose=plugin`, the method, the URL **without its query**, the status and the time. Never headers or bodies.
   A plugin that polls a dead service therefore logs an ERROR per poll.
@@ -1164,8 +1169,8 @@ bundle.shutdown
   `bundle.set(cancelled: true)` makes a call without `cancel:` raise `HttpCancelled`.
 - **A hook that raises fails the call** (`Testing::HookFailed`, with the hook's error) where chi would log it and
   go on; `bundle.lenient { … }` collects them in `bundle.errors` instead.
-- **Sandbox.** A test runs with temp config and state homes (config.yml, memories, `ctx.data_dir`, the debug
-  log), `HOME`, `CLAUDE_CONFIG_DIR` and `CODEX_HOME`, no git config of yours, no Keychain and none of your
+- **Sandbox.** A test runs with temp config, state, data and cache homes (config.yml, memories, `ctx.data_dir`, the
+  debug log), `HOME`, `CLAUDE_CONFIG_DIR` and `CODEX_HOME`, no git config of yours, no Keychain and none of your
   `SAMAGOTCHI_*` settings; `sandbox.config(hash)` writes its config.yml.
 - **RSpec:** `require "samagotchi/testing/rspec"`; example groups tagged `:bundle` (a spec under a bundle's own
   `spec/` is tagged by itself) get `load_bundle(dir)`, `shipped_bundle(name)` and `sandbox`, each example in its

data/docs/sessions.md

@@ -51,6 +51,14 @@ chi sessions stats ID [--format text|json]            # cost, tokens and progres
 
 `chi sessions stats ID` prints what `/stats` prints in a terminal, headed by `<id8>  <status>  <model>`: a live worker answers its Bridge's `GET stats` (no model call, and the command never starts a worker); without one, or when the worker does not answer in time, the same snapshot is rebuilt from the session's saved `analytics.json` (and the line says so when a worker was live). `--format json` prints one object `{session_id, status, live, metrics}` with the snapshot as `metrics` (its `turn_records` / `tool_records` are the recent ones only: a live worker's newest finished turn and any not yet saved, the disk snapshot's newest saved turn; `analytics.json` holds them all); a session with no `analytics.json` yet reports `metrics: null` (`(no metrics yet)` in text) and still exits 0. An unknown or ambiguous id exits 1 with the same wording `chi sessions stop` uses.
 
+`analytics.json` also has a `side` block when the session made side requests (the idle recap, `/btw` and other
+plugins' `ctx.ask_model`): `requests`, `prompt_sum`, `completion_sum`, `cached_sum`, `cache_write_sum`,
+`reasoning_sum`, `cost_sum` (the reported cost; null until one was), `cost_estimate_sum` (from the target host's
+price; 0 without one) and `by_kind` (`{recap: {requests, cost_sum, cost_estimate_sum}, btw: {…}}`, in first-seen
+order: `recap`, else the asking bundle's name). It has no records: the block itself is saved (at once between turns,
+by the turn's end during one) and loaded; it is never in `tokens` or `model_segments`. `chi sessions stats --format
+json` has it in `metrics.side`; a file without it (older, or no side requests) has none.
+
 Each turn record in `analytics.json` names the model the turn ran on as `model_ref` (the asked `host:model`, from its first generation; `model` stays the name the server says it served); a turn stopped before it asked a model has none. The first turn after a `/model` switch (or a hook's) to another model also records what its first generation prefilled on the new model: `switch_prefill_tokens` (the prompt less the cached reads; none under 128 tokens, or for a generation with estimated counts) and `switch_prefill_cost_estimate` (from the new model's configured price, no completion; none without a price). A session saved before this has no `model_ref` on its records.
 
 A session whose worker waits for an answer (a question, a hook's question, a guardrail approval, or the step-limit question of a turn that ran out of steps, which waits between turns) reads `waiting` in the status column, and json has `waiting: "question"|"approval"|"hook"|"continue"` and `waiting_id`, the question's id for `chi answer --question` (both null otherwise). A delegate's approval its parent relayed to its own card (see *Delegating*) reads `waiting (in parent ab12)`, json `relayed_to: "ab12…"` (the parent's short id, else null). Only while a worker runs it: a question a dead worker left in the file shows the saved status. Answer it with `chi answer`, the web or `chi --attach ID`; `chi sessions stop ID` frees the worker instead.

data/docs/testing.md

@@ -83,6 +83,25 @@ The kit's own specs, in `spec/samagotchi/testing/`, keep it and the bundles hone
   bundle's `Boundary::EXCEPTIONS` entry, each with why. A new internal reference fails it, and so does an exception
   no longer used. Fix the reference (the kit or a stable API), or add the exception with its why.
 
+## Guardrail cases corpus
+
+`spec/fixtures/guardrails/cases.jsonl` holds one labelled tool call per line, run by
+`spec/guardrails/cases_corpus_spec.rb` against a fixed rule set (`spec/fixtures/guardrails/rules.yml`) or the
+shipped guardrails bundle's rules. A case:
+
+- `id` (required, unique, kebab-case), `tool` (required: `execute`, `task_create`, `write`, `edit` or `read`),
+  `command` (a shell tool) or `path` (a file tool), `cwd` (optional: the call's `cwd:`, relative to the spec's
+  temp repo), `expect` (required), `rule` (a rule id), `rules` (optional: `fixture`, the default, or
+  `guardrails-bundle`), `source` (required: where the case came from: `heredoc-fp`, `heredoc-bypass`,
+  `chi-answer-piped`) and `note` (optional: why the label is what it is).
+- `expect` is one of two kinds: `match` / `no_match` say whether rule `rule` matches the call (`Rule#matches?`),
+  and `allow` / `ask` / `deny` the whole rule set's decision (`Rules#check`, not the Gate's core checks); with
+  `rule` given, an ask or deny must also be decided by that rule.
+
+Add a case with every guardrail false positive or miss you fix, under the `source` it came from. Never relabel
+a case to make a spec pass: a case that goes red means the code is wrong. The spec also keeps the corpus
+well formed (unique ids, known keys and labels, a rule that exists in its set).
+
 ## While you work: affected specs
 
 ```sh

data/lib/samagotchi/bootstrap/config_writer.rb

@@ -280,7 +280,7 @@ module Samagotchi
       # neither url: nor host: is Anthropic's own API (HostConfig's rule).
       def location(fields)
         url = fields["url"].to_s.strip
-        url = ANTHROPIC_URL if url.empty? && anthropic?(fields) && fields["host"].to_s.strip.empty? && fields["port"].to_s.strip.empty?
+        url = HostConfig::ANTHROPIC_URL if url.empty? && anthropic?(fields) && fields["host"].to_s.strip.empty? && fields["port"].to_s.strip.empty?
         unless url.empty?
           uri = URI.parse(url)
           path = uri.path.to_s.chomp("/")

data/lib/samagotchi/bootstrap_command.rb

@@ -337,8 +337,8 @@ module Samagotchi
         @exit = usage_error(e.message)
         return nil
       end
-      explain_name(base, name, reason)
       outcome = writer.write(name: name, fields: fields, model: model, dry_run: options[:dry_run])
+      explain_name(base, name, reason) unless outcome.kind == :exists
       code = report(outcome, model)
       return code unless INSTALLS_BUNDLES.include?(outcome.kind)
 

data/lib/samagotchi/bundles/guardrails/guardrails/rules.yml

@@ -176,12 +176,12 @@ rules:
   # ── answering chi's own questions around chi answer ───────────────────
   # A parent agent answers a child's approval with chi answer, which holds it
   # to guardrails.parent_approvals. These shapes go around that: chi --attach
-  # or chi -p with stdin from a pipe, a here-string or a file (a chi after 0.12 treats
-  # those as a parent too, but an older child doesn't), and a POST to the
-  # Bridge's or the web's answer route.
+  # or chi -p with stdin from a pipe, a here-string or a file other than
+  # /dev/null (a chi after 0.12 treats those as a parent too, but an older
+  # child doesn't), and a POST to the Bridge's or the web's answer route.
   - id: chi-answer-piped
     tool: shell
-    command: '(\|[^;&|\n]*\bchi\s([^;&|\n]*\s)?(--attach|--prompt|-p)\b|\bchi\s([^;&|\n]*\s)?(--attach|--prompt|-p)\b[^;&|\n]*<)'
+    command: '(\|[^;&|\n]*\bchi\s([^;&|\n]*\s)?(--attach|--prompt|-p)\b|\bchi\s([^;&|\n]*\s)?(--attach|--prompt|-p)\b[^;&|\n]*<(?!\s*/dev/null(?![\w./-])))'
     verdict: ask
     scopes: [once, session]
     reason: answers chi's questions from a pipe or a file, around chi answer

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

@@ -1,6 +1,6 @@
 ---
 name: guardrails
-version: 0.9.0
+version: 0.9.1
 scope: system
 description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, git hooks, chi's own config and attached context from the shell, chi context add --cmd, chi broadcast, answering chi around chi answer, removing a memory, writing a memory that reaches the system prompt (identity, model notes) or a model overlay; in strict mode also git rebase and writes and git in another checkout outside the session's repo), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
 trust_level: reviewed

data/lib/samagotchi/bundles/slow-commands/manifest.yml

@@ -1,12 +1,12 @@
 ---
 name: slow-commands
-version: 0.2.2
+version: 0.2.3
 scope: system
 description: "Remembers commands that ran past the execute limit in a project; the next identical execute is denied once a turn with advice to run it with task_create and task_wait; /slow-commands lists and forgets them"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:6bf5da2501a6404cda01c95975b005fce179f756c56222771c5ee857d7ba4b98
+  sha256: sha256:249615f1d8529ab020ea9872bb42b00463594f20a9ec44fecc4e0f58d34dce91
 # Execute::HANDED_OVER, read when the plugin loads (0.59.0); after_tool_call's
 # call:, elapsed_ms: and result: (0.57.0)
 requires_chi: ">= 0.59.0"

data/lib/samagotchi/bundles/slow-commands/plugin.rb

@@ -21,7 +21,8 @@
 # `env X=… cmd` is `X=… cmd`, an `env` with -C/-i/-u (or any other option)
 # stays as typed. The entry's `shown` is the last run as typed. Input that ends inside a quote, $(…)
 # or heredoc is never recorded, nor one with a $(…), backticks or a heredoc
-# cat/tee read as data: ShellLex makes those one placeholder, so different
+# a data reader reads as data (ShellLex: cat, tee, git commit -F -, gh …
+# --body-file -): ShellLex makes those one placeholder, so different
 # commands would share a key.
 #
 # after_tool_call records: timed out (killed at the limit), handed over as

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

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

data/lib/samagotchi/engine.rb

@@ -552,6 +552,30 @@ module Samagotchi
       @session_observer.notify(type: :recap_ready, recap: recap, generation: generation, covered: covered)
     end
 
+    # Count one side request (a recap, a plugin's ctx.ask_model: IdleClient's
+    # on_usage) in the session's side line, apart from its turns' totals.
+    # Folded and announced as :side_usage under the event lock, so the side
+    # blocks reach the UIs in fold order (the lock order event lock →
+    # metrics mutex is the existing one); then, between turns, saved to
+    # analytics.json (a running turn's end or checkpoint saves it), unless
+    # the session is gone (no session file: a late recap thread must not
+    # recreate a deleted session's folder; the folder itself may not exist
+    # yet before a first turn). Safe from any thread: the recap's, a
+    # plugin's, the turn's.
+    # @param usage [SideUsage]
+    # @return [void]
+    def note_side_usage(usage)
+      synchronize_events do
+        block = @metrics.add_side(usage)
+        @session_observer.notify(type: :side_usage, kind: usage.kind, side: block)
+      end
+      sid = @session&.id
+      return if sid.nil? || turn_running?
+      return unless File.exist?(Session.session_file(sid, state_dir: session_state_dir))
+
+      @metrics.persist(state_dir: session_state_dir)
+    end
+
     # @return [SessionMetrics] the per-session analytics collector
     attr_reader :metrics
 
@@ -2544,9 +2568,9 @@ module Samagotchi
         declared_tools: -> { toolkit_explained.declared.map(&:name) },
         use_toolkit: ->(name) { use_toolkit(name) },
         cancel_controller: ->(handler: false) { plugin_cancel_controller(handler: handler) },
-        ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:, model: nil|
+        ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:, model: nil, source: nil|
           ask_side_model(request, timeout: timeout, max_tokens: max_tokens, cancel_controller: cancel_controller,
-                                  model: model)
+                                  model: model, source: source)
         },
         model_name: -> { effective_model_ref },
         model_key: -> { @model_key },
@@ -2591,13 +2615,15 @@ module Samagotchi
     # IdleClient, so it shares nothing with the turn's backend. The client
     # is kept while the target and timeout stay (what it learned, e.g. a
     # refused thinking-off, holds for the next request); the session's id
-    # goes with the request.
+    # goes with the request. Its usage counts in the session's side line
+    # (#note_side_usage) under +source+, the asking bundle's name.
     # @return [String] the answer
-    def ask_side_model(request, timeout:, max_tokens:, cancel_controller:, model: nil)
+    def ask_side_model(request, timeout:, max_tokens:, cancel_controller:, model: nil, source: nil)
       target = model.nil? ? session_model_recap_target : configured_side_target(model)
       client = side_model_client(target, timeout)
       started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      answer = client.ask(request, max_tokens: max_tokens, cancel_controller: cancel_controller, session_id: @session&.id)
+      answer = client.ask(request, max_tokens: max_tokens, cancel_controller: cancel_controller, session_id: @session&.id,
+                                   kind: source.to_s.empty? ? "ask" : source.to_s, on_usage: method(:note_side_usage))
       Log.info(:plugins, "ask_model", model: target.label, answer_model: answer.model, chars: answer.text.length,
                                       ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round)
       answer.text

data/lib/samagotchi/guardrails/data_readers.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Guardrails
+    # Which shell commands read their stdin as data and never run it: cat and
+    # tee (to stdout), and a git or gh command taking its message from stdin.
+    # Pure word predicates over one simple command's words (the lexer's
+    # ShellLex). Everything else is an unknown consumer and stays matched.
+    module DataReaders
+      # Commands that print what they read.
+      SINKS = %w[cat tee].freeze
+      # What a heredoc body that a data reader reads becomes (the same value
+      # as ShellLex::HEREDOC).
+      HEREDOC = "\0HEREDOC"
+      # A word that is a redirection (>, >>, 2>&1, <; the same as
+      # ShellLex::REDIRECT).
+      REDIRECT = /\A\d*[<>]/
+      # git's global options that take the next word.
+      GIT_OPTIONS_WITH_VALUE = %w[-C -c --git-dir --work-tree --namespace].freeze
+      # A >& target that names an fd instead of a file: a number or -.
+      FD_TARGET = /\A(\d+|-)\z/
+
+      module_function
+
+      # The command word among a simple command's words: the NAME= words and
+      # the redirections dropped, and with a redirection written with a space
+      # (> /tmp/x) its target word too. nil when there is none.
+      def command_word(words)
+        index = command_index(words)
+        words[index] if index
+      end
+
+      # Where command_word's word is in +words+ (nil when there is none).
+      def command_index(words)
+        i = 0
+        while i < words.size
+          word = words[i]
+          if word.match?(REDIRECT)
+            i += 1 if word.match?(/\A\d*[<>]{1,2}\z/)
+          elsif !word.match?(/\A[A-Za-z_]\w*=/)
+            return i
+          end
+          i += 1
+        end
+        nil
+      end
+
+      # Whether a cat or tee command sends its output to a file (a file
+      # written can be run later): a stdout redirection whose target isn't
+      # /dev/null, a dangling >, or a tee argument that is no option,
+      # redirection, heredoc or /dev/null.
+      def writes_file?(words)
+        return true if stdout_file?(words)
+
+        File.basename(command_word(words).to_s) == "tee" && tee_file?(words)
+      end
+
+      # Whether one of +words+ sends stdout to a file: a >, >>, 1>, 1>>, >& or
+      # 1>& redirection (its target in the word, or in the next word when the
+      # operator ends it) whose target names a file and isn't /dev/null. A dup
+      # to an fd writes no file: >&2, >&-, 2>&1, and a spaced ">& 2" or
+      # ">& -". A >& with any other target does write one: bash reads
+      # ">& file" and ">&file" as "&>file".
+      def stdout_file?(words)
+        words.each_with_index do |word, i|
+          match = word.match(/\A1?(>>?)(&?)(.*)\z/m)
+          next unless match
+
+          amp = match[2]
+          target = match[3]
+          target = words[i + 1] if target.empty? # "> file", ">& 2"
+          return true if target.nil? # a dangling > or >&
+          next if target == "/dev/null"
+          next if !amp.empty? && target.match?(FD_TARGET)
+
+          return true
+        end
+        false
+      end
+
+      # Whether a tee command writes a file of its own (an argument that
+      # isn't an option, a redirection, a heredoc, a body or /dev/null).
+      def tee_file?(words)
+        verb = command_index(words)
+        return false unless verb
+
+        i = verb + 1
+        while i < words.size
+          word = words[i]
+          if word.match?(REDIRECT)
+            i += word.match?(/\A\d*[<>]{1,2}\z/) ? 2 : 1
+            next
+          end
+          return true if filename_word?(word)
+
+          i += 1
+        end
+        false
+      end
+
+      # Whether a tee argument names a file: not an option, a heredoc's tag,
+      # a body word (HEREDOC, SUBST, a script) or /dev/null.
+      def filename_word?(word)
+        !word.start_with?("-", "<<") && !word.include?("\0") && !word.include?("\n") && word != "/dev/null"
+      end
+
+      # Whether a simple command reads its stdin as a text file it never
+      # runs: cat or tee, git commit/tag -F - (--file -), gh pr|issue … -F -
+      # (--body-file -) or gh release … -F - (--notes-file -).
+      def data_reader?(words)
+        args = arguments(words)
+        verb = File.basename(args.first.to_s)
+        return true if SINKS.include?(verb)
+
+        case verb
+        when "git" then git_reader?(args)
+        when "gh" then gh_reader?(args)
+        else false
+        end
+      end
+
+      # Whether word +index+ of a simple command is the value of a message
+      # option of a data reader: git commit/tag -m/--message, gh pr|issue …
+      # -b/--body/-t/--title, gh release … -n/--notes/-t/--title. A
+      # "$(cat <<'EOF' … EOF)" there is a message, not code.
+      def message_arg?(words, index)
+        return false unless index.positive?
+
+        option = words[index - 1]
+        args = arguments(words)
+        case File.basename(args.first.to_s)
+        when "git" then git_message_option?(args, option)
+        when "gh" then gh_message_option?(args, option)
+        else false
+        end
+      end
+
+      # A simple command's arguments: the NAME= words, the redirections (with
+      # their spaced targets), the <<TAG words and the heredoc bodies left
+      # out.
+      def arguments(words)
+        args = []
+        i = 0
+        while i < words.size
+          word = words[i]
+          if word.match?(REDIRECT)
+            i += word.match?(/\A\d*[<>]{1,2}\z/) ? 2 : 1
+            next
+          end
+          args << word unless word.match?(/\A[A-Za-z_]\w*=/) || heredoc_word?(word)
+          i += 1
+        end
+        args
+      end
+
+      # Whether a word is a heredoc's <<TAG or one of its bodies.
+      def heredoc_word?(word)
+        word.match?(REDIRECT) || word.include?("\0") || word.include?("\n")
+      end
+
+      # The words after git's global options ([-C dir …] commit), nil when
+      # they run out.
+      def git_arguments(args)
+        i = 1
+        i += GIT_OPTIONS_WITH_VALUE.include?(args[i]) ? 2 : 1 while i < args.size && args[i].start_with?("-")
+        args[i..]
+      end
+
+      def git_reader?(args)
+        rest = git_arguments(args)
+        return false unless rest
+
+        subcommand, *opts = rest
+        return false unless %w[commit tag].include?(subcommand)
+
+        stdin_file?(opts, "-F", "--file")
+      end
+
+      def gh_reader?(args)
+        case args[1]
+        when "pr", "issue"
+          %w[create comment edit review].include?(args[2]) && stdin_file?(args.drop(3), "-F", "--body-file")
+        when "release"
+          %w[create edit].include?(args[2]) && stdin_file?(args.drop(3), "-F", "--notes-file")
+        else
+          false
+        end
+      end
+
+      # Whether +opts+ take their text from stdin: "-F -", "--file -",
+      # "-F-" or "--file=-".
+      def stdin_file?(opts, short, long)
+        opts.each_cons(2).any? { |a, b| [short, long].include?(a) && b == "-" } ||
+          opts.include?("#{short}-") || opts.include?("#{long}=-")
+      end
+
+      def git_message_option?(args, option)
+        rest = git_arguments(args)
+        rest && %w[commit tag].include?(rest.first) && %w[-m --message].include?(option)
+      end
+
+      def gh_message_option?(args, option)
+        case args[1]
+        when "pr", "issue"
+          %w[create comment edit review].include?(args[2]) && %w[-b --body -t --title].include?(option)
+        when "release"
+          %w[create edit].include?(args[2]) && %w[-n --notes -t --title].include?(option)
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/rules.rb

@@ -13,7 +13,9 @@ module Samagotchi
     #            a name may be a glob ("mcp_*", "mcp_{git,gh}_*"); it
     #            matches the call's name or the tool a plugin tool's call
     #            acts as (Targets#acts_as: an MCP tool behind call_tool)
-    #   command: a Ruby regex on a shell tool's command
+    #   command: a Ruby regex on a shell tool's command, the body of a
+    #            heredoc its command only reads as data left out
+    #            (Targets#rule_command, ShellLex.code_text)
     #   path:    "outside_repo", or a glob on the resolved paths (absolute
     #            or "**/…" globs match the absolute path; others the path
     #            relative to the repo root, the cwd outside one)
@@ -61,7 +63,7 @@ module Samagotchi
           return false unless targets
           return false unless for_model?(targets.model_name, targets.model_key, -> { targets.small_model? })
           return false if tools && !tool_matches?(targets.tool) && !(targets.acts_as && tool_matches?(targets.acts_as))
-          return false if command && !(targets.command && command.match?(targets.command))
+          return false if command && !(targets.rule_command && command.match?(targets.rule_command))
           return false if path && !path_matches?(targets)
           return false if git && !targets.git_outside_repo?
           return false if touches && !targets.touches_chi?