herdr-gentle-shell 1.6.2 → 1.8.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 +130 -41
- package/README.md +48 -25
- package/docs/theme-sync.md +284 -0
- package/extensions/gentle-herdr-state.ts +279 -157
- package/extensions/herdr-theme-sync.ts +388 -0
- package/lib/customize-panel.js +92 -17
- package/lib/theme-projection.js +159 -0
- package/lib/theme-store.js +230 -0
- package/package.json +3 -2
package/DESIGN.md
CHANGED
|
@@ -154,13 +154,13 @@ an explicit writer-ownership decision. Rationale follows each choice.
|
|
|
154
154
|
absent under single-writer handoff (O1). Gentle renders exactly two rows
|
|
155
155
|
for the `pi` agent: row 1 is the heading context as exactly one active
|
|
156
156
|
cell — the active `gentle_heading_*` value holds `<icon> <project>` plus
|
|
157
|
-
compact nonempty changes segments (` +N`, ` -N
|
|
158
|
-
cell (e.g. `● myproj +110 -22
|
|
157
|
+
compact nonempty changes segments (` +N`, ` -N`) in that same
|
|
158
|
+
cell (e.g. `● myproj +110 -22`). Exactly one row-1 cell is nonempty,
|
|
159
159
|
so Herdr inserts zero inter-cell `·` separators. The cell sits on white
|
|
160
160
|
`#ffffff` (SIDEBAR_PROJECT) so the project text stays white; symbol
|
|
161
161
|
`contains` rules recolor the icon (unchanged state mapping) plus ` +`
|
|
162
|
-
green (added), ` -` red (deleted, leading-space match so hyphens inside
|
|
163
|
-
project names never turn red)
|
|
162
|
+
green (added), and ` -` red (deleted, leading-space match so hyphens inside
|
|
163
|
+
project names never turn red). `gentle_project`,
|
|
164
164
|
`gentle_changes_summary`, and the change-segment tokens stay published
|
|
165
165
|
and owned for compatibility but are wired into no visible row; row 2 is
|
|
166
166
|
the agent context (the
|
|
@@ -483,7 +483,7 @@ explorers with count 3 → `explorer (3)`; 5 files
|
|
|
483
483
|
`● myproj +110 -22` (` +` green for added, ` -` red for deleted with a
|
|
484
484
|
leading-space match, zero `·` separators because exactly one heading cell
|
|
485
485
|
is nonempty).
|
|
486
|
-
A review label renders `rdd` with a blue `●` (`#89b4fa`, same as explorer
|
|
486
|
+
A review label renders `rdd` with a blue `●` (`#89b4fa`, same as explorer). A
|
|
487
487
|
`gentle_orchestrating_v1` marker renders the pink `gentle` (machine display
|
|
488
488
|
key `orchestrating`, pink palette unchanged): it covers the principal's
|
|
489
489
|
queued/running subs and pending launches, and it yields to a delegate role
|
|
@@ -579,8 +579,7 @@ display — repairs a missed `error:` label edge, §4.3),
|
|
|
579
579
|
`gentle_roles_v1` (authoritative activity roles,
|
|
580
580
|
oldest-first by immutable firstSeen), `gentle_names_v1` (compat transport only — never
|
|
581
581
|
rendered), `gentle_changes_v2` (normative; a
|
|
582
|
-
v1-only pane renders no change segments, §4.3).
|
|
583
|
-
(`foreground_cwd` ?? `cwd`) feeds the daemon-side pull marker (§5.3).
|
|
582
|
+
v1-only pane renders no change segments, §4.3).
|
|
584
583
|
Foreign `pi_subagents_work_v1` / `state_*` / `title_*` are observed only to
|
|
585
584
|
ignore them under O1 (never parsed for state, never deleted).
|
|
586
585
|
|
|
@@ -706,7 +705,7 @@ cap has lapsed, does it recede to `idle` (§4.3).
|
|
|
706
705
|
`#cba6f7` (distinct from explorer blue, verify teal, orchestrating pink),
|
|
707
706
|
ask orange `#fab387`, blocked red `#f38ba8`, done green `#a6e3a1`,
|
|
708
707
|
idle grey `#7c7f93` (recedes), review blue `#89b4fa` (same as
|
|
709
|
-
explorer
|
|
708
|
+
explorer; internal TaskStore role slug stays `rdd`, machine display
|
|
710
709
|
key stays `review`). Native separators on row 2 are acceptable. The
|
|
711
710
|
`gentle_state_*` / `gentle_agent_*` / `gentle_icon_*` /
|
|
712
711
|
`gentle_row_*` combined names stay published for compatibility but are
|
|
@@ -735,20 +734,17 @@ cap has lapsed, does it recede to `idle` (§4.3).
|
|
|
735
734
|
running delegates and no pending launches; a settled principal with
|
|
736
735
|
running delegates keeps the role word) | `idle`. Role labels append the
|
|
737
736
|
total count when at least two delegates run.
|
|
738
|
-
- Row-2 changes: the nonempty `+N`/`-N
|
|
737
|
+
- Row-2 changes: the nonempty `+N`/`-N` segments ride as their own
|
|
739
738
|
structural row-2 cells after the eleven title cells (each its own color
|
|
740
|
-
cell with no rules — added green, deleted red,
|
|
739
|
+
cell with no rules — added green, deleted red, never
|
|
741
740
|
swapped; empty segments collapse so nothing renders). `+N`/`-N` come
|
|
742
741
|
from fresh `gentle_changes_v2`
|
|
743
|
-
(exact SessionChanges evidence totals, never git status)
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
- Each `+N`/`-N`/`↑N` segment renders only when its total is > 0; each
|
|
750
|
-
rides its own structural row-2 cell (added green, deleted red, pull
|
|
751
|
-
blue, no rules, never swapped; empty segments collapse). `gentle_project`,
|
|
742
|
+
(exact SessionChanges evidence totals, never git status). The row carries
|
|
743
|
+
no ahead/behind marker relative to the branch: only the exact added and
|
|
744
|
+
deleted line counts.
|
|
745
|
+
- Each `+N`/`-N` segment renders only when its total is > 0; each
|
|
746
|
+
rides its own structural row-2 cell (added green, deleted red,
|
|
747
|
+
no rules, never swapped; empty segments collapse). `gentle_project`,
|
|
752
748
|
`gentle_heading_*`, `gentle_agent` (both the single and per-display
|
|
753
749
|
forms), and `gentle_changes_summary` stay published for compatibility
|
|
754
750
|
but render no visible row. The retired
|
|
@@ -756,11 +752,11 @@ cap has lapsed, does it recede to `idle` (§4.3).
|
|
|
756
752
|
badge is never emitted (see the §4.3 versioning rule).
|
|
757
753
|
- Placement: exactly two pi-only rows — row 1 the native `state_icon` +
|
|
758
754
|
`workspace` + `agent` strings (3 cells, no custom wiring, no plugin
|
|
759
|
-
colors), row 2 the eleven `gentle_title_*` state cells plus the
|
|
760
|
-
change-segment cells (
|
|
755
|
+
colors), row 2 the eleven `gentle_title_*` state cells plus the two
|
|
756
|
+
change-segment cells (13 cells: 11 state + 2 changes), each row within
|
|
761
757
|
Herdr's 16-token per-row ceiling — with the
|
|
762
758
|
herdr-pi-tree palette (added green `#a6e3a1`,
|
|
763
|
-
removed red `#f38ba8`,
|
|
759
|
+
removed red `#f38ba8`, working golden `#f9e2af`, ask
|
|
764
760
|
orange `#fab387`, orchestrating pink fuchsia `#f5c2e7`, explorer/rdd blue `#89b4fa` (same color; internal role slug stays `rdd`,
|
|
765
761
|
visible word is `rdd`, machine key stays `review`), judge purple `#cba6f7` (distinct),
|
|
766
762
|
blocked/error red `#f38ba8`,
|
|
@@ -993,10 +989,10 @@ report with a higher seq lands. Parity contract: `working` carries the specific
|
|
|
993
989
|
|
|
994
990
|
The package ships one CLI switch command,
|
|
995
991
|
`node bin/gentle-sidebar.js (enable|disable|status|toggle)` (§7), and one in-Pi
|
|
996
|
-
command, `/herdr-gentle:customize`, with exactly
|
|
997
|
-
sidebar agent rows
|
|
998
|
-
before the `enabled()` pane gate, so
|
|
999
|
-
Pi session outside a Herdr pane. It owns no state of its own and reimplements
|
|
992
|
+
command, `/herdr-gentle:customize`, with exactly three switches: the managed
|
|
993
|
+
sidebar agent rows, the Moshi notification channel and the Herdr theme sync
|
|
994
|
+
(§12). The command registers before the `enabled()` pane gate, so every switch
|
|
995
|
+
stays reachable from a plain Pi session outside a Herdr pane. It owns no state of its own and reimplements
|
|
1000
996
|
nothing:
|
|
1001
997
|
|
|
1002
998
|
- `Sidebar agent rows` drives the Herdr plugin's own `bin/configure.js` —
|
|
@@ -1057,11 +1053,11 @@ exactly one mechanism writes each piece of state.
|
|
|
1057
1053
|
`gentle_orchestrating_v1`, `gentle_principal_v1`, `gentle_done_v1`,
|
|
1058
1054
|
`gentle_ask_v1`, `gentle_review_v1`, `gentle_error_v1`,
|
|
1059
1055
|
`gentle_changes_v2`,
|
|
1060
|
-
`gentle_changes_v1`) and the daemon publishes its
|
|
1056
|
+
`gentle_changes_v1`) and the daemon publishes its 71-token owned family
|
|
1061
1057
|
chunked ≤ 16 per report (row 1 is the 3 native tokens
|
|
1062
1058
|
`state_icon`/`workspace`/`agent`; the legacy 11 `gentle_heading_*` compat
|
|
1063
1059
|
family stays published but wired into no visible row. Row 2 wires 11
|
|
1064
|
-
title +
|
|
1060
|
+
title + 2 change cells = 13 — each within the per-row ceiling). Names are
|
|
1065
1061
|
advisory; roles are authoritative for display and role labels carry the
|
|
1066
1062
|
running total as a suffix when at least two delegates run.
|
|
1067
1063
|
- TTL: `expiry <= now + 60000` at write; readers use `now` at read.
|
|
@@ -1078,8 +1074,8 @@ exactly one mechanism writes each piece of state.
|
|
|
1078
1074
|
(`GENTLE_STATUS_FAST_QUIET_FRAMES`) or a TTL-bounded window
|
|
1079
1075
|
(`GENTLE_STATUS_FAST_WINDOW_MS`), 250 ms floor, single dynamic
|
|
1080
1076
|
`setTimeout` chain. The active-display trigger exists because the row data
|
|
1081
|
-
the daemon
|
|
1082
|
-
|
|
1077
|
+
the daemon refreshes by a frame rather than from a producer report —
|
|
1078
|
+
`agent.list` plus the presence prefix — cannot be driven by a
|
|
1083
1079
|
producer report; only `idle` counts as settled, so an idle pane keeps the
|
|
1084
1080
|
baseline exactly.
|
|
1085
1081
|
Drawing is event-synchronized; polling is only the fallback. Every landed
|
|
@@ -1112,10 +1108,9 @@ exactly one mechanism writes each piece of state.
|
|
|
1112
1108
|
Shutdown closes the socket and its retry timer, and neither keeps the process
|
|
1113
1109
|
alive. Idle cost with no events is exactly today's: an idle subscription is
|
|
1114
1110
|
silent and the loop sleeps as before.
|
|
1115
|
-
What the subscription can never drive stays poll-only: the
|
|
1116
|
-
|
|
1117
|
-
|
|
1118
|
-
because Herdr emits no event for either. That is why the fast cycle is armed
|
|
1111
|
+
What the subscription can never drive stays poll-only: the daemon's own
|
|
1112
|
+
`agent.list` snapshot and the presence prefix, because Herdr emits no event
|
|
1113
|
+
for either. That is why the fast cycle is armed
|
|
1119
1114
|
by a rendered non-idle display, and why polling is never removed.
|
|
1120
1115
|
The sleep is also capped at the nearest live `gentle_done_v1` expiry AND the
|
|
1121
1116
|
nearest pending view-dwell deadline (`DONE_VIEW_DWELL_MS`) among
|
|
@@ -1145,7 +1140,7 @@ exactly one mechanism writes each piece of state.
|
|
|
1145
1140
|
`gentle_heading_*`, `gentle_project`, `gentle_row_*` (each family now
|
|
1146
1141
|
includes the `judge` display alongside the original ten), plus display-only
|
|
1147
1142
|
`gentle_changes_added`, `gentle_changes_deleted`,
|
|
1148
|
-
`
|
|
1143
|
+
`gentle_changes_summary`); no change to `pi_subagents_work_v1`, `state_*`,
|
|
1149
1144
|
`title_*`, or native `working`/`blocked`/`idle` semantics.
|
|
1150
1145
|
`gentle_title_error` keeps its machine-key-derived token name; only its
|
|
1151
1146
|
user-facing value is `blocked` (§5.3). `gentle_title_review` likewise
|
|
@@ -1155,7 +1150,9 @@ exactly one mechanism writes each piece of state.
|
|
|
1155
1150
|
likewise keeps its machine-key-derived token name; its user-facing value is
|
|
1156
1151
|
a non-contemplated subagent's own sanitized name, never the word `working`.
|
|
1157
1152
|
The retired `*_working_subs` token family (the old `working (n)`
|
|
1158
|
-
count display) is swept, never written.
|
|
1153
|
+
count display) is swept, never written. The retired
|
|
1154
|
+
`gentle_changes_pull` name (the removed behind-upstream `↑N` marker) is
|
|
1155
|
+
swept the same way, never written.
|
|
1159
1156
|
- Coexistence: `herdr-pi-tree` stays installed but disabled for gentle-owned
|
|
1160
1157
|
panes (O1). No uninstall, no token migration, no dual-run merge — ownership
|
|
1161
1158
|
handoff is by enable/disable switch, reversible at any time.
|
|
@@ -1164,9 +1161,9 @@ exactly one mechanism writes each piece of state.
|
|
|
1164
1161
|
panel, the ODD and Issues readers, and the `Plugin tools` toggles no longer
|
|
1165
1162
|
ship. This package publishes the Herdr producer sidecar and the Moshi channel
|
|
1166
1163
|
only; `bin/gentle-sidebar.js` is its one CLI and `/herdr-gentle:customize`
|
|
1167
|
-
its one in-Pi command, carrying just the sidebar-rows and
|
|
1168
|
-
Its provider slot `globalThis[Symbol.for("herdr-gentle.customize.v1")]`
|
|
1169
|
-
removed, so no other extension renders those
|
|
1164
|
+
its one in-Pi command, carrying just the sidebar-rows, Moshi and theme-sync
|
|
1165
|
+
switches. Its provider slot `globalThis[Symbol.for("herdr-gentle.customize.v1")]`
|
|
1166
|
+
stays removed, so no other extension renders those switches.
|
|
1170
1167
|
- Rollback: disable this plugin → producer stops writing; consumer sweeps
|
|
1171
1168
|
only `gentle_*` tokens + labels it set (O5); pi-tree re-enable restores
|
|
1172
1169
|
`↳N` behavior with zero data migration.
|
|
@@ -1223,7 +1220,7 @@ exactly one mechanism writes each piece of state.
|
|
|
1223
1220
|
- **U5. Changes badge — RESOLVED (two-row contract):** the `±N` vs `~N`
|
|
1224
1221
|
selection no longer exists — the combined badge is retired in favor of
|
|
1225
1222
|
independent `+N`/`-N` segments from exact `gentle_changes_v2` added/deleted
|
|
1226
|
-
totals, plus the daemon-side
|
|
1223
|
+
totals, plus the daemon-side change cells (§5.3). The producer mirrors
|
|
1227
1224
|
the Gentle Shell `SessionChanges` model semantics over the same transcript
|
|
1228
1225
|
`SESSION_CHANGE_ENTRY` evidence (never git and never an approximate
|
|
1229
1226
|
reaggregation): files keyed by `(root, path)`, evidence-ID dedup,
|
|
@@ -1247,10 +1244,102 @@ confirming each criterion has a normative section:
|
|
|
1247
1244
|
| V1 | Sidebar shows the active TaskStore role with live subagents | §4.2 (role source G3 + `gentle_roles_v1`), §5.2–§5.3 |
|
|
1248
1245
|
| V2 | Sidebar shows `ask` on open question | §4.2 (G4 → `ask:`), §5.2 priority, §7 notify-once |
|
|
1249
1246
|
| V3 | Sidebar shows `review` during native review | §4.2 (review tool lifecycle → `review:`, incl. capture-group parent call), §5.2 priority |
|
|
1250
|
-
| V4 | Change segments render from Gentle session-changes | §4.2/§4.4 (`gentle_changes_v2`), §5.3 `+N`/`-N
|
|
1247
|
+
| V4 | Change segments render from Gentle session-changes | §4.2/§4.4 (`gentle_changes_v2`), §5.3 `+N`/`-N` |
|
|
1251
1248
|
| V5 | No collision with pi-tree `↳N` / `state_*` names | §3 O1/O2/O4, §9 rollback |
|
|
1252
1249
|
| V6 | Stale panes fall back to `idle`, orphans swept on handover | §3 O5, §5.4, §6 |
|
|
1253
1250
|
|
|
1254
1251
|
Task closes when V1–V6 are all traceable above and the file re-read reports
|
|
1255
1252
|
path + line count. Any untraceable cell → `status: partial` with the gap
|
|
1256
1253
|
list, not silent.
|
|
1254
|
+
|
|
1255
|
+
## 12. Theme sync (Pi palette → Herdr theme)
|
|
1256
|
+
|
|
1257
|
+
Herdr's palette follows the theme active in Gentle Shell / Pi, or one theme
|
|
1258
|
+
pinned while the sync is off (S1–S5). The switch lives with the other two in
|
|
1259
|
+
`/herdr-gentle:customize`; the user-facing reference is
|
|
1260
|
+
[docs/theme-sync.md](docs/theme-sync.md). Three modules with three owners, and
|
|
1261
|
+
one direction of data:
|
|
1262
|
+
|
|
1263
|
+
| Module | Package | Owns |
|
|
1264
|
+
|---|---|---|
|
|
1265
|
+
| `lib/theme-store.js` | Pi (`herdr-gentle-shell`) | The one persisted document (`gentle-theme.json`): the state-dir resolution copied verbatim from the sidecar's Moshi flag, a normalised read, and the atomic replace. |
|
|
1266
|
+
| `lib/theme-projection.js` | Pi | The pure translation: assignable Herdr theme names, Herdr token order, `HERDR_ROLE_SOURCES`, `projectPalette`, `paletteFingerprint`, and the `null`/`Off` spelling the panel paints. No filesystem, no host import. |
|
|
1267
|
+
| `herdr-plugin/lib/gentle-theme-config.js` + `bin/configure-theme.js` | Herdr plugin | Everything that touches `config.toml`: payload validation, the managed block, the refusals, the atomic write with its own `.bak`, and the optional reload. |
|
|
1268
|
+
|
|
1269
|
+
Two thin glue layers sit above them and own no state: the follower
|
|
1270
|
+
`extensions/herdr-theme-sync.ts` (tick, fingerprint, one spawn per change,
|
|
1271
|
+
notices) and the switch in `extensions/gentle-herdr-state.ts` plus
|
|
1272
|
+
`lib/customize-panel.js` (`applyThemeSync`, `applyThemeSelection`,
|
|
1273
|
+
`customize status`). Pi colours become hex strings in the follower through
|
|
1274
|
+
`colorToHex` from `@earendil-works/pi-tui`, which is why the follower is its own
|
|
1275
|
+
extension rather than a section of the state sidecar: the sidecar is loaded by
|
|
1276
|
+
every suite as a renamed copy with one stubbed host import, and the projection
|
|
1277
|
+
needs no host at all.
|
|
1278
|
+
|
|
1279
|
+
**The state file is the only persisted truth.** `gentle-theme.json` holds
|
|
1280
|
+
`{sync, theme, updatedAt}` and nothing else is cached, mirrored or inferred: the
|
|
1281
|
+
panel and the follower read the same document, so the row, the switch and the
|
|
1282
|
+
applied palette can never disagree. Missing is inert (`sync:false`,
|
|
1283
|
+
`theme:null`); a document that cannot be read or parsed is a refusal — `ok:false`,
|
|
1284
|
+
painted `Unknown`, follower silent — never a guess, and it is written over only
|
|
1285
|
+
when the user acts. The default install (sync off, no theme) therefore writes
|
|
1286
|
+
nothing at all (S7), while a stored pin is carried across a sync toggle so
|
|
1287
|
+
turning the sync off restores that choice instead of unassigning it.
|
|
1288
|
+
|
|
1289
|
+
**Tick and fingerprint.** The host publishes no theme-change event, so the
|
|
1290
|
+
palette is a pull-read of `ctx.ui.theme` (or `ctx.ui.getTheme(name)` for a pin):
|
|
1291
|
+
one immediate evaluation on `session_start` and then one every 500 ms, on an
|
|
1292
|
+
unreferenced timer so an idle follower never keeps Pi alive. Each evaluation
|
|
1293
|
+
computes two identities — the requested `[sync, chosen]` and the palette
|
|
1294
|
+
fingerprint (`[theme name, sorted token/hex pairs]`) — and acts only when one
|
|
1295
|
+
differs from the last one it recorded, so a theme recoloured in place (same
|
|
1296
|
+
name, new colours) is noticed without a restart, and the same palette is never
|
|
1297
|
+
applied twice. The observation is recorded **before** the spawn, so a failed or
|
|
1298
|
+
refused apply is never retried on the next tick and never blocks the next real
|
|
1299
|
+
change either. One apply is in flight at a time, each spawn is capped at 60 s,
|
|
1300
|
+
and the apply is exactly
|
|
1301
|
+
`<plugin>/bin/configure-theme.js --apply --json --reload` with the projection on
|
|
1302
|
+
stdin. Nothing on shutdown writes, removes or reloads: Herdr keeps the last
|
|
1303
|
+
applied palette (S5). There is deliberately no Herdr pane gate — the config is
|
|
1304
|
+
the user's own and outlives any pane — and no automatic repair of a config the
|
|
1305
|
+
user also edits.
|
|
1306
|
+
|
|
1307
|
+
**Managed block and refusal policy.** The writer owns a second marker-delimited
|
|
1308
|
+
block (`# BEGIN herdr-gentle-theme (managed; do not edit)` …
|
|
1309
|
+
`# END herdr-gentle-theme`) holding `[theme] name = "one-dark"` and a
|
|
1310
|
+
`[theme.custom]` table, in a fixed token order with lower-cased hex, so the same
|
|
1311
|
+
palette is always the same bytes, `current` is a no-op answer, and a refusal can
|
|
1312
|
+
never be mistaken for a change. It reuses `bin/configure.js`'s
|
|
1313
|
+
`herdrConfigPath`/`readConfig`/`writeAtomic`/`removeBlock`/`appendBlock`/
|
|
1314
|
+
`reloadConfig` primitives rather than copying them, so both blocks fail, back up
|
|
1315
|
+
and reload identically — but shares no marker bytes and no backup file, because
|
|
1316
|
+
two writers that share markers each treat the other's block as their own and the
|
|
1317
|
+
last one erases the first. Validation happens before disk: an unknown theme
|
|
1318
|
+
name, an unknown token or a non-`#rrggbb` value is a refusal, not a file Herdr
|
|
1319
|
+
would reject or silently ignore. A `[theme]` or `[theme.custom]` table outside
|
|
1320
|
+
the markers is user config: refuse, never adopt, merge or overwrite. Malformed
|
|
1321
|
+
markers (lone begin, lone end, end before begin, a second pair) refuse instead
|
|
1322
|
+
of guessing where the block ends. `--remove` on an absent block is `absent` and
|
|
1323
|
+
exits 0 even when a foreign table exists, because uninstall must not touch user
|
|
1324
|
+
config. Every refusal guarantees no write, no reload and unchanged config bytes;
|
|
1325
|
+
exit 1 means a stale `--check` or a reload that failed after a successful write.
|
|
1326
|
+
|
|
1327
|
+
**Limits** (the §10 style, none of them a promise this design makes):
|
|
1328
|
+
|
|
1329
|
+
- The 500 ms tick is the whole observation granularity — there is no event to
|
|
1330
|
+
subscribe to, so a theme change is noticed within one tick and not sooner.
|
|
1331
|
+
- The automated evidence is a stubbed Pi host plus a real CLI stand-in on disk;
|
|
1332
|
+
**no live Pi TUI run is recorded**. `ctx.ui.theme`, `getTheme`,
|
|
1333
|
+
`getAllThemes`, `select` and `notify` are used as documented, and a host
|
|
1334
|
+
missing one degrades to "nothing changed" rather than to a guess.
|
|
1335
|
+
- Herdr's surface tokens (`sidebar_bg`, `panel_bg`, `active_row_bg`,
|
|
1336
|
+
`selection_bg`, `surface*`) and `peach` are never written: Pi names
|
|
1337
|
+
foregrounds and accents, not panel backgrounds, so backgrounds and status
|
|
1338
|
+
colours stay with the Herdr base theme.
|
|
1339
|
+
- One machine: another Herdr client reads its own `config.toml`, so this is a
|
|
1340
|
+
local sync and not a fleet setting.
|
|
1341
|
+
- Plugin-root resolution goes through `herdr plugin list --json` and fails
|
|
1342
|
+
closed on zero or ambiguous matches; that refusal is reported once per session
|
|
1343
|
+
and retried silently afterwards.
|
|
1344
|
+
- The CLI requires Node 18 or newer; an older runtime exits 1 before reading
|
|
1345
|
+
anything.
|
package/README.md
CHANGED
|
@@ -40,9 +40,9 @@ nested `codemode` call, which starts while a sibling dialog is still awaited) or
|
|
|
40
40
|
assistant message arriving while it is open — never counts either, so a Gentle Shell command
|
|
41
41
|
menu opened mid-work leaves the row on the agent's real activity), and
|
|
42
42
|
permission waiting; `gentle_review` starts never speculate ask, amber/orange `?`), `blocked`, `done`, `idle`) plus compact
|
|
43
|
-
changes segments
|
|
43
|
+
changes segments (nonempty ` +N`/` -N`
|
|
44
44
|
with leading spaces, symbols color-distinguished by `contains` rules: ` +` green for added,
|
|
45
|
-
` -` red for deleted
|
|
45
|
+
` -` red for deleted — added stays green, deleted stays red),
|
|
46
46
|
reduced from `gentle_*`
|
|
47
47
|
pane-metadata tokens. It coexists with `herdr-pi-tree` through a single-writer handoff: while
|
|
48
48
|
this plugin owns a pane, `herdr-pi-tree` stays disabled for that pane, so the
|
|
@@ -206,11 +206,11 @@ the native `state_icon`, is Herdr-native and not plugin-controlled); row 2
|
|
|
206
206
|
wires the eleven presence-encoded `gentle_title_*` state cells (state word
|
|
207
207
|
only, one current title per frame, each in its state's semantic color as
|
|
208
208
|
base fg with no rules; role words carry a running-count suffix above one)
|
|
209
|
-
followed by the
|
|
210
|
-
change-segment tokens (added green `+N`, deleted red `-N`,
|
|
209
|
+
followed by the two
|
|
210
|
+
change-segment tokens (added green `+N`, deleted red `-N`,
|
|
211
211
|
each its own color cell with no rules, never swapped). The review leg
|
|
212
212
|
renders the user-facing word `rdd` in blue `#89b4fa` (same as
|
|
213
|
-
explorer
|
|
213
|
+
explorer; internal TaskStore role slug stays `rdd`, machine display key
|
|
214
214
|
and token names stay `review` — review execution is silent, never a
|
|
215
215
|
notification; only an actual waiting prompt renders `ask` (desktop attention
|
|
216
216
|
is Herdr's native `blocked` toast); the judge delegate role renders `judge` in
|
|
@@ -234,8 +234,8 @@ for compatibility but are wired into no visible row.
|
|
|
234
234
|
Only one `gentle_title_*` token carries a value per frame (presence
|
|
235
235
|
encoding), so row 2 shows the current state word plus any nonempty change
|
|
236
236
|
segments while the rest render empty; native separators on row 2 are
|
|
237
|
-
acceptable. Row 1 holds 3 native cells and row 2 holds
|
|
238
|
-
+
|
|
237
|
+
acceptable. Row 1 holds 3 native cells and row 2 holds 13 cells (11 state
|
|
238
|
+
+ 2 changes), each within Herdr's 16-token per-row ceiling (full block below).
|
|
239
239
|
The `gs` label of an isolated Gentle Shell pane needs no key here: `gs` is not
|
|
240
240
|
one of Herdr's canonical agents, so `rows_by_agent.gs` is a configuration error
|
|
241
241
|
rather than an inert key. Only the daemon's label ladder (DESIGN.md §5.5)
|
|
@@ -247,7 +247,7 @@ makes that row appear, and `rows_by_agent` stays keyed by the canonical `pi`.
|
|
|
247
247
|
# row 1 native state_icon + workspace + agent, row 2 state word + changes.
|
|
248
248
|
# The parent [ui.sidebar.agents] table is user-owned and never touched here.
|
|
249
249
|
[ui.sidebar.agents.rows_by_agent]
|
|
250
|
-
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" }
|
|
250
|
+
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" }]]
|
|
251
251
|
# END herdr-gentle-agents
|
|
252
252
|
```
|
|
253
253
|
|
|
@@ -255,11 +255,11 @@ The
|
|
|
255
255
|
single row-1 heading cell mirrors the Gentle Shell SessionChanges model semantics
|
|
256
256
|
(write/edit tool outcomes, never `git status`, never an approximate
|
|
257
257
|
reaggregation): files keyed by `(root, path)` with snapshot-continuity and
|
|
258
|
-
unavailable counts (unavailable files stay in the file count with 0/0)
|
|
259
|
-
branch is behind its upstream (branch-ab status only, no diff). `gentle_project`,
|
|
258
|
+
unavailable counts (unavailable files stay in the file count with 0/0). `gentle_project`,
|
|
260
259
|
`gentle_changes_summary`, and the segment
|
|
261
|
-
tokens (`gentle_changes_added`/`_deleted
|
|
262
|
-
compatibility but render no visible row.
|
|
260
|
+
tokens (`gentle_changes_added`/`_deleted`) stay published for
|
|
261
|
+
compatibility but render no visible row. The changes row carries no
|
|
262
|
+
ahead/behind marker relative to the branch. Pink `gentle` (machine key
|
|
263
263
|
`orchestrating`, pink palette unchanged) is the
|
|
264
264
|
only user-facing `gentle`: it renders while the principal session actively
|
|
265
265
|
works — even with zero subagents, with or without a fresh root marker — and
|
|
@@ -357,7 +357,7 @@ role word such as `worker`, `explorer`,
|
|
|
357
357
|
once the principal itself is idle — and also while a
|
|
358
358
|
task-mode subagent call blocks the principal's turn, until it returns), that
|
|
359
359
|
a row never reads `gentle` on an idle pane; row 1
|
|
360
|
-
shows the single heading cell (`● <project>` plus ` +N`/` -N
|
|
360
|
+
shows the single heading cell (`● <project>` plus ` +N`/` -N` inline, zero `·`) after edits; then `ask` on an open
|
|
361
361
|
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; neither does a span the agent proves it is not waiting on, since a run blocked on its own dialog cannot start a new top-level tool execution (a nested `codemode` call proves nothing: it starts while a sibling dialog is still awaited) or finish an assistant message, so a Gentle Shell command menu opened mid-work keeps the row on the agent's real activity), or permission waiting; `gentle_review` starts never speculate ask, and no failed tool ever does either: a tool error changes nothing, see the error rule below). `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
|
|
362
362
|
`HERDR_CONFIG_PATH` on a temp file for apply/uninstall checks.
|
|
363
363
|
|
|
@@ -400,7 +400,7 @@ producer's own beat is 15 s by default and
|
|
|
400
400
|
TTL. Reports in one window collapse into one frame, and refresh-driven frames
|
|
401
401
|
are floored at 250 ms, so a burst can never spin the daemon. Polling stays the
|
|
402
402
|
fallback for every lifecycle signal and the only source for what no Herdr event
|
|
403
|
-
carries (the
|
|
403
|
+
carries (the presence prefix), so a
|
|
404
404
|
missed, undelivered, or rejected event never sticks. Read-only
|
|
405
405
|
supervision triage ships beside it: the `doctor` and `whois` plugin actions
|
|
406
406
|
(`node bin/gentle-doctor.js`, `node bin/gentle-whois.js`) plus the explicit-pane
|
|
@@ -440,13 +440,14 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
440
440
|
NeedsAttention toast and sound, so the sidebar carries the error on the
|
|
441
441
|
durable `gentle_error_v1` token while the pane stays quiet on `working`,
|
|
442
442
|
and no phone envelope is sent).
|
|
443
|
-
- Single-cell row-1 heading (`<icon> <project>` plus ` +N`/` -N
|
|
443
|
+
- Single-cell row-1 heading (`<icon> <project>` plus ` +N`/` -N`
|
|
444
444
|
inline, exactly one nonempty cell so zero `·` separators; white base with
|
|
445
445
|
`contains` rules keeping ` +` green (added), ` -` red (deleted,
|
|
446
|
-
leading-space match)
|
|
446
|
+
leading-space match)) mirroring the Gentle Shell
|
|
447
447
|
SessionChanges model semantics over Gentle tool outcomes, never `git`
|
|
448
448
|
status and never an approximate reaggregation (root+path continuity and
|
|
449
|
-
unavailable counts)
|
|
449
|
+
unavailable counts). The changes row carries no ahead/behind marker
|
|
450
|
+
relative to the branch.
|
|
450
451
|
Session-change tokens are refreshed/cleared from the current Gentle Shell
|
|
451
452
|
session model and never carried across sessions.
|
|
452
453
|
- Single-writer coexistence with `herdr-pi-tree`: no shared token names, no
|
|
@@ -483,10 +484,11 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
483
484
|
managed Herdr rows and records the owned native-extension exclusion;
|
|
484
485
|
`disable` removes only our owned rows and exclusion, never a user table.
|
|
485
486
|
See [docs/sidebar-control.md](docs/sidebar-control.md).
|
|
486
|
-
- In-Pi switches (`/herdr-gentle:customize`):
|
|
487
|
-
state and
|
|
487
|
+
- In-Pi switches (`/herdr-gentle:customize`): three switches, all local
|
|
488
|
+
state and all reachable from a plain Pi session outside a Herdr pane. With
|
|
488
489
|
no argument the command opens the floating panel in Gentle Shell's own
|
|
489
|
-
layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications
|
|
490
|
+
layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications`,
|
|
491
|
+
`Herdr Theme`)
|
|
490
492
|
and one right pane headed `<Category> · n/m` with its setting rows, each row
|
|
491
493
|
painting the stored value with `●` and the other with `○`; one line above the
|
|
492
494
|
footer describes the focused setting (`<setting> — <what it changes>`), and
|
|
@@ -498,11 +500,14 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
498
500
|
it is a key the panel answers to, and a narrow card compacts it instead of
|
|
499
501
|
wrapping. Pointer input still works without being advertised — a click on a
|
|
500
502
|
category selects it, a click on a row applies it, and a click outside the
|
|
501
|
-
panes is ignored. Each category owns
|
|
503
|
+
panes is ignored. Each category owns its own rows: `Herdr Sidebar`
|
|
502
504
|
shows the single `Sidebar agent rows` row, and the only Moshi switch is the
|
|
503
|
-
`Notifications` row under `Moshi notifications
|
|
504
|
-
|
|
505
|
-
|
|
505
|
+
`Notifications` row under `Moshi notifications`, while `Herdr Theme` owns
|
|
506
|
+
both theme rows (the `Theme sync` toggle and the non-toggle
|
|
507
|
+
`Gentle Shell theme` value row described in the subsection below). The
|
|
508
|
+
sidebar and Moshi switches are never mixed — `Sidebar agent rows` neither
|
|
509
|
+
reads nor writes `gentle-moshi.json`, so turning the agent rows off never
|
|
510
|
+
turns the notification channel off. Herdr's own
|
|
506
511
|
done/ask attention (the finished and needs-attention pop-ups and their
|
|
507
512
|
sound) is Herdr's native behavior, configured in Herdr itself — its config
|
|
508
513
|
and its settings — and this package deliberately offers no switch for it:
|
|
@@ -517,7 +522,8 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
517
522
|
`settings.json`, running the `moshi-hook` pairing gate before enabling (a
|
|
518
523
|
refusal writes nothing) and reloading Pi only when that settings entry
|
|
519
524
|
actually changed. `/herdr-gentle:customize status` prints one read-only line
|
|
520
|
-
(`customize status: sidebar=<on|off|unknown> moshi=<on|off
|
|
525
|
+
(`customize status: sidebar=<on|off|unknown> moshi=<on|off>
|
|
526
|
+
theme-sync=<on|off|unknown> theme=<name|none|unknown>`); an unknown
|
|
521
527
|
argument, Esc, or a cancelled menu writes nothing. A sidebar verdict of
|
|
522
528
|
`unknown` is never a refusal: the panel says the state is unknown and
|
|
523
529
|
choosing `On` still runs the apply step, reporting that step's own error
|
|
@@ -587,6 +593,22 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
587
593
|
reached through `/herdr-gentle:customize`. See
|
|
588
594
|
[docs/herdr-session-open.md](docs/herdr-session-open.md).
|
|
589
595
|
|
|
596
|
+
### Theme sync (Herdr palette follows Pi)
|
|
597
|
+
|
|
598
|
+
`/herdr-gentle:customize` → `Herdr Theme` is one switch and one pinned value.
|
|
599
|
+
`Theme sync` is **OFF by default**: while it is on, Herdr's palette is the
|
|
600
|
+
palette of the theme Pi is showing, and it follows a theme change while Pi keeps
|
|
601
|
+
running. While it is off, `Gentle Shell theme` assigns one Gentle Shell / Pi
|
|
602
|
+
theme by name and the picker's `Off (no theme assigned)` entry clears the pin; the row is refused while the sync is on
|
|
603
|
+
(`Turn Theme sync off to pick a specific theme.`). Turning the sync off writes
|
|
604
|
+
nothing to Herdr, so **Herdr keeps the last applied palette** — a fresh install
|
|
605
|
+
whose sync is off and whose theme is unassigned writes nothing at all. State is
|
|
606
|
+
one file, `gentle-theme.json`, beside `gentle-moshi.json`; the palette reaches
|
|
607
|
+
Herdr through the plugin's own `bin/configure-theme.js`, which owns a marked
|
|
608
|
+
`[theme]` block and refuses to touch a `[theme]` table you maintain yourself.
|
|
609
|
+
See [docs/theme-sync.md](docs/theme-sync.md) for the projection, the CLI and
|
|
610
|
+
the limits.
|
|
611
|
+
|
|
590
612
|
## Documentation
|
|
591
613
|
|
|
592
614
|
| Your task | Start here |
|
|
@@ -597,6 +619,7 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
597
619
|
| Supervision triage (read-only doctor/trace/whois) | [docs/diagnostics.md](docs/diagnostics.md) |
|
|
598
620
|
| Lifecycle recovery and interruption (polling fallback) | [docs/supervision.md](docs/supervision.md) |
|
|
599
621
|
| Sidebar switch (`bin/gentle-sidebar.js`) | [docs/sidebar-control.md](docs/sidebar-control.md) |
|
|
622
|
+
| Theme sync (Pi palette → Herdr theme) | [docs/theme-sync.md](docs/theme-sync.md) |
|
|
600
623
|
| Herdr session opener (`herdr_session_open`) | [docs/herdr-session-open.md](docs/herdr-session-open.md) |
|
|
601
624
|
| Performance trace and its report | [docs/performance-trace.md](docs/performance-trace.md) |
|
|
602
625
|
|