samagotchi 0.88.0 → 0.90.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f395ab65a9e00861ae1dda52090efbbe363946df8098702f14c41cdc665f7bb3
-  data.tar.gz: 9f22902c72237fd51481b78f1cc91197fdc474e7f5b816e0a4429d354eb5c0aa
+  metadata.gz: 06240ded5e15bc55c7c3467bc7d5c0e79daecd5822291feebf72bbab6e6e6cb7
+  data.tar.gz: 52adfdbb519ba9bed3575d55abe737dbca654d81c3c213706a556b56742628af
 SHA512:
-  metadata.gz: 2db614ca70a821eb84905eef2d8a8fead4ac4c95b9521cb32417e034fd9f6c923dd97974f25aa2a401d3131fa479ac1911bc8e8f41aa1f383b4e34f925c51078
-  data.tar.gz: 0a2625e7ce2e7022628f5a1e14c6277eeab21caf21ae4968e908cfe68735be5c39dea2f638137f96b63a0d0ed0796f60bc7c1d3a4e71db87dc453716012957cc
+  metadata.gz: 33fdd1b34ce5e0840330451bb90675fe6fb9de6903d3569f3d8e6559e09cad004bcd40bfeec0e0468943d0b2d2abfce8a21d097152c86a53bd2cd332e0386437
+  data.tar.gz: 5b19168272d7de67413c480c59bbee363b14a0ba106cdc146632cfb03be45cc646367454758fcbe95aba7562926ab700620e839b2526e818875312f5453d413d

data/CHANGELOG.md

@@ -8,6 +8,40 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.90.0] - 2026-10-19
+
+### Changed
+
+- SSE `tool_call_started` carries no `call`, `turn_completed` no `result`; read `tool`/`params`/`view` and
+  `turn_summary.output`. `?raw=1` on the worker's stream shows them.
+- docs/bundle-authoring.md (the guide chi reads to write a bundle) makes edit → `check --fix` → `test` → `try` the
+  loop, with `install --dev .` while iterating and `try` as the live check; its test example runs as written.
+
+### Fixed
+
+- `chi -p` followed by one of chi's own flags (`chi -p --non-interactive "text"`, `-p -v`) now exits 2 with a usage
+  error instead of taking the flag as the prompt.
+
+Update with `chi update` (the system bundle 0.90.0), then restart `chi web`.
+
+## [0.89.0] - 2026-10-19
+
+### Added
+
+- `chi bundle try PATH -p TEXT` runs one real model turn in an isolated sandbox with the bundle and shipped
+  `guardrails` installed and a $1 cost cap; `--json` exposes an experimental machine-readable trace.
+- `chi bundle install --dev PATH` installs a bundle you are writing as a link to its folder: edits to its plugin,
+  hooks, rules and scripts apply at the next session with no re-install, and their sha256 isn't checked (that
+  bundle only). Memories are copied; re-install with `--force` to pick up memory edits. A re-install from the same
+  PATH prunes dropped hooks. It refuses chi-shipped bundles and profiles and warns when a linked script needs
+  `chmod +x`. `upgrade` refuses it; `uninstall` never touches PATH. `chi bundle status` shows `dev → PATH (missing)`
+  if the source is gone.
+
+### Changed
+
+- minitest is now a dependency of the gem, so `chi bundle test` runs a bundle's Minitest tests (and the one
+  `chi bundle new` writes) on a slim or vendored install without `gem install minitest`.
+
 ## [0.88.0] - 2026-10-19
 
 ### Added
@@ -3495,7 +3529,9 @@ 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.88.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.90.0...HEAD
+[0.90.0]: https://github.com/dm1try/samagotchi/compare/v0.89.0...v0.90.0
+[0.89.0]: https://github.com/dm1try/samagotchi/compare/v0.88.0...v0.89.0
 [0.88.0]: https://github.com/dm1try/samagotchi/compare/v0.87.0...v0.88.0
 [0.87.0]: https://github.com/dm1try/samagotchi/compare/v0.86.0...v0.87.0
 [0.86.0]: https://github.com/dm1try/samagotchi/compare/v0.85.0...v0.86.0

data/bin/chi

@@ -74,6 +74,7 @@ options = { verbose: false, no_interrupt: Samagotchi::Config.get("no_interrupt")
 cli_overrides = {}
 
 # Strict kebab enforcement: --recap_base_url is unknown (OptionParser would otherwise accept _ as -)
+known = %w[--prompt --resume --attach --shared --no-shared --model --thinking --toolkit --tool --no-tool --set --parent-answers --memory --mute --append-system-prompt --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token] + Samagotchi::Config.cli_entries.map(&:cli_flag)
 ARGV.each do |arg|
   next unless arg.start_with?("--") && arg.include?("_")
 
@@ -82,7 +83,6 @@ ARGV.each do |arg|
   base = arg.split("=", 2).first
   # If dashed version is a known flag (registry or hardcoded), reject underscore variant
   dashed = base.tr("_", "-")
-  known = %w[--prompt --resume --attach --shared --no-shared --model --thinking --toolkit --tool --no-tool --set --parent-answers --memory --mute --append-system-prompt --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token] + Samagotchi::Config.cli_entries.map(&:cli_flag)
   if known.include?(dashed) || known.include?(base)
     warn "Unknown option: #{arg} (did you mean #{dashed}?)"
     exit 1
@@ -191,8 +191,33 @@ end
 # value (-p, --model …: the parser's own list) keeps its next word, so
 # `chi -p "--no-tool=x is broken"` is a prompt. A tool name never starts
 # with "-": `--no-tool --` or `--no-tool --model` is a missing argument.
-takes_value = parser.instance_variable_get(:@stack).flat_map do |list|
-  list.list.select { |switch| switch.is_a?(OptionParser::Switch::RequiredArgument) }.flat_map { |switch| switch.long + switch.short }
+switches = parser.instance_variable_get(:@stack).flat_map { |list| list.list }
+                                          .select { |switch| switch.is_a?(OptionParser::Switch) }
+switch_flags = switches.flat_map { |switch| switch.long + switch.short }
+known_flags = (known + switch_flags).uniq
+takes_value = switches.select { |switch| switch.is_a?(OptionParser::Switch::RequiredArgument) }
+                      .flat_map { |switch| switch.long + switch.short }
+reject_prompt_flag = lambda do |flag, value|
+  if known_flags.include?(value)
+    warn "Error: #{flag} needs the prompt text right after it (got the flag #{value}) (see chi --help)"
+    exit 2
+  end
+end
+index = 0
+while index < ARGV.size && ARGV[index] != "--"
+  arg = ARGV[index]
+  if %w[-p --prompt].include?(arg)
+    reject_prompt_flag.call(arg, ARGV[index + 1])
+    index += 2
+  elsif arg.start_with?("--prompt=")
+    reject_prompt_flag.call("--prompt", arg.delete_prefix("--prompt="))
+    index += 1
+  elsif arg.start_with?("-p") && arg != "-p"
+    reject_prompt_flag.call("-p", arg.delete_prefix("-p").delete_prefix("="))
+    index += 1
+  else
+    index += takes_value.include?(arg) ? 2 : 1
+  end
 end
 missing_no_tool = lambda do
   warn "Error: missing argument: --no-tool (see chi --help)"

data/docs/architecture.md

@@ -187,10 +187,15 @@ higher-level events so UIs get clean turn boundaries without inferring them:
   model's thinking, `0` = never; plus `continue: true` for a continue turn, `resumed: true` for a step-limit Continue,
   `images:` with the prompt's image refs)
 - `:turn_completed` — `{ result:, turn_summary:, display_pending: }` (`result`: the final
-  `LLM::ModelResult`; `display_pending`: `after_turn` hooks may still present the answer)
+  `LLM::ModelResult`; Engine event (clients get it without `result`); `display_pending`: `after_turn` hooks may still
+  present the answer)
 - `:turn_canceled` — `{ cancellation_reason:, cancelled_by:, duration_ms: }` (`cancelled_by`: the bundle or hook label that
   stopped it, for `cancellation_reason: :hook`; else nil)
 
+These are the Engine's raw events. The worker's SSE projection omits `call` from
+`:tool_call_started` and `result` from `:turn_completed`; the answer remains in
+`turn_summary.output`.
+
 A turn started with `origin:` carries it on each of these (and `:turn_failed`).
 
 Every event is a `Hash` with a `:type` symbol key; the sink must not raise (the Engine
@@ -246,7 +251,8 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   `session_state_snapshot`. `?snapshot=1` joins with a snapshot frame instead of a replay;
   `?client_id=` names whose stream it is (`Bridge#open_streams_except`, used by `POST /exit`).
   Each event goes out as clients get it (`Bridge::ClientEvent.project`, in `SSEWriter#write_event`, live
-  and replayed alike); only a `generation_chunk` changes, to chi's own format (the chunk contract below).
+  and replayed alike); `generation_chunk`, `tool_call_started` and `turn_completed` are projected to the
+  contracts below. The ring retains raw events for replay and `?raw=1`.
   `?raw=1` writes events as the engine emitted them, for debugging on the worker's port: `chi web`'s
   `/api/sessions/:id/stream` never passes it on (`Web::App#stream_query`).
   An attached terminal's stream (`EventStream` with `rediscover:`) looks for the session's live
@@ -265,6 +271,22 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
          "event_seq":812}
   ```
 
+  A `tool_call_started` frame keeps its row fields but omits the model's `call`:
+
+  ```
+  event: tool_call_started
+  data: {"type":"tool_call_started","iteration":2,"call_index":1,"tool":"write",
+         "params":"path=notes.txt","event_seq":812}
+  ```
+
+  A `turn_completed` frame omits `result`; `turn_summary.output` carries the answer:
+
+  ```
+  event: turn_completed
+  data: {"type":"turn_completed","turn_summary":{"output":"Done."},
+         "display_pending":false,"event_seq":813}
+  ```
+
   `counts` is `ContextUsage.normalize` of the provider's payload without `ctx_pct` (normalize computes it
   without the session's LLM context budget; a client counts `total_tokens` against the window or budget, as
   `ContextStatus#generation_done` does for the TUI) and with its nil keys left out: cumulative for the

data/docs/bundle-authoring.md

@@ -9,15 +9,33 @@ files, what a hook sees, how to test, and what goes wrong. The full references a
 ```
 chi bundle new my-bundle     # ./my-bundle: manifest.yml, plugin.rb, test/my_bundle_test.rb, README.md
 cd my-bundle                 # edit plugin.rb and the test
-chi bundle test              # the tests, on chi's own Ruby and lib (exit status: the tests')
+chi bundle install --dev .   # once while iterating: link this folder; edits load in the next session
 chi bundle check --fix       # manifest, files, shas (--fix rewrites them), requires_chi, install + load in a sandbox
-chi bundle install .         # into the user's chi; a NEW session loads it (a running one doesn't)
+chi bundle test              # tests on chi's own Ruby and lib (exit status: the tests')
+chi bundle try . -p "Say hello"  # one real model turn; trace the bundle in an isolated install sandbox
+chi bundle uninstall my-bundle && chi bundle install .  # at the end: leave dev mode, copy it in
 ```
 
-`check` prints one finding per line, `error|warn|info CODE file[:line]: message (fix: hint)`, and exits 1 on any
-error. Run it after every edit: an install takes exactly what it checks. It installs into a temp sandbox, not
-the user's config or state, but `check` and `test` run the bundle's plugin and hooks in their own process, as
-written: run them on code you'd install.
+The loop is **edit → `check --fix` → `test` → `try`**. `install --dev .` links the folder once, so a new session
+loads your edits with no reinstall (a running one doesn't; `try` doesn't need the link: it installs into its own
+sandbox). Memories are copied: re-install with `--force` from the same PATH to pick up memory edits. At the end,
+`uninstall NAME` leaves dev mode and a plain `install .` copies the bundle in (chi refuses it over a dev link).
+Dev-linked scripts aren't chmodded: chi warns with a `chmod +x PATH/scripts/x` hint; set the bit on the source.
+
+`check` prints one finding per line (`error|warn|info CODE file[:line]: message (fix: hint)`), exits 1 on any error
+and installs into a temp sandbox, not the user's config or state; run it after every edit. `check` and `test` run
+the bundle's plugin and hooks in their own process, as written: run them on code you'd install.
+
+## Trying a bundle
+
+After `chi bundle check --fix`, run `chi bundle try . -p "Say hello"` for one real model call using the user's
+configured hosts and keys. It installs the bundle plus chi's shipped guardrails and a default $1 cost cap, then
+prints tool calls, hook notices, cards, questions, the answer, token totals and cost.
+
+The child uses a temporary config, state and working directory; the user's other bundles and memories aren't loaded,
+nor are the current project's `AGENTS.md` / `CLAUDE.md` files. This is not a security sandbox: the bundle and tools
+run with the user's real HOME and account, and can access files and services available there. Use `try` only with
+code you trust. See [CLI: Trying a bundle](cli.md#trying-a-bundle) for flags, `--json`, `--keep` and exit statuses.
 
 ## The files
 
@@ -68,29 +86,36 @@ that list is never fired (`check` warns). The two a bundle wants most, for an `e
 Match on `result:`, not `output:`. An execute's result is its `stdout:` and `stderr:` blocks (each left out when
 empty), then `exit: N` (`exit: 0 (no output)` when both were empty); a non-zero exit makes `status:` `"error"`.
 Act through `ctx`: `ctx.notify(text, level: :warn)`, `ctx.steer(text)` (a line the model reads before its next
-step), `ctx.card(…)`, `ctx.stop_turn(reason)`, `ctx.ask_user(…)`, `ctx.data_dir` (the bundle's own folder),
+step), `ctx.card(…)`, `ctx.stop_turn(reason)`, `ctx.ask_user(…)`, `ctx.data_dir` (the bundle's state folder),
 `ctx.cwd`, `ctx.log`. In a test, each recorded notice, steer or stop names its hook as `"plugin.rb (bundle
 my-bundle)"`, the plugin's label (a `hooks/x.rb` file's is `"x.rb (bundle my-bundle)"`).
 
 ## Testing it
 
-`chi bundle new` writes a Minitest test that passes as written: copy its shape. The kit (`samagotchi/testing`)
-loads the bundle's source through chi's own loaders, in a sandbox (temp HOME, config and state), and records what
-it did at chi's edges:
+`chi bundle new` writes a Minitest test that passes as written: copy its shape. The kit (`samagotchi/testing`) loads
+the bundle's source through chi's own loaders in a sandbox (temp HOME, config and state) and records what it did:
+`load_bundle`, then `bundle.command` / `bundle.fire`, and the effects in `bundle.notices`. `bundle.ctx.data_dir` and
+`sandbox.state_dir` are that test's temporary state, never the user's (the scaffold's plugin, tested):
 
 ```ruby
-bundle = load_bundle(BUNDLE, settings: { "greeting" => "hi" })   # in a Samagotchi::Testing::Case test
-bundle.command("/my-bundle chi")                     # → what the command returned
-bundle.fire(:after_tool_call, tool: "execute", status: "error", result: "exit: 1 (no output)", call: { … })
-bundle.tool_call({ name: "execute", content: "rm -rf /" }).deny?   # before_tool_call hooks, through the real gate
-bundle.tool("my_tool", path: "a.txt")                # a chi.tool, as the model calls it
-bundle.notices, bundle.steers, bundle.cards, bundle.stops, bundle.questions   # what it did
-bundle.answer({ selected: "yes" }); bundle.model_answers << "text"           # ask_user / ask_model answers
-bundle.http.stub(:get, "https://api.example/x", json: { ok: true })          # ctx.http, never the network
-bundle.set(cwd: dir, running: false); sandbox.config(hash); sandbox.fake_executable("gh", "echo '{}'")
-bundle.install                                        # installed as chi installs it: warnings, load failures
+require "minitest/autorun"
+require "samagotchi/testing/minitest"
+
+class MyBundleTest < Samagotchi::Testing::Case
+  def test_command_and_failed_execute_notice
+    bundle = load_bundle(File.expand_path("..", __dir__), settings: { "greeting" => "hi" })
+    assert_equal "hi, there", bundle.command("/my-bundle")
+    bundle.fire(:after_tool_call, tool: "execute", status: "error", call: { name: "execute", content: "false" },
+                                  result: "exit: 1 (no output)", output: "[execute]\nexit: 1 (no output)")
+    assert_equal "the command exited 1", bundle.notices.last.text
+    assert_equal File.join(sandbox.state_dir, "plugins", bundle.name), bundle.ctx.data_dir
+  end
+end
 ```
 
+`bundle.tool_call` runs guarded hooks; `bundle.tool` calls a registered tool. `bundle.steers`, `cards`, `stops` and
+`questions` record effects; `bundle.answer` / `model_answers` provide `ask_user` / `ask_model` answers.
+`bundle.http.stub` stubs `ctx.http`; `sandbox.config`, `sandbox.fake_executable` and `bundle.install` cover setup.
 The full list is in [plugins.md, Testing a bundle](plugins.md#testing-a-bundle-experimental). The kit is
 experimental (it may change before chi 1.0). If a test needs a fake of chi's own (a stub of a `Samagotchi::`
 class, a hand-built `ctx`), that is a gap in the kit: say so to the user rather than reaching into chi.
@@ -113,7 +138,7 @@ class, a hand-built `ctx`), that is a gap in the kit: say so to the user rather
 
 ## Verifying it live
 
-After `chi bundle install .`, one real session shows it works with the user's chi:
+`chi bundle try . -p "Say hello"` is the live check (trace, plugin, notices); after the final install, check the copy:
 
 ```
 chi send --new --wait --format json --dir /tmp/try -m "/my-bundle chi"   # the JSON names the session id

data/docs/cli.md

@@ -26,6 +26,9 @@
 - `chi update [--dry-run] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
 - `chi bundle install|upgrade|uninstall|status|diff|list|build|trash|new|test|check` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle)). `trash` lists and empties the bundle trash (moved files from uninstalls/upgrades). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument. `new`, `test` and `check` are for writing one: see [Writing a bundle](#writing-a-bundle-new-test-check)
 
+- `chi bundle try PATH -p TEXT [options]` — install a bundle in a temporary, filtered sandbox, run one real model turn,
+  and print its trace (see [Trying a bundle](#trying-a-bundle)).
+
 ### First setup
 
 `chi bootstrap TARGET` names the model server and writes the config for it:
@@ -100,8 +103,16 @@ The loop for a bundle you're writing (the whole path: [bundle-authoring.md](bund
   Bundler env: `test/**/*_test.rb` on Minitest (`-r samagotchi/testing/minitest`), or else `spec/` on RSpec with
   the kit (`--options /dev/null -r samagotchi/testing/rspec`, as `rake bundles:specs`). `ARGS` go to the runner
   (`-- -n /name/`). Exit status: the tests'; 1 with no tests; 2 for usage, or when minitest / rspec doesn't load on
-  chi's Ruby. The tests run the bundle's code as written, with your environment (the kit sandboxes each
-  test's HOME and XDG dirs, not the process).
+  chi's Ruby (minitest is one of chi's gems; rspec is optional). The tests run the bundle's code as written, with
+  your environment (the kit sandboxes each test's HOME and XDG dirs, not the process).
+- `chi bundle install --dev PATH` installs the bundle in the local directory `PATH` (not a git URL, archive or name:
+  exit 2) as a link to it: its plugin, hooks, rules and scripts are `PATH`'s own files, so an edit applies at the
+  next worker or `chi web` restart with no re-install, and their sha256 isn't checked, for this bundle only (the
+  record says `dev`; every other bundle is checked as before). Its memories are copied at install. `chi bundle
+  status` shows `NAME vX dev → /abs/path`. `chi bundle upgrade NAME` refuses it (it follows its source already; to
+  leave dev mode: `chi bundle uninstall NAME`, then `chi bundle install` without `--dev`), as does a plain install
+  over it, and `--dev` over a normal install. `uninstall` removes the links and the record, never `PATH`'s files.
+  `check PATH` and `test PATH` are unchanged.
 - `chi bundle check [PATH] [--fix] [--set KEY=VALUE]` (PATH defaults to `.`) checks it as an install takes it, one
   finding per line, `error|warn|info CODE file[:line]: message (fix: hint)`, then `ok|failed: N errors, N
   warnings`. Exit 1 on any error, 0 otherwise, 2 for usage. It installs and loads the bundle in a temp sandbox
@@ -120,6 +131,34 @@ The loop for a bundle you're writing (the whole path: [bundle-authoring.md](bund
   exceptions aside) and `tests` (info: how to run them, or "no tests"). `--set KEY=VALUE` (repeatable, typed as
   `chi --set`) goes to `bundles: <name>:` in the sandbox's config.yml.
 
+### Trying a bundle
+
+`chi bundle try PATH -p TEXT [--model NAME] [--memory NAME] [--mute NAME] [--toolkit NAME] [--thinking LEVEL]
+[--set KEY=VALUE] [--json] [--keep] [--timeout SECONDS]` installs and runs the bundle in a temporary config, state
+and work directory, then prints a trace of tool calls, notices, questions, the answer, token totals and cost. The
+child's working directory is outside your repository, so project memories and `AGENTS.md` / `CLAUDE.md` files in
+your current directory aren't loaded. Your hosts, API-key environment variables, Keychain and other runtime
+settings are retained, but your configured bundles, hooks, guardrails, memories, appended system prompts and
+attached context sources are not copied. Chi installs its shipped `guardrails` and `cost-cap` bundles for the run;
+the default cap is $1 and `--set cost-cap.cap=N` changes it. Other `--set KEY=VALUE` entries are typed config
+values under `bundles: <tried-bundle>:`; unlike `chi --set BUNDLE.KEY=VALUE`, they are not session settings and
+aren't checked against `session_settings:`. `--memory` and `--mute` accept comma-separated names and repeat.
+`--timeout` defaults to 300 seconds. An ask that no one can answer or a guardrail denial is traced and warned
+about without changing the child's exit status; hook questions made with `ctx.ask_user` are invisible in
+non-interactive mode. `--keep` retains the temporary sandbox and prints its path and debug log. `--json` writes
+one experimental JSON object to stdout and human trace lines to stderr; its keys are `session_id`, `exit_code`,
+`answer`, `tools` (`index`, `name`, `args`, `status`, `duration_ms`), `notices`, `cards`, `questions`,
+`interactive_blocked`, `used_memories`, `tokens` (`prompt`, `completion`), `cost`, `cost_is_estimate`, `model`,
+`sandbox`, `denied` (1-based tool indexes) and `stderr_tail` (last 4,000 characters). Exit status: 2 for usage,
+1 for install/turn failure or timeout, 130 for Ctrl-C, otherwise the child's status.
+
+`try` runs the bundle's code and the model's tools with your real HOME, account and keys. Its temporary working
+directory and filtered config do not make untrusted code safe: a plugin, hook or model tool can still access files
+and services available to your account. Use it only for code you trust.
+
+Tool arguments are capped to 60 characters in the text trace and 200 in JSON; the text trace shows at most 10 answer
+lines, while JSON includes the full answer. Either may contain secrets.
+
 ### Listing the models
 
 `chi models` asks every host in `hosts:` for its models, in parallel, and prints the names `--model` (and

data/docs/internals/bundles.md

@@ -24,6 +24,7 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 |---|---|
 | `BundleCommand` (`lib/samagotchi/bundle_command.rb`) | `chi bundle install/upgrade/uninstall/status/diff/list/build/trash/new/test/check`; runs the Installer, prints its summary, runs the conflict agent step; refuses a source already installed under another name (`installed_under_another_name?`: a git URL bundle recorded under its repo's name before the manifest named it) |
 | `BundleCommand::Check` (bundle_command/check.rb) | `chi bundle check [PATH] [--fix] [--set K=V]`: a bundle being written, checked as an install takes it (docs/cli.md lists the codes); parses the manifest from `Shas.parseable` (a placeholder sha is a `sha` finding, not a YAML error), reads the user's installed bundles only for `clash`, and installs and loads through `Testing::Install` in a `Testing::Sandbox` with `force: true`, the log's echoes swallowed |
+| `BundleCommand::Try` (`bundle_command/try/`) | `chi bundle try PATH -p TEXT`: filtered-config `Sandbox` installs the tried bundle and shipped `guardrails` / `cost-cap` in a separate child, then `Run` starts one non-interactive chi process from its realpath work dir; `TraceReader` reads that session's analytics, cards and session JSON by id (never `Session.list`), joining timing and tool args for text or experimental JSON output. `Sandbox#child_env` is a Hash, never an ENV mutation; it keeps ordinary user model settings and Keychain access while dropping the spawner's session/guardrail/worker markers. |
 | `BundleCommand::Scaffold` (bundle_command/scaffold.rb) | `chi bundle new NAME`: the starting files (block-form `plugin:` entry, `requires_chi` at this chi, a kit test that passes as written); the manifest's shas are filled through `Shas.refresh` |
 | `BundleCommand::TestRun` (bundle_command/test_run.rb) | `chi bundle test`: `RbConfig.ruby -I <chi's lib>` on `test/**/*_test.rb` (Minitest) or `spec/` (RSpec, as `rake bundles:specs`), under `Bundler.with_unbundled_env` when Bundler's runtime is loaded |
 | `Shas` (shas.rb) | a manifest's `sha256:` lines: `.refresh(dir[, text])` rewrites them line by line (the layout kept; a `files:` entry it can't place raises `Shas::Error`), `.stale` → `[Stale(file, old, new)]` (`old` `""` for a placeholder, nil for a plugin / hook / script entry with no sha line), `.parseable` (a placeholder `sha256: sha256:` isn't YAML). Plain Ruby: `rake bundles:sha` / `bundles:check` (`script/release/release_tools.rb`) and `chi bundle check --fix` share it |
@@ -45,6 +46,15 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 | `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 |
 
+A dev install (`chi bundle install --dev PATH`, `Installer#initialize(dev: true)`) links instead of copying:
+`AssetInstaller#place` symlinks each hook, rule file, plugin and script into `.bundles/<name>/` to its realpath in
+the source (memories are still copied: their bases and the index are the install's), and the record gets `"dev": true`
+(`InstalledBundle#dev`, `source` the realpath) with `Provenance::DEV_SHA` (`sha256:dev`, never a hex digest) in
+place of every hook, rule, plugin and script sha256. `Provenance.sha_matches?` / `.unchecked?` read it as "not
+checked", which is how the readers below skip it for that bundle only. `Installer#refuse_dev_mismatch` keeps a dev
+and a normal install from replacing each other (this is also why `chi bundle upgrade` refuses a dev bundle);
+`Uninstaller` removes links with `rm_rf`/`rm_f`, which never follow them into the source.
+
 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.

data/docs/internals/engine.md

@@ -489,12 +489,12 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 | `:thinking_refused` / `:reasoning_history_refused` | the chat loop asked a step again without the thinking fields / the reasoning sent back; the Engine logs it and makes a once-per-session-and-host `:hook_notice` of it, the event itself never reaches the sink | `{iteration, model, level, detail}` |
 | `:pending_input_merged` | queued input joined the conversation | `{iteration, count, content, steers?, answer}` |
 | `:tool_dispatch_started` / `:tool_dispatch_completed` | around a batch | `{iteration, call_count}` |
-| `:tool_call_started` | before a call runs | see ToolRunner |
+| `:tool_call_started` | before a call runs | Engine event includes `call` (see ToolRunner); the Bridge's SSE frame omits it |
 | `:tool_call_completed` | after a call ran | see ToolRunner |
 | `:used_memories_updated` | a memory was read, and after the loop | `{used_memory_names, read_names?}` |
 | `:hook_notice` | a hook's or plugin's notify during a turn | `{hook, text, level}` (announced with `between_turns: true` outside a turn) |
 | `:guardrail_warning` | a guardrails line during a turn | `{message}` |
-| `:turn_completed` | normal end | `{result, turn_summary, display_pending}` |
+| `:turn_completed` | normal end | Engine event `{result, turn_summary, display_pending}`; the Bridge's SSE frame omits `result` (answer remains in `turn_summary.output`) |
 | `:turn_canceled` | Stop, hook stop, Ctrl-C | `{cancellation_reason, cancelled_by?, duration_ms}` |
 | `:turn_failed` | an error | `{error_class, message, duration_ms, error_kind?, retryable?, host?, summary?}` |
 | `:answer_display` | after the after_turn hooks (observers only, not the sink) | `{display, refs?}` (display a string, or nil; refs the count of the answer's refs, only when a hook attached some) |

data/lib/samagotchi/bridge/client_event.rb

@@ -10,8 +10,10 @@ module Samagotchi
     # the provider's raw `payload`, and no raw `content` (the chat loop's is
     # reasoning + content again, the native loop's the raw stream with its
     # tool-call bytes and thought tags): clients read `text`, `thinking`,
-    # `tool_call` and `counts`, never a provider's payload shape. `?raw=1` on
-    # the worker's stream skips this (debugging).
+    # `tool_call` and `counts`, never a provider's payload shape.
+    # :tool_call_started omits the model's `call`; clients render its row from
+    # the other fields. :turn_completed omits `result`; `turn_summary.output`
+    # carries the answer. `?raw=1` on the worker's stream skips this (debugging).
     #
     # Pure: the event is the one hash SessionObserver hands every observer
     # (the ring, TurnAccumulator, the other writers, SessionMetrics, hooks),
@@ -28,13 +30,19 @@ module Samagotchi
       # @param event [Hash] the engine's event (symbol keys; its payload has
       #   string keys)
       # @return [Hash] the event as clients get it: a copy for a
-      #   :generation_chunk, the same object for every other event
+      #   projected event, the same object for every other event
       def project(event)
-        return event unless event.is_a?(Hash) && event[:type].to_s == "generation_chunk"
+        return event unless event.is_a?(Hash)
 
-        projected = event.except(:payload, :content)
-        found = counts(event[:payload])
-        found ? projected.merge(counts: found) : projected
+        case event[:type].to_s
+        when "generation_chunk"
+          projected = event.except(:payload, :content)
+          found = counts(event[:payload])
+          found ? projected.merge(counts: found) : projected
+        when "tool_call_started" then event.except(:call)
+        when "turn_completed" then event.except(:result)
+        else event
+        end
       end
 
       # The payload's normalized counts, nil keys left out; nil when the

data/lib/samagotchi/bundle_command/test_run.rb

@@ -10,7 +10,7 @@ module Samagotchi
     # *_test.rb runs on Minitest with the kit's Case; a spec/ with no test/
     # on RSpec with the kit's helpers, as `rake bundles:specs` runs the
     # shipped ones. Outside any Bundler env (Bundler.with_unbundled_env, as
-    # SessionManager's unbundled_env_changes): chi's gems don't include minitest.
+    # InstalledGem.unbundled_env_changes), where chi's own gem dependency minitest loads.
     # When the framework loads only inside the Bundler env chi itself runs in
     # (a checkout or a vendored install: its gems in vendor/bundle), there.
     # The tests' exit status is #run's.
@@ -37,7 +37,7 @@ module Samagotchi
       private
 
       def minitest(tests)
-        return missing("minitest", "gem install minitest") unless loads?("minitest")
+        return missing("minitest", "it ships with chi: reinstall chi (gem install samagotchi)") unless loads?("minitest")
 
         requires = tests.map { |file| "require #{file.inspect}" }.join("; ")
         say("#{tests.size} test file#{"s" unless tests.size == 1}")

data/lib/samagotchi/bundle_command/try/run.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "open3"
+require "rbconfig"
+
+module Samagotchi
+  class BundleCommand
+    module Try
+      class Run
+        Result = Data.define(:exit_status, :stdout, :stderr, :session_id, :timed_out)
+        INTERRUPT_GRACE = 5
+        READER_GRACE = 2
+        GROUP_TERM_GRACE = 0.1
+        POLL_INTERVAL = 0.05
+
+        def initialize(sandbox)
+          @sandbox = sandbox
+        end
+
+        def run(prompt:, options:, timeout:)
+          command = [RbConfig.ruby, "-I", Sandbox::LIB_DIR, Sandbox::CHI,
+                     "--no-shared", "--non-interactive", "-p", prompt, *child_options(options)]
+          trap_state, old_traps = trap_forwarding
+          pid = nil
+          streams = []
+          readers = []
+          begin
+            Open3.popen3(@sandbox.child_env, *command, chdir: @sandbox.work_dir, pgroup: true, in: File::NULL) do |stdin, stdout, stderr, wait|
+              pid = wait.pid
+              streams = [stdout, stderr]
+              stdin.close
+              readers = streams.map { |stream| Thread.new { read_stream(stream) } }
+              attach_child(trap_state, pid)
+              timed_out = false
+              status = wait_for(wait, timeout)
+              if status == :timeout
+                timed_out = true
+                signal_group(pid, "INT")
+                status = wait_for(wait, INTERRUPT_GRACE)
+                if status == :timeout
+                  terminate_group(pid)
+                  status = wait.value
+                end
+              end
+              out, err = finish_readers(readers, streams)
+              code = timed_out ? CLI::Exit::FAILED : process_exit_status(status)
+              Result.new(exit_status: code, stdout: out, stderr: err, session_id: err[/^Session: (\S+)/, 1],
+                         timed_out: timed_out)
+            end
+          rescue SystemCallError => e
+            raise Sandbox::Error, "chi bundle try: couldn't run chi: #{e.message}"
+          ensure
+            terminate_group(pid) if pid
+            close_streams(streams)
+            stop_readers(readers)
+            restore_traps(old_traps)
+          end
+        end
+
+        private
+
+        def child_options(options)
+          args = []
+          %i[model toolkit thinking].each do |key|
+            args.concat(["--#{key}", options[key]]) if options[key]
+          end
+          %i[memory mute].each do |key|
+            Array(options[key]).each { |value| args.concat(["--#{key}", value]) }
+          end
+          args
+        end
+
+        def wait_for(wait, seconds)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+          loop do
+            return wait.value if wait.join(POLL_INTERVAL)
+            return :timeout if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          end
+        end
+
+        def trap_forwarding
+          state = { pid: nil, pending: nil }
+          old = {}
+          %w[INT TERM].each do |signal|
+            old[signal] = Signal.trap(signal) do
+              if state[:pid]
+                signal_group(state[:pid], signal)
+              else
+                state[:pending] ||= signal
+              end
+            end
+          end
+          [state, old]
+        end
+
+        def attach_child(state, pid)
+          state[:pid] = pid
+          pending = state[:pending]
+          state[:pending] = nil
+          signal_group(pid, pending) if pending
+        end
+
+        def restore_traps(old)
+          old.each { |signal, handler| Signal.trap(signal, handler) }
+        end
+
+        def signal_group(pid, signal)
+          Process.kill(signal, -pid)
+        rescue Errno::ESRCH
+          nil
+        end
+
+        def terminate_group(pid)
+          signal_group(pid, "TERM")
+          sleep(GROUP_TERM_GRACE)
+          signal_group(pid, "KILL")
+        end
+
+        def read_stream(stream)
+          output = +""
+          loop { output << stream.readpartial(16_384) }
+        rescue EOFError
+          output
+        rescue IOError
+          raise unless stream.closed?
+
+          output
+        end
+
+        def finish_readers(readers, streams)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + READER_GRACE
+          readers.each do |reader|
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            reader.join([remaining, 0].max)
+          end
+          close_streams(streams)
+          readers.each do |reader|
+            reader.join(0.1) if reader.alive?
+            reader.kill if reader.alive?
+          end
+          readers.map { |reader| reader.value.to_s }
+        end
+
+        def close_streams(streams)
+          streams.each { |stream| stream.close unless stream.closed? }
+        end
+
+        def stop_readers(readers)
+          readers.each do |reader|
+            reader.join(0.1)
+            reader.kill if reader.alive?
+          end
+          readers.each(&:join)
+        end
+
+        def process_exit_status(status)
+          status.exitstatus || (128 + status.termsig.to_i)
+        end
+      end
+    end
+  end
+end