samagotchi 0.66.0 → 0.68.0

data/docs/desktop.md

@@ -20,7 +20,8 @@ sessions. Keys:
 - **⏎** sends a message: `chi send -m <the line>` with the text as quoted context above it. With the line empty,
   the text is the message.
 - **⌘⏎** sends a note: `chi note`, the line (if any) then the text.
-- **⌥⏎** pastes into an agent in a kitty window without pressing Enter (see [Agents in kitty](#agents-in-kitty));
+- **⌥⏎** pastes into an agent in a kitty window or tmux pane without pressing Enter (see
+  [Agents in kitty and tmux](#agents-in-kitty-and-tmux));
   it is not a newline.
 - **⇧⏎** is a newline, in either field. Esc closes.
 
@@ -105,11 +106,15 @@ thumbnails sit under the message line, 48 px high, the file name as a tooltip; h
   the panel closes; files from Finder are sent as they are, never touched. A send with images may take up to 30 s
   (converting, a worker starting) before the panel gives up.
 
-## Agents in kitty
+## Agents in kitty and tmux
 
 The panel can also send to agent CLIs (claude, codex, gemini, aider, …) running in
-[kitty](https://sw.kovidgoyal.net/kitty/) windows, next to chi sessions. kitty only, through its remote control;
-off until you set it up:
+[kitty](https://sw.kovidgoyal.net/kitty/) windows or [tmux](https://github.com/tmux/tmux) panes, next to chi
+sessions. Each is off until you set it up; both can be on.
+
+### kitty
+
+Through kitty's remote control:
 
 1. In `kitty.conf`, remote control on and a socket: `allow_remote_control yes` and a `listen_on unix:…` line.
 2. Copy that `listen_on` value as it is into chi's config.yml:
@@ -121,7 +126,7 @@ off until you set it up:
 
    `kitty.agents` picks the programs listed (default `claude|codex|gemini|aider|opencode|cursor-agent|amp|goose`, a
    YAML list works too; `"*"` lists every window, shells too), `kitty.binary` the kitty to run (default
-   `/Applications/kitty.app/Contents/MacOS/kitty`). See [Configuration](configuration.md#desktop-helper-agents-in-kitty).
+   `/Applications/kitty.app/Contents/MacOS/kitty`). See [Configuration](configuration.md#desktop-helper-agents-in-kitty-and-tmux).
 3. Run `chi update` (or `chi desktop upgrade`): the helper reads these from its launch file, so **after every edit of
    `kitty:`** run it again. `chi update` only rewrites the launch file when only the settings changed (no rebuild);
    `chi desktop upgrade` always rebuilds.
@@ -130,28 +135,66 @@ The helper finds the sockets itself: kitty adds `-<pid>` to a `listen_on` path f
 `{kitty_pid}`), `~` and variables the helper knows are expanded, others (`${KITTY_PID}`) stay as written, as kitty
 keeps them. Several kitty instances all count. Only `unix:` sockets work.
 
-The panel lists the windows whose foreground program is one of the agents under a **kitty** divider, between live
-and recent sessions: "claude · <its title>", the folder below, a terminal icon, and a ⌘ number like the sessions.
-With the settings on but no agent running, one dim line says "no agents in kitty". A window counts when a foreground
-process's program is an agent, also as the script of `node …/codex` (that match is untested for codex and gemini).
+A window counts when a foreground process's program is an agent, also as the script of `node …/codex` (that match is
+untested for codex and gemini).
+
+### tmux
+
+Any terminal works (iTerm, Terminal, Ghostty, kitty…) for agents started inside tmux, with no macOS permission to
+grant:
+
+1. In chi's config.yml:
+
+   ```yaml
+   tmux:
+     enabled: true
+   ```
+
+   `tmux.agents` picks the programs listed (kitty.agents' default; `"*"` lists every pane), `tmux.binary` the tmux
+   to run (default: the `tmux` on your shell's PATH when the launch file is written, e.g. `/opt/homebrew/bin/tmux`;
+   the helper itself has no PATH). See [Configuration](configuration.md#desktop-helper-agents-in-kitty-and-tmux).
+2. Run `chi update` (or `chi desktop upgrade`), and again after every edit of `tmux:`. With no tmux found they say
+   "tmux.enabled but no tmux found on PATH: set tmux.binary", and the panel "tmux not found…".
 
-- **⏎** pastes into every chosen window and presses Enter: the text as a `> ` quote, a blank line, your message, then
+Every tmux server whose socket is in `$TMUX_TMPDIR/tmux-<uid>` (`/tmp/tmux-<uid>` by default) counts: the default
+server and `tmux -L <name>` ones. A server started with `-S` elsewhere, or a tmux on another machine (inside `ssh`),
+isn't seen. The socket dir and the binary are read when the launch file is written, like the rest of it.
+
+A pane counts when its foreground program is an agent. The helper asks `ps`, not tmux's `pane_current_command`: that
+names the native claude by its version file ("2.1.296"). A pane's title is shown unless it is tmux's default (the
+host name).
+
+### In the panel
+
+The panel lists the agents between live and recent sessions: "claude · <its title>", the folder below, a terminal
+icon, and a ⌘ number like the sessions. With one terminal on, the divider says **kitty** (or **tmux**); with both,
+it says **agents**, kitty's rows come first and each row has a small `kitty` or `tmux` tag. With the settings on but
+no agent running, one dim line says "no agents in kitty" ("in tmux", "in kitty or tmux"); a terminal that can't be
+asked gets a dim line with why, also beside the other terminal's rows. The list shows at most 9 targets: many agents
+can push recent sessions out.
+
+- **⏎** pastes into every chosen agent and presses Enter: the text as a `> ` quote, a blank line, your message, then
   one image path per line. Chosen together with chi sessions, each gets the message and the panel shows one line
   ("Sent. · sent to claude · samagotchi").
-- **⌥⏎** only pastes (no Enter), and only when every chosen target is a kitty window: build up several screenshots,
-  each with its own line, then press Enter in kitty. The footer shows **Paste ⌥⏎** instead of Note then.
-- **⌘⏎** with a kitty window chosen beeps: "Notes are for chi sessions". ⌥⏎ with a chi session: "Paste only is
-  for kitty windows".
+- **⌥⏎** only pastes (no Enter), and only when every chosen target is an agent: build up several screenshots,
+  each with its own line, then press Enter in the terminal. The footer shows **Paste ⌥⏎** instead of Note then.
+- **⌘⏎** with an agent chosen beeps: "Notes are for chi sessions". ⌥⏎ with a chi session: "Paste only is for
+  kitty windows" ("… for tmux panes", "… for agents in kitty or tmux" when tmux is on).
 - **Images:** a screenshot or other image data is copied to `$TMPDIR/chi-helper-sent/<uuid>.png` (or `.tiff`) and
   its path pasted; the agent reads it from there (claude attaches it as `[Image #1]`). These files are deleted a week
   later, at the helper's next start. Finder files are pasted with their own path, `'…'`-quoted when they hold spaces.
 - The paste arrives as one bracketed paste, so the agent takes newlines as text (claude shows long ones as
-  `[Pasted text]`). With `agents: "*"` beware of a program that doesn't turn bracketed paste on: the newlines would
-  act as Enter.
-- No delivery confirmation: before pasting, the helper checks the window is still there ("window closed" if not);
-  it can't know whether the agent read it. The 16 KB cap is chi's; a kitty window takes more.
-- Focus goes back to the app you came from, as for sessions. The last choice (kitty windows too) is preselected
-  while listed; ⌘ numbers shift as windows come and go.
+  `[Pasted text]`). In kitty, with `agents: "*"`, beware of a program that doesn't turn bracketed paste on: the
+  newlines would act as Enter. tmux brackets the paste only for a program that asked for it, and keeps the newlines
+  as typed, so they don't act as Enter there.
+- tmux: a pane scrolled back (copy mode) is taken out of it first, so the paste and Enter reach the agent (the
+  scroll position is lost). A pane in another tmux mode (the `choose-tree` tree, the clock) is refused: "pane in
+  tree-mode".
+- No delivery confirmation: before pasting, the helper checks the window or pane is still there ("window closed",
+  "pane closed" if not; also for a pane of a tmux server restarted since the panel listed it); it can't know whether
+  the agent read it. The 16 KB cap is chi's; a terminal takes more.
+- Focus goes back to the app you came from, as for sessions. The last choice (agents too) is preselected while
+  listed; ⌘ numbers shift as agents come and go.
 
 ## Install
 
@@ -182,7 +225,7 @@ rewrites `launch.json`, which the app reads at each send, so the app keeps its o
 | `chi desktop install [--force] [--login]` | builds, installs and starts it; `--force` replaces an existing copy |
 | `chi desktop upgrade` | rebuilds it for this chi and restarts it, keeping the login setting (always; `chi update` does it only when needed) |
 | `chi desktop uninstall` | quits it and removes the app, its login item, launch file and settings |
-| `chi desktop status` | version against chi's, how it runs chi, state dirs, Service, hotkey, process, login item |
+| `chi desktop status` | version against chi's, how it runs chi, state dirs, Service, hotkey, process, login item, host keys |
 
 `chi self` has a `desktop` line: `0.1.x (matches)`, `0.1.w (up to date for chi 0.1.x)` (an older build whose sources
 haven't changed), `0.1.w (chi is 0.1.x: chi update)` (a rebuild is due) or `not installed`. `chi desktop status`
@@ -198,11 +241,26 @@ exports. So `install` writes `~/Library/Application Support/Chi Helper/launch.js
 - only these variables, and only when they are set: `XDG_CONFIG_HOME`, `XDG_STATE_HOME`, `GEM_HOME`, `GEM_PATH`,
   `RUBYLIB`. No tokens and no `SAMAGOTCHI_*` settings go in;
 - the settings the panel needs from config.yml, as chi read them then: the `kitty:` section (when
-  `kitty.listen_on` is set) and `broadcast_timeout` (`broadcast.triage_deadline` + 10 s).
+  `kitty.listen_on` is set), the `tmux:` section (when `tmux.enabled`: the tmux binary and the socket dir resolved
+  then, and the agents) and `broadcast_timeout` (`broadcast.triage_deadline` + 10 s).
 
 The file freezes the install shell's values. If you install with a temporary `XDG_STATE_HOME`, the helper keeps
 using it. `status` prints the baked dirs.
 
+**Host API keys** don't go in the launch file either: with the variable a host's `api_key_env:` names unset, chi
+reads the key from the login Keychain (service `chi`, account the variable's name; see
+[API keys from the Keychain](configuration.md#api-keys-from-the-keychain)). Store each key the helper's sessions
+need once:
+
+```
+security add-generic-password -s chi -a FIREWORKS_API_KEY -w
+```
+
+`chi desktop status` has a `host keys` row for the hosts the helper's chi reads (the baked `XDG_CONFIG_HOME`'s
+config.yml): `FIREWORKS_API_KEY keychain` is fine; `WORK_API_KEY this shell only` (set in your terminal, not in
+the Keychain) or `unset` comes with the `security` command to store it. `install` and `upgrade` warn about the
+same keys. No row when no host has `api_key_env:`.
+
 ### The contract with chi
 
 The helper uses only these commands, so it could ship on its own later:
@@ -235,4 +293,14 @@ broadcast` says the note may be partly delivered.
   shortcuts.
 - **"Send to chi" missing on images in Finder or Preview** after an upgrade: the Services cache still has the old
   (text-only) entry; `/System/Library/CoreServices/pbs -update`, restart the helper, or log out and back in.
+- **A new session from the panel fails with `set VAR`**, or the model picker lists a host as unreachable: the
+  helper's chi has no environment variables, so the key must be in the Keychain (`chi desktop status`, host keys).
+  `security add-generic-password -s chi -a VAR -w`, then send again; no restart needed. A session started in a
+  terminal has the terminal's variables, but once its worker exited, a send from the panel wakes it without them.
+  A stopgap until the next reboot: `launchctl setenv VAR value` (then restart the helper).
+- **"tmux not found at …"** in the panel (or "no tmux found" from `chi update`): set `tmux.binary` to your tmux
+  (`which tmux` in a terminal), then `chi update`.
+- **No tmux agents listed while they run:** check `tmux.enabled: true` and that `chi update` ran since; then compare
+  the launch file's `tmux.socket_dir` with your server's socket, `tmux display-message -p '#{socket_path}'`: it must
+  be in that dir (a different `TMUX_TMPDIR`, or a server started with `-S`, isn't seen).
 - **"No live sessions":** start one with `chi` in a terminal; `chi sessions list --live --scope=all` shows the same list.

data/docs/guardrails.md

@@ -299,14 +299,14 @@ about with its arguments (`x: sum: a=20 b=22`), and an approval of "this
 call" is keyed by them.
 
 A plugin tool that runs other tools for the model (a dispatcher such as
-`mcp_call`) can say, in its `targets:`, which tool a call acts as (`acts_as:`)
+`call_tool`) can say, in its `targets:`, which tool a call acts as (`acts_as:`)
 and with which arguments (`args:`). A rule's `tool:` then matches the call's
-own name **or** the tool it acts as: `tool: mcp_github_*` fires for an
-`mcp_call` that acts as `mcp_github_merge_pull_request`, and `tool: mcp_call`
+own name **or** the tool it acts as: `tool: mcp_github_*` fires for a
+`call_tool` that acts as `mcp_github_merge_pull_request`, and `tool: call_tool`
 fires whatever it acts as. The question names the tool it acts as (by the
 `label:` its `targets:` gives, if any: display only) and shows its arguments, and an approval of "this call" is keyed by the real name, the
 alias and those arguments (`/guardrails` lists it as
-`mcp_call>mcp_github_merge_pull_request:number=7 …`), so it never covers a
+`call_tool>mcp_github_merge_pull_request:number=7 …`), so it never covers a
 direct call of that tool, nor a direct call's approval it. A tool can't act as
 one of chi's own tools or another bundle's tool: that `acts_as:` is dropped
 (and logged as `plugin_acts_as_dropped`), and the call is matched by its own
@@ -315,7 +315,10 @@ name.
 
 ```yaml
     - id: mcp-ask
-      tool: "mcp_*"          # every MCP call (mcp_call, acting as mcp_<server>_<tool>); not a find_mcp_tools search
+      # every MCP call (call_tool, acting as mcp_<server>_<tool>); not a find_tools search.
+      # Before the rename (mcp_call) it also matched that tool's own name, for a call whose
+      # tool resolved to nothing; call_tool refuses such a call anyway.
+      tool: "mcp_*"
       verdict: ask
       reason: an MCP server's tool
 ```

data/docs/hooks.md

@@ -534,8 +534,8 @@ stripped of surrounding whitespace, except file text, an edit's
 A `write`'s `content:` is the file text; an `edit` carries `old_text:` and
 `new_text:` (its `content:` is `""`). A plugin or MCP tool's call has its
 arguments whole on `args:` (string keys) instead, and its `content:` is those
-arguments as JSON. An MCP tool's call is the mcp bundle's `mcp_call`: `tool:
-"mcp_call"`, with `args: {"tool" => "<server>/<tool>", "args" => {…}}`.
+arguments as JSON. An MCP tool's call is chi's `call_tool` (its tool index's, which the mcp
+bundle runs): `tool: "call_tool"`, with `args: {"tool" => "<server>/<tool>", "args" => {…}}`.
 
 ## Bundle Hooks (unified workflow bundle)
 

data/docs/internals/anthropic.md

@@ -0,0 +1,156 @@
+# Anthropic Messages (`api: anthropic`)
+
+A host with `api: anthropic` (Anthropic itself, a gateway passing Claude through, a local server such as Splash,
+Fireworks' Anthropic-compatible API) runs the same chat loop as `api: openai`: `LLM::Adapters::BY_API` maps both apis
+to an adapter, `HostRegistry::HostEntry#chat?` is true for either, and `Engine#backend_for` picks `LLM::ChatLoop`
+(engine.md, "The model↔tool loop"). Only the adapter differs: `LLM::AnthropicMessages` instead of `LLM::OpenAIChat`.
+The user-facing settings (`dialect:`, `auth:`, `max_tokens`, the known limits) are in configuration.md.
+
+```
+ChatLoop::Run#generate
+  → ChatLoop#wire_messages                  # the OpenAI-shaped wire every chat host gets,
+                                            # plus anthropic_content on replayed model turns
+  → AnthropicMessages#chat
+      → #request_body                       # options as Messages takes them, breakpoints on or off
+          → AnthropicWire.translate         # system blocks + messages, cache_control placed
+          → AnthropicWire.tools             # function schemas → {name, description, input_schema}
+      → POST {base}/v1/messages             # LLM::HTTP: retries, cancel, first-token limit
+      → AnthropicAssembly#add per SSE event # → ChatResponse (text, reasoning, tool_calls, usage,
+                                            #   finish_reason, provider_content)
+      → a 400 it can fix: #refusal_fix, then the same request again (once per kind)
+```
+
+## Files
+
+Paths are under `lib/samagotchi/llm/`.
+
+| File | Role |
+|---|---|
+| `adapters.rb` | `Adapters::BY_API` (`openai`, `anthropic`), `.for(entry)`, `.build(api:, …)` for side requests (`IdleClient`) |
+| `anthropic_messages.rb` | `AnthropicMessages`: the request body, `#chat` (streamed or not), the 400 fixes, `#list_models`, `#thinking_fields`, `#replays_content?` |
+| `anthropic_wire.rb` | `AnthropicWire`: ChatLoop's wire messages as Messages' `system` and `messages`, the two breakpoints, tool ids and names |
+| `anthropic_assembly.rb` | `AnthropicAssembly`: a response from a whole body (`.from_message`) or stream events (`#add`), its usage in the OpenAI shape |
+| `dialect.rb` | `Dialect` (`STANDARD`, `FIREWORKS`): what a provider's `/v1/messages` does differently |
+| `prompt_cache.rb` | `PromptCache.control`: the `cache_control` a breakpoint carries (`cache.ttl`) |
+| `chat_loop.rb` | `ChatLoop#replay_blocks`, `#reasoning_history`'s floor, `Run#with_thinking` (saves `anthropic_content`) |
+
+## The adapter
+
+`AnthropicMessages.for(entry)` takes the host's API root, key variable, `auth:`, `dialect:` and remoteness;
+`HostRegistry#adapter_for` keeps one per host for the worker's life, so what it learns from a 400 (below) lasts that
+long. Each request posts `{base}/v1/messages` with `anthropic-version: 2023-06-01`, the key in the header the host's
+`auth:` names (else the dialect's: `x-api-key` on the standard one), and `Session-Id` (plus the dialect's
+`session_header`) when the loop has a session id.
+
+`#request_body` builds, in order: `model`, `max_tokens`, `system` (when there is one), `messages`, `stream`, `tools`
+with `tool_choice: {type: "auto"}` (when any), then the loop's options. The options lose chi's OpenAI-only fields
+(`DROPPED_OPTIONS`: `reasoning_effort`, `chat_template_kwargs`, `stream_options`, `prompt_cache_key`, `logprobs`,
+`top_logprobs`, `max_completion_tokens`); configured sampling passes as written. `max_tokens` is the options'
+(`default.max_tokens`), else the model list's `max_tokens` capped at `DEFAULT_MAX_TOKENS` (64000), and never over an
+output cap a 400 named. `#with_budget_room` keeps `max_tokens` above a budget-form `budget_tokens` plus `MIN_BUDGET`.
+
+`#thinking_fields(level)` is the thinking level on this wire: `off` is `thinking: {type: "disabled"}`; `low`, `medium`
+and `high` are `thinking: {type: "adaptive", display: <dialect's>}` with `output_config: {effort: <level>}`; `default`
+sends nothing. `#thinking_off_refused_fields` (low effort) is what `IdleClient` sends a side ask whose model refused
+thinking off.
+
+`#list_models` reads `GET {base}/v1/models` page by page (`limit=1000`, `after_id`, `has_more`/`last_id`, at most
+`AdapterCommon::MAX_MODEL_PAGES`, as OpenAIChat does); `#window_of` takes `max_input_tokens`, else the OpenAI-shaped fields (`ModelListing`).
+
+## Wire translation (`AnthropicWire.translate`)
+
+ChatLoop builds the same OpenAI-shaped wire messages for every chat host (`#wire_messages`); the adapter translates
+them:
+
+- The head system message becomes the top-level `system`, as text blocks: with its `cache_split:` (from
+  `SystemPrompt#stable_length`) two blocks, the stable part first. A later system message (a reminder, a turn note,
+  the CONTEXT line) becomes user text: a mid-conversation system role is model-gated.
+- An assistant message with saved blocks (`anthropic_content`) sends them verbatim, a `tool_use`'s name and id made
+  valid (`#valid_tool_use`); without them, a text block and its `tool_use` blocks (arguments parsed into the `input`
+  object, `{}` with a warning when they aren't a JSON object). An assistant message with neither is dropped.
+- Tool messages become `tool_result` blocks in a user message. Ids are made what Messages takes
+  (`AnthropicWire.tool_id`: invalid characters replaced and a short hash appended, the same on both sides), and tool
+  names too (`.tool_name`), so a malformed one never fails every later request.
+- User parts become text and `image` blocks (a data URL as base64, an http(s) URL as a url source).
+- Consecutive messages of one role merge into one, its `tool_result` blocks first. Blank text blocks are never sent;
+  a user message left empty says `(empty)`. `reasoning_content` and `cache_split` never go out.
+
+## The response (`AnthropicAssembly`)
+
+A stream is read from its `data:` lines alone (a gateway that drops the `event:` lines works), by content-block
+index: `message_start` (served model, usage), `content_block_start` (text, thinking, redacted_thinking, tool_use),
+`content_block_delta` (`text_delta`, `thinking_delta`, `signature_delta`, `input_json_delta`), `message_delta`
+(stop reason, `stop_details`, usage). `AnthropicMessages#chat_streamed` passes every event but `ping` to `on_delta`,
+`message_start` and `message_delta` with the usage so far attached (`#with_usage`); a block's start or delta counts as shown for the first-token limit
+(`.shows?`). A 200 whose body is a JSON error instead of a stream raises that error (`#raise_plain_error`).
+
+`#response` is a `ChatResponse`:
+
+- `provider_content`: the blocks as received (string keys). A blank text block is dropped (Messages refuses one sent
+  back); a `tool_use` input is an object; a thinking block always has a `signature` (`""` when none came).
+- `finish_reason` from `FINISH_REASONS`: `end_turn`/`stop_sequence` → `stop`, `max_tokens` and
+  `model_context_window_exceeded` → `length`, `tool_use` → `tool_calls`, `refusal` → `refusal`; anything else as it is.
+- Usage in the OpenAI shape the rest of chi reads (`TokenUsage`, `SessionMetrics`, `ContextStatus`, the web's
+  `ctx.js`): Messages counts `input_tokens` without the cache, so `prompt_tokens` is input + cache reads + cache
+  writes, with `cached_tokens` and `cache_write_tokens` under `prompt_tokens_details`. Every field is optional and the
+  later value wins; all zeros is no usage (`#usage_payload`: Fireworks' `message_start` carries only zeros).
+
+## Replaying thinking blocks
+
+Messages wants a model turn's blocks back as they came: a thinking block with its signature, in its place among the
+text and `tool_use` blocks (a tool loop with thinking needs the last assistant turn's). So:
+
+- `ChatLoop::Run#with_thinking` saves the response's `provider_content` on the model entry as `anthropic_content`,
+  beside `thinking:` (string keys, so a resumed session sends the same bytes).
+- `AnthropicMessages#replays_content?` is true, and `ChatLoop#replay_blocks` puts those blocks on the wire message,
+  which `AnthropicWire` sends verbatim. Not for an interrupted entry (its partial blocks have no signature) nor for
+  one with an unpaired call (it goes as flattened text). Before the reasoning boundary (`#reasoning_boundary`) the
+  thinking blocks are left out, so only the front of the history loses them; the conversation's last model entry,
+  when it has tool calls, keeps them even there (a run stopped between steps left its `tool_use` last).
+- `ChatLoop#reasoning_history` floors the level at `turn` on a replaying adapter: `drop` would remove the running
+  run's thinking, which Messages needs. For the same reason a reasoning 400 doesn't ask again without reasoning
+  (`Run#generate`: it would resend the same body).
+- A 400 about a thinking block's signature (`BadRequest#thinking_signature?`, a Claude 5.x block bound to a
+  different conversation) fails the turn for now; configuration.md has the known limit.
+
+## Cache breakpoints
+
+`#request_body` asks `AnthropicWire.translate` for breakpoints (`cache: PromptCache.control`, carrying `ttl: "1h"`
+under `cache.ttl: 1h`) only for a chat request (`purpose: "chat"`; a recap, `ctx.ask_model` or a triage sets none),
+on a dialect with `cache_breakpoints`, and until the host refused `cache_control`. Unlike `PromptCache.mark` on the
+OpenAI path, it doesn't look at the model id or remoteness. The two marks:
+
+1. the first `system` block (with `cache_split:`, the stable part; the per-session tail goes after it unmarked), which
+   caches the tools and the system prompt for every session on that prefix;
+2. the last user block that can carry one (`#mark_last`): never a thinking block, nor one that came from a later
+   system message, which moves every request.
+
+The log line's `cache=` says `on`, `1h` or nothing (`#cache_summary`). prompt-caching.md has the cache rules.
+
+## Dialects
+
+`LLM::Dialect` is a host's `dialect:` (`Dialect.parse` warns once on an unknown name or on a host whose api isn't
+`anthropic`): `auth` (the default key header), `thinking_display` (the `display` sent with adaptive or budget
+thinking, nil for none), `cache_breakpoints` and `session_header`.
+
+| Dialect | auth | thinking display | breakpoints | session header |
+|---|---|---|---|---|
+| `STANDARD` (no `dialect:`) | `x-api-key` | `summarized` | yes | none |
+| `FIREWORKS` | Bearer | none | no (an automatic prefix cache) | `x-session-affinity` |
+
+## 400 fallbacks
+
+`AnthropicMessages#chat` handles the 400s it can fix itself, once each per request, and remembers the fix for the
+adapter's life, so ChatLoop's broader paths never see them (`#refusal_fix`, logged under `http`; kept in an
+`LLM::RefusalMemo`, locked, since the turn, side-ask and recap threads share the host's adapter):
+
+| 400 about | Fix | Remembered |
+|---|---|---|
+| `thinking.display` (`DISPLAY_RE`) | no `display` from now on (`#without_display`), the thinking kept | per host (`thinking_display_refused`) |
+| adaptive thinking or its effort (`ADAPTIVE_REFUSED_RE`) | the budget form: `thinking: {type: "enabled", budget_tokens: BUDGETS[level]}`, no effort (`#budget_form`) | per model (`thinking_form_switched`) |
+| `cache_control` | no breakpoints | per host (`cache_control_refused`) |
+| `max_tokens: N > M` (`OUTPUT_CAP_RE`) | `max_tokens` capped at M | per model (`output_cap`) |
+
+The display check comes before the adaptive one: its path (`thinking.adaptive.display`) names adaptive too. A context
+overflow, a refused sampling field, a signature or a binding-controls 400 is not one of these: it goes on as it is,
+to the loop's own handling (ChatLoop's sampling and thinking-fields fallbacks) or to the turn's failure.

data/docs/internals/background-tasks.md

@@ -18,7 +18,7 @@ Recommended workflow:
 Behavior:
 
 - `execute`, `task_create` and the `!cmd` shell bang run the command in a non-login shell: `/bin/sh -c` on Linux; on macOS, when `/bin/zsh` is there, `/bin/zsh --emulate sh +o ignore_braces +o sh_glob -o bash_rematch +o bsd_echo -c` (macOS's `/bin/sh` is bash 3.2, which can't parse an apostrophe in a heredoc inside `"$( )"`, the usual commit message shape). That mode reads no rc files and keeps POSIX word splitting, unmatched globs left as is, `{1..3}`, `[[ … =~ (…) ]]` with `BASH_REMATCH`, arrays, `$'…'`, `&>` and echo expanding `\t`. Bash-only builtins and variables (`shopt`, `BASH_VERSION`, `${!prefix*}`, `read -p`) are not there.
-- Task metadata and output are persisted under `tmp/tasks/`.
+- Task metadata and output are persisted under `tmp/tasks/`: each task's `tmp/tasks/<id>/task.json` is a `TaskRecord` (`lib/samagotchi/tools/task_record.rb`, a value object: `.from_file` reads it, `#to_file` is the JSON object written, an update is a `#with`). Its keys keep their order; `stderr_path` and `handed_over_by` (a handed-over execute) and `stop_requested_by` (a stop under way or done) are left out until set. `bundles/slow-commands` reads these files on its own, so the shape is a contract.
 - A task record keeps its process's pid and start time (`pid_started`). Before `task_stop` signals, the pid must still lead its own process group and must not have started at another time; otherwise the pid was reused by another process, nothing is signalled and the task ends as failed. A start time that can't be read at that moment (a failed `ps`) falls back to the group check, as does a record without `pid_started` (from an older chi). `task_get`, `task_list`, `task_wait`'s polls and the running-task lists (a cancelled turn's note, a worker's idle exit) make the same check, so a task whose pid was reused reads as exited (failed) at once, not as running until a `task_stop`; on macOS that is one `ps` per running task per check (~5 ms).
 - A stop (`task_stop`, the user's Stop of an `execute`, the execute limit in kill mode) TERMs the task's process group, then KILLs it after a grace. The groups its processes started are stopped too: a GNU `timeout N cmd` (without `--foreground`) moves itself and its command to a group of its own. `ProcessGroup.stop` finds them with one `ps -A -o pid=,ppid=,pgid=` (~40 ms on macOS) before the TERM and again before the KILL, walking down from the group's members. A process whose parent already exited (reparented to init, e.g. a setsid'd `cmd &`, or a backgrounded `timeout N cmd &` after its shell exited) is not found and runs on.
 - Task listing is workspace-scoped (current project only).

data/docs/internals/bundles.md

@@ -35,6 +35,8 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 | `SystemBundle`, `ShippedUpdate` | the built-in system bundle (`ensure!` at Engine start, `sync` in `chi update`) and `chi update`'s upgrade of shipped bundles; both drive the Installer with `upgrade: true` |
 | `Uninstaller`, `Trash`, `Status`, `Listing` | remove, keep removed files, `chi bundle status`, `chi bundle list` |
 | `IndexUpdater`, `IndexSync` | the managed `index.md` lines (Installer; and the write/edit tools for memories) |
+| `IndexSize` | one scope's memory index as the prompt carries it (tokens, lines, bytes): `memory.index_warn_tokens`' crossing note after a memory write, `chi self`'s summary, the prompt's figures (`SystemPrompt`) |
+| `Placeholder` | `{{placeholder}}` patterns left in an installed memory, one line per file from `Installer#detect_placeholders`; a hint, never a gate |
 
 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`