samagotchi 0.152.0 → 0.154.0

data/docs/plugins.md

@@ -96,9 +96,8 @@ This adds a slash command. `name` is `/name`: a lowercase letter first, then a
 block returns the text to show (a String), or nil to show nothing. If the
 block raises, the user sees `/name: <error>`.
 
-A plugin command works in all three UIs:
+A plugin command works in both UIs, and in a `chi -p "/hello" --non-interactive` one-shot:
 
-- **REPL** (`chi --no-shared`): typed at the prompt, and Tab completes it.
 - **Attached TUI** (the default `chi`): the worker's snapshot names the
   session's commands, so the TUI sends `/hello` to the worker and Tab
   completes it. It needs a worker started after the bundle was installed.
@@ -107,7 +106,7 @@ A plugin command works in all three UIs:
   runs it too.
 
 A line that is not a known command keeps its old meaning: in the terminal
-UIs `/foo` goes to the model as a prompt; the web refuses it and names the
+`/foo` goes to the model as a prompt; the web refuses it and names the
 commands it knows.
 
 Any whitespace may follow the name, a newline too: `/hello` on its own line
@@ -117,7 +116,7 @@ blank lines and indentation as typed; only the ends are stripped).
 #### `anytime: true`
 
 A plugin's normal command waits for its turn: typed while a turn runs, it is
-refused as busy (the REPL puts it back into the prompt, the web into an empty composer; a plugin command can't
+refused as busy (the web puts it back into an empty composer; a plugin command can't
 ask to run after the turn, as the built-in `/model X` does). An `anytime: true` command
 runs **at once, on its own thread, beside the running turn**, and the turn
 goes on:
@@ -128,9 +127,6 @@ goes on:
   then its cards and notices **as it shows them**, and its output (the
   `command_ran`) when it finishes. So a card can say "working…" first and
   be replaced by the result.
-- In the REPL, typed while a turn runs, it starts on a thread. Its cards
-  print as it shows them, above the live region; its output prints there
-  too while the turn runs, or at the prompt once the turn has ended.
 
 Between turns an anytime command runs like any other, except that its
 cards print as it shows them rather than after its output.
@@ -142,8 +138,8 @@ running turn: they are not rows of the turn's step, and their events carry
 Its block runs on another thread than the turn, so it must be thread-safe:
 
 - Read the conversation through `ctx.messages`, a frozen copy. While a turn
-  runs, a worker's holds that turn so far; the REPL's is the conversation
-  **before** that turn (`ctx.messages_partial?` says so).
+  runs, a worker's holds that turn so far; a `--non-interactive` one-shot's
+  is the conversation **before** that turn (`ctx.messages_partial?` says so).
 - Show things only through `ctx` (`ctx.card`, `ctx.notify`), and return
   the text to show.
 - Keep your own state (instance variables) behind a `Mutex` if two
@@ -171,8 +167,7 @@ thinking is dropped). The TUI prefills `line --yes`, the web shows an Apply butt
 then runs again with `--yes` in `args` (drop it from your words). Outside a command (a hook, an init task, your
 own thread) it is always nil. A plain String or nil return is unchanged.
 
-A command that asks must not be `anytime: true`: the REPL shows only an anytime command's text, so its Apply would
-be lost. Needs chi 0.132.0.
+A command that asks must not be `anytime: true`: its Apply would be lost. Needs chi 0.132.0.
 
 ```ruby
 chi.command "/tone", "show or set this session's tone" do |args, ctx|
@@ -191,8 +186,8 @@ end
 `/help` (itself an anytime command) lists every command the session knows:
 chi's own, each bundle's with the bundle's name, and the terminal UIs' own
 (`/stats`, `/exit`, `/detach` …), marked where they run: `terminal only`,
-`attached only`, `repl only`, or `terminal and web only` (`/cut`).
-It works in all three UIs.
+`web only`, or `terminal and web only` (`/cut`).
+It works in both UIs.
 
 ### `chi.annotation(label, command:, template: "{quote}", send: false)`
 
@@ -244,8 +239,13 @@ Web only: the terminals type the command (`/claude validate <text>`).
 
 ### `chi.tool(name, description, params:, schema:, label:, preview:, targets:, refs:) { |args, ctx| … }`
 
-This adds a tool the model can call. It is declared in the system prompt and
-in the chat path's `tools:`, after chi's own tools.
+This adds a tool the model can call. A session's toolkit decides whether it
+is declared, as for a built-in ([Toolkits](configuration.md#toolkits)): `full`
+(and any kit on `base: full`) declares it, in the system prompt and in the
+chat path's `tools:`, after chi's own tools; a kit that doesn't list it (`lean`,
+`child`) leaves it **reachable**, found with `find_tools` as `chi/<name>` and
+run by `call_tool` as the tool itself ([the chi group](#chitool_sourcecall-acts_as-label-wait-prefix));
+`add:` declares it there, `remove:` takes it away.
 
 - `name`: a–z first, then a–z, 0–9 and `_`, up to 48 characters.
 - `params`: `{ name => property }`, where a property is a JSON Schema
@@ -462,6 +462,12 @@ end
   tool raises `ArgumentError` at once, as `chi.tool` does, and nothing is
   staged.
 - Inside `register`, use `chi.tool`: `replace_tools` raises there.
+- Whether the session needs `find_tools` and `call_tool` is set by the tools
+  registered when its worker started. A tool a set adds on a kit that
+  leaves it out is reachable when the kit declares them anyway (`lean` does,
+  for its left-out built-ins); on a kit that declares neither it stays out
+  of reach until the user declares it (`/toolkit add NAME`), with one warn
+  notice by your bundle's name.
 
 ### `chi.on(event, priority: 100) { |event, ctx| … }`
 
@@ -548,8 +554,8 @@ end
   so far run, and the next `value` tries again.
 - `service.running?`, `service.state` (`:idle`, `:running`, `:stopped`) and
   `service.stop`.
-- The services stop when chi leaves: the REPL exits, or the session's
-  worker exits (an idle exit, `/exit`, a crash, TERM). See
+- The services stop when chi leaves: the session's worker exits (an idle
+  exit, `/exit`, a crash, TERM), or a `--non-interactive` one-shot ends. See
   [Shutdown](#shutdown). A stopped service never starts again; `value`
   raises `Samagotchi::Plugin::Service::Stopped`.
 - A plugin whose load fails after it started services has them stopped.
@@ -565,7 +571,7 @@ repo, logging in, starting a server for the first time. `register` itself
 should return at once (everything in it runs before the session's UI is
 up), so it hands the slow part to `chi.init`. The block runs **on its own
 thread** once the session can show it: in a worker right after its Bridge
-is up (so a new web chat opens at once), in the REPL at its first prompt.
+is up (so a new web chat opens at once), in a `--non-interactive` one-shot as its turn starts.
 
 ```ruby
 class Plugin
@@ -589,7 +595,7 @@ end
 
 - **What the UIs show.** Every UI shows a running task (web: a spinner line
   over the composer, `mcp · Starting MCP server chrome (first run, saving
-  its tools)…`; the attached TUI: its activity row; the REPL: a line) and a
+  its tools)…`; the attached TUI: its activity row) and a
   line when it is done: `✓` and what the block returned, a short summary
   (`chrome ready, 3 tools`), or `<label>: done` for anything else. A UI that
   joins while it runs sees it too.
@@ -684,11 +690,12 @@ two tools in all, whatever the number of sources: `find_tools(query,
 group?)` (a keyword search that answers each match's `inputSchema`) and
 `call_tool(tool, args)` (calls one as `<group>/<tool>`; its row label is the
 first source's `label`). The index has one group of its own, **`chi`**: the
-built-ins the session's toolkit leaves out but doesn't remove
-([toolkits](configuration.md#toolkits)), each with its registered schema.
+built-ins and plugin tools (`chi.tool`) the session's toolkit leaves out but
+doesn't remove ([toolkits](configuration.md#toolkits)), each with its
+registered schema; never `find_tools` and `call_tool` themselves.
 The two tools are registered once, after the plugins load, and declared per
-toolkit when it reaches a source group or has a reachable built-in (`full`
-with no source declares neither). Nothing a
+toolkit when it reaches a source group or has a reachable tool, as the tools
+stood then (`full` with no source declares neither). Nothing a
 source publishes later changes the request's tools, only what a search
 answers, so the prompt cache keeps: the search tool's description lists the
 source groups as they were at load, and a `chi` line first, per toolkit.
@@ -703,24 +710,25 @@ session's toolkit. A source's
 group named `chi`, or named like an earlier group, is left out of search,
 lookup and the description, with one warning per name.
 
-**A built-in through `call_tool` runs as that built-in.** `call_tool(tool:
+**A chi tool through `call_tool` runs as that tool.** `call_tool(tool:
 "chi/delegate", args: {…})` (or a bare `delegate` while it's reachable) is
 turned into the `delegate` call itself before the guardrails, so rules on
 `delegate`, approvals (keyed `delegate:…`, the same as a direct call's),
 `before_tool_call`/`after_tool_call` hooks and the row see `delegate`, with
 `call[:via] == "call_tool"`; the row reads "delegate (via call_tool)", live
-and after a reload. `tool: call_tool` rules see MCP calls and misses only. A
-`chi/` name the toolkit removes or declares, or any built-in once
-`call_tool` itself is removed, is refused by its name before the guardrails
-(no hook, no card).
+and after a reload. A plugin tool's the same: `chi/web_search` runs as
+`web_search`, with its `label:`, `preview:` and `targets:`. `tool:
+call_tool` rules see MCP calls and misses only. A `chi/` name the toolkit
+removes or declares, or any chi tool once `call_tool` itself is removed, is
+refused by its name before the guardrails (no hook, no card).
 
 **On a Messages host the model calls them by name too.** With `api:
 anthropic` (not Fireworks' dialect), every tool `call_tool` reaches goes in
 the request's tools deferred (`defer_loading`: its name only, until
-something loads it): a built-in by its name, a source's tool by its
+something loads it): a built-in or plugin tool by its name, a source's tool by its
 `acts_as` (`mcp_fs_read`; one with a refusal, an acts_as two tools share, or
 a name another tool has stays out). A direct call of one runs whether
-anything loaded it or not: a built-in as itself (as if declared), a
+anything loaded it or not: a built-in or plugin tool as itself (as if declared), a
 source's tool as the `call_tool` call it stands for, so its rules,
 approvals, hooks and row are `call_tool`'s. Elsewhere such a call is
 refused with the `call_tool` route, as before.
@@ -806,7 +814,7 @@ A cheap System 1 question this bundle asks with `ctx.judge` or `ctx.judge_later`
 The plugin's context (the `ctx` its handlers get), for `register` itself:
 its settings, log and data_dir, for example. A `ctx.notify` or `ctx.card`
 while chi starts (inside `register`) is shown once the session's UI can show
-it (a worker's Bridge is up, the REPL's first prompt), after the plugins'
+it (a worker's Bridge is up), after the plugins'
 load warnings; a UI that joins later still gets it.
 
 ### Names
@@ -835,7 +843,7 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.scratch?` | whether the session is a `chi scratch` one (deleted when it ends) |
 | `ctx.delegate?` | whether the session is a delegate child: a task another session handed over |
 | `ctx.review?` | whether the session is a review session (`chi review`): one its participants read, not the owner's working session |
-| `ctx.frontend` | what runs the session, read now: `:repl` (the REPL, `-p` without `--non-interactive`), `:one_shot` (`-p --non-interactive`: one turn, then exit) or `:worker` (a session worker: the web, an attached TUI). Only a worker's answers reach the web while it runs; a REPL's show there once the session is opened. Until the host sets it (while the plugins load, inside `Engine.new`) it reads `:one_shot`, so read it in hooks and init tasks, not in `register` |
+| `ctx.frontend` | what runs the session, read now: `:one_shot` (`-p --non-interactive`: one turn, then exit) or `:worker` (a session worker: the web, an attached TUI). There is no `:repl` any more: a bundle that checks for it never matches. Only a worker's answers reach the web while it runs; a one-shot's show there once the session is opened. Until the host sets it (while the plugins load, inside `Engine.new`) it reads `:one_shot`, so read it in hooks and init tasks, not in `register` |
 | `ctx.continues` | the id of the session this one continues (a [continue](sessions.md#session-chains)'s new link), else nil |
 | `ctx.fork?` | whether the session is a fork (`ctx.sessions.fork`): it has a parent but isn't a delegate child, and started from a conversation, so its first prompt isn't its first user message |
 | `ctx.model` | the model the session runs on now: its resolved ref (`host:id`), right after `/model` too |
@@ -848,8 +856,9 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.data_dir` | `$XDG_STATE_HOME/samagotchi/plugins/<bundle>/`, created on first use: what the bundle keeps across sessions |
 | `ctx.session_dir` | this session's own folder there, created on use, read now; nil with no session yet. `ctx.session_dir(create: false)` is the same path with no folder made, for a read, so a session that saved nothing leaves none (a `File.read` of what isn't there raises `Errno::ENOENT`); needs chi newer than 0.143.0. chi removes it when the session is deleted, discarded or pruned, so don't build the path yourself. A `sessions/<id>.json` an older version of your bundle kept moves in as `state.json` (chi still removes one left there). Needs chi newer than 0.142.0 |
 | `ctx.log` | `ctx.log.info(:event, key: value)`: debug-log records tagged `plugins`, with `bundle=<bundle>` |
-| `ctx.messages` | the conversation, as a frozen copy, without the system prompt. While a turn runs, a session worker's (attached, web) adds that turn so far: its prompt, the model's text and the lines merged into it (no tool calls or thinking); the REPL's is the conversation before that turn. An entry may carry `at`, when it happened (docs/sessions.md, Message times) |
-| `ctx.messages_partial?` | whether `ctx.messages` leaves out a running turn (the REPL mid-turn), so a plugin can say what its answer is about |
+| `ctx.messages` | the conversation, as a frozen copy, without the system prompt. While a turn runs, a session worker's (attached, web) adds that turn so far: its prompt, the model's text and the lines merged into it (no tool calls or thinking); a `--non-interactive` one-shot's is the conversation before that turn. An entry may carry `at`, when it happened (docs/sessions.md, Message times) |
+| `ctx.last_answer` | the newest answer's text as the user saw it: the newest answer bubble of `ctx.messages`, its thoughts (one cut off before it closed too) and tool-call markup taken out, the rule chi's continue note uses. nil when there is none or it was a thought alone; mid-turn, a worker's can be the running turn's interim text. Needs chi newer than 0.153.0 |
+| `ctx.messages_partial?` | whether `ctx.messages` leaves out a running turn (a `--non-interactive` one-shot mid-turn), so a plugin can say what its answer is about |
 | `ctx.prompt_files` | the files whose text is in the session's system prompt now: the AGENTS.md chain (the work tree top down to the cwd) and the appended files (`append_system_prompt:`, `--append-system-prompt`); absolute paths, in prompt order, `[]` before the first build |
 | `ctx.objectives` | the session's [objectives](internals/objectives.md), read now, as a frozen value: `empty?`, `items` (each `id`, `text`, `status` `"active"`, `"done"` or `"dropped"`, `done_when`), `find(id)`, `text` (the lines the model is shown) and `moves` (the latest move per id; mid-turn, a worker's leaves the running turn's out). An edit not yet absorbed counts. Empty when the session has none. Use its methods, not its class. Needs chi newer than 0.148.0 |
 | `ctx.notify(text, level: :info, fallback_for: nil)` | one line to the user, labelled by the bundle (`my-bundle> …`). Every UI shows it, during a turn (a tool, a hook) or between turns (a command). `fallback_for: :display` marks a line that repeats the answer's display (`event[:present]`), which a UI that renders the display leaves out (`fallback_for: :editor`: a file the viewer could open from a ref in its editor): see [Hooks](hooks.md#what-a-hook-can-do-the-runtime). The keyword needs chi 0.35.0 (it raises on an older chi) |
@@ -865,9 +874,9 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `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 |
+| `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. Your bundle's own `chi.tool` tools are in it only on a kit that declares them (`full`, an `add:`); elsewhere they are reachable, not declared (the testing kit answers every tool, as on full, unless `bundle.set(declared_tools: […])`) |
 | `ctx.use_toolkit(name)` | put the session on toolkit `name` (yours from `chi.toolkit`, or chi's): saved, applied at the next turn's start and announced (`toolkit> toolkit: NAME from the next turn's start`, the web's tools chip follows). Only before the session's first model reply and outside a turn (the declared tools start every request, and a plugin doesn't ask first); otherwise it returns false and changes nothing: tell the user to run `/toolkit NAME`. An unknown name raises ArgumentError. Needs chi 0.66.0 |
-| `ctx.load_tools(names)` | load tools the session reaches but doesn't declare, so the model calls them by name: built-ins (`"delegate"`, `"chi/delegate"`), MCP tools (`"mcp_fs_read"`, `"fs/read"`). Returns the names it staged (the wire names); a declared tool, one loaded before, a removed or unknown one is skipped (an unknown one logged), so calling it every turn is fine. From a `before_turn` hook it loads for that turn; anywhere else (mid-turn too) from the next turn's start. Call it from a hook: before the session's first turn its toolkit isn't applied yet and nothing resolves. **A hint, not access**: the tools keep their guardrails and approvals, and only a host that takes tool changes (`api: anthropic`, not Fireworks) gets one, as a system message after the user's (`[tools loaded: delegate (your-bundle)]` in the session, a notice line live); elsewhere nothing is sent or saved, and the tools stay reachable with `call_tool`. A hook may switch the model after you call it, so the return value can't promise delivery. Raises ArgumentError for anything but an Array. Needs chi 0.99.0 |
+| `ctx.load_tools(names)` | load tools the session reaches but doesn't declare, so the model calls them by name: built-ins and plugin tools (`"delegate"`, `"chi/delegate"`, `"chi/web_search"`), MCP tools (`"mcp_fs_read"`, `"fs/read"`). Returns the names it staged (the wire names); a declared tool, one loaded before, a removed or unknown one is skipped (an unknown one logged), so calling it every turn is fine. From a `before_turn` hook it loads for that turn; anywhere else (mid-turn too) from the next turn's start. Call it from a hook: before the session's first turn its toolkit isn't applied yet and nothing resolves. **A hint, not access**: the tools keep their guardrails and approvals, and only a host that takes tool changes (`api: anthropic`, not Fireworks) gets one, as a system message after the user's (`[tools loaded: delegate (your-bundle)]` in the session, a notice line live); elsewhere nothing is sent or saved, and the tools stay reachable with `call_tool`. A hook may switch the model after you call it, so the return value can't promise delivery. Raises ArgumentError for anything but an Array. Needs chi 0.99.0 |
 | `ctx.context` | attach outside text to this session and list it: see [Attached context](#attached-context-ctxcontext) |
 | `ctx.cache_confirm(line, changed:)` | inside a command: nil to apply a prompt-cache-restarting change now, or a confirm to return as `[text, confirm]`: see [Commands that ask](#commands-that-ask-ctxcache_confirm). Needs chi 0.132.0 |
 
@@ -895,7 +904,7 @@ keeps JSON numbers and booleans. A name that is a core session setting is always
 ## Cards
 
 A card is a small framed message with buttons: a title, a body and
-actions. Core draws it in all three UIs; a plugin has no JS or CSS of its
+actions. Core draws it in both UIs (the attached TUI and the web); a plugin has no JS or CSS of its
 own.
 
 ```ruby
@@ -933,7 +942,6 @@ Where it shows:
 
 | | during a turn (a tool, a hook) | between turns (a command) |
 |---|---|---|
-| REPL | where it happens, above the live region | at the prompt, after the command's output |
 | attached TUI | where it happens | as it arrives |
 | web | a row of the running step | between the turns |
 
@@ -1218,7 +1226,7 @@ ctx.sessions.review(subjects: ["docs/plan.md"], seed: handoff)  # => a review se
   prefix); it runs as a turn, and a stopped session is woken. It waits up to
   5 s for the session's worker, so call it from an anytime command or a
   thread of your own, never from a tool or hook of a running turn. A
-  session open in a chi REPL can't take it.
+  session a `--non-interactive` one-shot has can't take it.
   - A running turn takes it at its next step. `delivery: :queue` runs it as
     a turn of its own after that turn instead (as `/queue TEXT` does; to an
     idle session it simply runs). A plugin never cuts the running turn's
@@ -1497,6 +1505,7 @@ bundle.judgments.runs("progress").last["asked"]          # the runs as chi saves
 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.set(declared_tools: %w[read])                     # ctx.declared_tools (default: every tool, as on full)
 bundle.set(cost: 2.5)                                    # ctx.cost: reported USD, or { reported:, estimated:, side:, known: }
 bundle.set(usage: { tool_calls: 40, active_ms: 600_000 }) # ctx.usage: { turns:, tool_calls:, tool_calls_by_tool:, steps:, active_ms:, tool_ms_by_tool: }
 bundle.set(turn_author: "p:p_0123abcd")                  # a participant's turn: ctx.turn_author, and author: on every event
@@ -1581,8 +1590,8 @@ docs/testing.md). **Minitest:** `require "samagotchi/testing/minitest"` and subc
 
 ## Shutdown
 
-When the REPL exits, or a session's worker exits (an idle exit, `/exit`, a
-crash, TERM), chi shuts the session's Engine down:
+When a session's worker exits (an idle exit, `/exit`, a crash, TERM), or a
+`--non-interactive` one-shot ends, chi shuts the session's Engine down:
 
 1. The idle jobs (reminders, the recap) stop.
 2. The plugins' init tasks are cancelled (`ctx.cancelled?` turns true).
@@ -1593,8 +1602,8 @@ crash, TERM), chi shuts the session's Engine down:
 
 ## Loading, and when it fails
 
-Plugins load when a session starts (`Engine.new`, in the REPL or a
-worker), after the bundle hooks. The steps are:
+Plugins load when a session starts (`Engine.new`, in a worker or a
+`--non-interactive` one-shot), after the bundle hooks. The steps are:
 
 1. The file must match the sha256 recorded at install (not checked for a bundle installed with `--dev`).
 2. chi must meet `requires_chi`. A bundle whose `requires_chi` this chi doesn't

data/docs/releasing.md

@@ -13,7 +13,7 @@ can run the whole release; the user approves the notes before the tag and the
   and `rake release:check` enforce it). The system bundle upgrades itself when
   chi starts.
 - **Every other shipped bundle** (btw, check-in, guardrails, known-names,
-  loop-guard, mcp, skills, slow-commands, agents-md, cost-cap, work-cap, source-links, github-pr, coordinator, claude-peer, codex-peer, ruby, model-notes, decision-card, and the profiles core and dev) has its own semver in its
+  loop-guard, mcp, skills, slow-commands, agents-md, cost-cap, work-cap, source-links, github-pr, coordinator, claude-peer, codex-peer, ruby, model-notes, decision-card, web-search, and the profiles core and dev) has its own semver in its
   `manifest.yml` and, when it needs a newer chi, a `requires_chi:` line. They never upgrade by themselves: users run
   `chi update` (all of them, with the gem) or `chi bundle upgrade NAME`. So:
   - a change to a bundle's files bumps that bundle's `version:`