samagotchi 0.140.0 → 0.142.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.
Files changed (109) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +64 -1
  3. data/README.md +1 -1
  4. data/bin/chi +2 -0
  5. data/docs/architecture.md +14 -285
  6. data/docs/bundle-authoring.md +1 -0
  7. data/docs/cli.md +15 -7
  8. data/docs/configuration.md +57 -18
  9. data/docs/context.md +68 -6
  10. data/docs/guardrails.md +20 -11
  11. data/docs/hooks.md +9 -7
  12. data/docs/internals/attached-context.md +226 -0
  13. data/docs/internals/background-tasks.md +1 -1
  14. data/docs/internals/bridge.md +380 -0
  15. data/docs/internals/bundles.md +1 -0
  16. data/docs/internals/context-telemetry.md +1 -1
  17. data/docs/internals/engine.md +24 -18
  18. data/docs/internals/participants.md +13 -12
  19. data/docs/internals/remote-sessions.md +5 -2
  20. data/docs/internals/{tool-guardrails.md → tool-output-limits.md} +21 -2
  21. data/docs/memory.md +31 -1
  22. data/docs/plugins.md +162 -2
  23. data/docs/sessions.md +53 -28
  24. data/docs/system-one.md +122 -0
  25. data/docs/testing.md +3 -1
  26. data/lib/samagotchi/bridge.rb +2 -0
  27. data/lib/samagotchi/bundles/check-in/manifest.yml +6 -3
  28. data/lib/samagotchi/bundles/check-in/plugin.rb +101 -4
  29. data/lib/samagotchi/bundles/claude-peer/manifest.yml +2 -2
  30. data/lib/samagotchi/bundles/claude-peer/scripts/chi-peer-SKILL.md +14 -0
  31. data/lib/samagotchi/bundles/codex-peer/manifest.yml +2 -2
  32. data/lib/samagotchi/bundles/codex-peer/scripts/chi-peer-SKILL.md +15 -1
  33. data/lib/samagotchi/bundles/core/manifest.yml +2 -2
  34. data/lib/samagotchi/bundles/system/config_modification_protocol.md +2 -2
  35. data/lib/samagotchi/bundles/system/manifest.yml +4 -4
  36. data/lib/samagotchi/bundles/system/memory_guide.md +1 -1
  37. data/lib/samagotchi/bundles/system/self_map.md +1 -1
  38. data/lib/samagotchi/config.rb +74 -14
  39. data/lib/samagotchi/context_candidate_choice.rb +8 -0
  40. data/lib/samagotchi/context_candidates_log.rb +25 -1
  41. data/lib/samagotchi/context_command.rb +32 -9
  42. data/lib/samagotchi/context_judge.rb +6 -2
  43. data/lib/samagotchi/context_move.rb +31 -0
  44. data/lib/samagotchi/context_sources.rb +248 -10
  45. data/lib/samagotchi/engine.rb +68 -7
  46. data/lib/samagotchi/extension_load.rb +3 -2
  47. data/lib/samagotchi/guardrail_wiring.rb +36 -31
  48. data/lib/samagotchi/guardrails/chi_dirs.rb +7 -4
  49. data/lib/samagotchi/guardrails/path_resolve.rb +1 -1
  50. data/lib/samagotchi/guardrails/protected_paths.rb +7 -4
  51. data/lib/samagotchi/guardrails_command.rb +3 -3
  52. data/lib/samagotchi/judgments_command.rb +155 -0
  53. data/lib/samagotchi/kernel_loop.rb +13 -1
  54. data/lib/samagotchi/llm/chat_loop.rb +74 -10
  55. data/lib/samagotchi/llm/errors.rb +7 -5
  56. data/lib/samagotchi/llm/stray_tool_call.rb +61 -0
  57. data/lib/samagotchi/log_line.rb +1 -1
  58. data/lib/samagotchi/memory_bundle/entry_size.rb +100 -0
  59. data/lib/samagotchi/plugin/api.rb +33 -2
  60. data/lib/samagotchi/plugin/attached_context.rb +14 -2
  61. data/lib/samagotchi/plugin/context.rb +54 -1
  62. data/lib/samagotchi/plugin/judgments.rb +72 -0
  63. data/lib/samagotchi/plugin/loader.rb +3 -2
  64. data/lib/samagotchi/plugin/peer.rb +53 -0
  65. data/lib/samagotchi/plugin/sessions.rb +9 -2
  66. data/lib/samagotchi/run_options.rb +1 -0
  67. data/lib/samagotchi/self_report.rb +36 -0
  68. data/lib/samagotchi/send_command.rb +3 -1
  69. data/lib/samagotchi/session.rb +4 -0
  70. data/lib/samagotchi/session_access/contract.rb +3 -1
  71. data/lib/samagotchi/session_access/local.rb +24 -3
  72. data/lib/samagotchi/session_access/remote.rb +19 -8
  73. data/lib/samagotchi/session_access.rb +26 -6
  74. data/lib/samagotchi/session_commands.rb +3 -0
  75. data/lib/samagotchi/session_continue.rb +9 -2
  76. data/lib/samagotchi/session_manager.rb +13 -2
  77. data/lib/samagotchi/session_retention.rb +10 -0
  78. data/lib/samagotchi/side_judgments.rb +12 -1
  79. data/lib/samagotchi/system_one/answer.rb +63 -11
  80. data/lib/samagotchi/system_one/approval_label.rb +56 -0
  81. data/lib/samagotchi/system_one/approval_question.rb +2 -0
  82. data/lib/samagotchi/system_one/client.rb +43 -17
  83. data/lib/samagotchi/system_one/fake_backend.rb +1 -1
  84. data/lib/samagotchi/system_one/http_backend.rb +12 -4
  85. data/lib/samagotchi/system_one/judgment_settings.rb +61 -0
  86. data/lib/samagotchi/system_one/judgments.rb +260 -0
  87. data/lib/samagotchi/system_one/log.rb +4 -2
  88. data/lib/samagotchi/system_one/recording.rb +117 -0
  89. data/lib/samagotchi/system_one/runs.rb +179 -0
  90. data/lib/samagotchi/system_one/runs_store.rb +230 -0
  91. data/lib/samagotchi/system_one.rb +9 -0
  92. data/lib/samagotchi/testing/boundary.rb +5 -1
  93. data/lib/samagotchi/testing/bundle.rb +9 -2
  94. data/lib/samagotchi/testing/host.rb +2 -1
  95. data/lib/samagotchi/testing/judgments.rb +185 -0
  96. data/lib/samagotchi/testing/recorder.rb +5 -0
  97. data/lib/samagotchi/testing/recording_api.rb +1 -1
  98. data/lib/samagotchi/tool_output_cut.rb +26 -6
  99. data/lib/samagotchi/tool_response.rb +1 -1
  100. data/lib/samagotchi/tool_runner.rb +63 -4
  101. data/lib/samagotchi/toolkit_suggest.rb +11 -2
  102. data/lib/samagotchi/tools/memory.rb +28 -0
  103. data/lib/samagotchi/turn_note.rb +9 -0
  104. data/lib/samagotchi/version.rb +1 -1
  105. data/lib/samagotchi/web/app.rb +14 -8
  106. data/lib/samagotchi/web/public/chains.js +10 -2
  107. data/lib/samagotchi/web/session_access_routes.rb +7 -2
  108. data/lib/samagotchi/web/session_create.rb +1 -0
  109. metadata +17 -2
@@ -58,7 +58,7 @@ Implementation note:
58
58
 
59
59
  ## The runner's cut (`max_tool_output_chars`)
60
60
 
61
- After a tool's own limits, `ToolRunner` caps every result at `max_tool_output_chars` (default `10000`
61
+ After a tool's own limits, `ToolRunner` caps every result but a `memory_read`'s at `max_tool_output_chars` (default `10000`
62
62
  characters, both loops). How a longer one is cut is the tool's policy, `ToolOutputCut::POLICIES` (by the
63
63
  built-in name; a tool with none gets `:head`):
64
64
 
@@ -67,7 +67,26 @@ built-in name; a tool with none gets `:head`):
67
67
  | `execute` | `:head_tail_file` | a short head, a long tail, one gap line between them; the whole output saved in the session's folder |
68
68
  | `task_wait` | `:head_tail_ref` | the same head and tail, the gap line naming the task's log (`output_path`, `Tools::RefText`); nothing saved |
69
69
  | `delegate`, `delegate_result` | `:head_tail_ref` | the same, the gap line naming the child's reply file (its `output/<timestamp>.txt`); nothing saved |
70
- | `read` and every other tool (`task_get`/`task_list`/`task_create`/`task_stop`, `web_fetch`, `memory_read`, `context_read`, plugin and MCP tools) | `:head` | the first chars, then `[cut: N of M chars; read it in parts]` |
70
+ | `read` and every other tool (`task_get`/`task_list`/`task_create`/`task_stop`, `web_fetch`, `context_read`, plugin and MCP tools) | `:head` | the first chars, then `[cut: N of M chars; read it in parts]` |
71
+ | `memory_read` | `:head`, its own cap | not cut by `max_tool_output_chars`; see below |
72
+
73
+ `memory_read` is the one tool `max_tool_output_chars` does not cap, in any form (a name, a comma list, a blank name for the
74
+ indexes): a memory is read whole, since a model that needs the skill pays for all of it anyway. `ToolRunner#output_cap`
75
+ resolves the cap per call, so both loops get it (they both come through `ToolResponse.run_batch`). Two things can still
76
+ cut a `memory_read` result, both with the same `:head` cut and a line that says where the rest is, since `memory_read`
77
+ has no parts to read:
78
+
79
+ - `memory.read_max_chars` (default `0`: none). A positive value caps the result at that many characters.
80
+ - The overflow guard, with `memory.read_max_chars` at 0: a result over half the model's context window (in characters,
81
+ tokens x `context.chars_per_token`) is cut. A context overflow is a hard failure (`LLM::FailedTurn.keeps_work?` is
82
+ false), so the turn's work rolls back and a retry would repeat the same read. The window is the loop's own:
83
+ `KernelLoop#tool_output_window` (the client's probe, the turn's `window_tokens` setting), or for `LLM::ChatLoop` its
84
+ adapter's model list too (`ToolRunner.new(kernel, window:)`). An unknown window (`ContextWindow` falling back to
85
+ its default) has no guard. It checks this one result, not the context already used.
86
+
87
+ The line is `[cut: N of M chars; the rest is in the memory's .md file in <the memories dir(s) searched>: read it with
88
+ start_line]` ("the memories' .md files" for a comma list or the indexes). `ToolOutputCut::HEAD_CUT` does not match it.
89
+ `read` on a memory's file keeps the `max_tool_output_chars` cut: it has line ranges.
71
90
 
72
91
  `:head_tail_file` is for output whose end matters: a test run's summary, an error, the `exit:` line. The head is
73
92
  `execute.cut_head_chars` at most (default `1000`) and never more than a quarter of the room; the tail gets
data/docs/memory.md CHANGED
@@ -225,7 +225,7 @@ memory's line are left out), so their size is paid on every request. Nothing cap
225
225
  or trims them; chi measures them (tokens estimated as characters /
226
226
  `context.chars_per_token`) and shows the size:
227
227
 
228
- - `chi self` has a `memory index` row:
228
+ - `chi self` has a `memory index` row (and a `big memories` row, see [A memory's size](#a-memorys-size)):
229
229
  `system ~2.0k tokens (54 lines), project ~1.4k tokens (35 lines)`, with
230
230
  `, over 2500` inside the parentheses for a scope over
231
231
  `memory.index_warn_tokens`.
@@ -252,6 +252,36 @@ may each get it. Bundle installs and uninstalls and hand edits
252
252
  change index lines without a note; `chi self`'s row shows where an index
253
253
  stands.
254
254
 
255
+ ## A memory's size
256
+
257
+ `memory_read` returns a memory whole: `max_tool_output_chars` does not cut it (see [Tool output
258
+ guardrails](internals/tool-output-limits.md#the-runners-cut-max_tool_output_chars)), so each read of a memory pays its
259
+ size. Two limits stay:
260
+
261
+ - `memory.read_max_chars` (default `0`, no fixed cap) caps a `memory_read` result at that many characters.
262
+ - An overflow guard: with that at 0 and a known context window, a result over half the window is cut. A context
263
+ overflow fails the turn and rolls its work back, and a retry repeats the read. With an unknown window there is no guard.
264
+ It checks one result, not the context already used.
265
+
266
+ A cut result ends with `[cut: N of M chars; the rest is in the memory's .md file in <dir>: read it with start_line]`;
267
+ `read` the file with `start_line` for the rest.
268
+
269
+ `memory.entry_warn_tokens` (default `5000`, about 20K characters at the default `context.chars_per_token`; `0` turns it
270
+ off) is the size a write may take one memory to before the model is told. When a `memory_write` with content, or a
271
+ `write`/`edit` on a memory file, takes a memory from at or under the limit to over it, the tool result ends with one note
272
+ (a memory that did not exist counts as 0, so a first big write gets it):
273
+
274
+ > Note: memory 'NAME' is now ~N tokens (over memory.entry_warn_tokens 5000), paid on each read. When you next have a moment, tighten it; split out only parts that are read separately, since each new memory adds an index line to every prompt. Don't remove or merge memories unless the user asks.
275
+
276
+ Once per crossing, as the index's note: a write while the memory is already over gets none. None for a
277
+ description-only write, a remove, the verbatim `index` write, a model overlay, a `model_notes_*` memory (it has its own
278
+ warning), a bundle install or a hand edit. It is independent of `memory.index_warn_tokens`: with that at 0 this note
279
+ still comes, and a write that crosses both has both notes. Nothing is said when a memory is read: that would repeat on
280
+ every read. `chi self` has a `big memories` row instead: the memories over the limit in both scopes, largest first
281
+ (5, then `+N more`), `none` when there are none, a bundle's tagged `from <bundle>` (the shipped
282
+ `config_modification_protocol` is over on every install; the fix is upstream's). This is how a
283
+ memory already over the limit gets seen.
284
+
255
285
  ## Skills
256
286
 
257
287
  A **skill** is a memory named `skill_<name>` that holds the steps of a
data/docs/plugins.md CHANGED
@@ -787,6 +787,11 @@ file can't make itself a peer's, and uninstalling the bundle ends it.
787
787
  Subclasses of `Samagotchi::Plugin::Peer` (below) declare their `OUTBOX`
788
788
  source. Needs chi 0.67.0 (guard it with `chi.respond_to?(:peer_source)`).
789
789
 
790
+ ### `chi.judgment(name, questions:, positive: nil, negative: nil, shared_host: :skip)`
791
+
792
+ A cheap System 1 question this bundle asks with `ctx.judge` or `ctx.judge_later`: see
793
+ [Judgments](#judgments-chijudgment-and-ctxjudge).
794
+
790
795
  ### `chi.ctx`
791
796
 
792
797
  The plugin's context (the `ctx` its handlers get), for `register` itself:
@@ -822,6 +827,7 @@ full label, `plugin.rb (bundle my-bundle)`.
822
827
  | `ctx.delegate?` | whether the session is a delegate child: a task another session handed over |
823
828
  | `ctx.review?` | whether the session is a review session (`chi review`): one its participants read, not the owner's working session |
824
829
  | `ctx.frontend` | what runs the session, read now: `:repl` (the REPL, `-p` without `--non-interactive`), `:one_shot` (`-p --non-interactive`: one turn, then exit) or `:worker` (a session worker: the web, an attached TUI). Only a worker's answers reach the web while it runs; a REPL's show there once the session is opened. Until the host sets it (while the plugins load, inside `Engine.new`) it reads `:one_shot`, so read it in hooks and init tasks, not in `register` |
830
+ | `ctx.continues` | the id of the session this one continues (a [continue](sessions.md#session-chains)'s new link), else nil |
825
831
  | `ctx.fork?` | whether the session is a fork (`ctx.sessions.fork`): it has a parent but isn't a delegate child, and started from a conversation, so its first prompt isn't its first user message |
826
832
  | `ctx.model` | the model the session runs on now: its resolved ref (`host:id`), right after `/model` too |
827
833
  | `ctx.model_key` | that model's memory overlay key (`<name>.<key>.md`, what `memory_write current_model_only` writes) |
@@ -843,6 +849,7 @@ full label, `plugin.rb (bundle my-bundle)`.
843
849
  | `ctx.stop_turn(reason)` | stop the running turn after a warn notice with the reason; true when it stopped one now. In a `:before_tool_call` block it also denies that call |
844
850
  | `ctx.stop_generation(reason)` | cut the generation that is streaming: the turn goes on and the model is asked again ([hooks.md](hooks.md#watching-the-stream)). Shows nothing: post your own notice. True when it cut one now |
845
851
  | `ctx.ask_model(messages:, prompt:, …)` | a side answer from the session's model: see [Side answers](#side-answers-ctxask_model) |
852
+ | `ctx.judge(name, state:)`, `ctx.judge_later(name, state:) { |result| … }`, `ctx.judgments` | a cheap System 1 question this bundle declared, saved as a run: see [Judgments](#judgments-chijudgment-and-ctxjudge) |
846
853
  | `ctx.http` | an HTTP client for calling services (`get`, `post_json`, `request`): see [Calling services](#calling-services-ctxhttp) |
847
854
  | `ctx.sessions` | fork, send to, read, list and stop other sessions: see [Other sessions](#other-sessions-ctxsessions) |
848
855
  | `ctx.toolkit` | the name of the session's toolkit (`full` for a session from before toolkits); nil with no session |
@@ -982,6 +989,104 @@ Each call counts in the session's side requests, under the bundle's name: `/stat
982
989
  web's ctx tooltip (`2 (btw 1, recap 1) · …`), with its tokens and its cost (reported, else estimated from the target
983
990
  model's price), never in the session's own totals.
984
991
 
992
+ ## Judgments: `chi.judgment` and `ctx.judge`
993
+
994
+ A judgment is a small question for [System 1](system-one.md), the cheap judgment model: a yes/no with a probability, a
995
+ choice, or a score, in about the time a tool call takes. Where `ctx.ask_model` gets free text from the session's model,
996
+ a judgment gets a number from the model the user set for this, and every ask is saved, so a later comparison or
997
+ fine-tune has what was sent and what came of it. It is chi's own layer (approvals use the same `Client` and runs) and
998
+ gives a bundle no new power. Needs chi 0.142.0 (guard it with `chi.respond_to?(:judgment)`).
999
+
1000
+ ```ruby
1001
+ def register(chi)
1002
+ chi.judgment "progress", questions: { "progress" => { type: "noul", instructions: "Is this turn still making progress?" } },
1003
+ positive: "keep_going", negative: "stop", shared_host: :skip
1004
+
1005
+ chi.on(:after_tool_call) do |_event, ctx|
1006
+ @run = ctx.judge_later("progress", state: { prompt: @prompt, calls: @calls }) do |result|
1007
+ next if result.no_judgment? || result.audit?
1008
+
1009
+ ctx.notify("this turn looks stuck") if result.p < 0.2
1010
+ end
1011
+ end
1012
+
1013
+ chi.command("/going", "Say the turn is fine") do |_args, ctx|
1014
+ ctx.judgments.label(@run, "keep_going", by: "command")
1015
+ nil
1016
+ end
1017
+ end
1018
+ ```
1019
+
1020
+ **It is off until the user says so.** The full name is `<bundle>.<name>` (`check-in.progress`), and it asks nothing until
1021
+ config.yml's [`system_one.judgments`](configuration.md#bundles-judgments) gives it a mode, `audit` or `on`, which it can
1022
+ also give a host and a model of its own. Neither `audit` nor `on` changes anything by itself: `result.audit?` is the bundle's
1023
+ to honour (in audit, look and don't act). A full name is dot-separated words of a-z, 0-9, `_` and `-`, so a bundle whose
1024
+ name has a capital or a dot fails to load on this call. `approvals`, `context`, `guardrails` and `toolkit` as a first word and
1025
+ `.replay` at the end are core's.
1026
+
1027
+ `chi.judgment`:
1028
+
1029
+ - `questions:` is a map of id to `{type:, instructions:, criteria:}`: `"noul"`, `"choice"` (criteria: `{name => description or
1030
+ nil}`) or `"score"` (criteria: a list of levels). Or a callable given `ctx`, called at each ask, where they vary per
1031
+ session. A plain map is checked when declared, a bad one failing the plugin's load; a callable's result at each ask, raising there.
1032
+ - `positive:` and `negative:` name the label values that say the answer was right and wrong (a word or a list). They
1033
+ are saved in each run for a later comparison, and don't limit `label`.
1034
+ - `shared_host:` says what to do while a turn runs on the same local server (the same `hosts:` entry or the same URL
1035
+ root, and not a remote one), where an ask evicts the turn's cached prompt: `:skip`, the default, saves the run with `asked: false`, so a
1036
+ later replay can answer it; `:ask` asks anyway. Between turns and on a remote host, it asks either way. A turn's hooks count as in the
1037
+ turn, `:after_turn` and `:session_end` too: an ask there would still evict the prefix the next turn wants.
1038
+
1039
+ `ctx.judge(name, state:)` asks and waits, at most `system_one.timeout_ms`. `name` is as declared, without the bundle.
1040
+ `state:` is a String, Hash or Array: what the question is about, sent to the System 1 host and saved as sent (bytes that
1041
+ aren't UTF-8 replaced). It stops when the turn is stopped, as `ctx.http` does. **It returns a Result, and doesn't raise for
1042
+ anything that goes wrong on the way:**
1043
+
1044
+ | On the Result | |
1045
+ |---|---|
1046
+ | `no_judgment?` | no answers |
1047
+ | `answers` | `{id => answer}`: `.noul`, `.choice`, `.score` (a score is the probability-weighted level index, not a level number), `.level` (the name of the most likely level, when the response has a legend), `.confidence`, `.probabilities` |
1048
+ | `p(id)` | a `noul` question's probability of yes (nil for no answer, or another type); no id: the only question's |
1049
+ | `audit?`, `mode` | the judgment's mode: `"off"`, `"audit"` or `"on"` |
1050
+ | `run_id` | for `ctx.judgments`; nil when no run was saved |
1051
+ | `reason` | why there's no answer, below; nil with answers |
1052
+
1053
+ | `reason` | When | A run? |
1054
+ |---|---|---|
1055
+ | `:off` | no mode set | no |
1056
+ | `:no_host` | no `system_one.host`, nor one of its own, or a config still on the moved `guardrails.system_one` keys | no |
1057
+ | `:no_session` | no session bound yet | no |
1058
+ | `:failed` | the host couldn't be reached, timed out, refused, or sent something unusable | yes, with `failure` |
1059
+ | `:cancelled` | the turn was stopped during the ask | yes, with `failure: "cancelled"` |
1060
+ | `:shared_host` | `shared_host: :skip`, and a turn is running on it | yes, `asked: false` |
1061
+ | `:busy` | `judge_later` only: this judgment's last one still runs | yes, `asked: false` |
1062
+
1063
+ An undeclared name or a bad `state:` (not a String, Hash or Array, or nested too deep) raises `ArgumentError`, as `ask_model` does for a bad model, and so does `ctx.judge` in a
1064
+ `:generation_progress` handler, whose stream it would hold.
1065
+
1066
+ `ctx.judge_later(name, state:) { |result| … }` asks on its own thread and **returns the run's id at once** (nil when no run will be
1067
+ saved). One per judgment runs at a time. The block is optional, and gets the Result once, on another thread, however
1068
+ the ask went, also when nothing was asked. A block that raises is logged.
1069
+
1070
+ - **The block's `ctx.*` act on the session as it is then**, not as the handler's event: the turn may have ended, or the
1071
+ worker moved to another session. Compare `ctx.session_id` with the one you started from before acting.
1072
+ - A `judge_later` still running when chi shuts down gets a second, then it and its run are lost. On `chi -p
1073
+ --non-interactive` this is the usual end of a slow ask.
1074
+ - Snapshot what you need: the block sees only what it closes over.
1075
+
1076
+ `ctx.judgments.label(run_id, value, by: nil, strength: nil, question: nil)` saves what came of a run, as a later line on it;
1077
+ `ctx.judgments.acted(run_id, what)` saves what the bundle did about it. Both return whether they saved anything. `value`
1078
+ and `what` are the bundle's own words (up to 200 characters), mapped only at analysis. `by:` says what said it, always after
1079
+ the bundle's name (`check-in:card`). `strength:` is `"strong"` (the user said so) or `"weak"` (they may have clicked out of habit).
1080
+ A `nil` id saves nothing and isn't an error, so a run that wasn't saved needs no check; an id of anything this bundle didn't declare raises `ArgumentError`.
1081
+
1082
+ **What's saved.** A run holds the state as sent: prompts, commands and whatever else the bundle put there, in the
1083
+ user's state dir, for as long as sessions last ([System 1's saved runs](system-one.md)). Nothing is saved for a scratch
1084
+ session or in a participant's turn, later lines included (those asks still go to the host). `system_one.runs: off` stops all of it.
1085
+
1086
+ **Cost.** A judgment stays out of the session's spend, as all of System 1's do, and **a bundle's judgments on a hosted host aren't under a
1087
+ cost cap**. At about $0.000015 a question that's accepted; ask at a human pace all the same, not per stream batch. The tokens a host reports are
1088
+ saved in the run (`usage`).
1089
+
985
1090
  ## Calling services: `ctx.http`
986
1091
 
987
1092
  ```ruby
@@ -1079,6 +1184,8 @@ ctx.sessions.review(subjects: ["docs/plan.md"], seed: handoff) # => a review se
1079
1184
  `/title` of its own (see [Session titles](sessions.md#session-titles)).
1080
1185
  - An image a message names is copied into the child. One whose file is
1081
1186
  gone is dropped, with `[image x.png was not copied]` in its message.
1187
+ - This session's movable attached context goes too, with a note naming it
1188
+ (see [Movable context](context.md#movable-context)).
1082
1189
  - A child chi won't start raises `Error` with chi's reason: the session's
1083
1190
  model is gone from the config, or its toolkit is a config kit with an
1084
1191
  invalid `groups:` (`toolkit.kits`, `Toolkit.check_new!`).
@@ -1137,6 +1244,7 @@ ctx.context.decline(url: "https://github.com/acme/app/pull/42") # => "pr-42"
1137
1244
  ctx.context.propose(url: "https://github.com/acme/app/pull/42", title: "#42 Make the thing", mentions: ["#42", "feat/x"])
1138
1245
  ctx.context.candidates # => [#<data Candidate name="pr-42", url="https://…", title="#42 Make the thing", …>]
1139
1246
  ctx.context.withdraw("pr-42") # => true
1247
+ ctx.context.left_behind # => [#<data Left name="claude-inbox", hint="/tmp/…sock", from="3f2a9c1e-…">]
1140
1248
  ```
1141
1249
 
1142
1250
  [Attached context](context.md) for the session the plugin runs in: chi runs
@@ -1152,7 +1260,9 @@ gets a note when its text changes.
1152
1260
  user adds it (`ctx.context.declined?(name, url: nil)` says so, by the
1153
1261
  name or by the URL). `force: true` is for the user's own explicit choice
1154
1262
  (a click on the plugin's card): it attaches anyway and clears the
1155
- declined marker, by the name and by the URL.
1263
+ declined marker, by the name and by the URL. `movable: true|false` says
1264
+ whether a continue or a fork takes the source to the new session (by
1265
+ default a command source does; see [Movable context](context.md#movable-context)).
1156
1266
  - `decline(url:)` or `decline(name:)` marks the source declined in this
1157
1267
  session, as the user's removal does: `attach` skips it from then on. With
1158
1268
  `url:`, the name and hint come from the bundle's provider (`name:`
@@ -1179,6 +1289,12 @@ gets a note when its text changes.
1179
1289
  markers. `withdraw(name)` takes a candidate back (true when there was
1180
1290
  one); a source attached from it stays attached. Neither an attach nor a
1181
1291
  decline removes a candidate; deleting the session does.
1292
+ - `left_behind` (read-only) lists what the continue that started this
1293
+ session left with the previous link ([Movable
1294
+ context](context.md#movable-context)): `ContextSources::Left` values with
1295
+ `name`, `hint` (the last pushed one, else the source's) and `from` (the
1296
+ previous link's id); `[]` for a session that isn't a continue's. The peer
1297
+ bundles read it to ask their peer to pair again (below).
1182
1298
  - The source is the session's (not the project's), marked
1183
1299
  `added_by: plugin:<bundle>`. It is plugin code, so it isn't asked about as
1184
1300
  the agent's `chi context add --cmd` is.
@@ -1301,6 +1417,11 @@ bundle.notices.map(&:text) # also cards, steers, s
1301
1417
  bundle.questions.last.effects # an ask_user's tags as given: { "Continue" => :spend }
1302
1418
  bundle.answer({ selected: "yes" }) # the next ask_user's answer
1303
1419
  bundle.model_answers << "a summary" # the next ask_model's answer
1420
+ bundle.judgments.answer("progress", noul: 0.9) # ctx.judge's answer from now on; question: for one of several, or a block given the state
1421
+ bundle.judgments.fail("progress") # a failed backend; mode("progress", "off"), no_host("progress"), shared_host_busy too
1422
+ bundle.judgments.wait # judge_later's threads and blocks are done
1423
+ bundle.judgments.asks.last.state # the asks that reached System 1: name, state, questions, cancel
1424
+ bundle.judgments.runs("progress").last["asked"] # the runs as chi saves them; labels("progress"), acted_lines("progress") too
1304
1425
  bundle.sessions.on(:children) { |all:| [] } # ctx.sessions, scripted and recorded
1305
1426
  bundle.http.stub(:post, "http://127.0.0.1:9000/classify", json: { label: "safe" }) # ctx.http, never the network
1306
1427
  bundle.set(running: false) # the session's values: cwd:, messages:, cancelled: …
@@ -1946,6 +2067,18 @@ and goes with the session; another session starts from config.yml:
1946
2067
  | `/checkin mode ask` / `nudge` / `notify` | the mode |
1947
2068
  | `/checkin nudge` / `later` / `stop` | the card's actions, also by hand |
1948
2069
 
2070
+ **Asking System 1 (audit).** Each check-in also asks the cheap judgment model
2071
+ `check-in.progress` — "Is this turn still making progress toward what the user
2072
+ asked?" — on a side thread, with the owner's prompt, the calls since the last
2073
+ check-in (each cut as it is captured, about 4 KB in all), the count and the
2074
+ elapsed time. It is off until you give it a mode in
2075
+ [`system_one.judgments`](configuration.md#bundles-judgments), and nothing is
2076
+ acted on: the answer is saved, and so is what the user then did with the card
2077
+ (`nudge`, `keep_going`, `stop`, or `turn_stopped` when the card was still open
2078
+ when the turn ended), as a label on that run for a later look. The card, the
2079
+ nudge and the notice are the same either way. See
2080
+ [System 1's saved runs](system-one.md).
2081
+
1949
2082
  ## The slow-commands bundle
1950
2083
 
1951
2084
  `chi bundle install slow-commands` installs the bundle shipped with chi (`chi
@@ -2375,6 +2508,27 @@ Claude pairs; without one the bundle costs one tool declaration.
2375
2508
  the remote machine can send into this Claude session (sshd makes it the
2376
2509
  user's, mode 0600 by default): fine on your own machine or pod, not a shared
2377
2510
  host. Claude's own skill has the same under "chi on another machine over SSH".
2511
+ - **A continue.** The pairing's two sources are pushed, so they stay with
2512
+ the old session when you continue it ([Movable
2513
+ context](context.md#peers-and-a-continue)). The new session's worker posts
2514
+ Claude one message, from a quiet init task, to the socket the old
2515
+ `claude-inbox` last had:
2516
+
2517
+ ```
2518
+ chi <old> · moved · continued as <new id>
2519
+ This chi session was continued as <new id>. Pair with <new id> the way you paired with <old>, then answer there (chi context push claude-outbox <new id>).
2520
+ ```
2521
+
2522
+ Claude's skill pairs again with the new id the same way it paired before
2523
+ (the same `CHI_REMOTE` and `--inbox-socket`). It is posted once (a marker
2524
+ under the bundle's `sessions/<id>/`, so a worker restart doesn't post it
2525
+ again); a post that fails (that Claude session ended) is logged and
2526
+ dropped. An outbox-only pairing has no inbox to post to: Claude's next
2527
+ answer to the old id is refused with the new one (`<old> was continued as
2528
+ <id>`), and the skill pairs again and pushes the answer there. The new
2529
+ session's note says which: `Left with 3f2a9c1e: claude-inbox, claude-outbox
2530
+ (Claude's pairing: chi asks Claude to pair again with this session).`, or
2531
+ `(Claude pairs again when it next answers)`.
2378
2532
  - **Asking first.** The tool has no `targets:`, so guardrails match it by name
2379
2533
  only: to be asked before each send, add a rule ([Rules in
2380
2534
  config.yml](guardrails.md#rules-in-configyml)):
@@ -2498,6 +2652,12 @@ skill install card) works the same.
2498
2652
  peer's, Codex's answers wake chi up to `context.peer_turns` turns in a row,
2499
2653
  and `VERDICT OK` wakes chi once to close the round. Needs chi 0.67.0 (the closing
2500
2654
  wake: the chi released with this bundle).
2655
+ - **A continue** works as claude-peer's: the new session queues Codex the
2656
+ `moved` message on the thread the old `codex-inbox` named, once, and
2657
+ Codex's skill pairs again with the new id (the same `CHI_REMOTE`, if any).
2658
+ A pairing through a remote has no inbox: Codex pairs again when its next
2659
+ push is refused. A closed Codex session still takes the message; it waits
2660
+ for `codex resume` there.
2501
2661
 
2502
2662
  ## The ruby bundle
2503
2663
 
@@ -2612,7 +2772,7 @@ for one model family, loaded into the prompt only for the models a note's
2612
2772
  prefix and against its model key, case-insensitively, and `*` also matches
2613
2773
  `/`: `*deepseek-v4*` covers `deepseek/deepseek-v4.1-flash` on any provider,
2614
2774
  MLX and GGUF names, but not `deepseek-ai/DeepSeek-R1-Distill-Qwen-32B`.
2615
- - **Tested.** `spec/model_ids.yml` lists real id forms and the exact notes
2775
+ - **Tested.** `lib/samagotchi/bundles/model-notes/spec/model_ids.yml` lists real id forms and the exact notes
2616
2776
  each loads (negative rows included); the spec installs the bundle and
2617
2777
  resolves each through `sandbox.model_notes_for`
2618
2778
  ([Testing a bundle](#testing-a-bundle-experimental)). It also checks each
data/docs/sessions.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Sessions
2
2
 
3
- Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/sessions/<uuid>.json` (XDG-aware via `XDG_STATE_HOME`) plus a sidecar dir `<uuid>/` with `input/`/`notes/`/`output/`/`owner.lock`/`bridge.json` (`Session.session_dir`), and `tool_output/` once a long `execute` result was cut: its whole output, which the cut result names (`ToolOutputFiles`, the newest 50 kept; see [Tool output guardrails](internals/tool-guardrails.md#the-runners-cut-max_tool_output_chars)). Besides the messages and turn state, the JSON keeps `written_by` (the chi version that saved it last; see *Which chi a worker runs*), `used_memory_names` (what the session read), `preloaded_memory_names` (`--memory`) and `muted_memory_names` (`--mute`), the last two written before the worker starts so a respawn builds the same prompt, `prompt_notes`, the model notes the system prompt carried at its last build (`[{name, scope, chars, digest}]`, see [Memory](memory.md#model-notes)), `parent_id`, the session that delegated this one (see *Delegating*; `null` otherwise), and `continues`, the session this one continues (the previous link of a chain, see *Session chains*; `null` otherwise); files from before those keys read as empty lists, no parent and no previous link. `model_name` is the resolved model ref (an alias applied, `host:id` when it names a host), so a resumed session keeps its model when an alias is retargeted; `model_typed` is the name it was given as when that differs (an alias), for the `models:` lookup after a resume (`null` otherwise).
3
+ Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/sessions/<uuid>.json` (XDG-aware via `XDG_STATE_HOME`) plus a sidecar dir `<uuid>/` with `input/`/`notes/`/`output/`/`owner.lock`/`bridge.json` (`Session.session_dir`), and `tool_output/` once a long `execute` result was cut: its whole output, which the cut result names (`ToolOutputFiles`, the newest 50 kept; see [Tool output guardrails](internals/tool-output-limits.md#the-runners-cut-max_tool_output_chars)). Besides the messages and turn state, the JSON keeps `written_by` (the chi version that saved it last; see *Which chi a worker runs*), `used_memory_names` (what the session read), `preloaded_memory_names` (`--memory`) and `muted_memory_names` (`--mute`), the last two written before the worker starts so a respawn builds the same prompt, `prompt_notes`, the model notes the system prompt carried at its last build (`[{name, scope, chars, digest}]`, see [Memory](memory.md#model-notes)), `parent_id`, the session that delegated this one (see *Delegating*; `null` otherwise), and `continues`, the session this one continues (the previous link of a chain, see *Session chains*; `null` otherwise); files from before those keys read as empty lists, no parent and no previous link. `model_name` is the resolved model ref (an alias applied, `host:id` when it names a host), so a resumed session keeps its model when an alias is retargeted; `model_typed` is the name it was given as when that differs (an alias), for the `models:` lookup after a resume (`null` otherwise).
4
4
 
5
5
  **Message times:** an entry of `messages` may carry `at`, when it happened: a local-offset ISO time with milliseconds (`2026-10-24T14:32:05.120+02:00`). User prompts, lines merged into a turn and steers, reminders, context and task notes, and the model's replies have one (a note's is its `created_at`); tool results, `!cmd` messages and chi's own turn notes don't, nor does anything saved before chi stamped messages (no backfill). It is for the UIs only (the gap dividers, a bubble's time): it never goes to the model, so it changes nothing in the requests or their prompt cache. The one time the model reads is the reminders': due reminders go into a turn as a system message headed `[SYSTEM: REMINDERS DUE 2026-10-24 14:32 local]` (the turn's local time; `ReminderQueue#inject!`), written into the saved content then, so a later request sends the same text.
6
6
 
@@ -45,6 +45,8 @@ A new session field (the rule in `Session::FIELDS`' comment): only top-level key
45
45
 
46
46
  <a id="archiving-a-session"></a>**Archiving a session:** `chi sessions archive ID...`, `/archive` in a terminal and the Web UI's `archive` go through `SessionManager.archive_session`: it writes `<id>/archived` (`{"archived_at": …}`; not a session.json field, which every save rewrites) for the session and its delegated children. `Session.list` leaves archived sessions out unless `include_archived:`, and everything built on it follows: `chi sessions list` (`--archived` shows them, `[archived]`), the summaries (`--live`, json/tsv, the desktop panel, the agent's `list_sessions`) and the retention prune, which neither deletes nor counts them against `max_count`. `children_of` (max_children, `delegate_result`) still sees them, and `--resume`/`--attach ID`, `chi send`/`chi note ID` reach them as before. Refused: a turn running in the session or in one of its children (naming the child; 409 `busy` on the web), a prompt queued in `input/` (it would run on the next resume) or a live worker's step-limit question still open, in it or a child (409 `busy` too), a plain REPL owning it (`owned_by_tui`), a `chi scratch` session (`scratch`). A live idle worker is stopped first, and the marker is written even if it is still shutting down. Input a human typed brings a session back (`{"unarchived_at": …}`): a prompt from the web, an attached or plain terminal or `chi send` (origin `web:*`, `tui:*`, `cli:send`, none), steering merged into a running turn, a `/continue` answer or a question answered (the step-limit question too); a delegate's follow-up, a plugin's turn, a reminder, the idle recap, a note and just opening it don't. A child's input brings only the child back. The retention sweep ages an unarchived session from when it was unarchived, so unarchiving an old session doesn't let the next sweep take it. `/archive` leaves the session first, as `/exit` does, then archives it: in an attached terminal the worker is asked to exit (one that stays up for another UI is stopped by the archive; a running turn, a queued prompt or an open step-limit question refuses it), and an empty session is discarded instead; `chi scratch` refuses it. Typed while a turn runs, `/archive` waits for the turn's end (an attached terminal for the commands queued behind it too) and then archives. `chi sessions unarchive ID...` and the web's `unarchive` bring back the whole family. Web routes: `POST /api/sessions/:id/archive` (200 `{status, session_id, archived, stopped, discarded}`, ids) and `POST /api/sessions/:id/unarchive` (200 `{status, session_id, unarchived}`). The session hub and `GET /api/sessions` keep archived sessions, `archived: true` in their summaries: the page leaves them out of the strip, its count and the list at render, and the `archived` toggle beside the all-sessions search shows them, dimmed with an `archived` badge. The info bar marks a session whose live worker runs an older chi than the newest installed (`worker_version` in its summary): `chi 0.18.1 · Restart`, which asks to confirm and calls `POST /api/sessions/:id/restart` (a refusal's reason shows in a toast); a worker from before restarts shows `chi sessions stop ID` instead. The info bar reads `continue → · archive · stop · delete` (`unarchive` on an archived one; no `continue →` on a link continued already, see *Session chains*; `continue →` is a plain button like `archive`, in the accent on an archived session, where it is the thing to do); archiving the open session stays on it, with an Undo toast.
47
47
 
48
+ **System 1's saved runs** last as long as sessions: the sweep ages them by day file, and deleting a session purges its runs ([system-one.md](system-one.md)).
49
+
48
50
  **Lazy sweep:** automatic prune runs only while `chi web` runs, at most once per `session.sweep_interval_hours` (default 24): the web's session hub gives it a chance on its periodic full scan, and `GET /api/sessions` does too. No cron, and a terminal-only chi never sweeps. Manual prune is always available.
49
51
 
50
52
  <a id="cli"></a>**CLI:**
@@ -111,6 +113,51 @@ chi sessions clean --dry-run --days 7 # test sessions older than 7 da
111
113
  - A `chi scratch` session (`"scratch": true`) is deleted when its REPL ends; one a killed process left behind is deleted by the next sweep, `prune` or `clean`, whatever its age or status, once nobody owns it. `list` shows it as `[scratch]` (every text form; `scratch: true` in `--format json`); `chi web` never shows one. See [CLI: Scratch sessions](cli.md#scratch-sessions).
112
114
  - For ad-hoc manual QA use `SAMAGOTCHI_ENV=test XDG_STATE_HOME=/tmp/chi-test-$USER chi ...` to isolate from real state; the flag also marks sessions that `chi web` or an attached `chi` spawn (their workers inherit the environment), so `clean` finds them if they land in the real state.
113
115
 
116
+ ## Session file
117
+
118
+ `Session::FIELDS` is the table of `<uuid>.json`, in the order `Session#save` writes it (`Session.from_h` and `#to_h` both go by it; 41 keys). A key a file lacks reads as the default below; `review`, `first_turn_id`, `verdicts` and `verify_fresh` are written only when set (`OPTIONAL_FIELDS`). A key this chi doesn't know is kept and written back as it was (see the rule above). "Who writes it": the Engine runs in the session's worker (or the REPL); the rest are named.
119
+
120
+ | Key | Meaning | Written by |
121
+ |-----|---------|------------|
122
+ | `metadata_version` | The file format version (`METADATA_VERSION`, 3). | `Session#save` |
123
+ | `written_by` | The chi version that saved the file last (see *Which chi a worker runs*). | `Session#save` |
124
+ | `id` | The uuid; also the file name. Required. | `Session.new_session` |
125
+ | `mode` | `assist`, the only mode. Required. | `SessionManager.spawn_session` |
126
+ | `model_name` | The resolved model ref (an alias applied; `host:id` when it names a host), so a resume keeps the model. Required. | creation, `/model` |
127
+ | `model_typed` | The name it was typed as when that differs (an alias), for the `models:` lookup after a resume; `null` otherwise. | creation, `/model` |
128
+ | `working_directory` | The folder the session runs in. Required. | creation |
129
+ | `messages` | The conversation (symbol keys in memory, strings on disk). While a turn runs, a save writes the turn's checkpoint here instead (`TurnCheckpoint`). | the Engine, per turn |
130
+ | `created_at`, `updated_at` | ISO times; `updated_at` is stamped by every save and orders the lists. Required. | `Session#save` |
131
+ | `status` | `idle`, `running`, `error` or `stopped` (turn state, not liveness; a stop is also the `<id>/stopped` marker). | the worker / Engine; the marker by `chi sessions stop` |
132
+ | `last_prompt` | The newest prompt; a session created with a first prompt holds it here until its worker takes it; after an `error` status, the reason. | `SessionManager.spawn_session`, the Engine, `Session.mark_error` |
133
+ | `first_preview` | The first user message as a one-line preview (whitespace collapsed, 80 characters), or the first context note's (`note: …`) until a message is typed. Cached so lists and `Session.resolve_id`'s ambiguity message need not read `messages`. | `Session#save` (`compute_first_preview!`) |
134
+ | `title` | The name the user gave (`/title`, whitespace collapsed, 80 characters); shown in place of `first_preview` (`display_title`); a continue's new link inherits it. The recap's auto title is not stored here. See [Session titles](#session-titles). | `/title` (`TitleCommand`), `SessionManager` |
135
+ | `test_run` | Tagged by `SAMAGOTCHI_ENV=test`, `RACK_ENV=test` or `CI` (see Test-session hygiene). | creation |
136
+ | `pending_question` | The question the worker waits on (`PendingQuestion`), `null` with none. | `QuestionDesk` |
137
+ | `used_memory_names` | The memories the session read. | the Engine |
138
+ | `project_root` | The project the session started in, stored because a worktree may be deleted later; `null` outside a repo. | creation |
139
+ | `preloaded_memory_names`, `muted_memory_names` | `--memory` and `--mute`, written before the worker starts so a respawn builds the same prompt. | creation |
140
+ | `prompt_notes` | The model notes the system prompt carried at its last build (`[{name, scope, chars, digest}]`, see [Memory](memory.md#model-notes)). | the Engine, at each prompt build |
141
+ | `parent_id` | The session that delegated this one or forked it (`ctx.sessions.fork`); `null` otherwise. See [Delegating](#delegating). | `SessionManager.spawn_session`; `ChildMove` writes a `parent.json` beside it instead of this file |
142
+ | `scratch` | A `chi scratch` session, deleted when its REPL ends. | creation |
143
+ | `last_turn` | How the last turn ended (`LastTurn`), for a parent's wait and the web's notifications. | the Engine, at a turn's end |
144
+ | `verdicts` | Verdict cards recorded by completed Verify turns, in append order. | `Engine#record_verdict`, `VerifyFresh` |
145
+ | `delegate` | Started by the `delegate` tool (a fork has a `parent_id` but isn't one). | `Tools::Delegate` via `spawn_session` |
146
+ | `llm_context` | The session's own LLM context values (strategy, apply rule, budget), over the model's; `null` with none. | creation (`--llm-context`), `/llm-context`; copied by a fork and a continue, not a delegate child |
147
+ | `continues` | The previous link of a chain; `null` otherwise. See [Session chains](#session-chains). | `SessionContinue` |
148
+ | `thinking` | The session's own thinking level (`off`/`low`/`medium`/`high`), over the process default and the model's. | creation (`--thinking`), `/thinking`; kept by a continue and a fork |
149
+ | `reasoning_history` | Its own `reasoning_history` level (`drop`/`turn`/`all`). | `/reasoning-history`; carried like `thinking` |
150
+ | `appended_prompt_files` | The absolute paths of the files `--append-system-prompt` put into the system prompt (config.yml's `append_system_prompt:` entries are not stored); kept by respawns, copied by a fork and a continue (`SessionSetup`). | creation |
151
+ | `toolkit` | The toolkit it was created on, as named (`{name, add, remove}`); `null` is `full`. See [Toolkits](configuration.md#toolkits). | creation, `/toolkit` |
152
+ | `toolkit_origin` | Why it is on that kit: `default`, `chosen` (also the reading of a file from before the field), `inherited` or `suggested`. | creation, `/toolkit`, the toolkit suggestion |
153
+ | `bundle_settings`, `config_settings` | `--set`: `BUNDLE.KEY` values by bundle and the session-settable core keys; kept by a respawn, a continue and a fork, not by a delegate child. | creation |
154
+ | `interrupted_turn` | The mark of a turn a worker checkpointed and never finished (`InterruptedTurn`); the next worker settles it and sets it to `null`. | the worker |
155
+ | `parent_answers` | Its own `guardrails.parent_answers` (it may only tighten config.yml's). | creation (`--parent-answers`), `/parent-answers` |
156
+ | `working_set_pins` | The working-set items the user pinned (`/working-set pin`); kept by a respawn, a continue and a fork. | the Engine's command |
157
+ | `review` | A review session's subjects and source (`SessionReview`), see [Review sessions](#review-sessions). | `ReviewStart` |
158
+ | `first_turn_id` | The id the creating prompt's turn gets, so a wait can name it (`chi send --new --wait`, `--wait --turn T ID`); `null` for a session created idle. | `SessionManager.spawn_session` |
159
+ | `verify_fresh` | A Verify fresh child's requester, rules and claim (`VerifyFreshOrigin`). | `VerifyFresh.start`, once |
160
+
114
161
  ## Context notes
115
162
 
116
163
  A context note is text pushed into a session as background: not a prompt, and it starts no turn.
@@ -239,7 +286,7 @@ chi send --new --continues last:3fa2 -m "new day" # the next link of 3fa2's
239
286
  - `--wait ID` with no message (no `-m`, nothing piped) sends nothing: it waits for the session's next reply and prints and exits as above. With a turn running, that turn's reply (its `interrupted_turn` mark names it), not a turn's queued behind it; with the step-limit question standing, the reply of the turn its Continue runs; with an idle session whose last turn already ended, that ended turn is the answer: its reply, or its end when it left no reply — a turn that finished in the gap between waits is reported, not waited for. With none of those (or a worker whose `bridge.json` lacks `turn_ids`), the next reply of any turn. A running session is fine (that is the point), so after exit 3, 4 or 130 an agent waits again this way while the user answers in the web or `chi --attach`; the question pending when it starts doesn't count again. An idle session with no worker waits until something wakes one. With `--new`, or two ids, it is a usage error (exit 2).
240
287
  - `--set KEY=VALUE` (with `--new`, repeatable) gives the new session a setting of its own, as `chi --set` does (see *Session settings* below): a core key a session may set (`--set recap.enabled=false`) or a bundle's `BUNDLE.KEY` (`chi send --new --set cost-cap.cap=3 -m "…"` starts it with a $3 cap). A key no session sets (`guardrails.mode`), a bundle or key the installed bundles don't offer, or a value of another type than the key takes (`recap.enabled=maybe`, `cost-cap.cap=five`) is a usage error (exit 2), as is `--set` without `--new`.
241
288
  - `--parent-answers LEVEL` (with `--new`) gives the new session its own `guardrails.parent_answers` (`hard`, `standard`, `soft`), tighten-only: config.yml's applies when it is stricter, with `chi send: warning: --parent-answers soft is looser than config.yml's …`. See *Parent answers* below.
242
- - `--continues ID` (with `--new`) starts the next link of that session's chain instead (see *Session chains*): in its folder, on its model (or the one `--model` names), LLM context, thinking level, toolkit, session settings and parent answers, so `--dir`, `--llm-context*`, `--thinking`, `--toolkit`, `--tool`, `--no-tool`, `--set` and `--parent-answers` are refused beside it; `ID` may be a prefix or `last:ID`, the chain's latest link. Without a message the new link starts idle; `--wait` then has nothing to wait for (a usage error). It prints `<full id> started (continues 3fa2c1d0)`, with `; 2 delegates moved` inside the parentheses when open delegates moved to it; a refusal (continued already, naming the next link; an open delegate that can't move; a turn running) is `chi send: refused: …`, exit 1, and a `--model` it can't start on is `chi send: could not start a session: …`, exit 1, nothing archived. A fallback to the default model (below) prints `chi send: warning: …`.
289
+ - `--continues ID` (with `--new`) starts the next link of that session's chain instead (see *Session chains*): in its folder, on its model (or the one `--model` names), LLM context, thinking level, toolkit, session settings and parent answers, so `--dir`, `--llm-context*`, `--thinking`, `--toolkit`, `--tool`, `--no-tool`, `--set` and `--parent-answers` are refused beside it; `ID` may be a prefix or `last:ID`, the chain's latest link. Without a message the new link starts idle; `--wait` then has nothing to wait for (a usage error). It prints `<full id> started (continues 3fa2c1d0)`, with `; 2 delegates moved` inside the parentheses when open delegates moved to it, and `; context moved: pr-412, ci; context stayed: notes` for its [attached context](context.md#movable-context); a refusal (continued already, naming the next link; an open delegate that can't move; a turn running) is `chi send: refused: …`, exit 1, and a `--model` it can't start on is `chi send: could not start a session: …`, exit 1, nothing archived. A fallback to the default model (below) prints `chi send: warning: …`.
243
290
  - The 16 KiB cap applies: `git diff | chi send --new …` on a big diff is refused; name the branch in the message instead and let the session read it.
244
291
  - A session nobody attaches to stalls at its first question or guardrail ask until someone answers it (`chi answer`, the web, `chi --attach`), and its worker stays up meanwhile: it doesn't idle-exit while a question waits (`chi sessions list` shows it as `waiting`; `chi sessions stop ID` frees it). Otherwise it idle-exits after `session.idle_exit_minutes` like any worker. These are ordinary sessions: delete them like any other.
245
292
 
@@ -259,12 +306,13 @@ A session can **continue** an earlier one: "the next run of the same routine" (a
259
306
 
260
307
  - **What it copies:** the previous link's folder, its model (the name it was typed as, so an alias holds) unless the continue names one (`--model`, the web's `model`), and its own LLM context values. A model given is checked like a new session's (a host config.yml doesn't have refuses the continue, nothing archived). An inherited model whose host can't run it any more (gone from config.yml, `enabled: false`, an alias naming another host) **falls back to the default model** with a warning, `gone:org/model can't run (unknown host 'gone' in model …); started on <default>`, decided before the archive; with no default model configured the continue is refused. The carry note doesn't mention the model. The new link carries no transcript, so a different model, or another provider, starts clean there. Its preview is the previous link's (until its first message is saved), unless it starts with a message. Its title (`/title`) is the previous link's, with or without a first message.
261
308
  - **The carry note:** the new link starts with a context note from `session chain` (shown in its transcript as `note from session chain`), queued before its worker spawns, so its first turn sees it: `This session continues 3fa2c1d0 (2026-10-08 09:12), the previous link of its chain. Its recap, as of 2026-10-08 18:02:` and the previous link's recap (`recap.json`; cut at 8000 characters). No recap (fewer user turns than a recap needs, recaps off, none written in time): `… It left no recap.` Never more than the recap: no transcript. An idle new link holding only the note is kept, not discarded as empty.
309
+ - **Its attached context:** the previous link's movable sources (a command source by default; a pushed one stays) are copied to the new link before its worker starts, with their last text and the removed and muted markers, and a second note (`attached context`, after the carry note) names what moved and what stayed. A push into the archived link is then refused with the new link's id. See [Movable context](context.md#movable-context).
262
310
  - **The recap first:** a previous link with a live worker is asked for a recap (the Bridge's `POST /recap`) and given up to 30 s to write it; one with none wrote its recap when its worker left.
263
311
  - **The previous link is archived** before the new one starts, by the archive's own rules (see *Archiving a session*): a turn running, a prompt queued or the step-limit question refuse it, a live idle worker is stopped, a plain REPL's session is refused. Its finished delegates are archived with it, as any archive does.
264
312
  - **Its open delegates move to the new link** instead: each direct delegate that is running, waiting for an answer, has a live worker or a reply its parent wasn't given, or has such a delegate below it (checked again after the recap wait, so one delegated meanwhile moves too). It moves with its own delegates, stays unarchived, and from then on is the new link's: its card folds under the new link, its reports ring the new link (an idle one runs a wake turn for them, as for its own delegates), `delegate_result` and the `⑂` chip count it there, and what its parent was already told (`delegates.json`) and any report still waiting come along, so nothing is reported twice. A moved delegate gets a context note from `session chain`, `Your parent session is now 4b7e9a01 (…), the next link of its session chain: …`, as its system prompt keeps naming the parent it started with. The move writes `<child>/parent.json` (`{parent_id, from, at}`) beside the child's session file, never the file itself, so a live child worker saving its own copy changes nothing; every reader applies it (a later move overwrites it; it is never removed). A continue is **refused for an open delegate that can't move** (`SessionContinue::Refused`, naming it): one whose live worker runs an older chi (`older chi worker 0.46.1; restart it`: `chi sessions restart <id>`, or stop it) or that is open in a chi REPL (close it there). An older `chi web` or CLI still running shows a moved delegate under the archived link until it is restarted.
265
313
  - **If the continue fails part-way:** a new link that fails to start gives its moved delegates back before it is deleted (each gets a note saying so; its worker is stopped first, if one started, and a worker that won't stop is reported, the link left), with any report one of them rang it with meanwhile; the previous link, back in the lists, is woken for reports waiting. A continue that dies in the middle leaves a `move.json` in the new link's folder: the new link's next worker finishes that move (only the delegates it names, and without a second note to one already told) as it starts. Until the new link's own worker holds it, a ring from a moved delegate doesn't start another (a `starting` marker in its folder, which that worker removes; a stale one, over 60 s old or from a process that is gone, is ignored). An open delegate below an archived delegate refuses the continue (`under archived …`): unarchive that one, or archive this one.
266
314
  - **Refused too:** a link that is continued already (naming the link that continues it; continue that one, or `last:<id>`), a previous link whose folder is gone, and one whose model's host can't run it when no default model is configured to fall back to. A refusal starts nothing and archives nothing; a new link that fails to start puts back what was archived. Every refusal that can be known up front (the archive's ones included) comes before the recap wait. One continue of a session runs at a time (a lock in its folder; other chains don't wait), so a double click finds the first one's link and is refused, while a `last:<id>` continue that waited follows the chain to its new end.
267
- - **Web:** `POST /api/sessions` takes `continues: "<id, prefix or last:id>"`, with `idle: true` (a new link waiting for its first message, previewed by the previous link's, or `preview`) or a `prompt`, and `model` (or `model_name`) for the new link's model, but not `dir`, `llm_context`, `thinking`, `settings`, `toolkit`, `tools`, `no_tools` or `parent_answers` (400 `invalid_continues`: the previous link's are taken). 201 is the new session's summary, `continues` set, with `moved`: the ids of the delegates that moved to it (`[]` for none), and `model_warning`: the default-model fallback's warning, then any about the model id, joined by `; ` (`null` for none), and `opener`: the previous link's first typed message, in full, when that link continues one itself (`null` otherwise: a chain's first link's first message is its task); 404 `not_found`; 400 `ambiguous_id` for a prefix of several sessions, `invalid_model` for a given model whose host config.yml doesn't have (or a fallback with no default model); 409 `continued` with `next_id` (the link that continues it already, which the page opens instead), `open_children` with `ids` (open delegates that can't move), `folder_gone`, `busy`, `scratch` or `owned_by_tui`. Every session summary carries `continues`.
315
+ - **Web:** `POST /api/sessions` takes `continues: "<id, prefix or last:id>"`, with `idle: true` (a new link waiting for its first message, previewed by the previous link's, or `preview`) or a `prompt`, and `model` (or `model_name`) for the new link's model, but not `dir`, `llm_context`, `thinking`, `settings`, `toolkit`, `tools`, `no_tools` or `parent_answers` (400 `invalid_continues`: the previous link's are taken). 201 is the new session's summary, `continues` set, with `moved`: the ids of the delegates that moved to it (`[]` for none), and `model_warning`: the default-model fallback's warning, then any about the model id, joined by `; ` (`null` for none), and `opener`: the previous link's first typed message, in full, when that link continues one itself (`null` otherwise: a chain's first link's first message is its task), and `moved_context`: `{moved: [names], stayed: [{name, why}]}`, the attached context it took (`why` `pushed` or `not movable`); 404 `not_found`; 400 `ambiguous_id` for a prefix of several sessions, `invalid_model` for a given model whose host config.yml doesn't have (or a fallback with no default model); 409 `continued` with `next_id` (the link that continues it already, which the page opens instead), `open_children` with `ids` (open delegates that can't move), `folder_gone`, `busy`, `scratch` or `owned_by_tui`. Every session summary carries `continues`.
268
316
  - **The page:** the info bar's `continue →` continues the open session (`continues: <id>, idle: true`; it reads `continuing…` through the recap wait) and opens the new link with an opener in the composer, not sent (a draft written in this session stays instead; one carried over from another session or the start page gives way to the opener, and the toast's **Restore draft** brings it back): the previous link's own first typed message when that link continues one (the 201's `opener`; a `!shell` line isn't taken), else `Continue where we left off.`. So whatever you sent on the last link comes back on the next one, and editing it once changes it for every later link; the previous link is archived, a toast says so (`Continued 3fa2c1d0 in 4b7e9a01; 3fa2c1d0 is archived; 1 open delegate moved`), and a moved delegate's card folds under the new link. When the previous link's model's host is gone the link starts on the default model and the toast carries the server's `model_warning` too, and then stays until closed. A fresh link (one with no turn yet, however it was made: `continue →`, `chi send --new --continues`, a reload) shows the model picker in its composer with the link's model, until its first turn starts (a failed or canceled first turn ends it too); a pick runs `/model <name>` in the link (a command bubble; the info bar follows) and changes neither the start page's remembered model nor its Recent list, and a Send right after it waits for the `/model` to be taken. A link a chi REPL owns, or one continued already, shows none. A link continued already has no `continue →`: its `→` link goes to the next link (a stale page's continue answered 409 `continued` opens `next_id`). A continue refused for open delegates that can't move shows a toast that names each one (its preview and what the server says to do: `older chi worker 0.46.1; restart it`, `open in a chi REPL; close it there`), each a link to its page; any other refusal shows the server's words. The info bar of a link carries `← 2026-10-08` (the previous link's day) and, on an earlier link, `2026-10-10 →`, each a link with its id, its full start (`2026-10-10 14:32`) and its preview in the tooltip; a neighbour that started on the open link's own day shows its time instead (`← 09:12`, `14:32 →`). A link made by `continue →` inherits the previous link's preview (and its title, if it has one) when it is created, so its card keeps its chain's title whatever opener it is sent, and its top bar and browser tab show its card's title. A link with a recap of its own reads its auto title, else its recap's first sentence, instead (a link without one reads its chain's name, and a first link's recap names its chain). A link whose title is the opener and nothing else (a `chi send --new --continues` link whose first message is `Continue where we left off.`) shows its chain's first link's title instead, on its card, in the popover and in its info bar's title line, display only (its messages and data keep the opener; its own title when the first link is gone). The lists fold a chain into the card of its latest listed link, whatever the earlier links' archived state (typing in an archived link brings it back, folded there still), their delegates with them: the card's `↩ #N` chip (`#N of M` when later links aren't listed; its tooltip `Session chain: link N of M`) opens a popover of the other links, newest first (`#N`, its date, with its time (`2026-10-17 14:32`) when another link of the chain started the same day, its own title when it differs from the card's (a link inherits its chain's, so mostly it doesn't), else its recap's first sentence, else its preview, `archived`), a click opens one; the chip shows a live dot or `waiting` for a link that has a worker or waits on the user, and a waiting link puts its chain's card first. All sessions folds nothing while a search is typed or the `archived` toggle is on: every link is a card of its own then, its chip `#N of M`, with its own delegates folded in, so a search finds an earlier link and its delegates.
269
317
  - **CLI:** `chi send --new --continues (ID|PREFIX|last:ID) [--model M] [-m TEXT]` (see *Starting a session*).
270
318
  - **Which link:** an id, a unique prefix, or `last:<id or prefix>`, the latest link of the chain that session is in. It walks the links that still exist: a deleted link in the middle (`chi sessions delete`, the retention sweep of an unarchived one) ends the walk before it, so `last:` of an earlier link then names that earlier link, and continuing it starts a second line beside the links after the gap; name a link after the gap instead. A trigger names the chain this way: `chi send` to an archived link would bring it back (a human's input), not continue the chain.
@@ -310,30 +358,7 @@ sessions](cli.md#review-sessions)); both start idle and print the `chi share` li
310
358
 
311
359
  ## Toolkits
312
360
 
313
- A session file's `toolkit` (`{"name", "add", "remove"}`) is the toolkit it was created on, as named: config's
314
- `toolkit.default`, `toolkit.child` for a delegate child, or `chi --toolkit` / `chi send --new --toolkit` (with
315
- `--tool` / `--no-tool`). It is never resolved again from config: a respawned or woken worker declares the same
316
- tools. `null` (a session from before toolkits) is `full`. A continue (`continue →`, `chi send --new --continues`)
317
- and a fork (`ctx.sessions.fork`) keep it, as they keep the thinking level; a delegate child gets the kit its
318
- `delegate` call names (`toolkit:`, any kit the parent knows) or `toolkit.child`; one its worker can't resolve
319
- declares every tool (full). The file stores only the name: a kit's tools and prompt text come from its definition.
320
- `/toolkit` changes it, saved at once, from the next turn's start. See
321
- [Toolkits](configuration.md#toolkits).
322
-
323
- `toolkit_origin` records why the session is on that kit: `default` for the configured kit, `chosen` for a
324
- user-selected kit (including `/toolkit` and `ctx.use_toolkit`), `inherited` for a continue or fork, or `suggested`
325
- when `toolkit.suggest.mode: on` switched it ([Toolkits](configuration.md#toolkits)). A session file from before the
326
- field reads as `chosen`. Only a `default` session is ever suggested a kit.
327
-
328
- A `find_tools` result on a chat host saves the tools its hit loads as `loaded: ["list_sessions", "mcp_fs_read"]` on
329
- its `tool_response` entry (wire names: a built-in's, an MCP tool's `mcp_<server>_<tool>`), whatever the host: a
330
- later turn on `api: anthropic` (after a `/model` switch, a resume) sends the load as references, any other host
331
- ignores it. The names stay deferred for the session's life, across respawns, `--resume` and forks.
332
-
333
- A plugin's `ctx.load_tools` leaves a system entry `{"role": "system", "kind": "tool_change", "content": "[tools loaded:
334
- delegate (bundle)]", "tool_change": {"add": ["delegate"], "by": "bundle"}}` after the turn's user message, only on a
335
- host that takes tool changes (`api: anthropic`). It is never the system head, counts as conversation, is hidden in
336
- the web and TUI histories, and goes to no other wire; its names stay deferred for the session's life like a load's.
361
+ A session's `toolkit` and `toolkit_origin` are in the [Session file](#session-file) table. What a toolkit is, how it is saved at creation, what a continue, a fork and a delegate child get, `/toolkit`, and how `find_tools` loads and `ctx.load_tools` tool changes are saved in the conversation: [Toolkits](configuration.md#toolkits).
337
362
 
338
363
  ## Parent answers
339
364
 
@@ -424,7 +449,7 @@ mise.toml pins Ruby 3.4 gets that `ruby`, `gem` and `bundle` in its tools while
424
449
 
425
450
  ## Delegating
426
451
 
427
- The `delegate` tool hands a task to a **child session**: an ordinary chi session in a worker of its own, started in the parent's `working_directory` with the task, verbatim, as its first user message, on the parent's model unless the call names one (`model:` takes a name or an alias, resolved as `--model` is; an unknown host comes back as the tool's `Error:` line; an id the host's saved model list doesn't have starts the child with a `Warning: host 'h' doesn't list model 'x' (did you mean: …?)` line in the result). Children run in parallel and only their **final reply** comes back to the parent: the child's newest `output/<timestamp>.txt` file, which the worker writes at the end of each turn that produced visible text, cut head-and-tail above 64 KB (`DelegateWait.cut`); a reply longer than `max_tool_output_chars` keeps its start and its end (the conclusion), with a gap line naming that `output/` file, where the whole reply is (`ToolOutputCut`'s `:head_tail_ref`; see [Tool output guardrails](internals/tool-guardrails.md#the-runners-cut-max_tool_output_chars)). Nothing of the child's trace enters the parent's context. Nothing is hidden: a child shows in `chi sessions list` (`↳ <parent>`), the web (folded into its parent's card on the strip and in all sessions, whose `▸ N delegates` chip lists the delegates at any depth, see Web UI above; a card of its own with a `↳` chip when its parent isn't listed; `↑ <parent id>` in its info bar, its tooltip `delegated by session …`; the parent's info bar carries a `⑂ N` chip counting its delegates, with how many run, wait, are done, failed, stopped or idle in the tooltip and the waiting ones named in the attention colour; a click opens all sessions), the terminal's status row (a parent's `⑂ 2 running · 1 waiting`, see [Status Line](cli.md#status-line)) and the `list_sessions` tool (`child`; the parent shows as `parent` in the child's own list); the user can `chi --attach <child id>` and steer it mid-run, and `chi send` and `send_note` reach it like any session.
452
+ The `delegate` tool hands a task to a **child session**: an ordinary chi session in a worker of its own, started in the parent's `working_directory` with the task, verbatim, as its first user message, on the parent's model unless the call names one (`model:` takes a name or an alias, resolved as `--model` is; an unknown host comes back as the tool's `Error:` line; an id the host's saved model list doesn't have starts the child with a `Warning: host 'h' doesn't list model 'x' (did you mean: …?)` line in the result). Children run in parallel and only their **final reply** comes back to the parent: the child's newest `output/<timestamp>.txt` file, which the worker writes at the end of each turn that produced visible text, cut head-and-tail above 64 KB (`DelegateWait.cut`); a reply longer than `max_tool_output_chars` keeps its start and its end (the conclusion), with a gap line naming that `output/` file, where the whole reply is (`ToolOutputCut`'s `:head_tail_ref`; see [Tool output guardrails](internals/tool-output-limits.md#the-runners-cut-max_tool_output_chars)). Nothing of the child's trace enters the parent's context. Nothing is hidden: a child shows in `chi sessions list` (`↳ <parent>`), the web (folded into its parent's card on the strip and in all sessions, whose `▸ N delegates` chip lists the delegates at any depth, see Web UI above; a card of its own with a `↳` chip when its parent isn't listed; `↑ <parent id>` in its info bar, its tooltip `delegated by session …`; the parent's info bar carries a `⑂ N` chip counting its delegates, with how many run, wait, are done, failed, stopped or idle in the tooltip and the waiting ones named in the attention colour; a click opens all sessions), the terminal's status row (a parent's `⑂ 2 running · 1 waiting`, see [Status Line](cli.md#status-line)) and the `list_sessions` tool (`child`; the parent shows as `parent` in the child's own list); the user can `chi --attach <child id>` and steer it mid-run, and `chi send` and `send_note` reach it like any session.
428
453
 
429
454
  - `delegate(task, model:, session:, cwd:, wait:, timeout:)`: starts a child and, by default, waits for its reply. `wait: false` is the usual way for work that takes a while, several children side by side, or to keep talking with the user: it returns at once, the parent ends its turn or works on, and the reply comes back by itself as a *delegate report* (below), in a turn of its own if the parent is idle. The tool descriptions tell the model so, and to wait (`wait: true`, `delegate_result`) only when its turn can't go on without the reply. `timeout`, default 600 s, leaves a slow child running; 0 checks once without waiting. With `session:` (a child's id or prefix) the task goes to that child as a follow-up instead, delivered like `chi send` (client id `delegate:<parent short id>`, shown as `delegate>` in the child's UIs); only this session's children take one. The wait (`wait: true`, a later `delegate_result`) and the delegate report are for the reply of the child's turn the follow-up went to: its running turn, which it merges into, or the turn of its own it runs when the child is idle (`turn` in `delegates.json`, set when the child's worker names `turn_ids`), not a newer reply of a turn queued behind it. A follow-up merged as a steer into a turn the child started at that moment (a wake, a reminder, another message) gets that turn's reply or question. A child on its first turn, or with an older worker, gives its next reply, as before.
430
455
  - `cwd:` starts the child in another folder of the parent's repository: a linked worktree (`git worktree add ../<repo>-<task> -b <branch>`, which the model runs with `execute` first, under guardrails; chi runs no git here) or a subfolder; a relative path is taken from the parent's folder. The folder must exist, have the parent's project root (the same common git dir, `MemoryPaths.project_root`) and be in a work tree: a git dir (`.git`, `.git/objects`, a bare layout's `.bare`) or a bare layout's container is refused (`git rev-parse --is-inside-work-tree`, read-only, decides). Outside git only a subfolder of the parent's folder is allowed. Otherwise the tool returns `Error: cwd must be a folder of this session's repository …` or `… is not in a work tree …`. A follow-up (`session:`) refuses `cwd:`: the child keeps its folder. The child's guardrails measure from its own worktree, and project memories, `list_sessions` and the web's project are the same as the parent's.