samagotchi 0.79.0 → 0.80.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc74f7069433e0f6be4252973309183e17c3ecc7ad06800684bf9be6fe40015f
-  data.tar.gz: 12a8d7e7c8002a8762d7752f6cae9bd20fae6565cb2d81636cc1ca9a6ff2469d
+  metadata.gz: 5e8f390119025dcb6df095574fb9e59e94952c709a69ae6bc6e02ffa037e1a0d
+  data.tar.gz: c67e91b18d0ef7ac8916b03045c214c12ebcf98b469f84b0ae355bb41491388e
 SHA512:
-  metadata.gz: 004ef50c618ba8bb488adf9e5623da491691bf37850946870bb94511451d8e56876288232d0bae0212dcfc7d9a1c79544d4297ef0ab8692f5678ff3617fc144c
-  data.tar.gz: cb551afd6bdae21bfd61a4ff64ead0306816b41b88f4b5083fbf5e7d2afbb9ef9b9353d5d5750ccbfd1764fe10db8c60f8eb534a2cd4d728b04e3145f84dad4a
+  metadata.gz: 4c936b332ee7cafb74cb4e09b7f3b80acac7ba1247988e755078c61e72c201489b1a48f8970c6c3d70d88b7cedc31cf432d01c5b14018073a517b65f76e45de6
+  data.tar.gz: dc77457ac7bf6a0018966bef40ccaa67da732a43edbe21e0fbcef1193583a3e00934c70c4230d3fcf14f5dd23012730f9c41bb16be8d7a64754f361ff3c2ab4a

data/CHANGELOG.md

@@ -8,6 +8,34 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.80.0] - 2026-10-17
+
+### Added
+
+- Web: the message box has an image button next to Start / Send that opens a file picker (on a phone, the camera or
+  the photo library); the picked images are added like pasted ones. A message now takes at most 20 images of up to
+  20 MB each as you add them, pasted, dropped or picked, and a toast names the files left out, instead of the send
+  failing.
+- Bundles: `samagotchi/testing` (experimental), a test kit for bundles: load a bundle in a sandbox, fire its hooks, run its commands and tools, record steers, notices and cards (RSpec `:bundle` groups or Minitest `Testing::Case`; docs/plugins.md "Testing a bundle"). The shipped bundles' specs now live in each bundle's own `spec/` and use it; a boundary spec keeps bundles on the stable surface.
+- Plugins: `ctx.http`, an HTTP client for calling services (`get`, `post_json`, `request`): short default timeouts, one error type (`Samagotchi::Plugin::HttpError`), a 4xx/5xx returned as a Response, one INFO `http` log line per call without query, headers or body (`purpose=plugin`, `bundle=`), and a call made for the turn stops when the turn is stopped (docs/plugins.md "Calling services"; experimental until 1.0). The test kit fakes it: `bundle.http.stub(…)`, `requests`, `unmatched`, and a request no stub answered fails the test.
+- `chi bootstrap` sets up Anthropic Messages hosts: a server that refuses the OpenAI model list but lists Anthropic's
+  way (api.anthropic.com, a Messages-only gateway) is written as `api: anthropic` (the url without `/v1`, `auth: bearer`
+  when only Bearer worked), with `dialect: fireworks` for Fireworks' host or model ids. `--api openai|anthropic` and
+  `--dialect standard|fireworks` override the detection; direct Fireworks stays `api: openai` with a hint, and a test
+  turn's 404 on `/chat/completions` hints `--api anthropic`. A hand-written urlless `api: anthropic` host counts as
+  api.anthropic.com, so bootstrapping it again writes nothing.
+- Plugins: `ctx.ask_model(model: "host:id")` asks a configured model (a host:id ref, an alias, or a model one of the hosts lists) instead of the session's; an unknown ref raises `ArgumentError`.
+
+### Changed
+
+- Web: the start page says "+ new session" (and "new session in …") instead of "+ new chat", matching the rest of the UI.
+- Web: the latest-sessions strip hides and shows with the same edge grip as the composer's (a drag up hides it, a drag
+  down or a click shows it, Enter/Space on the focused grip toggles, and the choice is remembered): the tile's `hide ▴`
+  and the top bar's `▴ hide` are gone, and while the strip is hidden its pill — now only its status — opens All
+  sessions in one click instead of showing the strip first.
+
+Update with `chi update` (the system bundle 0.80.0), then restart `chi web`.
+
 ## [0.79.0] - 2026-10-17
 
 ### Fixed
@@ -3282,7 +3310,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.79.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.80.0...HEAD
+[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
 [0.77.0]: https://github.com/dm1try/samagotchi/compare/v0.76.0...v0.77.0

data/README.md

@@ -69,10 +69,12 @@ Point chi at your model server; it works out the rest and writes
 chi bootstrap 192.168.1.29:8081          # llama.cpp on another machine
 chi bootstrap localhost:11434            # any OpenAI-compatible server
 chi bootstrap https://openrouter.ai/api/v1 --key-env OPENROUTER_API_KEY
+chi bootstrap https://api.anthropic.com --key-env ANTHROPIC_API_KEY
 chi bootstrap                            # look on this machine's usual ports
 ```
 
-It finds out whether the server is llama.cpp or OpenAI-compatible, picks the
+It finds out whether the server is llama.cpp, OpenAI-compatible or Anthropic's
+Messages API, picks the
 model (or asks, when there are several), sends one test request and writes
 the config. With a config already there, it adds a `hosts:` entry and keeps
 the rest of the file. Then it installs the `core` bundles (loop-guard,
@@ -127,7 +129,7 @@ pbpaste | chi send -m "same bug?" <id>    # a message to a session, the clipboar
 chi send --new --wait -m "review feat/x"  # a new session you can watch in the web; prints the answer
 ```
 
-`@shot.png` in a prompt (or a pasted/dropped image in the web UI) shows the model an image, when it can see them; see [Images](docs/cli.md#images).
+`@shot.png` in a prompt (or a pasted, dropped or picked image in the web UI) shows the model an image, when it can see them; see [Images](docs/cli.md#images).
 
 `/model` switches models, Ctrl-C cancels a turn, and Ctrl-D or `/detach` detaches (the session keeps running; `chi --attach ID` comes back). `/exit` detaches and stops the session's worker too, unless something still needs it (a running turn, another UI); `chi --resume ID` picks the conversation up again. `/exit --delete` also deletes the session once the worker has gone; `chi sessions delete ID` deletes one from the shell. `/archive` (or `chi sessions archive ID`) hides a session from every list and keeps it for good; `chi sessions list --archived` finds it again.
 
@@ -220,9 +222,9 @@ once, for the session, for the repo, or for the whole rule in the repo.
 ## Development
 
 ```sh
-bundle exec rspec    # Ruby specs
-npm test             # web frontend specs
-npm run e2e          # web UI happy paths in Chromium, fake model (once: npx playwright install chromium)
+bundle exec rspec spec lib/samagotchi/bundles/*/spec   # Ruby specs (chi's and the shipped bundles' own)
+npm test                                               # web frontend specs
+npm run e2e                                            # web UI happy paths in Chromium, fake model (once: npx playwright install chromium)
 ```
 
 Integration specs against a live model server, and what the suite isolates: [docs/testing.md](docs/testing.md).

data/docs/cli.md

@@ -2,7 +2,7 @@
 
 ## Commands
 
-- `chi bootstrap [HOST[:PORT]|URL]` — first setup: find the model server (llama.cpp or OpenAI-compatible), pick the model, send a test request and write config.yml, or add a `hosts:` entry to an existing one (see [First setup](#first-setup))
+- `chi bootstrap [HOST[:PORT]|URL]` — first setup: find the model server (llama.cpp, OpenAI-compatible or Anthropic Messages), pick the model, send a test request and write config.yml, or add a `hosts:` entry to an existing one (see [First setup](#first-setup))
 - `chi` — start a session in a background worker and attach the terminal to it, so the Web UI (or another terminal) can share it (see [Sharing a session](#sharing-a-session))
 - `chi -p "your prompt"` — run a prompt, then stay attached
 - `chi -p "your prompt" --non-interactive` — run a prompt, print the answer, exit
@@ -33,12 +33,23 @@
 ```sh
 chi bootstrap 192.168.1.29:8081          # host:port (an IP or localhost: port 8080 when none; a domain: https 443, then http 80)
 chi bootstrap https://openrouter.ai/api/v1 --key-env OPENROUTER_API_KEY
+chi bootstrap https://api.anthropic.com --key-env ANTHROPIC_API_KEY
 chi bootstrap                            # try localhost 8080, 11434, 1234, 8000
 ```
 
 - **What it is.** llama.cpp's `/props` answering means the native API (no
   `api:`); otherwise `GET /v1/models` answering means an OpenAI-compatible
-  server (`api: openai`). A URL with a path is the API base as given
+  server (`api: openai`). Only when that list is refused with 400, 401 or 403
+  does chi ask Anthropic's way (`anthropic-version`, the key in `x-api-key`,
+  once more as Bearer after a 401/403): a list there means Anthropic's
+  Messages API (`api: anthropic`, the url without `/v1`; `auth: bearer` when
+  only Bearer worked). A server that serves both, such as Splash, stays
+  `api: openai`. Fireworks (its host, or model ids under `accounts/fireworks/`)
+  on the Messages API gets `dialect: fireworks`; direct Fireworks is found as
+  OpenAI-compatible first and stays `api: openai`, with a line saying
+  `--api anthropic` takes its Messages API instead. `--api openai|anthropic`
+  and `--dialect standard|fireworks` (which implies `--api anthropic`) skip the
+  detection. A URL with a path is the API base as given
   (`…/api/v1`); a domain without a scheme is tried over https, then http.
   Each request is tried once, with 5 s timeouts, so a refused port answers
   at once.
@@ -51,8 +62,11 @@ chi bootstrap                            # try localhost 8080, 11434, 1234, 8000
   (a terminal gets a numbered list, a script the ids and exit 2). A llama.cpp
   server also shows its context size and the prompt profile its chat template
   matches.
-- **The test.** One short chat request ("test: answered in 1.1 s"); `--no-test`
-  skips it. A failed test still writes the config, says so and exits 1.
+- **The test.** One short chat request ("test: answered in 1.1 s"; `POST /v1/messages`
+  on `api: anthropic`); `--no-test` skips it. A failed test still writes the config,
+  says so and exits 1. A server found as OpenAI-compatible whose `/chat/completions`
+  answers 404 gets the hint `try --api anthropic` (a gateway's Messages url that also
+  lists the OpenAI way).
 - **The file.** With no config.yml it writes a small commented one:
   `default.model` as `<host>:<model>` and one `hosts:` entry named `local`
   (localhost), `lan` (an IP) or after the domain (`openrouter`); `--name`
@@ -662,9 +676,12 @@ A model that can see images gets them these ways:
 - **A path in plain words**: "check /home/me/shot.png and describe it". The
   model calls `read` on it and sees the picture; the tool line ends in
   `→ image 1280×800`.
-- **The Web UI**: paste or drop images into the composer. Each shows as a chip
-  (× removes it) and is sent with the message; an image alone is sent as
-  `[image: name]`. Messages show thumbnails; a click opens one full size.
+- **The Web UI**: paste or drop images into the composer, or pick them with
+  its image button (left of Start / Send; on a phone it offers the camera and
+  the photo library, and is hidden while a turn runs). Each shows as a chip (× removes it) and is sent with the
+  message; an image alone is sent as `[image: name]`. A message takes up to 20
+  images of up to 20 MB each; a toast names the files left out (over a cap, or
+  not an image). Messages show thumbnails; a click opens one full size.
 - **`chi send --image PATH`** (repeatable, up to 20) with a message, from a
   script or another terminal: `chi send --image shot.png -m "why is this red?"
   3fa2`. The attached terminal and the web show it like an image typed there.

data/docs/configuration.md

@@ -10,8 +10,8 @@ Chi reads its settings from three places; the first that sets a value wins:
 
 then the built-in default. [All settings](#all-settings) lists them.
 
-`chi bootstrap HOST[:PORT]` writes a first config for a model server, or adds
-it to this file as a `hosts:` entry (see [First setup](cli.md#first-setup)).
+`chi bootstrap HOST[:PORT]` writes a first config for a model server (llama.cpp, OpenAI-compatible or Anthropic
+Messages), or adds it to this file as a `hosts:` entry (see [First setup](cli.md#first-setup)).
 
 Default path:
 
@@ -343,6 +343,9 @@ hosts:
 
 `auth:` works on any host (`bearer` is the default everywhere but `api: anthropic`).
 
+`chi bootstrap https://api.anthropic.com --key-env ANTHROPIC_API_KEY` writes such an entry (a gateway: its url;
+`--api anthropic` / `--dialect fireworks` when the detection can't tell, see [First setup](cli.md#first-setup)).
+
 **Claude 5.x preserved thinking:** Claude 5.x models (Opus, Sonnet and Haiku 5.5, Fable 5.1) bind each thinking
 block to everything before it: the system prompt, the tools and the earlier messages. chi keeps the history
 append-only, but the system prompt or the tools can change under a session: a resume or a worker respawn after
@@ -1467,8 +1470,8 @@ its own). The first target is a long session such as a day-long coordinator, whe
   (the same flags on `chi send --new`), in the session with `/llm-context strategy … apply … budget …`
   (docs/cli.md, "Session commands"), or from the web's `llm ctx` chip in the info bar.
 - **A new web chat:** the start page's `llm ctx` chip, beside the model picker, shows the picked model's values
-  and follows a model pick. Its form (titled "new chat") sets a choice for that one chat: the chip reads
-  `llm ctx stale · new chat` in the accent colour, and the create sends it as `POST /api/sessions`'s
+  and follows a model pick. Its form (titled "new session") sets a choice for that one chat: the chip reads
+  `llm ctx stale · new session` in the accent colour, and the create sends it as `POST /api/sessions`'s
   `llm_context` (`{"strategy": "stale,forget", "apply": "turn_end", "budget": "64k"}`, each a word as
   `/llm-context` takes it, `default` for unset; anything else answers `400 invalid_llm_context` and starts
   nothing), so the session file holds it before the first turn runs. It is not remembered: it resets after a

data/docs/internals/anthropic.md

@@ -180,7 +180,9 @@ Why not send drop_block on every request: it needs adaptive or enabled thinking
 thinking field, `off` sends disabled), it would put a beta header on every request to every host, and it would drop
 the same blocks again on every request until something pruned them. The reactive form does the same work in one
 place, for one extra 400 round trip per break. The `anthropic-thinking-prefix-mismatch` diagnosis header (on the
-400, undocumented) is kept on the provider error and logged as `diagnosis` on `thinking_recovered`.
+400, undocumented) is named by the adapter to its `LLM::HTTP` (`diagnosis_header:`, from
+`AnthropicBindingRecovery::DIAGNOSIS_HEADER`), which keeps it on the provider error; it is logged as `diagnosis` on
+`thinking_recovered`. The shared transport reads no provider header of its own.
 
 ## Cache breakpoints
 

data/docs/internals/bundles.md

@@ -44,6 +44,10 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 Readers of the installed state: `Hooks::BundleLoader` (Engine), `GuardrailWiring#bundle_rules`, `Plugin::Loader`,
 `ContextProviders` (scripts), `BundleNeeds` (index markers). Each goes through `Provenance.each_installed` / `#record`
 and checks the recorded sha256 (and `requires_chi`) before loading.
+The checks live in `Hooks::BundleLoader.load` and `Plugin::Loader.load_bundle`; the loading itself is
+`BundleLoader.load_hook_file` (one hook file, into a given `namespace:`) and `Plugin::Loader.register_file` (one
+plugin file: build, `register`, `commit!`), which raise instead of logging: the bundle test kit
+(`Samagotchi::Testing::Bundle`) loads a bundle's source through them, unchecked.
 
 ## Installer#run, in order
 

data/docs/internals/engine.md

@@ -350,14 +350,22 @@ read: the idle scheduler, the Bridge's request threads, plugin threads, the UIs.
 TurnState
   ├── running?
   ├── controller        (the running turn's CancellationController)
+  ├── thread, ended     (the turn's own thread; its end event is out: post-turn work)
   ├── sink              (the turn's on_event)
   ├── steers            (plugin steers for the running turn's next boundary)
   ├── carried_steers    (for the next turn that begins)
   └── activity clock    (last_activity_at, activity_seq)
 ```
 
-- `begin!(controller:, sink:)`: running, with controller and sink, in one step; carried steers become steers.
-- `finish!`: not running, controller and sink cleared; returns the steers never taken (logged as dropped).
+- `begin!(controller:, sink:)`: running, with controller and sink (and the calling thread, the turn's own), in one
+  step; carried steers become steers.
+- `ended!`: the turn's end is decided (`end_turn`, next to `turn.ended`): its after_turn / session_end hooks run
+  after it and before `finish!`.
+- `own_controller(handler:)`: the controller for work done for the turn itself, which a plugin's `ctx.http` call
+  without `cancel:` stops with (`Plugin::Host#cancel_controller`, `Engine#plugin_cancel_controller`): the turn's, on
+  its thread or inside a plugin handler, until `ended!`; nil elsewhere (an anytime command, a service, a plugin's
+  own thread) and outside a turn. An init task's own controller wins inside one.
+- `finish!`: not running, controller, thread and sink cleared; returns the steers never taken (logged as dropped).
 - `steer(text, source:)`: queues a steer for the running turn (false with no turn).
 - `steer_next_turn(text, source:)`: queues a steer for the next turn that begins.
 
@@ -515,7 +523,8 @@ Engine initialization (in this order, among other things):
   @tools = Tools::Builtins.registry; @command_registry (SessionCommands' built-ins); @plugin_tasks
   @toolkit_binding (ToolkitBinding: the kits, the plugins' among them, and the turn-start apply)
   @thinking_notices (ThinkingNotices); @tool_index = Tools::ToolIndex.new; @peer_sources = PeerSources.new
-  the bundles' plugins load (load_plugins → ExtensionLoad#load_plugins),
+  the bundles' plugins load (load_plugins → ExtensionLoad#load_plugins; each plugin's ctx is a
+    Plugin::Context over plugin_host, whose ctx.sessions it builds itself: the test kit passes its own, sessions:),
     then (plugins or not) @tool_index.declare(@tools): find_tools + call_tool (source "index", not core),
     declared per toolkit by Registry#declared? (a source registered at load, or a reachable built-in) and
     sets call_tool's unwrap (Tools::ToolIndex: the chi group from Registry#reachable_names, the sources'
@@ -728,6 +737,7 @@ Paths are under `lib/samagotchi/`.
 | `toolkit_binding.rb` | `ToolkitBinding`: the Engine's toolkit seam (the kits, `#explained`, `ctx.use_toolkit`, the turn-start `#apply!` behind `Engine#apply_toolkit!`) |
 | `hooks/registry.rb` | Hook registry, fire order, `Hooks::Runtime` |
 | `hook_routes.rb` | `HookRoutes`: the Engine's routes for a hook's or plugin's notice (`:hook_notice`, `fallback_for:`), question, stop and steer, and the guardrails' after-load line |
+| `question_desk.rb`, `pending_question.rb`, `question_answer.rb` | `QuestionDesk`: the one open question (ask, post, answer, cancel, relay mark); `PendingQuestion` and `QuestionAnswer`, its values (Hashes only in events, Bridge JSON, the session file and the hook/plugin `ask_user` result) |
 | `event_routes.rb` | `EventRoutes`: where a card (`Engine#show_card`), a notice (`HookRoutes#notify`) and a guardrails line (`#guardrail_notify`, turn or between turns only) go: held while the plugins load, an anytime command's, an init task's, a running turn's event, else announced or held for `holding_announcements` |
 | `engine_peers.rb`, `peer_sources.rb` | `Engine::PeerView` (what the kernel's peer tools see of the Engine) and `Engine::RelayPeer` (a delegate's approval relay); `PeerSources`: the attached context sources a peer bundle declares as its peer's answers (`chi.peer_source`) |
 | `extension_load.rb` | What an Engine loads at start: config.yml and bundle hooks, plugins, `bundles:` settings; events held while plugins load |

data/docs/plugins.md

@@ -744,6 +744,7 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.stop_turn(reason)` | stop the running turn after a warn notice with the reason; true when it stopped one now. In a `:before_tool_call` block it also denies that call |
 | `ctx.stop_generation(reason)` | cut the generation that is streaming: the turn goes on and the model is asked again ([hooks.md](hooks.md#watching-the-stream)). Shows nothing: post your own notice. True when it cut one now |
 | `ctx.ask_model(messages:, prompt:, …)` | a side answer from the session's model: see [Side answers](#side-answers-ctxask_model) |
+| `ctx.http` | an HTTP client for calling services (`get`, `post_json`, `request`): see [Calling services](#calling-services-ctxhttp) |
 | `ctx.sessions` | fork, send to, read, list and stop other sessions: see [Other sessions](#other-sessions-ctxsessions) |
 | `ctx.toolkit` | the name of the session's toolkit (`full` for a session from before toolkits); nil with no session |
 | `ctx.declared_tools` | the tool names the session's next turn declares (its toolkit resolved, with its own adds and removes): ask this, not the name, whether a tool is there |
@@ -842,6 +843,10 @@ next turn never see it, and no hook fires. It returns the answer text.
 - `max_tokens:` defaults to 1024. An answer cut off by it ends with `…`.
 - `cancel:` takes a `Samagotchi::CancellationController`; cancelling it
   aborts the request.
+- `model:` names a configured model instead of the session's: `"host:id"` for a host in config.yml `hosts:`, an
+  alias from `models:`, or a bare id one of the hosts lists or declares. The host's own key and settings are used;
+  a plugin never names a URL or a key here (that is [`ctx.http`](#calling-services-ctxhttp)). A ref that names
+  nothing configured raises `ArgumentError`, asking nothing: a typo never goes to another model.
 - It blocks until the answer comes, so call it from an anytime command or a
   thread of your own. A local server that runs one request at a time
   (llama.cpp with one slot) answers it after a running turn's current
@@ -853,6 +858,78 @@ 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.
 
+## Calling services: `ctx.http`
+
+```ruby
+# The http-echo bundle (spec fixture, docs/plugins.md "Calling services"):
+# one tool that asks a local HTTP service and returns its answer.
+class Plugin
+  def initialize(settings)
+    @url = settings.fetch("url", "http://127.0.0.1:9000/ask")
+  end
+
+  def register(chi)
+    chi.tool "ask_service", "Ask the local question service and return its answer",
+             params: { question: { type: "string", description: "What to ask", required: true } },
+             label: "asking" do |args, ctx|
+      res = ctx.http.post_json(@url, { question: args["question"] }, timeout: 5)
+      if res.ok?
+        res.json["answer"].to_s
+      else
+        ctx.log.warn(:ask_failed, status: res.status)
+        "the service answered #{res.status}"
+      end
+    rescue Samagotchi::Plugin::HttpError => e
+      "the service is not reachable: #{e.message}"
+    end
+  end
+end
+```
+
+That is `spec/fixtures/http_echo_bundle` (a spec keeps the two the same; `chi bundle install` it to try it): the
+shape to copy for a plugin that calls a service, tested on `bundle.http` as in
+`spec/samagotchi/plugin/http_echo_bundle_spec.rb`.
+
+One way to call an HTTP service, with timeouts, errors, logging and Stop handled the same for every bundle.
+`Net::HTTP` stays available for what this doesn't do (streaming, multipart, redirects, connection reuse).
+
+| | |
+|---|---|
+| `ctx.http.get(url, headers: {}, timeout: 10)` | GET |
+| `ctx.http.post_json(url, body, headers: {}, timeout: 10)` | POST `body` encoded as JSON, with `Content-Type` and `Accept: application/json` (unless `headers` names them) |
+| `ctx.http.request(method, url, body: nil, headers: {}, timeout: 10)` | GET, POST, PUT, PATCH, DELETE or HEAD; `body` is a String sent as is (set your own `Content-Type`) |
+
+Every call also takes `cancel:`, a `Samagotchi::CancellationController`, which replaces the default (below).
+
+- `url` is a String or URI, `http` or `https`. A bad URL, another scheme, an unknown method, a bad header, a
+  `timeout` that isn't a positive number, or a body `post_json` can't encode as JSON raises **ArgumentError**
+  before any request.
+- `timeout` (seconds) is the connect, the write and the **per-read** timeout, not a total deadline: a server that dribbles
+  bytes can take longer.
+- It returns a `Samagotchi::Plugin::Http::Response`: `status` (Integer), `headers` (frozen, lower-case names,
+  repeated values joined with `", "`), `body` (a String, `""` for HEAD or no body), `ok?` (2xx) and `json`. A
+  **4xx or 5xx is returned, not raised**: check `ok?`. A redirect is not followed: the 3xx comes back with its
+  `location` header.
+- `body` is tagged UTF-8 when its bytes are valid UTF-8, else left binary: `body.scrub` it before handing unknown
+  text to the model. There is no size limit: don't read an endpoint you don't trust to be small.
+- `json` parses the body on each call and raises `HttpError` ("not JSON: …") when it isn't JSON.
+- **One error type.** `Samagotchi::Plugin::HttpError` means the request didn't complete: refused, timed out, DNS,
+  TLS, reset, a malformed response, a bad compressed body, or `json` on a body that isn't JSON. No raw `Errno`,
+  `Net::` or `Zlib` error escapes (the original is the error's `cause`). The message says what and where
+  (`"POST 127.0.0.1:9000: connection refused"`), never headers or a body. `Samagotchi::Plugin::HttpCancelled`
+  (a subclass) means the call was cancelled.
+- `http_proxy`, `https_proxy` and `no_proxy` are honoured as for chi's model calls (loopback is never proxied).
+  chi's own `User-Agent` is always sent: yours is replaced.
+- **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.
+- **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.
+
+`ctx.http` is experimental until 1.0, like the test kit.
+
 ## Other sessions: `ctx.sessions`
 
 ```ruby
@@ -1003,7 +1080,9 @@ CHANGELOG line and bumps the shipped bundles that use it. Anything else under
    `Samagotchi::Plugin::ToolResult`, `Samagotchi::Plugin::ModelError` (and its
    subclass `Samagotchi::Plugin::ModelCancelled`),
    `Samagotchi::Plugin::Service::Stopped`, `Samagotchi::Plugin::Sessions::Error`
-   and `Samagotchi::Plugin::AttachedContext::Error`.
+   and `Samagotchi::Plugin::AttachedContext::Error`. `ctx.http` and its
+   `Samagotchi::Plugin::HttpError` (with the subclass `HttpCancelled`) and
+   `Samagotchi::Plugin::Http::Response` are **experimental until 1.0**, like the test kit.
 2. `Samagotchi::Plugin::Peer` as a base class. A subclass defines `post`,
    `check_hint!`, `paired_lines`, `transport_line`, `peer_dir` and
    `setup_paragraph` (optionally `skill_substitutions`), and sets `NAME`,
@@ -1020,6 +1099,12 @@ CHANGELOG line and bumps the shipped bundles that use it. Anything else under
    `Samagotchi::Log.debug`, `Samagotchi::Config.get` and
    `Samagotchi::VERSION`.
 
+`Samagotchi::Testing::Boundary::ALLOWED` is the checked copy of this list,
+and `Boundary::EXCEPTIONS` the per-bundle list of what each shipped bundle
+(and its specs) reaches beyond it, each with why: the APIs to design before
+that bundle could leave chi's repo. `spec/samagotchi/testing/boundary_spec.rb`
+fails on a reference in neither (docs/testing.md).
+
 **Used by shipped bundles today, but internal** (may change without notice; a
 bundle that needs one should ask for an API instead):
 
@@ -1032,6 +1117,62 @@ bundle that needs one should ask for an API instead):
   `Samagotchi::Guardrails::GitInfo`.
 - `Samagotchi::Tools::Execute.const_get` reflection.
 
+## Testing a bundle (experimental)
+
+`samagotchi/testing` loads a bundle the way chi does and records what it does at chi's edges, so a test
+needs no fake `chi` or `ctx`. It is **experimental**: it may change in any release before 1.0.0 and is not
+part of "Stable for bundles".
+
+```ruby
+require "samagotchi/testing"
+
+bundle = Samagotchi::Testing::Bundle.load("path/to/my-bundle", settings: { "every" => 3 },
+                                          host: { session_id: "s1", cwd: Dir.pwd })
+bundle.fire(:after_turn, status: "completed")            # → the event, after the hooks
+bundle.command("/mine stop")                             # → what the command returned
+bundle.tool("my_tool", path: "a.txt")                    # → the text the model reads
+verdict = bundle.tool_call({ name: "execute", content: "rm -rf /" })
+verdict.deny?                                            # a real Guardrails::Verdict (votes: verdict.votes)
+bundle.notices.map(&:text)                               # also cards, steers, stops, generation_stops, questions
+bundle.answer({ selected: "yes" })                       # the next ask_user's answer
+bundle.model_answers << "a summary"                      # the next ask_model's answer
+bundle.sessions.on(:children) { |all:| [] }              # ctx.sessions, scripted and recorded
+bundle.http.stub(:post, "http://127.0.0.1:9000/classify", json: { label: "safe" })   # ctx.http, never the network
+bundle.set(running: false)                               # the session's values: cwd:, messages:, cancelled: …
+bundle.shutdown
+```
+
+- **Real seams.** The plugin loads through `Plugin::Loader.register_file` (the real `chi` API and a real `ctx`),
+  the hook files through `Hooks::BundleLoader.load_hook_file`, into registries that already hold chi's own
+  commands and tools: a name chi has fails the load as it would in chi. `tool_call` runs a real
+  `Guardrails::Gate` (context and targets computed for the call; `verdict:` starts from one with a vote in it).
+  Only the edges are recorded: the session (`Testing::Host`), the hook helpers (`Testing::Runtime`),
+  `ctx.sessions`, `chi.init` tasks (`bundle.run_inits`) and `chi.replace_tools` sets
+  (`bundle.apply_staged_tools!`). No sha256 or `requires_chi` check: it loads the source as it is.
+- **More:** `bundle.plugin` (the instance `register` ran on, for its own methods), `bundle.declarations` (the
+  `chi.*` calls `register` made, in order, as made), `bundle.namespace`, `bundle.hook_names(event)`,
+  `bundle.run_inits`, `sandbox.write_memory(name, text, scope:)` / `memory_dir`, `sandbox.fake_executable(name,
+  body)` (first on `PATH`), `wait_until { }`.
+- **`ctx.http` is faked.** `bundle.http.stub(method, url_or_regexp, status: 200, headers: {}, body: nil, json: nil,
+  error: nil) { |request| … }` answers it: a String URL matches exactly (query included), a Regexp the full URL, later
+  stubs win, and a stub answers every matching call (a block that counts makes a sequence). `error: :refused` or
+  `:timeout` raises the `HttpError` the real client would; `bundle.http.requests` lists what the plugin sent
+  (`method`, `url`, `headers`, `body`, `json`) and `bundle.http.unmatched` what no stub answered. A request no stub
+  answered raises `Samagotchi::Testing::UnstubbedRequest` (not an `HttpError`, but a plugin may rescue it anyway) and
+  **fails the test at teardown** (RSpec and Minitest adapters: after the cleanup, and only a test that passed), so a
+  spec can't reach the network. With plain `Bundle.load` there is no teardown: check `bundle.http.unmatched`.
+  `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
+  `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
+  own sandbox, its bundles shut down after it (chi's shipped bundles keep theirs in `<bundle>/spec/`,
+docs/testing.md). **Minitest:** `require "samagotchi/testing/minitest"` and subclass
+  `Samagotchi::Testing::Case` (the same helpers).
+
 ## The btw bundle
 
 `chi bundle install btw` (or the `dev` profile) installs the bundle shipped with chi. It is written
@@ -1097,7 +1238,7 @@ bundles:
   and values: only the digest is stored) and `cwd`. A session with a saved
   list can search its tools at once and **doesn't start the server**: the
   first call of one of its tools does (the call's row shows the wait). So a
-  session that never uses MCP spawns nothing, and a new chat opens without
+  session that never uses MCP spawns nothing, and a new session opens without
   waiting for `npx`. If the live list differs from the saved one, the saved
   one is replaced, and so is what a search finds. The model's tools never
   change, so the prompt cache keeps. The saved file also keeps the first
@@ -1127,7 +1268,7 @@ bundles:
   you want at once.
 - **`npx -y …@latest` checks the npm registry on every start** (~3.4 s for
   `chrome-devtools-mcp`, against ~0.9 s for the installed binary). The cache
-  hides it from new chats, but not from the first call. For a faster first
+  hides it from new sessions, but not from the first call. For a faster first
   call, install the server once and run it directly:
 
   ```yaml

data/docs/releasing.md

@@ -63,7 +63,7 @@ as the GitHub release body.
 | `rake 'bundles:check[ci]'` | The CI workflow's (every push and PR): the same, except the version check leaves out the system bundle, which is changed and unbumped between releases (`release:bump` moves its version with VERSION). A task argument, not `CI=1`: GitHub sets `CI` in the release workflow too. |
 | `rake release:draft_changelog` | A draft Unreleased section from the commit subjects since the last tag, grouped. Stdout only. |
 | `rake release:bump[X.Y.Z]` | VERSION, the system manifest, Gemfile.lock, CHANGELOG, and `requires_chi: ">= X.Y.Z"` for each bundle marked `requires_chi_next` (the marker dropped). No commit. |
-| `rake release:check` | Clean tracked tree, VERSION == system bundle, a CHANGELOG section, no `requires_chi_next` left, `bundles:check`, `rake lint` (RuboCop), rspec + npm test, `gem build`, then a clean install into a temp GEM_HOME that runs `chi --version`, `chi self` and `chi bundle list` with a temp HOME. Needs the network (gem dependencies). |
+| `rake release:check` | Clean tracked tree, VERSION == system bundle, a CHANGELOG section, no `requires_chi_next` left, `bundles:check`, `rake lint` (RuboCop), rspec (both roots: `spec` and the bundles' own `spec/`) + `rake bundles:specs` + npm test, `gem build`, then a clean install into a temp GEM_HOME that runs `chi --version`, `chi self` and `chi bundle list` with a temp HOME. Needs the network (gem dependencies). |
 | `rake release:notes[X.Y.Z]` | Prints the CHANGELOG section (default: the current VERSION). |
 
 ## Runbook
@@ -165,4 +165,4 @@ things differ there, and a new spec that trips on them fails only on CI:
 To run it locally, use Docker with the Ruby build CI uses
 (`ruby-X.Y.Z-ubuntu-24.04-x64.tar.gz` from ruby/ruby-builder's releases) on
 `ubuntu:24.04` with `LANG=C.UTF-8`, `zip` and `git`, and run
-`CI=1 BUNDLE_PATH=… bundle exec rspec`.
+`CI=1 BUNDLE_PATH=… bundle exec rspec spec lib/samagotchi/bundles/*/spec`.

data/docs/sessions.md

@@ -76,7 +76,7 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 **Ordering:**
 
 - `Session.list` / `SessionManager.list_sessions` / `GET /api/sessions?sort=&order=&limit=&offset=` default to `updated_at desc` (newest activity first). Also supports `created_at`, `asc`. `X-Total-Count` header when paginated.
-- Web UI (`chi web`): the page's scope is in its URL. Started in a git repo, `chi web` opens `/?dir=<that folder>`: that project's sessions, and new chats start in that folder; the header chip says `<project> · all`, and `all` opens the same place without `?dir` (every session; a new chat there starts in the server's own folder, shown on the start page, and cards name their folder; `← <project>` goes back to the project view it came from, or to the server's own project). One server serves every project: a second `chi web` (from another repo) finds it through `GET /api/info` and prints (with `--open`, opens) its page for its own folder instead of starting another. The 3 latest sessions sit above the chat (`hide ▴` puts them away behind a `▾ N sessions` pill, remembered; in a window under 900 px wide, where the strip scrolls sideways, `▴ hide` sits in the top bar where the pill comes back; a window under 700 px tall hides them by itself, so a question or approval card in the stage keeps room, and the pill shows them until the window is tall again). A parent and its delegates are one card there: its `▸ 2 delegates · 1 live · 1 waiting` chip (the waiting part in the attention colour, the card's border too) opens their rows in a popover under it (a row per delegate at any depth, indented; a click opens that one, Esc or a click outside closes it, and the strip's order holds while it is open). A fork is a card of its own, and so is a delegate whose parent isn't listed (archived, another project), with its `↳ <parent>` chip; the pill counts cards, and every live or waiting session. "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). There a parent's card holds its delegates the same way, the chip opening their rows inside the card (each with an archive button on hover), open by itself while one of them waits on you; the count says `14 (+7 delegates)`, a search that matches a delegate shows its parent's card with the list open and the matching rows marked, and select mode picks cards (archiving a parent takes its delegates). The open session is in the URL (`#/s/<id>`), so a reload or a copied link opens it again; the chi logo top left goes back to the empty start for a new chat. The message box grows with its text; drag its top edge to keep it taller (double-click resets). A file in a tool row (a read, edit or write's title) and its diff lines are refs: hover one and click to open the current file in your editor at that line, on this machine only (`web.editor`; the browser's "always allow" for the page's port and VS Code's "allow opening local files" are asked once; see [Opening files from chi web](configuration.md#opening-files-from-chi-web)). So are an edit or write approval card's paths (at the first line the dry run changes) and its diff lines, before you approve, and the numbered lines of a read's output: `lines 40–60` under it opens the text as read, numbered, when the output is the file as-is (not the head/tail preview of a big file, an error or an image; no numbers after a cut). A `path:line` (or `path:line-line`) in an answer or a step's text is one too once the turn has ended, and after a reload, when it names a file a row or card on the page touched: the path under the session's folder, else the one touched file it ends with (a bare `app.js:12` when only one touched file is named so; two such files make it none); a path without a line counts only when it is a touched file exactly. Code blocks, links, bare URLs and inline code with more than the ref in it are left alone, and a file the session didn't touch is never linked; a link whose text is such a ref alone (github-pr's link to the PR diff) becomes a ref too, and its plain click still goes to the PR. A plugin's refs on an answer (an `after_turn` hook's, see [Refs on the answer](hooks.md#refs-on-the-answer-display-only)) are paired with its links and text whatever the rows touched: they can link a file the session didn't touch, or an issue or a commit, and add their own actions to the ref's menu. A plugin tool's row carries the refs its `refs:` gives (see [Refs on a tool's row](plugins.md#refs-on-a-tools-row)): its title opens the first, and its `▾` menu adds the others as `<ref> · <action>` (the URL on hover); their URL actions work on a phone too. A ref with more than one target shows a small `▾` on hover: it opens a menu of them, in order **PR diff** (a link's), **Open in editor**, **Show in turn** and **Copy path**, and a plain click runs the first (a link's own, else the editor, else show in turn). **Show in turn** scrolls to the tool row that touched the file (looked for in the ref's own step, then its own turn, then the rows before it, then the nearest after it; there, the last one showing the ref's line, else the last one), opens the steps, the stage's steps and the row's diff (or the read showing the line) and flashes the row and the line; an answer's or a step's ref and an approval card's path have it, not a row's own title or lines. It needs no editor, so a viewer without one (a phone on the LAN) gets an answer's refs with **Show in turn** as their click; a row's title and diff lines stay plain text there. On a touch screen a tap opens the menu. A ref with a target is a tab stop: Enter runs its first target, ↓ opens the menu (↑/↓ move, Enter picks, Esc closes back to the ref). Diff and read lines have their click only. The info bar copies `chi --attach <id>` for a terminal. A session whose prompt carried model notes has a `notes: deepseek` chip there (the names without `model_notes_`; the tooltip lists each with its scope and size; `session.prompt_notes` in `GET /api/sessions/:id`, the live worker's, else the session file's; see [Memory](memory.md#model-notes)). Its `llm ctx` chip names the LLM context strategy the next turn runs under (`llm ctx stale,forget · session`, in the accent colour when the session set its own; the tooltip gives each value's source), and its popover sets the session's own strategy, apply rule and budget, or follows the model again, by running `/llm-context` in the worker (the reply shows as a command bubble); `GET /api/sessions/:id`'s `session.llm_context` carries the values (the live worker's, else resolved from the session file), and a `command_ran` that changed them carries the new ones. Its `think` chip does the same for the thinking level (`/thinking`), and on a chat host its `reasoning` chip for the reasoning history (`reasoning all · session`, `/reasoning-history`; `session.reasoning_history`, null on a native host). A `/thinking` or `/reasoning-history` change that restarts the prompt cache asks first: the reply bubble has an **Apply (restarts the cache)** button that sends its `--yes` line (the chips' Set sends that line itself; see [Changes that restart the prompt cache](configuration.md#changes-that-restart-the-prompt-cache)). It shows the context used (`ctx 42%`) and the last generation's decode speed (`87 tok/s`, `~64 tok/s` when estimated; see `/stats` in [cli.md](cli.md#session-commands)); hovering `ctx` there or on a session card lists the session's tokens in (summed over every request, with the cached share), out (with reasoning) and the cost when the provider reports one, for this session only (one estimated from a `hosts.<name>.models` price shows with `~`: `cost: ~$0.54 ($0.42 reported, ~$0.12 estimated)`); after a `/model` switch the info bar's tooltip adds a `per model:` row per run of turns on one model above those totals (`splash:qwen3-35b · 6 turns · 96.0k in / 9.0k out · ~$0.02`, a switch's prefill under its row: `└ switch prefill 58.0k uncached prompt ≈$0.01`; the timing's `model_segments`, replaced by each `generation_completed`'s; the session cards stay as they were), and right after the switch its ctx % is the new model's window's; and the memory indexes its prompt holds (`memory index: ~3.4k tokens in this session's prompt (system 2.0k, project 1.4k)`; see [Memory](memory.md#the-indexs-size)). The start page's model picker (bottom left of the composer, the chosen name `▾`) chooses the model a new chat starts on, and a fresh chain link's (see [Session chains](#session-chains); there a pick shows as a `/model` command bubble in the link); it opens a search list over the conversation (↓ or a click; downward when the start page leaves no room above): an empty search shows the last 5 picks (Recent) and then each host's model ids A–Z under the host, the default host first (an id the host declares under `hosts.<name>.models` first, noted `config`, its tooltip `served by config (hosts.<name>.models)`; a host that failed to list its models keeps those ids, greyed and noted `host down`, still pickable; a remembered or default model stays chosen even then, greyed on the button); typed words must each match the host or the id (a substring, else for 3+ characters the letters in order, so `deepseek4.1 fla` finds `openrouter · deepseek/deepseek-v4.1-flash`), ⏎ picks, Esc/Tab close, a pick puts the focus in the message box: `GET /api/models` lists the hosts' models as chi spells them (`{default, models: [{name, host, id, configured?, unavailable?, sampling?, llm_context?}], warning?}`; `configured: true` marks an id declared under `hosts.<name>.models`, listed first under its host, `unavailable: true` one whose host failed to list its models; `sampling` is the model's configured request parameters as `/model` words them, the row's tooltip in the list; bare for the default host, `host:model` for the others, from the same cached lists as `/models`, a bounded wait, a host that is down noted in `warning`), and `POST /api/sessions` takes `model` (blank means the default). Beside it, an `llm ctx` chip shows the LLM context the picked model starts under (each `GET /api/models` row's `llm_context`, as the info bar's); its form sets one for the new chat only, sent as `POST /api/sessions`'s `llm_context` and never remembered (see [configuration.md](configuration.md#llm-context-a-sessions-own-strategy)). The start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first line that is one of the new session's commands (`/model …`) goes to `POST /api/sessions/:id/command` instead, as later ones do. The browser remembers the last model picked; a running session's model is in the info bar and changes only with `/model`. In the composer a line is a command when it is `!…` or starts with one of the session's command names (its `commands` list; `/stats`, `/exit` and the other terminal words get the page's own reply); an unknown `/word` (`/usr/bin/env is missing`) goes to the model as a prompt, as in a terminal; a one-word `/word` no command answers (`/modle`) is not sent: the page shows `Unknown command /modle. Did you mean /model? /help lists the commands.` (the "Did you mean" part only when a name is close). A `POST /turn` (or a session's first `prompt`) that is one of the worker's commands runs as that command too (`202 {status, command_id, session_id}`), so `chi send`, `chi -p` and a page whose command list lags all get the command. ↑/↓ in the composer walk the prompt history the TUI's ↑ walks ([Persistent Prompt History](cli.md#persistent-prompt-history)): ↑ with the caret on the first line, ↓ from the last line while browsing, ↓ past the newest brings the draft back; `GET /api/history` returns `{entries: [...]}`, oldest first (the page fetches it on focus and after each send). The server records a sent line in the routes once the worker took it (`POST /turn` accepted, a `!command` through `POST /command` or as a session's first line); `"history": false` in the body keeps it out (an image-only send).
+- Web UI (`chi web`): the page's scope is in its URL. Started in a git repo, `chi web` opens `/?dir=<that folder>`: that project's sessions, and new sessions start in that folder; the header chip says `<project> · all`, and `all` opens the same place without `?dir` (every session; a new session there starts in the server's own folder, shown on the start page, and cards name their folder; `← <project>` goes back to the project view it came from, or to the server's own project). One server serves every project: a second `chi web` (from another repo) finds it through `GET /api/info` and prints (with `--open`, opens) its page for its own folder instead of starting another. The 3 latest sessions sit above the chat, and the grip on the chat's top edge — the same thin handle as the composer's, its twin — puts them away and brings them back: a drag up (or a click, or Enter/Space on it) hides them, a drag down (or a click) shows them again, and the choice is remembered. A hidden strip leaves its status in the top bar (`N sessions · ● 1 live · ● 1 waiting`, from the cards), and a click on that pill opens All sessions, without showing the strip first. In a window under 900 px wide, where the strip scrolls sideways, the grip stays under it, outside the scroller; a window under 700 px tall hides the strip by itself, so a question or approval card in the stage keeps room, and the grip shows it until the window is tall again. A parent and its delegates are one card there: its `▸ 2 delegates · 1 live · 1 waiting` chip (the waiting part in the attention colour, the card's border too) opens their rows in a popover under it (a row per delegate at any depth, indented; a click opens that one, Esc or a click outside closes it, and the strip's order holds while it is open). A fork is a card of its own, and so is a delegate whose parent isn't listed (archived, another project), with its `↳ <parent>` chip; the pill counts cards, and every live or waiting session. "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). There a parent's card holds its delegates the same way, the chip opening their rows inside the card (each with an archive button on hover), open by itself while one of them waits on you; the count says `14 (+7 delegates)`, a search that matches a delegate shows its parent's card with the list open and the matching rows marked, and select mode picks cards (archiving a parent takes its delegates). The open session is in the URL (`#/s/<id>`), so a reload or a copied link opens it again; the chi logo top left goes back to the empty start for a new session. The message box grows with its text; drag its top edge to keep it taller (double-click resets). A file in a tool row (a read, edit or write's title) and its diff lines are refs: hover one and click to open the current file in your editor at that line, on this machine only (`web.editor`; the browser's "always allow" for the page's port and VS Code's "allow opening local files" are asked once; see [Opening files from chi web](configuration.md#opening-files-from-chi-web)). So are an edit or write approval card's paths (at the first line the dry run changes) and its diff lines, before you approve, and the numbered lines of a read's output: `lines 40–60` under it opens the text as read, numbered, when the output is the file as-is (not the head/tail preview of a big file, an error or an image; no numbers after a cut). A `path:line` (or `path:line-line`) in an answer or a step's text is one too once the turn has ended, and after a reload, when it names a file a row or card on the page touched: the path under the session's folder, else the one touched file it ends with (a bare `app.js:12` when only one touched file is named so; two such files make it none); a path without a line counts only when it is a touched file exactly. Code blocks, links, bare URLs and inline code with more than the ref in it are left alone, and a file the session didn't touch is never linked; a link whose text is such a ref alone (github-pr's link to the PR diff) becomes a ref too, and its plain click still goes to the PR. A plugin's refs on an answer (an `after_turn` hook's, see [Refs on the answer](hooks.md#refs-on-the-answer-display-only)) are paired with its links and text whatever the rows touched: they can link a file the session didn't touch, or an issue or a commit, and add their own actions to the ref's menu. A plugin tool's row carries the refs its `refs:` gives (see [Refs on a tool's row](plugins.md#refs-on-a-tools-row)): its title opens the first, and its `▾` menu adds the others as `<ref> · <action>` (the URL on hover); their URL actions work on a phone too. A ref with more than one target shows a small `▾` on hover: it opens a menu of them, in order **PR diff** (a link's), **Open in editor**, **Show in turn** and **Copy path**, and a plain click runs the first (a link's own, else the editor, else show in turn). **Show in turn** scrolls to the tool row that touched the file (looked for in the ref's own step, then its own turn, then the rows before it, then the nearest after it; there, the last one showing the ref's line, else the last one), opens the steps, the stage's steps and the row's diff (or the read showing the line) and flashes the row and the line; an answer's or a step's ref and an approval card's path have it, not a row's own title or lines. It needs no editor, so a viewer without one (a phone on the LAN) gets an answer's refs with **Show in turn** as their click; a row's title and diff lines stay plain text there. On a touch screen a tap opens the menu. A ref with a target is a tab stop: Enter runs its first target, ↓ opens the menu (↑/↓ move, Enter picks, Esc closes back to the ref). Diff and read lines have their click only. The info bar copies `chi --attach <id>` for a terminal. A session whose prompt carried model notes has a `notes: deepseek` chip there (the names without `model_notes_`; the tooltip lists each with its scope and size; `session.prompt_notes` in `GET /api/sessions/:id`, the live worker's, else the session file's; see [Memory](memory.md#model-notes)). Its `llm ctx` chip names the LLM context strategy the next turn runs under (`llm ctx stale,forget · session`, in the accent colour when the session set its own; the tooltip gives each value's source), and its popover sets the session's own strategy, apply rule and budget, or follows the model again, by running `/llm-context` in the worker (the reply shows as a command bubble); `GET /api/sessions/:id`'s `session.llm_context` carries the values (the live worker's, else resolved from the session file), and a `command_ran` that changed them carries the new ones. Its `think` chip does the same for the thinking level (`/thinking`), and on a chat host its `reasoning` chip for the reasoning history (`reasoning all · session`, `/reasoning-history`; `session.reasoning_history`, null on a native host). A `/thinking` or `/reasoning-history` change that restarts the prompt cache asks first: the reply bubble has an **Apply (restarts the cache)** button that sends its `--yes` line (the chips' Set sends that line itself; see [Changes that restart the prompt cache](configuration.md#changes-that-restart-the-prompt-cache)). It shows the context used (`ctx 42%`) and the last generation's decode speed (`87 tok/s`, `~64 tok/s` when estimated; see `/stats` in [cli.md](cli.md#session-commands)); hovering `ctx` there or on a session card lists the session's tokens in (summed over every request, with the cached share), out (with reasoning) and the cost when the provider reports one, for this session only (one estimated from a `hosts.<name>.models` price shows with `~`: `cost: ~$0.54 ($0.42 reported, ~$0.12 estimated)`); after a `/model` switch the info bar's tooltip adds a `per model:` row per run of turns on one model above those totals (`splash:qwen3-35b · 6 turns · 96.0k in / 9.0k out · ~$0.02`, a switch's prefill under its row: `└ switch prefill 58.0k uncached prompt ≈$0.01`; the timing's `model_segments`, replaced by each `generation_completed`'s; the session cards stay as they were), and right after the switch its ctx % is the new model's window's; and the memory indexes its prompt holds (`memory index: ~3.4k tokens in this session's prompt (system 2.0k, project 1.4k)`; see [Memory](memory.md#the-indexs-size)). The start page's model picker (bottom left of the composer, the chosen name `▾`) chooses the model a new session starts on, and a fresh chain link's (see [Session chains](#session-chains); there a pick shows as a `/model` command bubble in the link); it opens a search list over the conversation (↓ or a click; downward when the start page leaves no room above): an empty search shows the last 5 picks (Recent) and then each host's model ids A–Z under the host, the default host first (an id the host declares under `hosts.<name>.models` first, noted `config`, its tooltip `served by config (hosts.<name>.models)`; a host that failed to list its models keeps those ids, greyed and noted `host down`, still pickable; a remembered or default model stays chosen even then, greyed on the button); typed words must each match the host or the id (a substring, else for 3+ characters the letters in order, so `deepseek4.1 fla` finds `openrouter · deepseek/deepseek-v4.1-flash`), ⏎ picks, Esc/Tab close, a pick puts the focus in the message box: `GET /api/models` lists the hosts' models as chi spells them (`{default, models: [{name, host, id, configured?, unavailable?, sampling?, llm_context?}], warning?}`; `configured: true` marks an id declared under `hosts.<name>.models`, listed first under its host, `unavailable: true` one whose host failed to list its models; `sampling` is the model's configured request parameters as `/model` words them, the row's tooltip in the list; bare for the default host, `host:model` for the others, from the same cached lists as `/models`, a bounded wait, a host that is down noted in `warning`), and `POST /api/sessions` takes `model` (blank means the default). Beside it, an `llm ctx` chip shows the LLM context the picked model starts under (each `GET /api/models` row's `llm_context`, as the info bar's); its form sets one for the new session only, sent as `POST /api/sessions`'s `llm_context` and never remembered (see [configuration.md](configuration.md#llm-context-a-sessions-own-strategy)). The start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first line that is one of the new session's commands (`/model …`) goes to `POST /api/sessions/:id/command` instead, as later ones do. The browser remembers the last model picked; a running session's model is in the info bar and changes only with `/model`. In the composer a line is a command when it is `!…` or starts with one of the session's command names (its `commands` list; `/stats`, `/exit` and the other terminal words get the page's own reply); an unknown `/word` (`/usr/bin/env is missing`) goes to the model as a prompt, as in a terminal; a one-word `/word` no command answers (`/modle`) is not sent: the page shows `Unknown command /modle. Did you mean /model? /help lists the commands.` (the "Did you mean" part only when a name is close). A `POST /turn` (or a session's first `prompt`) that is one of the worker's commands runs as that command too (`202 {status, command_id, session_id}`), so `chi send`, `chi -p` and a page whose command list lags all get the command. ↑/↓ in the composer walk the prompt history the TUI's ↑ walks ([Persistent Prompt History](cli.md#persistent-prompt-history)): ↑ with the caret on the first line, ↓ from the last line while browsing, ↓ past the newest brings the draft back; `GET /api/history` returns `{entries: [...]}`, oldest first (the page fetches it on focus and after each send). The server records a sent line in the routes once the worker took it (`POST /turn` accepted, a `!command` through `POST /command` or as a session's first line); `"history": false` in the body keeps it out (an image-only send).
 - Web notifications: when a session needs you while the tab is hidden or behind another window (a question or a guardrail approval, a plugin card with buttons during a turn such as check-in's, a failed turn, a turn done after 10 s or more; a delegated session only for its questions, a canceled turn never), the page title counts it, `(N) Chi`, until you come back to the tab. The bell at the right of the top bar also turns on OS notifications ("needs an answer", "needs approval", "needs you", "turn failed", "done in 42 s", under the session's first message; a click opens the session): its first click asks the browser for the permission, and the choice is kept per browser. Any session of the page's scope counts, not only the open one. What was already so when the page loaded never counts, and several chi tabs show one notification per event. A chi tab in front tells the others (a `BroadcastChannel`), so while you look at one, the ones behind neither notify nor count what it shows; coming back to a tab clears those events in the other tabs' titles too. The hub's `session` frames carry what this needs: `pending_question` (`{id, kind}`, kind `question` or `approval`), `pending_card` (`{id, bundle}`: the running turn's card with actions, from `pending_card.json` that the worker keeps in the session's folder while one is open; a card without actions, such as loop-guard's, never counts) and `last_turn` (`{outcome, ended_at, seconds, origin}`, saved in the session's JSON as the engine ends each turn).
 - The web frontend is a zero-build ES-module stack in `lib/samagotchi/web/public/`: `data.js` (retrieval, typed SSE `openStream` for a session and `openEvents` for the session list), `sessions_list.js` (the list as a pure reducer over `GET /api/events`: a snapshot replaces it, an upsert keeps a known card in place, a removal drops it; `families()` groups delegates under their parent), `families_view.js` (a parent's family chip, its rows and the strip's popover; the chip and rows as lit-html templates), `keep_focus.js` (lit reuses a list's nodes by position: a redraw keeps the focus on the same item by its `data-id` / `data-name`), `chains.js` (session chains: the links from `continues`, the cards folded into the latest link's, its `#N` chip and rows as lit-html templates, the info bar's ← → links, a refused continue, and the fresh-link rule), `notify.js` (which of those events needs the user, for the notifications), `app.js` (presentation/state; a session with no live stream gets one when its `session` event says `bridge_up`, after one re-read: `event_seq` starts over in each worker, so a dropped stream is never resumed with its old cursor), `bubbles.js` (the history's bubbles between the turns' rows: output chunks, end lines, every client's prompt bubbles by `enqueued_id` with their queued/steered badges, the idle recap, guardrail warnings, hooks' notices, plugins' steers, command and note bubbles; lit-html templates, put in the history with the sticky follow by `createBubbles`), `cards_place.js` (where plugin cards and a snapshot's notices go in the history: a card added or updated in place by its id, a running turn's into its step, a snapshot's each above the first turn after it, a finished turn's notice in its step's rows and its question resolved where it was asked; a card's action buttons), `format.js` (pure formatters such as `previewOf`), `plain_line.js` (markdown out of the plain one-line places: the stage headline, a closed step's title, an answered question card's kept-reply line), `prompt_history.js` (the composer's ↑/↓ over the shared prompt history), `commands.js` (session commands: which composer lines are commands, the page's own replies, a `command_ran`'s bubble, the page's command bubbles kept across a re-read), `composer.js` (where a composer line goes, `routeComposerLine`: /cut and /queue, the start page's own replies, a session command or `!cmd`, a typo hint, else a turn; and a session command sent from the composer or a chip), `delivery_line.js` (the composer's row above the text field in a session, always there so the composer keeps its height: the key hint while idle, and the delivery line while a turn runs: where a message typed now goes in, from the step's phase, clock and size, whether "cut in now" can land, and the queue link for a worker with the `delivery` feature, as a pure `deliveryLine`, its lit-html template and `createDeliveryControl`, which ticks it and keeps a choice armed from a link; see docs/cli.md, "Typing during a turn"), `restore.js` (a failed turn's prompt handed back into this tab's composer, before or after its `/turn` ack), `lists_view.js` (the session lists: the strip and its pill, all sessions with its search, count and select mode, their cards, the family and chain popovers; the cards, tile and pill as lit-html templates, drawn as new nodes each time, and the lists' orders as pure functions), `stream_handlers.js` (the open session's stream event handlers, by event type, over the page's views and hooks; a snapshot replays through them too), `stage_view.js` (the stage view: the running turn pinned above the composer, then handed off into the history; its pure rules and texts in `stage_model.js`, its live slots (headline, now row, trail, ticks) in `stage_slots.js`, its cap and held height in `stage_frame.js`, the in-use watch that times the hand-off in `stage_watch.js`), `info_bar.js` (the session bar's info line as a lit-html template over a plain model: id, status, model, chain links, chips, ctx, speed, clock, worker badge), `info_bar_model.js` (that model and the bar's buttons' states, built from the page's session state, its list and its in-flight continues and restarts as pure functions; `app.js`'s `updateInfoBar` applies them every second while a turn runs), `session_state.js` (what the page knows about the open session: its empty state, and `sessionStateFrom`, the fields a `GET /sessions/:id` payload sets), `refs.js` (refs: a kind and a target on the element, a plugin's ref data (label, http(s) URL actions) bound in a WeakMap by `bindRef`, the targets per kind, show in turn, one delegated set of click, key and hover listeners), `ref_menu.js` (a ref's `▾` and its menu), `ref_scan.js` (the `path:line` refs in an answer's or a step's text that name a file the session's rows touched), `answer_refs.js` (the refs a plugin attached to an answer, its `display_refs`: bound to the answer's bubble, paired with its links and text, bound with `bindRef`). Unit-tested via `npm test` (`spec/web/public/*.test.js`).
 - Selecting a session in the web UI is read-only: `GET /api/sessions/:id` never spawns a worker (it reads a live worker's snapshot when one runs, else the session file). A prompt (`POST /turn`) or a command (`POST /command`) wakes the worker, and `/stream` briefly waits for a freshly-spawned bridge before answering. A caught-up SSE reconnect holds the stream open; `reset` markers are only sent for reconnects behind the ring window, or with a cursor from another worker (event ids are `<event_seq>-<epoch>`, one epoch per worker).