herdr-gentle-shell 0.0.0-stage → 1.0.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.
- package/DESIGN.md +876 -0
- package/LICENSE +21 -0
- package/README.md +460 -2
- package/bin/.gitkeep +0 -0
- package/bin/gentle-sidebar.js +53 -0
- package/docs/diagnostics.md +64 -0
- package/docs/herdr-session-open.md +160 -0
- package/docs/images/banner.png +0 -0
- package/docs/images/sidebar-example.png +0 -0
- package/docs/performance-trace.md +287 -0
- package/docs/sidebar-control.md +88 -0
- package/docs/supervision.md +96 -0
- package/extensions/.gitkeep +0 -0
- package/extensions/gentle-herdr-state.ts +3891 -0
- package/extensions/herdr-session-open.ts +399 -0
- package/lib/.gitkeep +0 -0
- package/lib/customize-panel.js +541 -0
- package/lib/gentle-sidebar.js +384 -0
- package/lib/herdr-session-notifications.js +320 -0
- package/lib/herdr-session-open.js +664 -0
- package/lib/host-settings.js +70 -0
- package/lib/perf-analyze.js +332 -0
- package/lib/perf-trace.js +684 -0
- package/lib/pi-extension-exclusion.js +405 -0
- package/package.json +39 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Jonathan Soto
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,461 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Herdr Gentle Shell
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+

|
|
4
|
+
|
|
5
|
+
Local Herdr plugin so the sidebar recognises Pi + Gentle Shell agents.
|
|
6
|
+
|
|
7
|
+
## What It Does
|
|
8
|
+
|
|
9
|
+
Reports per-pane agent state (`gentle` for generic activity — machine key
|
|
10
|
+
`working` — e.g. the orchestrator/main agent when settled with no fresh
|
|
11
|
+
root marker; `gentle` in pink while the principal
|
|
12
|
+
session actively works — even with zero
|
|
13
|
+
subagents — (machine display key
|
|
14
|
+
`orchestrating`, pink palette unchanged). The principal's own activity marker
|
|
15
|
+
(`gentle_principal_v1`, published while the principal session itself works and
|
|
16
|
+
cleared when it settles) decides the row — never the delegate count, and
|
|
17
|
+
never Herdr's aggregate native status (which reads `working` whenever any
|
|
18
|
+
delegate runs): while the principal is working it
|
|
19
|
+
reads `gentle` and no delegate role word wins; while the principal is idle
|
|
20
|
+
the oldest running delegate role shows — `explorer`, `worker`, `verify`,
|
|
21
|
+
`judge`, `rdd` — with the total running count in parentheses when two or
|
|
22
|
+
more subagents run, for example `explorer (3)`),
|
|
23
|
+
`ask` (three independent event legs — choice, native questionnaire, legacy rpiv — plus
|
|
24
|
+
executed `ask_user_question`/`ask_user_choice` tool calls (execution opens, end/result closes;
|
|
25
|
+
proposals never block), tool-gated `ui_prompt` dialog spans (a `custom` panel — agents view, ODD
|
|
26
|
+
viewer, changes view, design canvas — never counts: opening a panel is navigation, not a
|
|
27
|
+
question), and
|
|
28
|
+
permission waiting; `gentle_review` starts never speculate ask, amber/orange `?`), `blocked`, `done`, `idle`) plus compact
|
|
29
|
+
changes segments folded into the single row-1 heading cell (nonempty ` +N`/` -N`/` ↑N`
|
|
30
|
+
with leading spaces, symbols color-distinguished by `contains` rules: ` +` green for added,
|
|
31
|
+
` -` red for deleted, ` ↑` blue for pull — added stays green, deleted stays red),
|
|
32
|
+
reduced from `gentle_*`
|
|
33
|
+
pane-metadata tokens. It coexists with `herdr-pi-tree` through a single-writer handoff: while
|
|
34
|
+
this plugin owns a pane, `herdr-pi-tree` stays disabled for that pane, so the
|
|
35
|
+
two never share token names or the 16-token budget. Details live in
|
|
36
|
+
[DESIGN.md](DESIGN.md).
|
|
37
|
+
|
|
38
|
+
## What It Looks Like
|
|
39
|
+
|
|
40
|
+
<p align="center">
|
|
41
|
+
<img src="docs/images/sidebar-example.png" width="420" alt="Agents panel showing gentle states with change counts">
|
|
42
|
+
</p>
|
|
43
|
+
|
|
44
|
+
The Agents panel renders the active role (`worker`), the principal state (`gentle`),
|
|
45
|
+
and compact `+N` / `-N` change segments in one row per pane.
|
|
46
|
+
|
|
47
|
+
## Quick Start
|
|
48
|
+
|
|
49
|
+
Prerequisites: Linux, Node >= 18, Herdr meeting `min_herdr_version` in
|
|
50
|
+
`herdr-plugin/herdr-plugin.toml`, and
|
|
51
|
+
`herdr-pi-tree` installed (it stays installed but disabled for gentle-owned
|
|
52
|
+
panes).
|
|
53
|
+
|
|
54
|
+
Two packages install separately: the Herdr plugin (`herdr-plugin/`) and the
|
|
55
|
+
Pi package (the repository root, published to npm as `herdr-gentle-shell`
|
|
56
|
+
with the `pi-package` keyword). The two
|
|
57
|
+
packages version independently and release from two tag series —
|
|
58
|
+
`pi-vX.Y.Z` (npm publish) and `herdr-vX.Y.Z` (GitHub Release) — so either
|
|
59
|
+
side may lag the other; the Herdr side is not bumped when it carries no
|
|
60
|
+
change.
|
|
61
|
+
|
|
62
|
+
Source repository: `github.com/jonasotoaguilar/herdr-gentle-shell`, the
|
|
63
|
+
origin that publishes both packages and creates the releases.
|
|
64
|
+
|
|
65
|
+
### Install the Herdr plugin (always)
|
|
66
|
+
|
|
67
|
+
```sh
|
|
68
|
+
herdr plugin install jonasotoaguilar/herdr-gentle-shell/herdr-plugin
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
The Herdr side is always installed; the Pi package below is not optional
|
|
72
|
+
either, since the sidebar states come from it.
|
|
73
|
+
|
|
74
|
+
### Install the Pi package
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
pi install npm:herdr-gentle-shell
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Inside a Gentle Shell session, the same package is installed through the shell's launcher:
|
|
81
|
+
|
|
82
|
+
```sh
|
|
83
|
+
gentle-shell install npm:herdr-gentle-shell
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Both hosts install the same npm package,
|
|
87
|
+
`herdr-gentle-shell` — the Pi extension that publishes the
|
|
88
|
+
session facts behind the sidebar states — and only the host command differs.
|
|
89
|
+
|
|
90
|
+
Running Pi sessions still need `/reload` (or a restart) to pick up the
|
|
91
|
+
updated extension.
|
|
92
|
+
|
|
93
|
+
### Apply the sidebar override
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
herdr plugin action invoke configure --plugin herdr-gentle-shell
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
The action appends the managed pi-only `[ui.sidebar.agents.rows_by_agent]`
|
|
100
|
+
override described below and reloads the server; `herdr server reload-config`
|
|
101
|
+
and the daemon start (`node bin/gentle-status.js`) are the same commands run by
|
|
102
|
+
hand.
|
|
103
|
+
|
|
104
|
+
### Local development
|
|
105
|
+
|
|
106
|
+
Point Herdr at this checkout's plugin subdirectory (from this directory).
|
|
107
|
+
`herdr plugin link` only registers the directory; it runs no build.
|
|
108
|
+
|
|
109
|
+
```sh
|
|
110
|
+
herdr plugin link --enabled ./herdr-plugin
|
|
111
|
+
herdr plugin action invoke configure --plugin herdr-gentle-shell
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
The repository root is the Pi package (`herdr-gentle-shell`)
|
|
115
|
+
and `herdr-plugin/` is the Herdr plugin. Then run `/reload` in Pi to pick up
|
|
116
|
+
the local package.
|
|
117
|
+
|
|
118
|
+
For isolated/local use point Pi at a throwaway agent dir, e.g. from this
|
|
119
|
+
checkout `PI_AGENT_DIR=/tmp/pi-agent-test pi install .`.
|
|
120
|
+
|
|
121
|
+
### Update
|
|
122
|
+
|
|
123
|
+
The two packages update independently. The Pi package updates with:
|
|
124
|
+
|
|
125
|
+
```sh
|
|
126
|
+
pi update --extensions
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
and the Herdr plugin updates with:
|
|
130
|
+
|
|
131
|
+
```sh
|
|
132
|
+
herdr plugin update herdr-gentle-shell
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
To move the Herdr side to an explicitly older `herdr-vX.Y.Z` release, install
|
|
136
|
+
that ref after removing the current one:
|
|
137
|
+
|
|
138
|
+
```sh
|
|
139
|
+
herdr plugin install jonasotoaguilar/herdr-gentle-shell/herdr-plugin --ref herdr-vX.Y.Z
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
If the installed plugin is locally linked, the remote install replaces it
|
|
143
|
+
automatically and warns naming the plugin id; to restore a checkout afterwards
|
|
144
|
+
re-link it:
|
|
145
|
+
|
|
146
|
+
```sh
|
|
147
|
+
herdr plugin link --enabled ./herdr-plugin
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### Removal
|
|
151
|
+
|
|
152
|
+
```sh
|
|
153
|
+
herdr plugin action invoke unconfigure --plugin herdr-gentle-shell
|
|
154
|
+
pi remove npm:herdr-gentle-shell
|
|
155
|
+
herdr plugin uninstall herdr-gentle-shell
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
The `unconfigure` action takes the managed sidebar override out of the Herdr
|
|
159
|
+
config and reloads it; the user-owned `[ui.sidebar.agents]` table is left
|
|
160
|
+
intact. The settings exclusion is likewise
|
|
161
|
+
ownership-checked: only the entry this plugin added is removed, while a
|
|
162
|
+
pre-existing identical entry and unrelated settings are preserved. A foreign,
|
|
163
|
+
invalid, or misbound ownership record fails closed: removal warns, preserves
|
|
164
|
+
the entry, and still removes the plugin.
|
|
165
|
+
|
|
166
|
+
Path convention used below: `node bin/...` runs from the installed plugin
|
|
167
|
+
root, while `herdr-plugin/bin/...` is a repository location in this checkout.
|
|
168
|
+
`bin/configure.js` lives in the Herdr plugin and is no longer shipped by the
|
|
169
|
+
Pi package: `lib/gentle-sidebar.js` and the extension resolve the installed
|
|
170
|
+
Herdr plugin root through `herdr plugin list --json` (override
|
|
171
|
+
`GENTLE_HERDR_PLUGIN_ROOT` for isolated runs) and run that install's copy.
|
|
172
|
+
|
|
173
|
+
The `configure` action runs `node bin/configure.js --apply --reload`: it
|
|
174
|
+
appends one marked pi-only `[ui.sidebar.agents.rows_by_agent]` override for
|
|
175
|
+
canonical agent `pi` and reloads the server. Direct equivalents:
|
|
176
|
+
|
|
177
|
+
```sh
|
|
178
|
+
node bin/configure.js --check
|
|
179
|
+
node bin/configure.js --apply
|
|
180
|
+
node bin/configure.js --apply --reload # apply + `herdr server reload-config`
|
|
181
|
+
node bin/configure.js --uninstall --reload
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
### Sidebar override (non-destructive, pi-only)
|
|
185
|
+
|
|
186
|
+
`bin/configure.js` manages only its marked block and never edits the
|
|
187
|
+
user-owned `[ui.sidebar.agents]` table it sits under. The managed override is
|
|
188
|
+
exactly two pi-only rows: row 1 is the native Herdr tokens `state_icon`,
|
|
189
|
+
`workspace`, `agent` in that order as plain native token strings (no custom
|
|
190
|
+
cells, no colors wired here — row-1 glyph and identity coloring, including
|
|
191
|
+
the native `state_icon`, is Herdr-native and not plugin-controlled); row 2
|
|
192
|
+
wires the eleven presence-encoded `gentle_title_*` state cells (state word
|
|
193
|
+
only, one current title per frame, each in its state's semantic color as
|
|
194
|
+
base fg with no rules; role words carry a running-count suffix above one)
|
|
195
|
+
followed by the three
|
|
196
|
+
change-segment tokens (added green `+N`, deleted red `-N`, pull blue `↑N`,
|
|
197
|
+
each its own color cell with no rules, never swapped). The review leg
|
|
198
|
+
renders the user-facing word `rdd` in blue `#89b4fa` (same as
|
|
199
|
+
explorer/pull; internal TaskStore role slug stays `rdd`, machine display key
|
|
200
|
+
and token names stay `review` — review execution is silent, never a
|
|
201
|
+
notification; only an actual waiting prompt renders `ask` (desktop attention
|
|
202
|
+
is Herdr's native `blocked` toast); the judge delegate role renders `judge` in
|
|
203
|
+
purple `#cba6f7` (distinct from explorer blue, verify teal, and
|
|
204
|
+
orchestrating pink); the error value renders `blocked`; the orchestrating
|
|
205
|
+
leg renders the user-facing word `gentle` (machine key stays
|
|
206
|
+
`orchestrating`, pink `#f5c2e7`). Remaining state colors:
|
|
207
|
+
working/worker amber `#f9e2af`, explorer blue `#89b4fa`, verify teal
|
|
208
|
+
`#94e2d5`, ask orange `#fab387`, error red `#f38ba8`, done green `#a6e3a1`,
|
|
209
|
+
idle grey `#7c7f93`. Added stays green and deleted stays red; the mapping
|
|
210
|
+
is never swapped. The custom `$gentle_heading_*` / `$gentle_project` /
|
|
211
|
+
`$gentle_agent` cells and `gentle_changes_summary` stay published and owned
|
|
212
|
+
for compatibility but are wired into no visible row.
|
|
213
|
+
Only one `gentle_title_*` token carries a value per frame (presence
|
|
214
|
+
encoding), so row 2 shows the current state word plus any nonempty change
|
|
215
|
+
segments while the rest render empty; native separators on row 2 are
|
|
216
|
+
acceptable. Row 1 holds 3 native cells and row 2 holds 14 cells (11 state
|
|
217
|
+
+ 3 changes), each within Herdr's 16-token per-row ceiling (full block below).
|
|
218
|
+
|
|
219
|
+
```toml
|
|
220
|
+
# BEGIN herdr-gentle-agents (managed; do not edit)
|
|
221
|
+
# Sidebar override owned by herdr-gentle-agents: two pi-only rows —
|
|
222
|
+
# row 1 native state_icon + workspace + agent, row 2 state word + changes.
|
|
223
|
+
# The parent [ui.sidebar.agents] table is user-owned and never touched here.
|
|
224
|
+
[ui.sidebar.agents.rows_by_agent]
|
|
225
|
+
pi = [["state_icon", "workspace", "agent"], [{ token = "$gentle_title_working", fg = "#f9e2af" }, { token = "$gentle_title_orchestrating", fg = "#f5c2e7" }, { token = "$gentle_title_explorer", fg = "#89b4fa" }, { token = "$gentle_title_worker", fg = "#f9e2af" }, { token = "$gentle_title_verify", fg = "#94e2d5" }, { token = "$gentle_title_judge", fg = "#cba6f7" }, { token = "$gentle_title_ask", fg = "#fab387" }, { token = "$gentle_title_review", fg = "#89b4fa" }, { token = "$gentle_title_error", fg = "#f38ba8" }, { token = "$gentle_title_done", fg = "#a6e3a1" }, { token = "$gentle_title_idle", fg = "#7c7f93" }, { token = "$gentle_changes_added", fg = "#a6e3a1" }, { token = "$gentle_changes_deleted", fg = "#f38ba8" }, { token = "$gentle_changes_pull", fg = "#89b4fa" }]]
|
|
226
|
+
# END herdr-gentle-agents
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
The
|
|
230
|
+
single row-1 heading cell mirrors the Gentle Shell SessionChanges model semantics
|
|
231
|
+
(write/edit tool outcomes, never `git status`, never an approximate
|
|
232
|
+
reaggregation): files keyed by `(root, path)` with snapshot-continuity and
|
|
233
|
+
unavailable counts (unavailable files stay in the file count with 0/0); `↑N` shows when the pane
|
|
234
|
+
branch is behind its upstream (branch-ab status only, no diff). `gentle_project`,
|
|
235
|
+
`gentle_changes_summary`, and the segment
|
|
236
|
+
tokens (`gentle_changes_added`/`_deleted`/`_pull`) stay published for
|
|
237
|
+
compatibility but render no visible row. `gentle`
|
|
238
|
+
renders for generic activity (machine key `working`): the main agent when settled with no fresh root marker or roles
|
|
239
|
+
(or active subs with an unsalvageable role shape and no fresh marker); pink
|
|
240
|
+
`gentle` (machine key `orchestrating`, pink palette unchanged) renders while the principal session actively works — even with zero subagents —
|
|
241
|
+
retaining running-subagent or pending-launch coverage. The principal's own
|
|
242
|
+
activity decides the row, never the delegate count and never Herdr's
|
|
243
|
+
aggregate native status (the work token counts running delegates, and the
|
|
244
|
+
native status reads `working` for any running delegate, pending launch, or
|
|
245
|
+
live job — so neither can say the principal works): the dedicated
|
|
246
|
+
`gentle_principal_v1` marker is published while the principal session itself
|
|
247
|
+
works and cleared when it settles. A **working principal** reads `gentle` —
|
|
248
|
+
pink
|
|
249
|
+
`orchestrating` while a fresh root marker is live — and no delegate role word
|
|
250
|
+
wins; an **idle principal** shows the oldest running TaskStore role
|
|
251
|
+
(`explorer`, `worker`, `verify`, `judge`, `rdd`), however many delegates run.
|
|
252
|
+
Both yield to `ask`/`rdd`/`blocked` and terminal `done` — where `done` needs
|
|
253
|
+
settled-plus-empty (principal settled with no running delegates and no
|
|
254
|
+
pending launches; a settled principal with running delegates keeps the role
|
|
255
|
+
word, never `done`). A role word is not a subagent label; it carries the
|
|
256
|
+
total running delegate count in parentheses when that count exceeds one. The
|
|
257
|
+
work total is a direct projection of the
|
|
258
|
+
Gentle Shell TaskStore `running` records (only `running` counts as
|
|
259
|
+
executing; queued/waiting never count), never a calculated
|
|
260
|
+
pending-call estimate: pending tool calls are role-only display hints (exact
|
|
261
|
+
in-flight subagent agent -> role slug, so task-mode launches show the active
|
|
262
|
+
role even at count 0) plus label correlation, and
|
|
263
|
+
true concurrent tasks all count. A live `running` record is never regressed
|
|
264
|
+
by a racy non-final status read (only the authoritative launch outcomes,
|
|
265
|
+
completions, and presence terminals move it), so principal activity with
|
|
266
|
+
live delegates keeps `gentle` while an idle principal keeps the role word; a
|
|
267
|
+
sanitized unknown slug exactly
|
|
268
|
+
equal to `working` degrades to `gentle` (the bare word `working` never
|
|
269
|
+
renders).
|
|
270
|
+
Background launches (`subagent_run` with `mode: background`) announce
|
|
271
|
+
lifecycle over `message_end` custom results: an ACTIVE status promotes the
|
|
272
|
+
start into the tasks map like a task-mode record, so an active background
|
|
273
|
+
worker keeps the pane on live activity and shows the worker role word rather
|
|
274
|
+
than settling to `idle`/`done`.
|
|
275
|
+
Errors render as user-facing `blocked`.
|
|
276
|
+
Other agents are unaffected. `--apply` refuses (exit 2, no write) when an
|
|
277
|
+
unmanaged `rows_by_agent` override already exists; remove or rename it, then
|
|
278
|
+
re-run. Writes are atomic (temp file plus rename) with a backup at
|
|
279
|
+
`<config>.herdr-gentle-agents.bak`. The config path resolves exactly like the installed plugin's
|
|
280
|
+
`bin/gentle-status.js` (`HERDR_CONFIG_PATH`, then `XDG_CONFIG_HOME`, then
|
|
281
|
+
the platform default).
|
|
282
|
+
|
|
283
|
+
### Verification
|
|
284
|
+
|
|
285
|
+
```sh
|
|
286
|
+
node --check herdr-plugin/bin/configure.js
|
|
287
|
+
node --check herdr-plugin/bin/gentle-status.js
|
|
288
|
+
HERDR_CONFIG_PATH=/tmp/herdr-fixture.toml node herdr-plugin/bin/configure.js --apply
|
|
289
|
+
HERDR_CONFIG_PATH=/tmp/herdr-fixture.toml node herdr-plugin/bin/configure.js --check
|
|
290
|
+
HERDR_CONFIG_PATH=/tmp/herdr-fixture.toml node herdr-plugin/bin/configure.js --uninstall
|
|
291
|
+
herdr plugin action invoke configure --plugin herdr-gentle-shell
|
|
292
|
+
herdr server reload-config
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
Live check: with the daemon running and the override applied, open a Pi pane
|
|
296
|
+
and confirm row 2 shows pink `gentle` (machine key
|
|
297
|
+
`orchestrating`) while
|
|
298
|
+
the principal session actively works — even with zero subagents — and keeps
|
|
299
|
+
`gentle` while its delegates run (a role word such as `worker`, `explorer`,
|
|
300
|
+
`verify`, `judge` shows once the principal itself is idle), row 1 shows
|
|
301
|
+
the single heading cell (`● <project>` plus ` +N`/` -N`/` ↑N` inline, zero `·`) after edits / when behind upstream; then `ask` on an open
|
|
302
|
+
question (choice / native-questionnaire / legacy event legs, executed `ask_user_question`/`ask_user_choice`, tool-gated `ui_prompt` dialog spans (a `custom` panel — agents view, ODD viewer, changes view, design canvas — never counts, because opening a panel is navigation, not a question), or permission waiting; `gentle_review` starts never speculate ask) and `blocked` on error. `rdd` (machine key `review`) applies during acknowledged native capture/group execution only (`reviewerRunAcknowledged: true` at execution start — never proposal, never forecast-only, never `correctionLines` planning, never `gentle_review`/`gentle_review_scope` in any operation; no hook/sidebar signal observed; unknown legacy shapes stay dark; call-id tracked so thrown/cancelled calls still clear, read-only `assess` excluded). Bounded approximation: the acknowledged interval contains preparation and admission; no exact reviewer internal events exist today. The orchestrator-host `ask_user_choice` prompt emits no Pi tool/event observable by this extension and stays covered only by the event legs above. Never point the fixture commands at the live config: keep
|
|
303
|
+
`HERDR_CONFIG_PATH` on a temp file for apply/uninstall checks.
|
|
304
|
+
|
|
305
|
+
## Core Workflow
|
|
306
|
+
|
|
307
|
+
A Pi sidecar extension publishes `gentle_*` tokens per pane; a plugin daemon
|
|
308
|
+
reduces the Herdr snapshot to sidebar state on a poll cadence. Same transport
|
|
309
|
+
and TTL discipline as `herdr-pi-tree`, new token names, no new socket or
|
|
310
|
+
webhook. `[[startup]] node bin/gentle-status.js` (no args) is the polling-daemon
|
|
311
|
+
bootstrap (ensures the adaptive poll daemon is running: 10 s baseline,
|
|
312
|
+
`GENTLE_STATUS_POLL_MS`-overridable, with a 2 s fast cycle while recent ask
|
|
313
|
+
activity or send/publish failures are observed); `[[events]] on =
|
|
314
|
+
"pane.agent_detected"`, `pane.agent_status_changed`, `pane.exited`, and
|
|
315
|
+
`pane.closed` each run `node bin/gentle-status.js --refresh`, which ensures the
|
|
316
|
+
adaptive poll daemon is running and requests one coalesced immediate frame
|
|
317
|
+
so a newly opened project name/state renders without waiting for the next
|
|
318
|
+
poll tick. Polling stays the fallback for every lifecycle signal, so a missed
|
|
319
|
+
or undelivered event never sticks. Read-only
|
|
320
|
+
supervision triage ships beside it: the `doctor` and `whois` plugin actions
|
|
321
|
+
(`node bin/gentle-doctor.js`, `node bin/gentle-whois.js`) plus the explicit-pane
|
|
322
|
+
`node bin/gentle-trace.js <pane-id>` CLI — all read-only, none mutating state.
|
|
323
|
+
See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
324
|
+
[docs/diagnostics.md](docs/diagnostics.md) for the triage commands.
|
|
325
|
+
|
|
326
|
+
## Key Features You Should Know About
|
|
327
|
+
|
|
328
|
+
- Full v1 state matrix including the root-session `orchestrating` marker
|
|
329
|
+
(pink `●` + user-facing word `gentle`, while the principal session actively
|
|
330
|
+
works — even with zero subagents — retaining subagent/pending coverage;
|
|
331
|
+
yielding only to `ask`/`rdd`/`blocked` and terminal `done` (done needs
|
|
332
|
+
settled-plus-empty)) and the authoritative TaskStore role signal
|
|
333
|
+
(`explorer` / `worker` / `verify` / `judge` / `rdd` from `TaskRecord.agent`,
|
|
334
|
+
oldest running first by immutable first-seen, shown while the principal
|
|
335
|
+
itself is idle — a working principal keeps `gentle`, asserted by the
|
|
336
|
+
principal-only `gentle_principal_v1` marker rather than by the delegate
|
|
337
|
+
count or Herdr's aggregate native status; `gentle` (machine
|
|
338
|
+
key `working`) for the principal's own working state; an unknown delegation
|
|
339
|
+
keeps its original sanitized name, 32-char bound — never a generic
|
|
340
|
+
collapse), with a running-count suffix on role labels when two or more
|
|
341
|
+
delegates run, `ask` on blocked user input,
|
|
342
|
+
`rdd` during native review execution (machine key stays `review`; execution
|
|
343
|
+
is silent — desktop attention fires only for a waiting `ask` intent, as
|
|
344
|
+
Herdr's native toast), and
|
|
345
|
+
user-facing `blocked` for errors.
|
|
346
|
+
- Single-cell row-1 heading (`<icon> <project>` plus ` +N`/` -N`/` ↑N`
|
|
347
|
+
inline, exactly one nonempty cell so zero `·` separators; white base with
|
|
348
|
+
`contains` rules keeping ` +` green (added), ` -` red (deleted,
|
|
349
|
+
leading-space match), ` ↑` blue (pull)) mirroring the Gentle Shell
|
|
350
|
+
SessionChanges model semantics over Gentle tool outcomes, never `git`
|
|
351
|
+
status and never an approximate reaggregation (root+path continuity and
|
|
352
|
+
unavailable counts); behind-upstream `↑N` from branch-ab status only.
|
|
353
|
+
Session-change tokens are refreshed/cleared from the current Gentle Shell
|
|
354
|
+
session model and never carried across sessions.
|
|
355
|
+
- Single-writer coexistence with `herdr-pi-tree`: no shared token names, no
|
|
356
|
+
dual-write, scoped sweep of own tokens on handover.
|
|
357
|
+
- Gentle mode is enabled by default: while selected, this extension is the single publisher of native `pane.report_agent` (`working`/`blocked`/`idle`) alongside its metadata beats, with session path-or-id binding, monotonic seq, and a serial latest-wins coalesced queue. Parity contract: `working` carries the specific working role in the message (oldest running role word — known short word, unknown sanitized name, or `gentle` with no delegation; never bare generic `working`; machine keys unchanged); terminal `idle` fires only on a truly empty settle (principal settled plus zero running/queued plus zero pending plus zero live background jobs plus no human-wait prompt; settle-with-delegates/pending/jobs stays `working`, emitted once). Live background jobs (`bash_background` / `monitor`) are read from Gentle Shell's session-scoped `gentle-ai:jobs-sidebar` bus event, so waiting on a CI run or a long command keeps the row on `gentle` and never reaches `done`; `blocked` fires only for a real error or an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent). The native status keeps its aggregate meaning — it reads `working` while any delegate runs — while the sidebar row's working-vs-idle decision reads the principal-only `gentle_principal_v1` marker, so an idle principal with a running delegate shows the delegate role word instead of `gentle`. Our code never emits `done`/`finished` native states or a Herdr notification (the opt-in Moshi replacement below is a separate, off-by-default channel): the host owns finished text on `done`, `blocked`/unknown presentation, sound, and all desktop attention toasts (ask + finish) — there is no consumer toast path left to dedup. Single publisher by design: the managed native extension file stays on disk and is excluded through an ownership-bound Pi settings entry while Gentle mode is selected. `node bin/gentle-sidebar.js disable` removes only our owned exclusion and managed rows, gates our producer/daemon, and hands the sidebar back to the native publisher (running Pi sessions need `/reload`); never run both publishers on the same pane. Limits (unverified, host-owned): the host `idle`→`done`→`finished` mapping and unknown-state handling are owned by Herdr.
|
|
358
|
+
- Sidebar switch (`enable` / `disable` / `status` / `toggle`):
|
|
359
|
+
`node bin/gentle-sidebar.js <verb>` picks between this plugin's sidebar rows
|
|
360
|
+
and the native Herdr sidebar. `status` is read-only; `enable` converges the
|
|
361
|
+
managed Herdr rows and records the owned native-extension exclusion;
|
|
362
|
+
`disable` removes only our owned rows and exclusion, never a user table.
|
|
363
|
+
See [docs/sidebar-control.md](docs/sidebar-control.md).
|
|
364
|
+
- In-Pi switches (`/herdr-gentle:customize`): exactly two toggles, both local
|
|
365
|
+
state and both reachable from a plain Pi session outside a Herdr pane. With
|
|
366
|
+
no argument the command opens the restored floating two-pane panel
|
|
367
|
+
(`Herdr Sidebar` and `Moshi notifications`; `←/→` or `Tab` moves between the
|
|
368
|
+
category and value panes, `↑/↓` or `j/k` moves the cursor, `Enter` toggles the
|
|
369
|
+
focused switch and `Esc` closes). Each switch is one row that reads its stored
|
|
370
|
+
state, so `On` becomes `Off` and back in a single key press. The plain two-step menu stays as the fallback
|
|
371
|
+
when the TUI helpers or `ctx.ui.custom` are unavailable.
|
|
372
|
+
`Sidebar agent rows` drives the Herdr plugin's own `bin/configure.js`
|
|
373
|
+
(`--check` to read, `--apply --reload` / `--uninstall --reload` to change) and
|
|
374
|
+
never edits the Herdr config itself; `Moshi notifications` writes the flag
|
|
375
|
+
below and adds or removes the `-extensions/moshi-hooks.ts` exclusion in Pi's
|
|
376
|
+
`settings.json`, running the `moshi-hook` pairing gate before enabling (a
|
|
377
|
+
refusal writes nothing) and reloading Pi only when that settings entry
|
|
378
|
+
actually changed. `/herdr-gentle:customize status` prints one read-only line
|
|
379
|
+
(`customize status: sidebar=<on|off|unknown> moshi=<on|off>`); an unknown
|
|
380
|
+
argument, Esc, or a cancelled menu writes nothing. A sidebar verdict of
|
|
381
|
+
`unknown` is never a refusal: the panel says the state is unknown and
|
|
382
|
+
choosing `On` still runs the apply step, reporting that step's own error
|
|
383
|
+
when it refuses (the same behavior the menu always had). The run-by-hand
|
|
384
|
+
equivalents are the CLI and the flag file shown below.
|
|
385
|
+
- Optional Moshi replacement (off by default): one flag file,
|
|
386
|
+
`<state dir>/gentle-moshi.json` containing `{"enabled":true}` (the state dir
|
|
387
|
+
is `GENTLE_STATUS_STATE_DIR`, else the stored `herdr-gentle-agents` state dir
|
|
388
|
+
under `$XDG_STATE_HOME/herdr` or `~/.local/state/herdr`):
|
|
389
|
+
|
|
390
|
+
```sh
|
|
391
|
+
dir="${GENTLE_STATUS_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/herdr/plugins/herdr-gentle-agents}"
|
|
392
|
+
mkdir -p "$dir" && echo '{"enabled":true}' > "$dir/gentle-moshi.json"
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
`/herdr-gentle:customize` → `Moshi notifications` writes this flag for you,
|
|
396
|
+
and enabling there first requires the `moshi-hook` CLI on `PATH` with
|
|
397
|
+
`moshi-hook status --json` reporting `paired: true` (an unpaired host is
|
|
398
|
+
refused and nothing is written).
|
|
399
|
+
|
|
400
|
+
With the flag on, this plugin **replaces the
|
|
401
|
+
Moshi-managed Pi hook**: the same Moshi integration (Chat View, Live Activity,
|
|
402
|
+
session row, terminal context, phone-side approvals) keeps working, but
|
|
403
|
+
notifications follow this plugin's policy — one when Pi really needs your
|
|
404
|
+
input (`ask`) and one when Pi really finishes. Nothing per prompt, nothing per
|
|
405
|
+
turn. If `extensions/moshi-hooks.ts` is installed, add
|
|
406
|
+
`-extensions/moshi-hooks.ts` to the `extensions` list in your Pi
|
|
407
|
+
`settings.json` so the Moshi-managed hook cannot notify in parallel; that edit
|
|
408
|
+
leaves every other settings key and entry untouched. Removal of the flag (or
|
|
409
|
+
`{"enabled":false}`) silences this channel immediately — the flag is re-read
|
|
410
|
+
per event — and restoring the hook entry brings the original notifier back.
|
|
411
|
+
Moshi owns pairing and credentials; this plugin never
|
|
412
|
+
reads or stores a token, an absent daemon or unpaired host is a silent
|
|
413
|
+
no-op, and Pi is never interrupted by a Moshi failure.
|
|
414
|
+
- Delegation completion reconciled from Gentle Shell presence files, not chat
|
|
415
|
+
delivery: a delegate resolves only from an explicit terminal status or a
|
|
416
|
+
witnessed absence in a strictly newer verified activity generation of the
|
|
417
|
+
same session, bound to an immutable per-task execution epoch (new launch,
|
|
418
|
+
resume, or inactive-to-active transition — never a progress read or
|
|
419
|
+
heartbeat tick). Ambiguous, stale, or oversize snapshots never clear
|
|
420
|
+
tasks. Known limits: delegates that launch and finish between presence
|
|
421
|
+
publications never appear and still depend on chat delivery, and
|
|
422
|
+
absence-driven completion records `completed` without latching an error.
|
|
423
|
+
- TTL-bounded tokens: stale panes fall back to native `idle`.
|
|
424
|
+
- Herdr session opener (`herdr_session_open`): opens a Herdr panel running a
|
|
425
|
+
Pi session at a path. A linked Git worktree opens as a **worktree panel**
|
|
426
|
+
(reusing the workspace Herdr already has for that checkout); a repository's
|
|
427
|
+
primary checkout, a subdirectory or any generic directory opens as a
|
|
428
|
+
**normal panel**. Panel kind is decided from git, the pane Herdr names is
|
|
429
|
+
verified to belong to its workspace and to sit in the requested path before
|
|
430
|
+
Pi starts, and (unless `notify: false`) the caller is woken when that session
|
|
431
|
+
really finishes. The other worktree tools and the ODD and issues panels live
|
|
432
|
+
in `odd-worktree` now; the sidebar and Moshi switches stayed here and are
|
|
433
|
+
reached through `/herdr-gentle:customize`. See
|
|
434
|
+
[docs/herdr-session-open.md](docs/herdr-session-open.md).
|
|
435
|
+
|
|
436
|
+
## Documentation
|
|
437
|
+
|
|
438
|
+
| Your task | Start here |
|
|
439
|
+
| --- | --- |
|
|
440
|
+
| Protocol, token grammar, reducer, and coexistence rules | [DESIGN.md](DESIGN.md) |
|
|
441
|
+
| Compatibility, migration, and rollback | [DESIGN.md](DESIGN.md) §9 |
|
|
442
|
+
| Open decisions blocking implementation | [DESIGN.md](DESIGN.md) §10 |
|
|
443
|
+
| Supervision triage (read-only doctor/trace/whois) | [docs/diagnostics.md](docs/diagnostics.md) |
|
|
444
|
+
| Lifecycle recovery and interruption (polling fallback) | [docs/supervision.md](docs/supervision.md) |
|
|
445
|
+
| Sidebar switch (`bin/gentle-sidebar.js`) | [docs/sidebar-control.md](docs/sidebar-control.md) |
|
|
446
|
+
| Herdr session opener (`herdr_session_open`) | [docs/herdr-session-open.md](docs/herdr-session-open.md) |
|
|
447
|
+
| Performance trace and its report | [docs/performance-trace.md](docs/performance-trace.md) |
|
|
448
|
+
|
|
449
|
+
## Next Steps
|
|
450
|
+
|
|
451
|
+
- Ship the Pi producer extension (`extensions/`) and the Herdr consumer daemon
|
|
452
|
+
(`herdr-plugin/bin/` plus `herdr-plugin/lib/`); the daemon ships, the sidebar
|
|
453
|
+
override installs via the `configure` plugin action above.
|
|
454
|
+
- Resolve the open decisions in [DESIGN.md](DESIGN.md) §10 before implementing
|
|
455
|
+
against them.
|
|
456
|
+
- Live sidebar eyeball with subagents/`ask` remains the final acceptance check
|
|
457
|
+
(see Verification above).
|
|
458
|
+
|
|
459
|
+
## License
|
|
460
|
+
|
|
461
|
+
MIT — see [LICENSE](LICENSE).
|
package/bin/.gitkeep
ADDED
|
File without changes
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
'use strict';
|
|
3
|
+
|
|
4
|
+
// Package-side CLI for the Gentle/native sidebar switch (S7):
|
|
5
|
+
// node bin/gentle-sidebar.js (enable|disable|status|toggle) [--json]
|
|
6
|
+
//
|
|
7
|
+
// The only supported sidebar switch in this package; see lib/gentle-sidebar.js
|
|
8
|
+
// and docs/sidebar-control.md. Isolated use:
|
|
9
|
+
// GENTLE_STATUS_STATE_DIR=/tmp/s PI_CODING_AGENT_DIR=/tmp/a
|
|
10
|
+
// HERDR_CONFIG_PATH=/tmp/c.toml node bin/gentle-sidebar.js status
|
|
11
|
+
//
|
|
12
|
+
// Exit codes: 0 success; 1 operational failure; 2 usage failure.
|
|
13
|
+
|
|
14
|
+
const sidebar = require('../lib/gentle-sidebar.js');
|
|
15
|
+
|
|
16
|
+
function usage() {
|
|
17
|
+
console.error('usage: node bin/gentle-sidebar.js (enable|disable|status|toggle) [--json]');
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
function main() {
|
|
21
|
+
const args = process.argv.slice(2);
|
|
22
|
+
const verb = args[0];
|
|
23
|
+
const json = args.includes('--json');
|
|
24
|
+
for (const flag of args.slice(1)) {
|
|
25
|
+
if (flag !== '--json') {
|
|
26
|
+
console.error(`gentle-sidebar: unknown flag ${flag}`);
|
|
27
|
+
usage();
|
|
28
|
+
process.exit(2);
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
let result;
|
|
32
|
+
if (verb === 'enable') result = sidebar.enable();
|
|
33
|
+
else if (verb === 'disable') result = sidebar.disable();
|
|
34
|
+
else if (verb === 'status') result = sidebar.status();
|
|
35
|
+
else if (verb === 'toggle') {
|
|
36
|
+
const mode = sidebar.readMode();
|
|
37
|
+
if (mode.state === 'malformed') {
|
|
38
|
+
console.error(`gentle-sidebar: mode file is malformed (expected {"version":1,"enabled":boolean}); fix or remove it first.`);
|
|
39
|
+
process.exit(1);
|
|
40
|
+
}
|
|
41
|
+
result = mode.publish ? sidebar.disable() : sidebar.enable();
|
|
42
|
+
} else {
|
|
43
|
+
console.error(`gentle-sidebar: unknown verb ${verb === undefined ? '(none)' : JSON.stringify(verb)}`);
|
|
44
|
+
usage();
|
|
45
|
+
process.exit(2);
|
|
46
|
+
}
|
|
47
|
+
if (json) console.log(JSON.stringify({ code: result.code, message: result.message }));
|
|
48
|
+
else if (result.code === 0) console.log(result.message);
|
|
49
|
+
else console.error(result.message);
|
|
50
|
+
process.exit(result.code);
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
if (require.main === module) main();
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Diagnostics (read-only)
|
|
2
|
+
|
|
3
|
+
Three standalone Node CLIs for supervision triage. All are read-only:
|
|
4
|
+
they never create the state directory, write tokens/config/ledger, start
|
|
5
|
+
or stop the daemon, read transcripts, or dump private raw tokens, task
|
|
6
|
+
labels, or review verdicts. Herdr is reached only through fixed-argv
|
|
7
|
+
`HERDR_BIN_PATH` list commands; no socket calls are made or claimed.
|
|
8
|
+
|
|
9
|
+
## Commands
|
|
10
|
+
|
|
11
|
+
- `node herdr-plugin/bin/gentle-doctor.js [--help]` — daemon pidfile liveness
|
|
12
|
+
(signal 0; presence alone is not liveness), producer/token freshness
|
|
13
|
+
from one `herdr agent list` snapshot, managed sidebar override marker
|
|
14
|
+
scan. Prints `pass:`/`warn:`/`fail:` lines plus actionable `remedy:`
|
|
15
|
+
lines. When native mode is selected
|
|
16
|
+
(`gentle-sidebar-mode.json` holding `{"version":1,"enabled":false}`), skips
|
|
17
|
+
inactive Gentle daemon/producer/override checks and still checks snapshot
|
|
18
|
+
availability. An invalid mode file fails closed without exposing its contents.
|
|
19
|
+
Exit 0 pass/warn only, 1 any fail or failed snapshot, 2 bad args.
|
|
20
|
+
- `node herdr-plugin/bin/gentle-trace.js <pane-id>` — one JSON document for a pane
|
|
21
|
+
(e.g. `wBG:p1`): safe ids, agent, display, roles, count, freshness
|
|
22
|
+
booleans, identity session hash, and the safe interruption record.
|
|
23
|
+
A disappeared agent whose pane is still present traces as
|
|
24
|
+
`display: interrupted` / `label: Interrumpido` with the safe record;
|
|
25
|
+
confirmed pane absence stays `pane_not_found`. A failed snapshot or
|
|
26
|
+
unknown pane is a JSON `ok:false` failure, never an empty success.
|
|
27
|
+
Exit 0 traced, 1 unavailable/not-found, 2 bad args.
|
|
28
|
+
- `node herdr-plugin/bin/gentle-whois.js [--all]` — concise `PANE AGENT STATE ROLES
|
|
29
|
+
WORKSPACE` table in stable pane order, fitted to narrow widths with
|
|
30
|
+
control characters stripped. Default lists only plugin-owned panes;
|
|
31
|
+
`--all` also lists native/foreign panes without task names.
|
|
32
|
+
`Interrumpido` is diagnostic-only (valid ledger record while the pane
|
|
33
|
+
shows no fresh activity); the sidebar vocabulary is unchanged. Ledger
|
|
34
|
+
rows for panes missing from the agent list are confirmed with one
|
|
35
|
+
extra `pane list` call: confirmed presence renders the row, confirmed
|
|
36
|
+
absence shows no ghost, and a failed pane list fails explicitly.
|
|
37
|
+
Exit 0 rendered, 1 snapshot unavailable, 2 bad args.
|
|
38
|
+
|
|
39
|
+
Invalid arguments are rejected with exit 2 before any state read or
|
|
40
|
+
Herdr call. A failed `agent list` snapshot is always a failure (exit 1),
|
|
41
|
+
distinct from an empty-but-successful view.
|
|
42
|
+
|
|
43
|
+
## Environment
|
|
44
|
+
|
|
45
|
+
- `HERDR_BIN_PATH` — Herdr binary (default `herdr`).
|
|
46
|
+
- `GENTLE_STATUS_STATE_DIR` (else `HERDR_PLUGIN_STATE_DIR`, else the
|
|
47
|
+
default plugins state dir) — read for `gentle-status.pid` and the
|
|
48
|
+
`gentle-sidebar-mode.json` (`{version:1,enabled:boolean}`; missing defaults
|
|
49
|
+
to Gentle mode), and the `gentle-interruptions.json` ledger
|
|
50
|
+
(`{version:1,panes:{...}}` with only
|
|
51
|
+
identity hash, whitelisted unfinished displays, finite timestamps, and
|
|
52
|
+
reason `agent_disappeared`). A missing ledger is tolerated; a malformed
|
|
53
|
+
one is ignored with a warning and its arbitrary fields never exposed.
|
|
54
|
+
- `HERDR_CONFIG_PATH` — read for the managed sidebar marker scan.
|
|
55
|
+
- `COLUMNS` — whois table width (default 80, clamped 20–512).
|
|
56
|
+
|
|
57
|
+
## Shared library
|
|
58
|
+
|
|
59
|
+
`herdr-plugin/lib/gentle-diagnostics.js` holds the read-only helpers (path
|
|
60
|
+
resolution without mkdir, bounded reads, sanitization/width fitting,
|
|
61
|
+
strict ledger validation, pidfile signal-0 check, per-pane whitelist
|
|
62
|
+
summary via `herdr-plugin/lib/gentle-tokens.js`). It exposes only safe pane/workspace
|
|
63
|
+
ids, validated agent names, the agent_status enum, role slugs, running
|
|
64
|
+
counts, freshness booleans, and the identity hash.
|