samagotchi 0.64.0 → 0.66.0

data/lib/samagotchi/bundles/codex-peer/scripts/pair

@@ -0,0 +1,92 @@
+#!/bin/sh
+# pair: pair this Codex CLI session with a chi session (chi's codex-peer
+# bundle). Run from Codex, which sets CODEX_THREAD_ID:
+#
+#   sh <bundle dir>/scripts/pair <chi session id, prefix or chi web URL>
+#
+# It attaches two pushed sources to the chi session: codex-inbox, whose hint
+# is this session's thread id (chi's codex_send tool runs
+# `codex queue --thread <id>` with it), and codex-review, where Codex's
+# answers go. Again later, it only refreshes the thread id: the push carries
+# the new hint. CHI names the chi command (default: chi on the PATH).
+#
+# chi writes the session's context under its state folder, which Codex's
+# default sandbox doesn't let it write: ~/.codex/config.toml needs
+#   [sandbox_workspace_write]
+#   writable_roots = ["<state>/samagotchi/context"]
+# and a write refused says so.
+set -eu
+
+usage() {
+  echo "usage: pair <chi session id or URL (http://127.0.0.1:4567/#/s/<id>)>" >&2
+  exit 2
+}
+
+[ $# -eq 1 ] || usage
+case "$1" in
+  -h | --help) usage ;;
+  http://* | https://*)
+    id=$(printf '%s\n' "$1" | sed -n 's|.*/s/\([0-9A-Za-z-][0-9A-Za-z-]*\).*|\1|p')
+    [ -n "$id" ] || { echo "pair: no session id in $1 (a chi web URL ends in #/s/<id>)" >&2; exit 2; }
+    ;;
+  *) id=$1 ;;
+esac
+
+thread=${CODEX_THREAD_ID:-}
+if [ -z "$thread" ]; then
+  echo "pair: CODEX_THREAD_ID isn't set: run this from a Codex CLI session" >&2
+  exit 2
+fi
+chi=${CHI:-chi}
+
+# Prints chi's error, and the writable_roots line when the sandbox refused.
+fail() {
+  printf '%s\n' "$1" >&2
+  case "$1" in
+    *"Operation not permitted"* | *"Read-only file system"* | *"Permission denied"*)
+      state=${XDG_STATE_HOME:-$HOME/.local/state}
+      config='~/.codex/config.toml'
+      [ -z "${CODEX_HOME:-}" ] || config=$CODEX_HOME/config.toml
+      cat >&2 <<MSG
+pair: Codex's sandbox can't write chi's state: add to $config
+  [sandbox_workspace_write]
+  writable_roots = ["$state/samagotchi/context"]
+then restart Codex and pair again.
+MSG
+      ;;
+  esac
+  exit 1
+}
+
+# A JSON string: backslashes, quotes, tabs and newlines escaped.
+json() {
+  printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/	/\\t/g' |
+    awk 'BEGIN { ORS = ""; printf "\"" } NR > 1 { print "\\n" } { print } END { printf "\"" }'
+}
+
+# Attaches a pushed source, unless the session has one of that name already.
+attach() {
+  name=$1
+  shift
+  if ! out=$($chi context add "$name" --push "$@" "$id" 2>&1); then
+    if ! $chi context show "$name" --json "$id" >/dev/null 2>&1; then
+      fail "$out"
+    fi
+  fi
+}
+
+attach codex-inbox --why "the Codex session paired with you: send it parts with codex_send" --hint "$thread"
+text="Codex peer inbox
+thread: $thread
+codex cwd: $PWD
+paired: $(date '+%Y-%m-%d %H:%M')
+Send to it with the codex_send tool (your skill_codex_peer memory); its answers come as the codex-review context."
+if ! out=$(printf '{"text":%s,"hint":%s,"summary":%s}\n' "$(json "$text")" "$(json "$thread")" \
+  "$(json "Codex paired from $PWD")" | $chi context push codex-inbox "$id" 2>&1 >/dev/null); then
+  fail "$out"
+fi
+
+attach codex-review --why "Codex's answers to what you sent it (codex-peer)" --hint "latest Codex reply"
+
+echo "paired with chi $id (thread $thread)"
+$chi context ls "$id"

data/lib/samagotchi/bundles/codex-peer/skill_codex_peer.md

@@ -0,0 +1,68 @@
+# Skill: codex peer (send a part to the paired Codex session)
+
+A Codex CLI session the user works with can be paired with this chi
+session. Codex pairs from its side (its `chi-peer` skill): it attaches the
+`codex-inbox` context (its thread id) and `codex-review` (where its answers
+come). Then `codex_send` sends it a part of the work, for a **validate**, as
+**context**, or with a **question**.
+
+This is not a fresh review run (a headless `codex exec` that starts from
+nothing). It is a Codex that already knows the work: send it a part, not the
+session.
+
+## When
+
+Only when the user asks: "send this to Codex", "validate this with Codex",
+"give Codex this as context", "ask Codex whether…". Never after each turn,
+never on your own initiative.
+
+## Steps
+
+1. Is `codex-inbox` attached (`context_read` with no name lists it)? If not,
+   say so and don't call the tool: the user pairs from Codex. Once:
+   `/codex install-skill` (it installs Codex's `chi-peer` skill); then they
+   tell Codex "pair with chi <this session's id>".
+2. Pick exactly the part the user means (a plan step, a diff, a finding, your
+   last answer), not the whole conversation. Name the files, functions and
+   diff ranges Codex should look at, so it can check them itself.
+3. Call `codex_send`:
+   - `kind`: `validate` (check this, answer with a verdict), `context` (for
+     Codex to know; it answers only if something is wrong) or `question`.
+   - `title`: one short line; Codex's answer names it.
+   - `text`: the part, then what to check or ask and what you are unsure of.
+     A long text goes to a file Codex reads; you don't have to do anything.
+4. Tell the user it was sent, then go on. Don't wait, don't poll, don't send
+   it again.
+5. A validate's answer comes as an update of the `codex-review` context and
+   wakes you. `context_read codex-review`, check that its title matches what
+   you sent, and act on it with the user: its last line is
+   `VERDICT: OK`, `VERDICT: CHANGES` or `VERDICT: UNSURE (why)`. Codex's
+   verdict is advice; the user decides.
+
+## When it fails
+
+- "that Codex session is gone": Codex has no record of that thread. Tell the
+  user to pair again from Codex. A Codex session that was only closed is not
+  "gone": the send succeeds and the message waits for it (below).
+- "no codex on the PATH" or "no Codex CLI at …": the chi that runs this
+  session can't find `codex`; the user installs it or sets `CODEX=` to its
+  path where chi runs.
+- "Codex didn't take the message in 10 s": the Codex side didn't answer the
+  queue; the send was stopped. Say so; don't retry in a loop.
+- No answer to a validate after a while (the user asks where it is): say so
+  plainly. The Codex session may have been closed: the message waits for it;
+  the user runs `codex resume` there or pairs again from a new Codex
+  session. Codex may be mid-turn (a queued message runs after its turn), or
+  its sandbox can't write chi's state: its `~/.codex/config.toml` needs the
+  `writable_roots` line for chi's context folder (`/codex install-skill`
+  shows it), and Codex must be restarted after adding it.
+
+## Don't
+
+- Don't send secrets, tokens or whole conversations.
+- Don't answer Codex's reply with a thanks or an acknowledgement: that starts
+  a loop. One send per request.
+
+The user can send without you: `/codex validate <text>`,
+`/codex context <text>`, `/codex last` (your last answer, as context), and
+`/codex` shows whether a Codex is paired.

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

@@ -1,8 +1,8 @@
 ---
 name: coordinator
-version: 0.3.0
+version: 0.4.0
 scope: system
-description: "Coordinate parallel work: the coordinator skill (split the work, one worktree and child session per task, check each report, ask before each merge, a handoff memory to resume from), /coordinate <goal>, /coordinate resume, /coordinate end and /children"
+description: "Coordinate parallel work: the coordinator skill (split the work, one worktree and child session per task, check each report, ask before each merge, a handoff memory to resume from), /coordinate <goal>, /coordinate resume, /coordinate end and /children; the coordinator toolkit (lean + delegate, delegate_result, list_sessions)"
 trust_level: reviewed
 files:
   skill_coordinator.md:
@@ -10,6 +10,6 @@ files:
     description: "Coordinate parallel work: split it, delegate each task wait:false in its own worktree (cwd:), check each report, ask the user before each merge; resume from a handoff_* memory"
 plugin:
   file: plugin.rb
-  sha256: sha256:cc2986da0e734d2a5d6da2def682cc558c63c16e47b3605d55c597414027497d
-# the handoff memory needs memory_write's description-only form and remove: (0.36.0)
-requires_chi: ">= 0.36.0"
+  sha256: sha256:caaddd24fbec2c66fa0e88937478b7ec7799bac7c98d5dc7f71ffc3fc227953a
+# the coordinator toolkit needs chi.toolkit and ctx.use_toolkit (0.66.0)
+requires_chi: ">= 0.66.0"

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

@@ -31,6 +31,13 @@
 #
 # A child is asked before it changes anything outside its worktree by chi
 # itself (the core child-boundary guardrail), in every mode: nothing to set up.
+#
+# The coordinator toolkit is lean plus the tools that run children
+# (delegate, delegate_result, list_sessions). /coordinate puts the session
+# on it before it asks the model (ctx.use_toolkit), which chi allows only
+# before the session's first model reply and outside a turn: otherwise it
+# says to run /toolkit coordinator, unless the session declares delegate
+# anyway.
 class Plugin
   CARD_ID = "children"
   # A card takes 6 actions: Refresh and up to 5 Stops.
@@ -47,7 +54,11 @@ class Plugin
 
   def initialize(_settings = {}); end
 
+  TOOLKIT = "coordinator"
+  TOOLKIT_TOOLS = %w[delegate delegate_result list_sessions].freeze
+
   def register(chi)
+    chi.toolkit TOOLKIT, base: "lean", add: TOOLKIT_TOOLS
     chi.command "/children", "this session's child sessions: state, branch, last reply; all, stop <id>",
                 anytime: true do |args, ctx|
       children_command(args.to_s.strip, ctx)
@@ -179,12 +190,23 @@ class Plugin
   end
 
   def ask(ctx, request, done)
+    note = toolkit_note(ctx)
     begin
       ctx.sessions.send(ctx.session_id, request)
     rescue Samagotchi::Plugin::Sessions::Error => e
-      return "/coordinate: #{e.message}. Send this yourself:\n\n#{request}"
+      return [note, "/coordinate: #{e.message}. Send this yourself:\n\n#{request}"].compact.join("\n")
     end
-    done
+    [note, done].compact.join("\n")
+  end
+
+  # Puts the session on the coordinator toolkit (ctx.use_toolkit); nil when
+  # it is on it now, or chi refused but the session declares delegate
+  # anyway (its toolkit resolved: full, a kit on full), else the line that
+  # says how.
+  def toolkit_note(ctx)
+    return nil if ctx.toolkit == TOOLKIT || ctx.use_toolkit(TOOLKIT) || ctx.declared_tools.include?("delegate")
+
+    "This session's toolkit (#{ctx.toolkit}) has no delegate: run /toolkit #{TOOLKIT} to give it the coordinator's tools."
   end
 
   def quote(text)

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

@@ -1,6 +1,6 @@
 ---
 name: dev
-version: 0.4.0
+version: 0.5.0
 scope: system
 description: "Developer tools"
 trust_level: reviewed
@@ -14,3 +14,4 @@ includes:
 - github-pr
 - coordinator
 - claude-peer
+- codex-peer

data/lib/samagotchi/bundles/system/config_modification_protocol.md

@@ -57,7 +57,7 @@ Only the nested form is read. An env name used as a top-level key (`SAMAGOTCHI_D
 **Excluded maps** (YAML-only, not part of the flat registry; skipped by scalar loader):
 
 - `model_aliases:` map of alias → model id (`ModelRef.parse`, through `HostRegistry#resolve`). Keys lowercased on write (`ConfigFile.write_model_alias!`). Values may be bare `model` or qualified `host:model` (hybrid; only `:` names a host, `org/model` is an id). Aliases apply once: never point an alias at another alias.
-- `hosts:` map of `name → {host, port | url, transport, api, api_key_env, profile, first_token_timeout, vision, sampling, thinking, enabled, models}` (`ConfigFile.hosts_config`, `host_registry.rb` `HostEntry`). Names lowercased; `url:` (http/https, optional path) replaces host/port, never both; `api_key_env:` names the env var holding the API key (never write a key into config.yml); `transport` overrides `server.transport`; `first_token_timeout` (seconds, `0` = off; a negative or non-number warns and is ignored) overrides `server.first_token_timeout` for that host; `models:` (a map of model ids, or a plain list) declares ids the host serves whatever its `/v1/models` lists: no "doesn't list" warning, and a bare id routes there as if listed (`HostModel`); an entry may hold `price: {input, output, cache_read?, cache_write?}` in USD per 1M tokens (`ModelPrice`; an unset cache rate is the input rate), which estimates a cost the provider doesn't report or reports as 0 (`cost_estimate`, shown as `~$`), and `served: [ids] | any`, the models a gateway may answer that id with (no served-model warning for them); model settings stay in the root `models:`; a worker reads `hosts:` from the file as it starts (`SAMAGOTCHI_HOSTS_JSON` replaces it for a process it is set on; `SessionManager.spawn_options` unsets it for workers).
+- `hosts:` map of `name → {host, port | url, transport, api, api_key_env, auth, dialect, profile, first_token_timeout, vision, sampling, thinking, enabled, models}` (`ConfigFile.hosts_config`, `host_registry.rb` `HostEntry`). Names lowercased; `url:` (http/https, optional path) replaces host/port, never both; `api_key_env:` names the env var holding the API key (never write a key into config.yml); `auth:` (`bearer|x-api-key`) is the header the key goes in (default `x-api-key` on `api: anthropic`, Bearer elsewhere); `dialect:` (`fireworks`, or `standard` for the default; `api: anthropic` only) adjusts the Messages wire for that provider (Bearer by default, no thinking `display`, no `cache_control`, `x-session-affinity`; `LLM::Dialect`, docs/configuration.md "Anthropic Messages hosts"); `transport` overrides `server.transport`; `first_token_timeout` (seconds, `0` = off; a negative or non-number warns and is ignored) overrides `server.first_token_timeout` for that host; `models:` (a map of model ids, or a plain list) declares ids the host serves whatever its `/v1/models` lists: no "doesn't list" warning, and a bare id routes there as if listed (`HostModel`); an entry may hold `price: {input, output, cache_read?, cache_write?}` in USD per 1M tokens (`ModelPrice`; an unset cache rate is the input rate), which estimates a cost the provider doesn't report or reports as 0 (`cost_estimate`, shown as `~$`), and `served: [ids] | any`, the models a gateway may answer that id with (no served-model warning for them); model settings stay in the root `models:`; a worker reads `hosts:` from the file as it starts (`SAMAGOTCHI_HOSTS_JSON` replaces it for a process it is set on; `SessionManager.spawn_options` unsets it for workers).
 - `models:` map of model id or alias → `{profile, vision, sampling, thinking, reasoning_history}` (`ConfigFile.model_settings`). `thinking:` (here, on a host, or `thinking.level` for every model) is `off|low|medium|high|default` (`Thinking`; unquoted `off` works, `on` is not a level; `default` = send nothing). Precedence: the session's own level (`/thinking LEVEL`, saved in the session; `chi --thinking` on a session run, `chi send --new --thinking`) > `chi web --thinking`/`SAMAGOTCHI_THINKING_LEVEL` > `models:` > `hosts.<name>.thinking` > `thinking.level` in config.yml > `default`. A `sampling:` key wins over the fields a level sends (`null` drops one); `docs/configuration.md` "Thinking". `reasoning_history:` (here or on a host) is `drop|turn|all`, which of its reasoning a chat host's model gets back. Precedence: the session's own level (`/reasoning-history LEVEL`, saved in the session) > `SAMAGOTCHI_REASONING_HISTORY` > `models:` > `hosts.<name>.reasoning_history` > `turn`; `docs/configuration.md` "Reasoning history". `/thinking` and `/reasoning-history` ask before a change that restarts the prompt cache; `--yes` applies it (`chi send` commands apply directly). `sampling:` (here or on a host) is a map of request fields passed to the provider as written (`temperature`, `top_p`, `presence_penalty`, `repeat_penalty`, …; a model's fields win over its host's per field; `null` = don't send; chi's own fields like `max_tokens`/`stream` are refused with a warning; `docs/configuration.md` "Sampling"). Keys match case-insensitively. `profile` (here or on a host) is `qwen36|gemma4`: the raw prompt format for native hosts. Precedence: `--profile`/`SAMAGOTCHI_MODEL_PROFILE` > `models:` > `hosts.<name>.profile` > the llama.cpp server's chat template > the name (`qwen`/`gemma`) > `qwen36` (`ModelProfile.resolve`). Set one when a model's name hides its family (e.g. a Qwen fine-tune under another name on mlx, which has no template to read).
 - `hooks:` map of `hooks_dir` + per-event lists `{path, on_error}` (`Hooks::Loader.load`). `hooks_dir` may start with `~`.
 - `guardrails:` tool-call rules (`docs/guardrails.md`; read in `Engine#guardrail_rules`, parsed by `Guardrails::Rules.parse`): `enabled` (bool, default true; `false` drops rules and hooks' asks, a deny still applies; config.yml only, like every `guardrails` setting: no env variable), `parent_approvals` (`off`, the default: a parent agent's `chi answer` can only deny an approval; `once`: it may give "Allow once" too; a convention for an honest parent, not a security boundary, and the user's choice: set it only when the user asks), `rules:` (list), `disable:` (a rule id or a list of them, `id` or `bundle:id`, switching off a bundle's or config rule without editing it), `small_models` (`auto`, the default: small = 32B or less read from the name; a glob or list of globs; `[]` for none). A rule takes only `id`, `tool`, `command`, `path`, `git`, `models`, `verdict`, `reason`, `scopes`: `id` required; at least one of `tool` (a name, `shell` = execute + task_create, a `File.fnmatch` glob like `"mcp_*"`, or a list), `command` (a Ruby regex on the shell command), `path` (a glob, or `outside_repo`: outside the session's repo, tmp folders and memory files excepted), `git` (only `outside_repo`: a shell call runs commit/add/reset/… in another checkout); `models` (optional: `small`, a model-name glob, or a list; without it the rule is for every model); `verdict` `ask|deny`; `scopes` (for `ask`) a subset of `once, session, repo, rule`. **Any parse error (an unknown key, a bad regex, no verdict) makes chi deny every tool call** until fixed, so validate with `YAML.safe_load` and keep the list shape. Rules are read again on the next tool call after config.yml or a bundle's rules change: no restart needed. Installed bundles' rule files (`chi bundle install guardrails`) add to them; `/guardrails` lists what loaded.
@@ -128,7 +128,7 @@ A guardrail rule's `tool:` may be a glob (`tool: "mcp_*"`, verdict `ask`) to cov
 ## Validations
 
 - **Model name** (`default.model` / `SAMAGOTCHI_DEFAULT_MODEL`): `ModelProfile.required_model_name` — non-empty string, otherwise harness fails fast at startup. Via `Config.get("default.model")`.
-- **Host api** (`hosts.<name>.api`): `llama_cpp|mlx|omlx` (raw-prompt loop; also the transport) or `openai` (chat loop at `http://HOST:PORT/v1`). Absent: raw-prompt loop. It replaces the removed `backend` setting.
+- **Host api** (`hosts.<name>.api`): `llama_cpp|mlx|omlx` (raw-prompt loop; also the transport), `openai` (chat loop at `http://HOST:PORT/v1`) or `anthropic` (chat loop over the Messages API at `{url}/v1/messages`; without `url:`/`host:` it is `https://api.anthropic.com`). Absent: raw-prompt loop. It replaces the removed `backend` setting.
 - **Transport** (`server.transport`): enum `llama_cpp|mlx|omlx`.
 - **Profile** (`models.<id>.profile`, `hosts.<name>.profile`, `SAMAGOTCHI_MODEL_PROFILE`): enum `qwen36|gemma4`; an unknown one warns and is ignored.
 - **Alias name** (`write_model_alias!`):

data/lib/samagotchi/bundles/system/delegated.md

@@ -5,6 +5,7 @@ Another chi session (the parent) gave you this task. It reads only your last mes
 - Finish the task in this turn if you can. End with one reply the parent can act on without asking back: the result first, then evidence (paths, commands run and what they printed), then anything you could not verify or finish.
 - Do only what the task asks. A question ("why does this spec fail?", "what calls X?", "check whether…") gets a report, not file changes: say what you found and what change you would make, and leave making it to the parent. Edit files only when the task asks you to change, fix, add or write something, and then only the files that takes.
 - The parent may send follow-up messages later; each one is a new turn in this same session, with what you did so far.
-- Work in the directory you were started in: every cd, read, edit, test and commit stays in it (in a linked worktree, never the repository's other checkouts). Don't change config, install bundles, edit managed files or write memories unless the task asks for it.
+- Work in the directory you were started in: every cd, read, edit, test and commit stays in it (in a linked worktree, never the repository's other checkouts). Don't change config, install bundles or edit managed files unless the task asks for it.
+- Don't write memories. When a memory or skill looks wrong, or the task's own instructions led you astray, say so in your reply: what and why. The parent has more context and decides the general fix.
 - You can't delegate further. Don't start other chi sessions, and send notes only to the parent.
 - If you are blocked, stop and say so in the reply with the exact question. Use ask_user_question only when the task says the user is watching.

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.64.0
+version: 0.66.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
   self_map.md: sha256:dfc19266259a9af1e0d769b7e0f67996b740b0c9921fdf3dadad973f6e5c144a
-  config_modification_protocol.md: sha256:99ad8a596cc0f5129caf82cc00314d597f0ec309be96e2d48ca4fa936b4ae343
-  memory_guide.md: sha256:b0a1ba42c5334d4117b5733c8c26d7477364baca9169b0c0a711de6ac7fc7f3c
-  delegated.md: sha256:aedaa1e756a244904c5560fff0424e06fb468bbdcb0358bccefe321d67cd2614
+  config_modification_protocol.md: sha256:301895777916dd998d8946aaa2e8f3a6e7f2b18eaf9362eef11471ae602d54ab
+  memory_guide.md: sha256:c48eea744db69e4f3e9bb415e9a03a8c78bbcaa1205ad3b1fb157a079f92d22e
+  delegated.md: sha256:a0d6ddcd4a8be06526d964898611775fd251cfd9d145a9d16afaccaa503597bd

data/lib/samagotchi/bundles/system/memory_guide.md

@@ -94,7 +94,7 @@ Bundles are versioned directories/zips/tar.gz/git URLs with a `manifest.yml` and
 - Integrity: each file's sha256 is recorded at install; a hook/plugin/rule file changed afterwards is not loaded (rules: every call denied) until reinstalled. It is an integrity check, not proof of authorship.
 - Installing = trusting its Ruby code (hooks, plugin), like a gem. Install only copies; the code runs at the next session start (`Engine.new`), so a running worker needs a restart to pick it up.
 - A bundle without `*.md` (btw, mcp, loop-guard) adds no line to the prompt's memory index.
-- Profiles are shipped bundles with only `includes:` (bundle names): `core` (loop-guard, check-in, guardrails, slow-commands; `chi bootstrap` installs it) and `dev` (known-names, mcp, btw, skills, source-links, github-pr, coordinator, claude-peer). `chi bundle install core` installs the ones not installed and records them; a bundle the user uninstalled stays out on a later install, upgrade or `chi update`, which install only bundles new to the profile. `chi bundle uninstall core` removes its recorded bundles, then core (`docs/memory.md` "Bundle profiles").
+- Profiles are shipped bundles with only `includes:` (bundle names): `core` (loop-guard, check-in, guardrails, slow-commands; `chi bootstrap` installs it) and `dev` (known-names, mcp, btw, skills, source-links, github-pr, coordinator, claude-peer, codex-peer). `chi bundle install core` installs the ones not installed and records them; a bundle the user uninstalled stays out on a later install, upgrade or `chi update`, which install only bundles new to the profile. `chi bundle uninstall core` removes its recorded bundles, then core (`docs/memory.md` "Bundle profiles").
 
 ### CLI — `chi bundle`
 

data/lib/samagotchi/cache_confirm.rb

@@ -25,12 +25,15 @@ module Samagotchi
 
     # A command's argument words with --yes / -y (anywhere) taken out.
     # @param args [String] what follows the command name
-    # @return [Array(String, Boolean)] the rest, stripped and downcased, and
-    #   whether --yes was there
-    def split(args)
-      words = args.to_s.strip.downcase.split
-      yes = words.any? { |word| YES_FLAGS.include?(word) }
-      [(words - YES_FLAGS).join(" "), yes]
+    # @param downcase [Boolean] false keeps the words' case (/toolkit: a
+    #   plugin's or MCP server's tool names can be mixed case)
+    # @return [Array(String, Boolean)] the rest, stripped (and downcased),
+    #   and whether --yes was there
+    def split(args, downcase: true)
+      text = args.to_s.strip
+      words = (downcase ? text.downcase : text).split
+      flags, rest = words.partition { |word| YES_FLAGS.include?(word.downcase) }
+      [rest.join(" "), !flags.empty?]
     end
 
     # Whether a change must ask first: the effective level changes, the

data/lib/samagotchi/client.rb

@@ -195,9 +195,11 @@ module Samagotchi
     # @param api_key_env [String, nil] the variable holding the host's API
     #   key (llama.cpp's --api-key), sent as a bearer token on every request;
     #   nil sends no Authorization header
+    # @param auth [Symbol, nil] the header the key goes in (LLM::ApiKey::SCHEMES;
+    #   HostEntry#auth_scheme), nil: Bearer
     # @param env [Hash] where the key variable is read
     def initialize(host: nil, port: nil, open_timeout: nil, read_timeout: nil, transport: nil, sleeper: nil, scheme: nil,
-                   first_token_timeout: nil, name: nil, api_key_env: nil, env: ENV)
+                   first_token_timeout: nil, name: nil, api_key_env: nil, auth: nil, env: ENV)
       # Unified config precedence: CLI > ENV > file > default (via Samagotchi::Config)
       @host          = host || Samagotchi::Config.get("server.host")
       @port          = (port || Samagotchi::Config.get("server.port")).to_i
@@ -217,7 +219,7 @@ module Samagotchi
       @label = name.to_s.empty? ? @transport.label : name.to_s
       @http = LLM::HTTP.new(label: @label, open_timeout: @open_timeout, read_timeout: @read_timeout,
                             sleeper: sleeper, first_token_timeout: first_token_timeout,
-                            api_key: LLM::ApiKey.for(api_key_env, host: @label, env: env))
+                            api_key: LLM::ApiKey.for(api_key_env, host: @label, env: env, scheme: auth))
     end
 
     # Seconds a completion may take to stream its first text, or nil.

data/lib/samagotchi/commands/registry.rb

@@ -15,6 +15,15 @@ module Samagotchi
       # (:refuse, "busy").
       MID_TURN = %i[anytime queue refuse].freeze
 
+      # A plugin's pill in the web's selection bar (chi.annotation,
+      # docs/plugins.md): it prepares +line+ (a command line of its entry)
+      # and +template+ filled from the selection, and fills the composer
+      # with it, or sends it at once (+sends+).
+      Annotation = Data.define(:label, :line, :template, :sends) do
+        # As a listing names it ({label:, line:, template:, send:}).
+        def to_h = { label: label, line: line, template: template, send: sends }
+      end
+
       # @!attribute id [Symbol] the entry's key (:model, :rollback, …)
       # @!attribute name [String] "/model", "!rollback", …
       # @!attribute mid_turn [Symbol, #call] what a line of it does while a
@@ -28,7 +37,9 @@ module Samagotchi
       #   a built-in's with the line, and calls a bundle's with the text
       #   after the name
       # @!attribute source [String] "core", or the bundle that added it
-      Entry = Struct.new(:id, :name, :description, :mid_turn, :local, :uis, :match, :handler, :source,
+      # @!attribute annotations [Array<Annotation>] its selection-bar pills
+      #   (a bundle's command; empty for the rest)
+      Entry = Struct.new(:id, :name, :description, :mid_turn, :local, :uis, :match, :handler, :source, :annotations,
                          keyword_init: true) do
         def match?(text) = match.call(text)
 
@@ -88,15 +99,16 @@ module Samagotchi
       # @param anytime [Boolean] mid_turn: :anytime (a bundle's command)
       # @param mid_turn [Symbol, #call, nil] see Entry; nil takes +anytime+
       # @param match [#call, nil] the default matches the name alone or the
-      #   name, a space and arguments
+      #   name, any whitespace (a newline too) and arguments
+      # @param annotations [Array<Annotation>] see Entry
       # @return [Entry]
       def register(name, description, id: nil, anytime: false, mid_turn: nil, local: false, uis: nil, match: nil,
-                   source: "core", &handler)
+                   source: "core", annotations: [], &handler)
         raise ArgumentError, "command #{name} is already registered" if @entries.any? { |entry| entry.name == name }
 
         entry = Entry.new(id: id || name.delete_prefix("/").to_sym, name: name, description: description,
                           mid_turn: mid_turn || (anytime ? :anytime : :refuse), local: local, uis: uis, match: match || default_match(name),
-                          handler: handler, source: source)
+                          handler: handler, source: source, annotations: annotations.dup.freeze)
         @entries << entry
         entry
       end
@@ -162,11 +174,15 @@ module Samagotchi
       # What a snapshot tells a UI without an Engine (see .from_listing).
       # @return [Array<Hash>] {name:, description:, anytime:, mid_turn:,
       #   local:, uis:, source:} per entry, in registration order; anytime
-      #   is true only when every line is (mid_turn "anytime")
+      #   is true only when every line is (mid_turn "anytime"). An entry
+      #   with annotations adds annotations: [Annotation#to_h] (the web's
+      #   selection bar; other UIs ignore the key).
       def listing
         @entries.map do |entry|
-          { name: entry.name, description: entry.description, anytime: entry.anytime,
-            mid_turn: entry.mid_turn_label, local: entry.local ? true : false, uis: entry.uis&.map(&:to_s), source: entry.source }
+          item = { name: entry.name, description: entry.description, anytime: entry.anytime,
+                   mid_turn: entry.mid_turn_label, local: entry.local ? true : false, uis: entry.uis&.map(&:to_s), source: entry.source }
+          item[:annotations] = entry.annotations.map(&:to_h) if entry.annotations&.any?
+          item
         end
       end
 
@@ -188,7 +204,8 @@ module Samagotchi
       end
 
       def default_match(name)
-        ->(text) { text == name || text.start_with?("#{name} ") }
+        after = /\A#{Regexp.escape(name)}\s/
+        ->(text) { text == name || after.match?(text) }
       end
     end
   end

data/lib/samagotchi/config.rb

@@ -194,6 +194,12 @@ module Samagotchi
       # the config surface.
       Entry.new(key: "reasoning_history",        yaml_path: %w[reasoning_history],        type: :string, default: nil,              expose: %i[env]),
 
+      # The toolkit a new session is stored on (Toolkit.configured): the tools
+      # its prompts declare. full (every built-in) when unset; child: a
+      # delegate child's. toolkit.kits (the user's own) is read by Toolkit.kits.
+      Entry.new(key: "toolkit.default",          yaml_path: %w[toolkit default],          type: :string, default: nil,              expose: %i[env config]),
+      Entry.new(key: "toolkit.child",            yaml_path: %w[toolkit child],            type: :string, default: nil,              expose: %i[env config]),
+
       Entry.new(key: "default.max_tokens",       yaml_path: %w[default max_tokens],       type: :integer, default: nil,              expose: %i[env config cli]),
       Entry.new(key: "max_tool_output_chars",    yaml_path: %w[max_tool_output_chars],    type: :integer, default: 10_000,          expose: %i[env config cli]),
 
@@ -279,7 +285,7 @@ module Samagotchi
     # Maps of named entries and the keys an entry may hold
     # (ConfigFile.hosts_config, ConfigFile.model_settings).
     MAP_ENTRY_KEYS = {
-      "hosts" => %w[host port url transport api api_key_env profile first_token_timeout vision sampling thinking
+      "hosts" => %w[host port url transport api api_key_env auth dialect profile first_token_timeout vision sampling thinking
                     reasoning_history enabled remote window_tokens steer_cut_after llm_context_strategy llm_context_apply llm_context_budget_tokens models].freeze,
       "models" => %w[profile vision sampling thinking reasoning_history window_tokens steer_cut_after llm_context_strategy llm_context_apply
                      llm_context_budget_tokens].freeze
@@ -287,7 +293,8 @@ module Samagotchi
     # The keys a hosts.<name>.models entry may hold (HostModel.parse_map).
     HOST_MODEL_KEYS = %w[price served].freeze
     # Section keys beyond the registry's: guardrails' YAML rules (Engine#guardrail_rules).
-    SECTION_EXTRA_KEYS = { "guardrails" => %w[rules disable].freeze }.freeze
+    # And toolkit's kits (Toolkit.kits).
+    SECTION_EXTRA_KEYS = { "guardrails" => %w[rules disable].freeze, "toolkit" => %w[kits].freeze }.freeze
 
     # Fast lookup maps
     BY_KEY = ENTRIES.each_with_object({}) { |e, h| h[e.key] = e }.freeze
@@ -851,9 +858,10 @@ module Samagotchi
 
     HOSTS_KEY = "hosts"
     VALID_TRANSPORTS_FOR_CONFIG = %w[llama_cpp mlx omlx].freeze
-    # How chi talks to a host: a raw-prompt api (also the Client transport) or
-    # openai, the chat loop against <host>/v1.
-    VALID_APIS_FOR_CONFIG = (VALID_TRANSPORTS_FOR_CONFIG + %w[openai]).freeze
+    # How chi talks to a host: a raw-prompt api (also the Client transport),
+    # or a chat api the chat loop talks (LLM::Adapters): openai (Chat
+    # Completions against <host>/v1) or anthropic (Messages).
+    VALID_APIS_FOR_CONFIG = (VALID_TRANSPORTS_FOR_CONFIG + %w[openai anthropic]).freeze
     HOST_NAME_RE = /\A[a-z0-9][a-z0-9._-]*\z/i
     ENV_NAME_RE = /\A[A-Za-z_][A-Za-z0-9_]*\z/