samagotchi 0.142.0 → 0.143.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +66 -7
- data/README.md +1 -0
- data/docs/architecture.md +13 -6
- data/docs/bundle-authoring.md +6 -6
- data/docs/bundles.md +1232 -0
- data/docs/cli.md +36 -6
- data/docs/configuration.md +11 -12
- data/docs/context.md +10 -10
- data/docs/guardrails.md +7 -9
- data/docs/hooks.md +19 -2
- data/docs/internals/attached-context.md +2 -3
- data/docs/internals/bundles.md +5 -3
- data/docs/internals/engine.md +9 -3
- data/docs/internals/prompt-caching.md +12 -12
- data/docs/internals/web-push.md +1 -1
- data/docs/memory.md +2 -2
- data/docs/plugins.md +26 -1251
- data/docs/sessions.md +2 -2
- data/docs/sub-agent.md +6 -6
- data/docs/system-one.md +2 -2
- data/lib/samagotchi/bundle_command/api_calls.rb +132 -0
- data/lib/samagotchi/bundle_command/check.rb +50 -34
- data/lib/samagotchi/bundle_command/installed_check.rb +86 -0
- data/lib/samagotchi/bundle_command/scaffold.rb +1 -0
- data/lib/samagotchi/bundle_settings_check.rb +58 -0
- data/lib/samagotchi/bundles/agents-md/manifest.yml +4 -2
- data/lib/samagotchi/bundles/agents-md/plugin.rb +1 -1
- data/lib/samagotchi/bundles/btw/manifest.yml +4 -2
- data/lib/samagotchi/bundles/btw/plugin.rb +1 -1
- data/lib/samagotchi/bundles/check-in/manifest.yml +7 -6
- data/lib/samagotchi/bundles/check-in/plugin.rb +7 -14
- data/lib/samagotchi/bundles/claude-peer/manifest.yml +3 -3
- data/lib/samagotchi/bundles/claude-peer/plugin.rb +1 -1
- data/lib/samagotchi/bundles/claude-peer/scripts/pair +1 -1
- data/lib/samagotchi/bundles/codex-peer/manifest.yml +2 -2
- data/lib/samagotchi/bundles/codex-peer/plugin.rb +1 -1
- data/lib/samagotchi/bundles/coordinator/manifest.yml +2 -2
- data/lib/samagotchi/bundles/coordinator/plugin.rb +1 -1
- data/lib/samagotchi/bundles/core/manifest.yml +2 -2
- data/lib/samagotchi/bundles/cost-cap/manifest.yml +6 -3
- data/lib/samagotchi/bundles/cost-cap/plugin.rb +5 -7
- data/lib/samagotchi/bundles/github-pr/manifest.yml +3 -1
- data/lib/samagotchi/bundles/known-names/manifest.yml +3 -1
- data/lib/samagotchi/bundles/loop-guard/manifest.yml +4 -2
- data/lib/samagotchi/bundles/loop-guard/plugin.rb +1 -1
- data/lib/samagotchi/bundles/mcp/manifest.yml +4 -2
- data/lib/samagotchi/bundles/mcp/plugin.rb +2 -2
- data/lib/samagotchi/bundles/ruby/manifest.yml +2 -2
- data/lib/samagotchi/bundles/ruby/plugin.rb +1 -1
- data/lib/samagotchi/bundles/skills/manifest.yml +4 -2
- data/lib/samagotchi/bundles/skills/plugin.rb +1 -1
- data/lib/samagotchi/bundles/slow-commands/manifest.yml +4 -2
- data/lib/samagotchi/bundles/slow-commands/plugin.rb +1 -1
- data/lib/samagotchi/bundles/source-links/manifest.yml +3 -1
- data/lib/samagotchi/bundles/system/config_modification_protocol.md +1 -1
- data/lib/samagotchi/bundles/system/manifest.yml +3 -3
- data/lib/samagotchi/bundles/system/self_map.md +2 -2
- data/lib/samagotchi/bundles/work-cap/manifest.yml +6 -3
- data/lib/samagotchi/bundles/work-cap/plugin.rb +11 -13
- data/lib/samagotchi/context_candidate_choice.rb +12 -3
- data/lib/samagotchi/context_candidates.rb +4 -1
- data/lib/samagotchi/context_candidates_log.rb +11 -0
- data/lib/samagotchi/context_status.rb +1 -2
- data/lib/samagotchi/engine.rb +33 -68
- data/lib/samagotchi/extension_load.rb +8 -2
- data/lib/samagotchi/hook_routes.rb +37 -2
- data/lib/samagotchi/hooks/bundle_loader.rb +20 -4
- data/lib/samagotchi/hooks/registry.rb +23 -5
- data/lib/samagotchi/host_model.rb +3 -3
- data/lib/samagotchi/host_registry.rb +14 -7
- data/lib/samagotchi/kernel_loop.rb +7 -2
- data/lib/samagotchi/llm/chat_loop.rb +5 -0
- data/lib/samagotchi/llm/stray_tool_call.rb +23 -16
- data/lib/samagotchi/memory_bundle/builder.rb +4 -2
- data/lib/samagotchi/memory_bundle/installed_bundle.rb +9 -2
- data/lib/samagotchi/memory_bundle/installed_copy.rb +92 -0
- data/lib/samagotchi/memory_bundle/installer.rb +2 -0
- data/lib/samagotchi/memory_bundle/manifest.rb +23 -13
- data/lib/samagotchi/memory_bundle/provenance.rb +4 -1
- data/lib/samagotchi/memory_bundle/shipped_update.rb +13 -1
- data/lib/samagotchi/model_catalog.rb +3 -2
- data/lib/samagotchi/models_command.rb +1 -1
- data/lib/samagotchi/plugin/api.rb +14 -11
- data/lib/samagotchi/plugin/context.rb +10 -0
- data/lib/samagotchi/plugin/loader.rb +4 -2
- data/lib/samagotchi/plugin/peer.rb +17 -22
- data/lib/samagotchi/plugin_session_state.rb +32 -5
- data/lib/samagotchi/prompt_warmup.rb +1 -9
- data/lib/samagotchi/session_access/local.rb +1 -1
- data/lib/samagotchi/session_access/remote.rb +3 -3
- data/lib/samagotchi/session_archive_command.rb +3 -3
- data/lib/samagotchi/session_commands.rb +4 -4
- data/lib/samagotchi/session_config.rb +9 -3
- data/lib/samagotchi/session_continue.rb +1 -1
- data/lib/samagotchi/session_manager.rb +15 -6
- data/lib/samagotchi/system_one/judgments.rb +8 -25
- data/lib/samagotchi/system_one/log.rb +21 -0
- data/lib/samagotchi/system_one/recording.rb +1 -1
- data/lib/samagotchi/terminal_ui/attach_link.rb +2 -2
- data/lib/samagotchi/terminal_ui/attached_loop/exit_commands.rb +1 -1
- data/lib/samagotchi/terminal_ui/attached_loop.rb +1 -1
- data/lib/samagotchi/terminal_ui/local_link.rb +1 -1
- data/lib/samagotchi/terminal_ui/remote_link.rb +1 -2
- data/lib/samagotchi/testing/judgments.rb +0 -9
- data/lib/samagotchi/update_command.rb +49 -16
- data/lib/samagotchi/version.rb +1 -1
- data/lib/samagotchi/web/app.rb +1 -0
- data/lib/samagotchi/web/auto_update.rb +79 -49
- data/lib/samagotchi/web/auto_update_record.rb +59 -0
- data/lib/samagotchi/web/public/app.js +8 -4
- data/lib/samagotchi/web/public/hash_intent.js +24 -0
- data/lib/samagotchi/web/public/index.html +3 -1
- data/lib/samagotchi/web/public/revise_stack.js +14 -5
- data/lib/samagotchi/web/session_control.rb +3 -3
- data/lib/samagotchi/web/update_check.rb +7 -6
- data/lib/samagotchi/web/update_ops.rb +80 -25
- metadata +8 -1
data/docs/cli.md
CHANGED
|
@@ -34,9 +34,9 @@
|
|
|
34
34
|
- `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text or images to a session (live, stopped or new) as a message (⏎, a turn runs) or a context note (⌘⏎) (see [Desktop helper](desktop.md))
|
|
35
35
|
- `chi models [--format text|json] [--timeout S] [TEXT]` — list the models every configured host offers, as the names `--model` takes (see [Listing the models](#listing-the-models))
|
|
36
36
|
- `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles. Run by a session's `execute`, the `model` row (and host, loop, profile, thinking, served model) is **that session's** model, labelled `(this session <id8>; default …)`; elsewhere it is the default, `(default)`. `model key` is the memory overlay key (`<name>.<key>.md`), and `big memories` the memories over `memory.entry_warn_tokens` ([Memory](memory.md#a-memorys-size)), and `model notes` the model notes a prompt of that model loads (`model_notes_deepseek (system, 612 chars)`, `none`; inside a session its `--mute` list is left out). `chi self --model` prints only the model a new session starts on, an alias resolved to its target (the desktop helper's hint)
|
|
37
|
-
- `chi update [--dry-run] [--to VERSION] [--json] [--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))
|
|
37
|
+
- `chi update [--dry-run] [--to VERSION] [--json] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, and check the bundles from elsewhere, in one table (see [Updating](#updating))
|
|
38
38
|
- `chi home`, `chi home set [--ruby PATH]`, `chi home doctor` — the chi home: the one Ruby (and its gem path) every chi launch boots, whoever launches it. `chi home` shows it (its Ruby, the newest chi in it, gem home and path, `mise`, when and by which chi it was set, and the chi you ran when that is another one; exit 1 with the problem when it can't boot chi), `set` records this chi's Ruby and gem path (or `--ruby PATH`'s own; it must have samagotchi), `doctor` checks it and what should follow it, one row each with `ok`, `warn` or `fail` and what to run (exit 1 on a `fail`; see [Checking it](configuration.md#checking-it-chi-home-doctor)). At a terminal, a chi on another Ruby than the home's says so in one dim line a day. This machine only (see [The chi home](configuration.md#the-chi-home))
|
|
39
|
-
- `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), [
|
|
39
|
+
- `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), [Bundles](bundles.md#the-btw-bundle), [the mcp bundle](bundles.md#the-mcp-bundle) [the loop-guard bundle](bundles.md#the-loop-guard-bundle), [the check-in bundle](bundles.md#the-check-in-bundle) and [the skills bundle](bundles.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)
|
|
40
40
|
|
|
41
41
|
- `chi guardrails replay [--dry-run] [--threshold T] [--model M]` — seed System 1's record from the approvals this machine's sessions already answered: each ask is judged by the configured model and written to `guardrails/judgments.jsonl` with the answer the user gave, then a per-rule table prints (asks, allowed, denied, would-be auto-allows, false allows, asks with no judgment). A parent agent's answer is not the user's: only its deny is replayed, and only where the parent could have allowed. `--dry-run` judges without writing, `--threshold` overrides `guardrails.system_one.threshold` for the table, `--model` the configured model for this run. Exit 2 when `guardrails.system_one.mode` is off or no `host` is set; a usage error exits 2 (see [System 1](guardrails.md#system-1-experimental))
|
|
42
42
|
- `chi judgments ls` / `chi judgments report NAME [--days N]` — what [System 1's saved runs](system-one.md) hold: each judgment's digests, runs, labels, failures, models and size; one judgment's counts, p histogram and labels by value. Reads only; local only; `--days` must be a positive whole number.
|
|
@@ -153,7 +153,9 @@ The loop for a bundle you're writing (the whole path: [bundle-authoring.md](bund
|
|
|
153
153
|
then forces), `install` (each Installer warning, a `needs` one as warn, and each plugin or hook load failure at
|
|
154
154
|
the source `file:line`; skipped while a placeholder sha is unfilled), `registered` (info: each command, tool,
|
|
155
155
|
hook with its priority, init, toolkit, tool source and peer source), `hook-event` (warn: a `chi.on` event chi
|
|
156
|
-
never fires), `
|
|
156
|
+
never fires), `settings` (warn: a `--set` the manifest's `settings:` rules out, as config.yml's `bundles:` is told), `api` (warn: a `ctx.*` / `chi.*` call or a keyword this chi's API lacks, read from the source with
|
|
157
|
+
Prism against the API's own classes, on a path that never runs too; written on a local `ctx` / `chi` itself, so a
|
|
158
|
+
`s = ctx.sessions` variable isn't followed; a name the plugin guards with `respond_to?` is left), `boundary` (warn: a `Samagotchi::` name outside "Stable for bundles"; a shipped bundle's listed
|
|
157
159
|
exceptions aside) and `tests` (info: how to run them, or "no tests"). `--set KEY=VALUE` (repeatable, typed as
|
|
158
160
|
`chi --set`) goes to `bundles: <name>:` in the sandbox's config.yml.
|
|
159
161
|
|
|
@@ -229,8 +231,10 @@ btw 0.1.1 up to date
|
|
|
229
231
|
known-names 0.1.0 0.1.1 updated
|
|
230
232
|
core 0.1.0 0.2.0 updated (+ new-bundle)
|
|
231
233
|
infra_tools 1.0.0 skipped (not from chi)
|
|
234
|
+
infra_tools warn api plugin.rb:3: ctx.old_name isn't in chi 0.3.0's plugin API (fix: docs/plugins.md has the API)
|
|
232
235
|
Chi Helper 0.2.0 up to date (launch file refreshed)
|
|
233
236
|
workers 2 live on 0.2.0: they keep it until restarted (chi sessions restart 2ea8c1f0 91b0d2aa); or they idle out after 30 min with nothing attached
|
|
237
|
+
Bundles not from chi are left as they are: their author's next version, or chi bundle upgrade NAME, is what changes them
|
|
234
238
|
Also shipped, not installed: dev (mcp, skills, source-links) (chi bundle install NAME)
|
|
235
239
|
done
|
|
236
240
|
```
|
|
@@ -239,8 +243,10 @@ done
|
|
|
239
243
|
newest release. It must be newer than the running chi; an equal or older
|
|
240
244
|
version is refused.
|
|
241
245
|
- `--json` writes the component rows as one JSON array on stdout. Each row has
|
|
242
|
-
`component`, `from`, `to`, `status`, `failed` and `
|
|
243
|
-
array of edited filenames
|
|
246
|
+
`component`, `from`, `to`, `status`, `failed`, `kept` and `level` fields;
|
|
247
|
+
`kept` is an array of edited filenames, and `level` is `warn` or `error` on a
|
|
248
|
+
re-check's row (below), `null` on the others. Install progress is written to
|
|
249
|
+
stderr.
|
|
244
250
|
|
|
245
251
|
- **chi web update notices.** By default, chi web checks RubyGems about 30
|
|
246
252
|
seconds after it starts and every 24 hours after that. Once a stable release
|
|
@@ -302,6 +308,30 @@ done
|
|
|
302
308
|
A bundle of the same name from elsewhere (a zip, git) is skipped ("not from
|
|
303
309
|
chi"), a newer installed one is left, one whose new version needs a newer
|
|
304
310
|
chi is skipped, and bundles you didn't install stay uninstalled.
|
|
311
|
+
- **Bundles not from chi** are never changed, but the chi the update leaves
|
|
312
|
+
checks what is installed of them (the plugin, hooks and rules as they are,
|
|
313
|
+
not their source, which may be gone) with `chi bundle check`'s own checks,
|
|
314
|
+
and each warning or error is a row under the bundle's name: `requires_chi`
|
|
315
|
+
ruling this chi out, a plugin or hook that no longer loads, a hook on an event
|
|
316
|
+
chi no longer fires, a `ctx`/`chi` call the API lacks, a reference to chi's
|
|
317
|
+
internals, a name chi now ships, or a hook or plugin edited since it was installed (it
|
|
318
|
+
doesn't load). What only an author can act on (shas, unlisted files, tests, a
|
|
319
|
+
missing `requires_chi`, its floor, `trust_level`) is left out, and so are
|
|
320
|
+
profiles. A clean bundle gets no row beyond its `skipped (not from chi)`.
|
|
321
|
+
- **They fail nothing:** an error row too has `failed: false` and leaves the exit
|
|
322
|
+
status 0, chi web's **Update** and `update.auto` done. A warning repeats on
|
|
323
|
+
every run until the bundle changes, and a second run still says `everything is up to date`.
|
|
324
|
+
- **Each runs in a child process**, with your config.yml `bundles: <name>:`
|
|
325
|
+
settings in a sandbox: its code runs, as in any session. One that exits or
|
|
326
|
+
doesn't answer in 30 s is an `error check` row of its own; the rest go on.
|
|
327
|
+
- **Under the new chi:** the check runs in the update handed over to, so the new
|
|
328
|
+
API is what it's held against. When that hasn't happened, a row says
|
|
329
|
+
`external bundles … not checked (…)` instead of an answer about the old
|
|
330
|
+
API: `--dry-run` with a newer gem to install (without one, a dry run checks,
|
|
331
|
+
against this chi), and a gem installed with no way to hand over (run `chi
|
|
332
|
+
update` again). A failed gem install checks against this chi, since it stays.
|
|
333
|
+
- `--no-bundles` (`update.bundles: false`) leaves these out too: no check, no row
|
|
334
|
+
but `bundles skipped`.
|
|
305
335
|
- **Profiles** (`core`, `dev`): an installed one installs the bundles a new
|
|
306
336
|
chi added to it (`updated (+ name)`), even at the same version, and retries
|
|
307
337
|
one that failed before; one you uninstalled stays out. See [Bundle
|
|
@@ -1500,7 +1530,7 @@ chi --remote work sessions list
|
|
|
1500
1530
|
|
|
1501
1531
|
SSH can forward a Unix socket as well, which is how claude-peer's pairing makes
|
|
1502
1532
|
a Claude session on this laptop reachable from chi on that machine
|
|
1503
|
-
(`pair --inbox-socket <path>`): see [
|
|
1533
|
+
(`pair --inbox-socket <path>`): see [bundles.md](bundles.md#the-claude-peer-bundle), "chi on another
|
|
1504
1534
|
machine".
|
|
1505
1535
|
|
|
1506
1536
|
How it works inside (`SessionAccess`, chi web's routes, where each check runs):
|
data/docs/configuration.md
CHANGED
|
@@ -127,7 +127,7 @@ own subsystems: `hosts:` (below), `models:` (see "Prompt profile" and
|
|
|
127
127
|
`guardrails:` (see [Guardrails](guardrails.md)), `bundles:` (a bundle's
|
|
128
128
|
settings for its hooks, see [Hooks: Settings](hooks.md#settings); a session's own
|
|
129
129
|
`--set BUNDLE.KEY=VALUE`, for a key the bundle's manifest lists in `session_settings:`, lays over them, see
|
|
130
|
-
[Per-session settings](plugins.md#per-session-settings); `--set KEY=VALUE` does the same for a few core keys,
|
|
130
|
+
[Per-session settings](plugins.md#per-session-settings); a name no installed bundle has, or a key its manifest's `settings:` rules out, warns at a session's start; `--set KEY=VALUE` does the same for a few core keys,
|
|
131
131
|
see "Per-session settings" below),
|
|
132
132
|
`memories:` and `append_system_prompt:` (see "Appended prompt files"). Their entry names (host names, model ids, aliases) are yours to
|
|
133
133
|
choose. The `memories:` list is the persistent baseline for preloaded memory entries —
|
|
@@ -1452,7 +1452,7 @@ To skip loading AGENTS.md (all of the chain), set `skip_agents_md: true` at the
|
|
|
1452
1452
|
|
|
1453
1453
|
Nested `AGENTS.md` files (in directories the session doesn't run in) are
|
|
1454
1454
|
steered into the conversation on first touch by the `agents-md` bundle
|
|
1455
|
-
([The agents-md bundle](
|
|
1455
|
+
([The agents-md bundle](bundles.md#the-agents-md-bundle)); `skip_agents_md`
|
|
1456
1456
|
disables that steering too.
|
|
1457
1457
|
|
|
1458
1458
|
## Appended prompt files
|
|
@@ -1547,9 +1547,7 @@ toolkit:
|
|
|
1547
1547
|
says `from this turn`, and that request re-reads the whole prompt (system prompt, tools and conversation, which
|
|
1548
1548
|
the defer limits keep small) without `/toolkit`'s cache confirmation. `/toolkit` or `ctx.use_toolkit` marks the
|
|
1549
1549
|
toolkit chosen, and nothing is suggested after that; a `/toolkit` sent during a turn runs after it and replaces
|
|
1550
|
-
that turn's suggestion.
|
|
1551
|
-
root, as audit checks), on mode asks only on a session's first turn, never on the deferred path, and sends no
|
|
1552
|
-
warm-up (one info line). Otherwise an idle worker for an eligible session sends one warm-up ask with the real
|
|
1550
|
+
that turn's suggestion. An idle worker for an eligible session sends one warm-up ask with the real
|
|
1553
1551
|
question and a stand-in prompt so the server has its prefix cached; its answer is dropped and never logged, and
|
|
1554
1552
|
the first real ask stops a warm-up still running. Each answered ask's line in `toolkit_suggestions.jsonl` adds
|
|
1555
1553
|
`did`: `suggested`, `default`, `defer`, `chosen` (the toolkit was no longer the default), `unavailable` (the
|
|
@@ -1796,9 +1794,8 @@ context:
|
|
|
1796
1794
|
mode: audit
|
|
1797
1795
|
```
|
|
1798
1796
|
|
|
1799
|
-
|
|
1800
|
-
|
|
1801
|
-
[prompt caching](internals/prompt-caching.md)).
|
|
1797
|
+
The asks run beside the turn, on any host: they cost the session's cached prompt nothing on the model's own Splash
|
|
1798
|
+
either (see [prompt caching](internals/prompt-caching.md)).
|
|
1802
1799
|
|
|
1803
1800
|
|
|
1804
1801
|
## Bundles' judgments
|
|
@@ -2150,17 +2147,19 @@ Both are read when chi web starts (restart it to apply a change). What it does,
|
|
|
2150
2147
|
it pushes the failed row's reason and stays quiet until a newer release (or you, with the button) tries again.
|
|
2151
2148
|
3. **Restarts** (`update.restart: idle`). Stale workers first, only those whose session is idle and untouched for
|
|
2152
2149
|
10 minutes (so nobody who is about to type loses their worker), and each worker still refuses by itself when
|
|
2153
|
-
something holds it ([sessions](sessions.md))
|
|
2154
|
-
idle exit or the session's **Restart**. Then chi web itself, once no turn runs anywhere: it first runs the
|
|
2150
|
+
something holds it ([sessions](sessions.md)). Then chi web itself, once no turn runs anywhere: it first runs the
|
|
2155
2151
|
restart's own command with `--version` (20 s at most) and restarts only if the newest chi answers with the
|
|
2156
2152
|
release's version; otherwise chi web stays up and the phone hears "chi X is installed; chi web didn't restart".
|
|
2157
2153
|
The restart is the **Restart chi web** one: same port, same token, same Tailscale Serve handler, the open page's
|
|
2158
2154
|
streams reconnect in a few seconds and a Reload toast follows. It doesn't wait for a page in front: the page isn't
|
|
2159
2155
|
reloaded by itself, so a draft in the composer stays. A **Send** or **Allow** pressed in those few seconds fails
|
|
2160
2156
|
with its error and leaves the text in the composer: press it again.
|
|
2157
|
+
The workers left are tried again every 5 minutes, by the same rule and from the restarted chi web too, for a day from
|
|
2158
|
+
the install; after that they wait for their own idle exit or the session's **Restart**. A newer release in that day
|
|
2159
|
+
installs as usual and takes them over.
|
|
2161
2160
|
4. **Says so.** The restarted chi web pushes "chi updated to X" ("chi web and 3 sessions restarted; 1 restarts when
|
|
2162
|
-
idle. Kept your edits in 2 files.")
|
|
2163
|
-
the workers move over when you restart them (the page's toast offers it). The push needs the phone set up
|
|
2161
|
+
idle. Kept your edits in 2 files."); the later restarts of those sessions push nothing more. With
|
|
2162
|
+
`update.restart: never` the push is "chi X is installed" and chi web and the workers move over when you restart them (the page's toast offers it). The push needs the phone set up
|
|
2164
2163
|
([Phone notifications](#phone-notifications-web-push)); without it the page's toasts and
|
|
2165
2164
|
`$XDG_STATE_HOME/samagotchi/update_check.json` (`auto`) are the record.
|
|
2166
2165
|
|
data/docs/context.md
CHANGED
|
@@ -126,10 +126,10 @@ pbpaste | chi context push clip --project
|
|
|
126
126
|
```
|
|
127
127
|
|
|
128
128
|
A Claude Code session can be a pushed source too: the
|
|
129
|
-
[claude-peer bundle](
|
|
129
|
+
[claude-peer bundle](bundles.md#the-claude-peer-bundle)'s `pair` script attaches
|
|
130
130
|
`claude-inbox` (Claude's inbox socket as the hint) and `claude-outbox`, where
|
|
131
131
|
Claude pushes its answers as JSON with `wake: true`. The
|
|
132
|
-
[codex-peer bundle](
|
|
132
|
+
[codex-peer bundle](bundles.md#the-codex-peer-bundle)'s does the same for a
|
|
133
133
|
Codex session: `codex-inbox` (Codex's thread id as the hint) and
|
|
134
134
|
`codex-outbox`.
|
|
135
135
|
|
|
@@ -273,7 +273,7 @@ back the same way, its note plain, and pauses wakes too.
|
|
|
273
273
|
|
|
274
274
|
### Peer sources: the peer loop
|
|
275
275
|
|
|
276
|
-
The claude-peer and codex-peer bundles ([
|
|
276
|
+
The claude-peer and codex-peer bundles ([Bundles](bundles.md#the-claude-peer-bundle)) pair the
|
|
277
277
|
session with a Claude Code or Codex session; the peer's answers come back as
|
|
278
278
|
the `claude-outbox` / `codex-outbox` pushed source (the peer's `scripts/pair`
|
|
279
279
|
attaches it). The bundle declares that source a peer's (`chi.peer_source`,
|
|
@@ -358,7 +358,7 @@ An archived session that nobody continued takes pushes as before.
|
|
|
358
358
|
|
|
359
359
|
### Peers and a continue
|
|
360
360
|
|
|
361
|
-
A peer's pairing ([claude-peer, codex-peer](
|
|
361
|
+
A peer's pairing ([claude-peer, codex-peer](bundles.md#the-claude-peer-bundle):
|
|
362
362
|
`<peer>-inbox` and `<peer>-outbox`, both pushed) stays with the old session,
|
|
363
363
|
and the peer pairs again with the new one. The continue keeps what stayed in
|
|
364
364
|
the new session (`left.json` beside its sources: each name, its last pushed
|
|
@@ -462,11 +462,8 @@ What it asks, and when:
|
|
|
462
462
|
(a first "hi" doesn't count against it).
|
|
463
463
|
- **After a judged ask:** one re-ask once `reask_after_turns` more prompts of
|
|
464
464
|
yours came, with the conversation grown; then it is done.
|
|
465
|
-
- **Where it runs:** on
|
|
466
|
-
|
|
467
|
-
ends, so it never competes with the turn's prefill; the turn-end warm-up
|
|
468
|
-
waits for those asks and restores the cached prompt they pushed out. One
|
|
469
|
-
session's asks run one batch at a time.
|
|
465
|
+
- **Where it runs:** beside your turn, on any System 1 host. One session's
|
|
466
|
+
asks run one batch at a time.
|
|
470
467
|
|
|
471
468
|
### On mode
|
|
472
469
|
|
|
@@ -503,7 +500,10 @@ none at the thresholds then, with your prompts cut to 200 characters),
|
|
|
503
500
|
`p`), `attached` / `declined` with `by: "command"` (`/context attach|decline`,
|
|
504
501
|
the card's buttons), `attached` / `declined` / `detached` with `by: "user"`
|
|
505
502
|
(what you did otherwise, seen at your next turn's start; removing a source
|
|
506
|
-
declines it) and `withdrawn`.
|
|
503
|
+
declines it) and `withdrawn`. `chi sessions delete` drops a session's lines
|
|
504
|
+
from this log too, so the prompts it cut to 200 characters go with it; the
|
|
505
|
+
log's own size cap (5 MB, keeping the newest half) is what ages everything
|
|
506
|
+
else.
|
|
507
507
|
|
|
508
508
|
`chi context report [--days N]` counts it, with no prompts in the output
|
|
509
509
|
(this machine only):
|
data/docs/guardrails.md
CHANGED
|
@@ -11,7 +11,10 @@ are offered.
|
|
|
11
11
|
Who votes, in order:
|
|
12
12
|
|
|
13
13
|
1. `before_tool_call` hooks (Ruby; see [Hooks](hooks.md#guardrails-from-a-hook)).
|
|
14
|
-
2. Core checks: a required guardrail that failed to load, then
|
|
14
|
+
2. Core checks (`GuardrailWiring#checks`): a required guardrail that failed to load, then (a participant's turn only)
|
|
15
|
+
[the review boundary](#a-participants-review-boundary) or, for a pair turn,
|
|
16
|
+
[the pair boundary](#a-participants-pair-boundary), then protected paths, then (a `chi scratch` session only)
|
|
17
|
+
writes to the memories folder (rule `scratch-session`), then (a delegate child only)
|
|
15
18
|
[the child boundary](#a-delegate-childs-boundary).
|
|
16
19
|
3. YAML rules: `config.yml`'s `guardrails:` section, then installed bundles' rule files (by bundle name).
|
|
17
20
|
|
|
@@ -1086,12 +1089,8 @@ not `guardrails.system_one.mode`. Audit never changes the session's toolkit;
|
|
|
1086
1089
|
on mode's turn waits for the answer (at most `timeout_ms`, cut by a Stop)
|
|
1087
1090
|
and may start the session on the suggested kit (configuration.md, Toolkits).
|
|
1088
1091
|
Its warnings use the `toolkit` tag and its records are written to
|
|
1089
|
-
`toolkit_suggestions.jsonl` beside the guardrail logs.
|
|
1090
|
-
|
|
1091
|
-
the System 1 host is the model's local host: the same `hosts:` name, or
|
|
1092
|
-
another entry for the same server root (scheme, host and port). There is no
|
|
1093
|
-
reliable single-slot signal, so this host-identity check is the available
|
|
1094
|
-
contention guard. The session's own checks come first; the kits and the
|
|
1092
|
+
`toolkit_suggestions.jsonl` beside the guardrail logs. The session's own
|
|
1093
|
+
checks come first; the kits and the
|
|
1095
1094
|
suggestion log are read only for a session that can be asked, the log only
|
|
1096
1095
|
after an earlier `undecided`.
|
|
1097
1096
|
|
|
@@ -1101,8 +1100,7 @@ questions per proposed candidate, "Is this session's work about the
|
|
|
1101
1100
|
candidate?" and "Has the user stated a task yet?", on the same host and
|
|
1102
1101
|
model, gated by its own mode alone. It logs to `context_candidates.jsonl`
|
|
1103
1102
|
with the `context` tag; in on mode `ContextCandidateChoice` acts on the
|
|
1104
|
-
answer (attach, card, or nothing).
|
|
1105
|
-
local host: it asks after the turn ends there. Both side judgments run
|
|
1103
|
+
answer (attach, card, or nothing). Both side judgments run
|
|
1106
1104
|
through `SideJudgments` (one ask in flight per kind, a failure is one warn,
|
|
1107
1105
|
shutdown waits up to a second).
|
|
1108
1106
|
|
data/docs/hooks.md
CHANGED
|
@@ -228,7 +228,7 @@ turn. Don't ask questions or call the model from it: `event[:ask_user]`
|
|
|
228
228
|
returns nil at once here, and `ctx.ask_model` would hold the stream for its
|
|
229
229
|
whole answer. A hook that never returns hangs the turn, as any hook does. A
|
|
230
230
|
plugin's block that raises is logged (`plugin_hook_failed`) at most once a
|
|
231
|
-
minute.
|
|
231
|
+
minute, and its first failure in a worker shows once in every UI.
|
|
232
232
|
|
|
233
233
|
Two ways to act:
|
|
234
234
|
|
|
@@ -472,6 +472,23 @@ once in the UI.
|
|
|
472
472
|
Hook failures never break the engine loop — each hook is wrapped in its own
|
|
473
473
|
try/catch.
|
|
474
474
|
|
|
475
|
+
A bundle's `hooks/*.rb` file that **raises** tells you once per hook in a
|
|
476
|
+
worker, on the plugins' surface, whatever its `on_error` (the same notice a
|
|
477
|
+
`chi.on` handler gets):
|
|
478
|
+
|
|
479
|
+
```
|
|
480
|
+
plugins> guardrail guardrails.rb (bundle known-names) before_tool_call hook failed (RuntimeError: boom):
|
|
481
|
+
it denies every tool call it guards, and its next failures are in each denial's reason
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
The label names the file, the bundle and the event, so one line per hook: a
|
|
485
|
+
hook on a stream can't nag. `on_error` still decides what happens at every
|
|
486
|
+
firing — `skip` logs nothing, `log` warns each time (a stream hook at most
|
|
487
|
+
once a minute), a fail_closed `before_tool_call` hook denies the call — the
|
|
488
|
+
notice is only added on top. A config hook (config.yml's own files) keeps its
|
|
489
|
+
behaviour: no notice, just the log. A UI that joins later reads the same lines
|
|
490
|
+
from `Engine#plugin_warning`.
|
|
491
|
+
|
|
475
492
|
## Runtime Hook Registration
|
|
476
493
|
|
|
477
494
|
You can also register hooks programmatically during a turn (they are cleared
|
|
@@ -688,7 +705,7 @@ Notes:
|
|
|
688
705
|
- Ordering: bundle hooks fire by `(priority, bundle_name, hook_name)` (lower priority first), then plain `config.yml` hooks in registration order.
|
|
689
706
|
- Settings: a hook class with `initialize(settings = {})` gets the bundle's section of `config.yml` `bundles:` (see [Settings](#settings)).
|
|
690
707
|
- A bundle can also ship a `plugin.rb` whose `chi.on(event)` blocks are bundle hooks too, next to commands and tools; see [Plugins](plugins.md). There `ctx.notify`, `ctx.steer` and the other `ctx` helpers act as this page's `event[:notify]`… do for the event the block runs for.
|
|
691
|
-
- Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [
|
|
708
|
+
- Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Bundles](bundles.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Bundles](bundles.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Bundles](bundles.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Bundles](bundles.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Bundles](bundles.md#the-slow-commands-bundle)), `chi bundle install agents-md` (a plugin: a nested AGENTS.md is steered into the conversation on the first touch under its directory, see [Bundles](bundles.md#the-agents-md-bundle)), `chi bundle install cost-cap` (a plugin: a per-session $ cap, `/cap`, see [Bundles](bundles.md#the-cost-cap-bundle)), `chi bundle install work-cap` (a plugin: a per-session cap on tool calls and active minutes, `/workcap`, see [Bundles](bundles.md#the-work-cap-bundle)), `chi bundle install ruby` (a plugin: an RSpec run with no examples at all, a hint, see [Bundles](bundles.md#the-ruby-bundle)) `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Bundles](bundles.md#the-skills-bundle)), `chi bundle install github-pr` (attached context: the branch's open PR, see [Bundles](bundles.md#the-github-pr-bundle)), `chi bundle install coordinator` (a plugin: parallel work in worktrees and child sessions, see [Bundles](bundles.md#the-coordinator-bundle)), `chi bundle install claude-peer` / `codex-peer` (a plugin: talk to a Claude Code or Codex session, see [Bundles](bundles.md#the-claude-peer-bundle)) and `chi bundle install model-notes` (memories: reviewed model notes, see [Bundles](bundles.md#the-model-notes-bundle)).
|
|
692
709
|
- Installing a bundle executes its hook code at `Engine` startup. Only install bundles you trust, as you would a gem. Hooks are **not** executed at install time (copy-only); they are `module_eval`'d at `Engine.new` inside per-bundle `Samagotchi::Bundles::<name>` namespaces (no top-level `require` collisions). Keep hook files side-effect-free at load time; do work in `#call` — top-level side effects (require, IO, `at_exit`, global assignment) run once per `Engine.new` (class redefinition is idempotent).
|
|
693
710
|
|
|
694
711
|
Lifecycle:
|
|
@@ -144,9 +144,8 @@ nothing, so the next owner prompt asks again.
|
|
|
144
144
|
The driver is the Engine, not the judge: `Engine#start_context_judge` (an owner turn's start; skipped for participants,
|
|
145
145
|
review sessions and a Continue) and `judge_late_candidates` (a proposal after the prompts) call `context_judge_pass`.
|
|
146
146
|
It first logs status changes (`ContextCandidatesLog.look`), returns at `mode: off`, builds the due `Job`s, and hands
|
|
147
|
-
them to `SideJudgments` (`:context` kind: one thread, one batch per session at a time)
|
|
148
|
-
|
|
149
|
-
(before the prompt warm-up, which waits for it); any other host is asked at once.
|
|
147
|
+
them to `SideJudgments` (`:context` kind: one thread, one batch per session at a time), asked at once on any host,
|
|
148
|
+
the model's own server too.
|
|
150
149
|
|
|
151
150
|
`ContextCandidateChoice.after_judged` acts on `fields["would"]` in `on` mode only: *attach* → `judge_attach` (a
|
|
152
151
|
session source with `JUDGE_WHY`, no probability in the model-visible why), *offer* → one card (`offer_card`, buttons
|
data/docs/internals/bundles.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
How `lib/samagotchi/memory_bundle/` turns a bundle (a dir, git URL, zip or tar holding `manifest.yml`, `*.md`
|
|
4
4
|
memories and optional `hooks/`, `guardrails/`, a plugin file and `scripts/`) into installed state, and back. The
|
|
5
5
|
user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memory.md#what-a-bundle-owns) and
|
|
6
|
-
[plugins.md](../plugins.md).
|
|
6
|
+
[plugins.md](../plugins.md) and [bundles.md](../bundles.md).
|
|
7
7
|
|
|
8
8
|
## Where things live
|
|
9
9
|
|
|
@@ -25,6 +25,7 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
|
|
|
25
25
|
| `BundleCommand` (`lib/samagotchi/bundle_command.rb`) | `chi bundle install/upgrade/uninstall/status/diff/list/build/trash/new/test/check/try` (`install --dev`: the Installer's `dev:`, links and `Provenance::DEV_SHA`); 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) |
|
|
26
26
|
| `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 |
|
|
27
27
|
| `BundleCommand::Try` (`bundle_command/try/`) | `chi bundle try PATH -p TEXT`: `Command` (its flags, help and checks) drives the rest and `Render` prints the trace; a filtered-config `Sandbox` (its folders a `SandboxLayout`, the layout `Testing::Sandbox` uses too) 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 (`Bridge::CardStore.saved`, as the web does) and session JSON by id (never `Session.list`), joining timing and tool args for text or experimental JSON output (a turn a `--timeout` interrupt cut keeps its calls like a Ctrl-C, the one cut short answered as interrupted, so its rows come from the saved calls too; `Run::Result#timed_out` becomes `timed_out`). `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 (`ChildEnv`, the scrub a session's worker spawn uses too). The child runs in its own process group: a `--timeout` sends it INT, then `ProcessGroup.stop` (the groups its processes started too); after any exit the group is signalled only while a straggler is still in it, never a reaped group. `Sandbox#stop_leftovers` (before the trace, and in `cleanup`) stops what left the child's tree, found by the sandbox's own records: a delegate's worker by its session's `owner.lock`, a task by its running `task.json` whose pid still leads its group. |
|
|
28
|
+
| `BundleCommand::ApiCalls` (bundle_command/api_calls.rb) | what a plugin's source calls of the API, by Prism: `#findings` (a call or keyword the API's classes lack, `check`'s `api`), `#keywords` (the floor check's `call(keyword:)`). Its only list is `MEMBERS`, which object a member gives (`ctx.sessions` → `Plugin::Sessions`); a new such object joins it |
|
|
28
29
|
| `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` |
|
|
29
30
|
| `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 |
|
|
30
31
|
| `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 |
|
|
@@ -32,7 +33,7 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
|
|
|
32
33
|
| `SourceIdentity` (source.rb) | what a source is, for comparing two installs of one name: `shipped:<dir>` (any gem or checkout), `git:<url>` (no `#ref`, trailing `/` or `.git`), `path:<realpath>`; nil when it can't place one |
|
|
33
34
|
| `PreparedSource` (source.rb) | one source normalized once (dir, owned, git commit): `BundleCommand` reads the bundle's name from its `manifest.yml` (the name for every kind of source, a git URL too) and hands it to the Installer (`prepared:`), so a source is cloned or extracted once per command |
|
|
34
35
|
| `MemoryFiles` | which top-level `*.md` files of a bundle are its memories (`.select`: the `files:` list, else all but README/LICENSE and the like), `.unshipped` (listed, not shipped) and `.symlinks` (skipped: a symlink is never a memory) |
|
|
35
|
-
| `Manifest` | parses/validates `manifest.yml` (`name:` is the bundle's name and a directory under `.bundles/`, so a path such as `../x`, `a/b`, `.` or `..` is refused: `name: … is not a bundle name`; YAML that doesn't parse or isn't a mapping is a `ValidationError` too; files, hooks as `BundleHook`, plugin, scripts, needs, requires_chi, includes, context_providers, session_settings: the keys a session's `chi --set` may give, a list or a mapping of them to types (`SESSION_SETTING_TYPES`), recorded at install in `manifest.json` (`session_settings`, `session_setting_types`) for `SessionConfig` to check) and writes it (`Manifest.write`, for Builder). It ignores `requires_chi_next`, a shipped bundle's release-time marker (`script/release/release_tools.rb`, docs/releasing.md) |
|
|
36
|
+
| `Manifest` | parses/validates `manifest.yml` (`name:` is the bundle's name and a directory under `.bundles/`, so a path such as `../x`, `a/b`, `.` or `..` is refused: `name: … is not a bundle name`; YAML that doesn't parse or isn't a mapping is a `ValidationError` too; files, hooks as `BundleHook`, plugin, scripts, needs, requires_chi, includes, context_providers, session_settings: the keys a session's `chi --set` may give, a list or a mapping of them to types (`SESSION_SETTING_TYPES`), recorded at install in `manifest.json` (`session_settings`, `session_setting_types`) for `SessionConfig` to check; settings: the keys config.yml's `bundles: <name>:` may have, the same shape, recorded as `settings` (nil when the manifest has none) and `setting_types` for `BundleSettingsCheck`, whose warnings the Engine holds for the first turn and `SessionConfig`'s refusals share the words of) and writes it (`Manifest.write`, for Builder). It ignores `requires_chi_next`, a shipped bundle's release-time marker (`script/release/release_tools.rb`, docs/releasing.md) |
|
|
36
37
|
| `Installer` | one install/upgrade/dry run of one bundle (below) |
|
|
37
38
|
| `AssetInstaller` | the parts that live in `.bundles/<name>/`: hooks, guardrail rules, plugin, scripts; returns `AssetInstaller::Installed` (the paths the record keeps) |
|
|
38
39
|
| `Merger` | 3-way classification per file: `install`, `fast_forward`, `keep`, `noop`, `conflict` |
|
|
@@ -40,7 +41,8 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
|
|
|
40
41
|
| `InstalledBundle`, `BundleHook`, `PluginRef` | value objects for the record; tolerant of older records (missing keys read as empty). `BundleHook#events` is the manifest's `event:` or its `events:` list (written back as `event:` for one, as an older chi reads it); `Hooks::BundleLoader#load_hook_file` builds the hook once and registers it under each |
|
|
41
42
|
| `Builder` | `chi bundle build`: memories (+ the installed bundle's hooks, rules, plugin, scripts) → zip/tar/dir |
|
|
42
43
|
| `Profile` | meta bundles (`includes:`): install the members, record which; `InstallResult#kept_own` names a new member's memory files the user already had, with other bytes (`kept_own_line`, printed by `chi bundle`, `chi update` and `chi bootstrap`); a dry run runs each member's Installer as a dry run too, so it names them as well |
|
|
43
|
-
| `SystemBundle`, `ShippedUpdate` | the built-in system bundle (`ensure!` at Engine start, `sync` in `chi update`) and `chi update`'s upgrade of shipped bundles; both drive the Installer with `upgrade: true` |
|
|
44
|
+
| `SystemBundle`, `ShippedUpdate` | the built-in system bundle (`ensure!` at Engine start, `sync` in `chi update`) and `chi update`'s upgrade of shipped bundles; both drive the Installer with `upgrade: true`. `ShippedUpdate.external` is the rest: what `chi update` only checks |
|
|
45
|
+
| `InstalledCopy`, `BundleCommand::InstalledCheck` | `chi update`'s re-check of the bundles chi didn't ship ([docs/cli.md](../cli.md#updating)). `InstalledCopy` lays a record and its installed files out as a source folder (manifest.yml from `Manifest.write`, the files' own shas, memories from `bases/`); `InstalledCheck` forks per bundle (a plugin's `exit` or hang is that bundle's row; stdio to /dev/null, so `--json` stays parseable; `TIMEOUT`, then KILL of its group) and runs `Check.new(dir, installed: true)` there, which leaves out what only suits a source tree. The fork is the point: `Sandbox` swaps ENV and the plugin's code is arbitrary. `UpdateCommand#external_rows` makes the rows (`level`, never `failed`) and holds the check back while a newer gem is yet to take over (`@not_checked`), since a fork is this chi's code |
|
|
44
46
|
| `Uninstaller`, `Trash`, `Status`, `Listing` | remove, keep removed files, `chi bundle status`, `chi bundle list` |
|
|
45
47
|
| `IndexUpdater`, `IndexSync` | the managed `index.md` lines (Installer; and the write/edit tools for memories) |
|
|
46
48
|
| `EntrySize` | one memory's size in tokens: `memory.entry_warn_tokens`' crossing note after a memory write, `chi self`'s `big memories` row |
|
data/docs/internals/engine.md
CHANGED
|
@@ -742,7 +742,11 @@ step's text ([architecture.md](../architecture.md), the `display_refs` paragraph
|
|
|
742
742
|
- **Turn-scoped hooks** (`Engine#register_hook`, `Registry#register`) are cleared by `clear_hooks` in
|
|
743
743
|
`release_turn`.
|
|
744
744
|
- Order of a fire: bundle hooks (by priority, bundle, hook name), then config hooks, then turn-scoped hooks.
|
|
745
|
-
- A hook that raises is logged; it never breaks the turn.
|
|
745
|
+
- A hook that raises is logged; it never breaks the turn. A plugin's `chi.on` handler and a bundle's `hooks/*.rb`
|
|
746
|
+
file also tell the user, once per label in this Engine (`Hooks.wrap(on_failure:)` → `HookRoutes#plugin_hook_failed`: a
|
|
747
|
+
`:guardrail_warning` labelled `plugins`, with `Engine#plugin_warning` for a UI that joins later). The Engine hands
|
|
748
|
+
that callback to the hook files through `ExtensionLoad.new(hook_failed:)` → `Hooks::BundleLoader.load(hook_failed:)`;
|
|
749
|
+
a config hook (config.yml's own files) has none, and the test kit's sandbox gives none.
|
|
746
750
|
- A notice from a hook goes to the running turn's sink and the observers. Outside a turn it is announced with
|
|
747
751
|
`between_turns: true`; while the plugins load it is held and announced after. `EventRoutes#route` decides it, the
|
|
748
752
|
same routes as a card's (`Engine#show_card`), with their own marks (`NOTICE_MARKS`, `CARD_MARKS`); a guardrails
|
|
@@ -795,8 +799,10 @@ Engine
|
|
|
795
799
|
Both loops:
|
|
796
800
|
|
|
797
801
|
- <a id="a-reply-that-is-only-a-tool-call"></a>**A reply that is only a tool call** (`LLM::StrayToolCall`, `LLM::ChatLoop` only): a reply with no tool
|
|
798
|
-
calls whose whole text is one
|
|
799
|
-
|
|
802
|
+
calls whose whole text is one tool-call block closed by the tag that opened it (`<function=` by `</function>`, `<parameter=` by `</parameter>` or
|
|
803
|
+
`</function>`, `<tool_call>` by `</tool_call>`), with nothing else in it — the block need not carry inner tags — isn't an answer. A reply
|
|
804
|
+
opening with prose or a fence, or saying anything after the close, stays an answer, and the check is one string test on a normal one. Nothing is
|
|
805
|
+
guessed from the block and it never enters the history (`:generation_completed`
|
|
800
806
|
and `:after_generation` have already seen the text): `:generation_retrying` with `restarted` voids the streamed text, `:empty_answer_retry` with
|
|
801
807
|
`malformed` goes out, and a hidden `TurnNote.malformed_retry` asks again at the retry temperature. It has its own budget, so `retry.empty_answer: 0`
|
|
802
808
|
doesn't turn it off, and a real tool call resets it. Two in a row fail the turn with `LLM::MalformedGeneration`, keeping its earlier steps. Each is
|
|
@@ -80,19 +80,18 @@ right-hand column happens.
|
|
|
80
80
|
`toolkit.suggest.defer_turns` / `defer_tokens`) is engine-side, so `/toolkit`'s CacheConfirm doesn't apply: it
|
|
81
81
|
changes the declared tools at the front of the request, and the server re-reads **system prompt + tools +
|
|
82
82
|
conversation** on that turn. The defer bound keeps that conversation small; its notice says "from this turn".
|
|
83
|
-
When System 1 runs on the model's own single-slot local server (`Engine#system_one_shares_local_host?`), any
|
|
84
|
-
ask takes the slot and evicts its cached prefix: a first-turn ask costs that cache even when nothing switches
|
|
85
|
-
(there is little cached on a session's first turn), so on mode asks only there, skips the deferred path, and
|
|
86
|
-
sends no worker warm-up.
|
|
87
83
|
- The candidate judge (`context.candidates.mode`, `ContextJudge`) adds nothing to the model's request: its asks
|
|
88
84
|
go to System 1 only, and nothing it answers enters the running turn's history: on mode's attach writes only the
|
|
89
|
-
session's context folder, and its note comes with the between-turn delivery (`ContextAbsorber`), never mid-turn.
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
85
|
+
session's context folder, and its note comes with the between-turn delivery (`ContextAbsorber`), never mid-turn.
|
|
86
|
+
Its asks start beside the turn on any host. Bounded: at most two judged asks per candidate (one re-ask after
|
|
87
|
+
`reask_after_turns` owner prompts), plus a deferred ask per owner prompt before a task is stated.
|
|
88
|
+
- System 1's asks (`SystemOne::Client`, `/v1/systemone`) go beside the turn on any host, the model's own Splash too,
|
|
89
|
+
because they don't cost the session its cached prompt there. Measured 2026-11-01 on a local Splash with a 60k-token
|
|
90
|
+
session: the next request still had 60,064 tokens cached in 0.13 s after 3 asks (0.09 s with none), and 60,160 cached
|
|
91
|
+
in 0.18 s after 10 asks during generation; asks answered in 108-158 ms during a turn, and those 10 took the
|
|
92
|
+
generation from 2.87 s to 4.43 s. An earlier guard skipped or deferred them on the assumption that an ask takes the
|
|
93
|
+
slot and evicts the prefix, never measured there; don't rebuild it from that assumption. Not measured: a prefix past
|
|
94
|
+
Splash's cache capacity (262144 tokens).
|
|
96
95
|
- A kit's prompt text (`toolkit.kits.<name>.prompt:`, `chi.toolkit … prompt:`) sits after the appended files and
|
|
97
96
|
before the memory indexes (`SystemPrompt#kit_prompt_section`): one prefix per kit, never per-session text, so
|
|
98
97
|
sessions on the kit share it; a memory write (the indexes after it) doesn't move it. It is part of the
|
|
@@ -275,7 +274,8 @@ is prefilled once. The native and the chat loop use the same plan.
|
|
|
275
274
|
## Server-side settings worth knowing
|
|
276
275
|
|
|
277
276
|
- **Splash:** `--persistent-cache` (with `--max-cache-disk`) keeps restore points across restarts. Splash learns
|
|
278
|
-
a new branch point on the 2nd session, so the 3rd one gets the full reuse.
|
|
277
|
+
a new branch point on the 2nd session, so the 3rd one gets the full reuse. System 1's asks on the same server leave
|
|
278
|
+
a session's cached prefix alone (measured 2026-11-01, above).
|
|
279
279
|
- **llama.cpp:** `--cache-ram` (the host-memory prompt cache, 8 GiB by default in recent builds) is what keeps
|
|
280
280
|
sessions apart: when a task starts on a slot, the idle slots' state goes to that cache, and an unpinned request
|
|
281
281
|
restores the best match on whatever slot it gets. So a recap or another session between two turns costs
|
data/docs/internals/web-push.md
CHANGED
|
@@ -188,7 +188,7 @@ from saying it twice across restarts). The key's `chi:` prefix keeps sw.js from
|
|
|
188
188
|
|
|
189
189
|
`updated` is sent by the **restarted** chi web (its AutoUpdate finds the run at `phase: web`): the exec ends the
|
|
190
190
|
old process, and `Notifier#stop` does not flush the shows still in their hold, so a push queued just before it would
|
|
191
|
-
be lost. Sending from the new process also proves it came up.
|
|
191
|
+
be lost. Sending from the new process also proves it came up. The workers left then restart without another show.
|
|
192
192
|
|
|
193
193
|
**Seeding**: `Notifier#start(hub)` subscribes with `snapshot: true` and takes the summaries as the seed, so what is
|
|
194
194
|
open already never pushes. The hub's projection is empty before its first scan, so `Server.start` runs `hub.scan`
|
data/docs/memory.md
CHANGED
|
@@ -182,7 +182,7 @@ Working habits for this model:
|
|
|
182
182
|
`model_notes_deepseek` (`models: *deepseek-v4*`) and `model_notes_tone`
|
|
183
183
|
(`models: *`, concise answers for every model). Each note's provenance
|
|
184
184
|
and evidence is in the bundle's `notes/README.md`, and its spec pins which
|
|
185
|
-
model ids load which note ([
|
|
185
|
+
model ids load which note ([Bundles](bundles.md#the-model-notes-bundle)).
|
|
186
186
|
- **Your own note of the same name wins.** The install skips a
|
|
187
187
|
`model_notes_<name>.md` you already have and never owns it, so your note
|
|
188
188
|
is what loads, the two never stack, and upgrades leave it alone.
|
|
@@ -320,7 +320,7 @@ A skill is plain Markdown, no frontmatter:
|
|
|
320
320
|
|
|
321
321
|
It is a memory like any other: `memory_read`, `chi --mute skill_release`,
|
|
322
322
|
`chi bundle build` share it. The optional `skills` bundle (`chi bundle install
|
|
323
|
-
skills`, [docs/
|
|
323
|
+
skills`, [docs/bundles.md](bundles.md#the-skills-bundle)) adds `/skill save`,
|
|
324
324
|
`/skill list`, `/skill show`, `/skill diff`, keeps older versions with a
|
|
325
325
|
one-line diff after each update, and nudges a model that skips a failing
|
|
326
326
|
step instead of fixing the skill.
|