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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +64 -1
- data/README.md +1 -1
- data/bin/chi +2 -0
- data/docs/architecture.md +14 -285
- data/docs/bundle-authoring.md +1 -0
- data/docs/cli.md +15 -7
- data/docs/configuration.md +57 -18
- data/docs/context.md +68 -6
- data/docs/guardrails.md +20 -11
- data/docs/hooks.md +9 -7
- data/docs/internals/attached-context.md +226 -0
- data/docs/internals/background-tasks.md +1 -1
- data/docs/internals/bridge.md +380 -0
- data/docs/internals/bundles.md +1 -0
- data/docs/internals/context-telemetry.md +1 -1
- data/docs/internals/engine.md +24 -18
- data/docs/internals/participants.md +13 -12
- data/docs/internals/remote-sessions.md +5 -2
- data/docs/internals/{tool-guardrails.md → tool-output-limits.md} +21 -2
- data/docs/memory.md +31 -1
- data/docs/plugins.md +162 -2
- data/docs/sessions.md +53 -28
- data/docs/system-one.md +122 -0
- data/docs/testing.md +3 -1
- data/lib/samagotchi/bridge.rb +2 -0
- data/lib/samagotchi/bundles/check-in/manifest.yml +6 -3
- data/lib/samagotchi/bundles/check-in/plugin.rb +101 -4
- data/lib/samagotchi/bundles/claude-peer/manifest.yml +2 -2
- data/lib/samagotchi/bundles/claude-peer/scripts/chi-peer-SKILL.md +14 -0
- data/lib/samagotchi/bundles/codex-peer/manifest.yml +2 -2
- data/lib/samagotchi/bundles/codex-peer/scripts/chi-peer-SKILL.md +15 -1
- data/lib/samagotchi/bundles/core/manifest.yml +2 -2
- data/lib/samagotchi/bundles/system/config_modification_protocol.md +2 -2
- data/lib/samagotchi/bundles/system/manifest.yml +4 -4
- data/lib/samagotchi/bundles/system/memory_guide.md +1 -1
- data/lib/samagotchi/bundles/system/self_map.md +1 -1
- data/lib/samagotchi/config.rb +74 -14
- data/lib/samagotchi/context_candidate_choice.rb +8 -0
- data/lib/samagotchi/context_candidates_log.rb +25 -1
- data/lib/samagotchi/context_command.rb +32 -9
- data/lib/samagotchi/context_judge.rb +6 -2
- data/lib/samagotchi/context_move.rb +31 -0
- data/lib/samagotchi/context_sources.rb +248 -10
- data/lib/samagotchi/engine.rb +68 -7
- data/lib/samagotchi/extension_load.rb +3 -2
- data/lib/samagotchi/guardrail_wiring.rb +36 -31
- data/lib/samagotchi/guardrails/chi_dirs.rb +7 -4
- data/lib/samagotchi/guardrails/path_resolve.rb +1 -1
- data/lib/samagotchi/guardrails/protected_paths.rb +7 -4
- data/lib/samagotchi/guardrails_command.rb +3 -3
- data/lib/samagotchi/judgments_command.rb +155 -0
- data/lib/samagotchi/kernel_loop.rb +13 -1
- data/lib/samagotchi/llm/chat_loop.rb +74 -10
- data/lib/samagotchi/llm/errors.rb +7 -5
- data/lib/samagotchi/llm/stray_tool_call.rb +61 -0
- data/lib/samagotchi/log_line.rb +1 -1
- data/lib/samagotchi/memory_bundle/entry_size.rb +100 -0
- data/lib/samagotchi/plugin/api.rb +33 -2
- data/lib/samagotchi/plugin/attached_context.rb +14 -2
- data/lib/samagotchi/plugin/context.rb +54 -1
- data/lib/samagotchi/plugin/judgments.rb +72 -0
- data/lib/samagotchi/plugin/loader.rb +3 -2
- data/lib/samagotchi/plugin/peer.rb +53 -0
- data/lib/samagotchi/plugin/sessions.rb +9 -2
- data/lib/samagotchi/run_options.rb +1 -0
- data/lib/samagotchi/self_report.rb +36 -0
- data/lib/samagotchi/send_command.rb +3 -1
- data/lib/samagotchi/session.rb +4 -0
- data/lib/samagotchi/session_access/contract.rb +3 -1
- data/lib/samagotchi/session_access/local.rb +24 -3
- data/lib/samagotchi/session_access/remote.rb +19 -8
- data/lib/samagotchi/session_access.rb +26 -6
- data/lib/samagotchi/session_commands.rb +3 -0
- data/lib/samagotchi/session_continue.rb +9 -2
- data/lib/samagotchi/session_manager.rb +13 -2
- data/lib/samagotchi/session_retention.rb +10 -0
- data/lib/samagotchi/side_judgments.rb +12 -1
- data/lib/samagotchi/system_one/answer.rb +63 -11
- data/lib/samagotchi/system_one/approval_label.rb +56 -0
- data/lib/samagotchi/system_one/approval_question.rb +2 -0
- data/lib/samagotchi/system_one/client.rb +43 -17
- data/lib/samagotchi/system_one/fake_backend.rb +1 -1
- data/lib/samagotchi/system_one/http_backend.rb +12 -4
- data/lib/samagotchi/system_one/judgment_settings.rb +61 -0
- data/lib/samagotchi/system_one/judgments.rb +260 -0
- data/lib/samagotchi/system_one/log.rb +4 -2
- data/lib/samagotchi/system_one/recording.rb +117 -0
- data/lib/samagotchi/system_one/runs.rb +179 -0
- data/lib/samagotchi/system_one/runs_store.rb +230 -0
- data/lib/samagotchi/system_one.rb +9 -0
- data/lib/samagotchi/testing/boundary.rb +5 -1
- data/lib/samagotchi/testing/bundle.rb +9 -2
- data/lib/samagotchi/testing/host.rb +2 -1
- data/lib/samagotchi/testing/judgments.rb +185 -0
- data/lib/samagotchi/testing/recorder.rb +5 -0
- data/lib/samagotchi/testing/recording_api.rb +1 -1
- data/lib/samagotchi/tool_output_cut.rb +26 -6
- data/lib/samagotchi/tool_response.rb +1 -1
- data/lib/samagotchi/tool_runner.rb +63 -4
- data/lib/samagotchi/toolkit_suggest.rb +11 -2
- data/lib/samagotchi/tools/memory.rb +28 -0
- data/lib/samagotchi/turn_note.rb +9 -0
- data/lib/samagotchi/version.rb +1 -1
- data/lib/samagotchi/web/app.rb +14 -8
- data/lib/samagotchi/web/public/chains.js +10 -2
- data/lib/samagotchi/web/session_access_routes.rb +7 -2
- data/lib/samagotchi/web/session_create.rb +1 -0
- 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`, `
|
|
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-
|
|
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
|
|
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-
|
|
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.
|