herdr-gentle-shell 1.6.1 → 1.7.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 +32 -35
- package/README.md +23 -19
- package/extensions/gentle-herdr-state.ts +75 -4
- package/package.json +1 -1
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
|
|
@@ -208,7 +208,7 @@ Sidecar only: ships beside `herdr-agent-state.ts`, never modifies it.
|
|
|
208
208
|
|---|---|---|
|
|
209
209
|
| `agent_start` / `isIdle=false` (main actively working, incl. 0 active subs) | `gentle_work_v1=<hash>:0:<exp>` + `gentle_principal_v1=<hash>:<exp>` (principal-only activity marker) + `gentle_orchestrating_v1=<hash>:<exp>` (root marker while main actively works) + clear `herdr:blocked` labels | the pink `gentle` (machine key `orchestrating`, with or without a fresh root marker) while the principal session actively works, even with zero subagents |
|
|
210
210
|
| TaskStore `running` non-empty (G3; queued/waiting never execute) | `gentle_work_v1=<hash>:<count>:<exp>` (total delegates — snapshot-confirmed running records plus distinct in-flight `subagent_run`/`subagent_continue` calls, §4.2 — never a principal-working signal) + `gentle_roles_v1=<csv>` (roles from `TaskRecord.agent`, authoritative, oldest-first) + `gentle_names_v1=<csv>` (compat transport only, never rendered) + `gentle_orchestrating_v1=<hash>:<exp>` (root-only marker, §4.3) | the oldest running role word (known short word or unknown sanitized name) whenever the principal itself is not working; a working principal reads `gentle` instead; role labels show the total when two or more delegates run |
|
|
211
|
-
| `ASK_USER_CHOICE_BLOCKED_EVENT` / `gentle-pi:ask-user-choice:blocked` (G4), incl. questionnaire + tool-gated `ui_prompt` dialog spans (`kind` other than `custom` — a panel or overlay such as the agents view, ODD viewer, changes view or design canvas never counts, because opening a panel is navigation, not a question), plus direct Pi in-process `tool_execution_start` opens / `tool_execution_end` / `tool_result` closes for the exact tools `ask_user_question` and `ask_user_choice`, tracked by `toolCallId` in a call-id set (a `tool_call` proposal alone never opens; an abort/error end with no result still closes; overlapping calls correct; cleared on result/end/reset/shutdown; event legs and error > ask > review precedence unchanged; boundary: only what Pi emits as execution events is observable — a host ask UI that never emits one stays covered by the event legs only). `gentle_review` starts (any operation) never enter ask: the former consent-eligible pending signal fired before any outcome/UI and falsely blocked pre-granted sessions | `herdr:blocked` label `ask:<intentId>` + durable `gentle_ask_v1=<hash>:<intentId>:<exp>` on every beat while ask is active (null/clear when inactive — repairs a missed label edge; §4.3) | `ask` (existing machine key, user-facing `ask`, amber/orange, native `?`) |
|
|
211
|
+
| `ASK_USER_CHOICE_BLOCKED_EVENT` / `gentle-pi:ask-user-choice:blocked` (G4), incl. questionnaire + tool-gated `ui_prompt` dialog spans (`kind` other than `custom` — a panel or overlay such as the agents view, ODD viewer, changes view or design canvas never counts, because opening a panel is navigation, not a question; and a prompt span the agent proves it is not waiting on never counts either — a top-level `tool_execution_start` (never a nested `codemode` call, which starts while a sibling dialog is still awaited) or an assistant `message_end` while the span is open withdraws it until `ui_prompt_end`, because a run genuinely blocked on its own dialog cannot also start new top-level executions or finish assistant messages, while a slash-command option menu such as `/rdd`, the `/warp` list or the `customize` fallback renders through `ctx.ui.select` and keeps the agent working; the host gives no origin signal, so entry stays immediate and only those two signals withdraw, never `tool_execution_update` — live background jobs emit it while a real ask may be open), plus direct Pi in-process `tool_execution_start` opens / `tool_execution_end` / `tool_result` closes for the exact tools `ask_user_question` and `ask_user_choice`, tracked by `toolCallId` in a call-id set (a `tool_call` proposal alone never opens; an abort/error end with no result still closes; overlapping calls correct; cleared on result/end/reset/shutdown; event legs and error > ask > review precedence unchanged; boundary: only what Pi emits as execution events is observable — a host ask UI that never emits one stays covered by the event legs only). `gentle_review` starts (any operation) never enter ask: the former consent-eligible pending signal fired before any outcome/UI and falsely blocked pre-granted sessions | `herdr:blocked` label `ask:<intentId>` + durable `gentle_ask_v1=<hash>:<intentId>:<exp>` on every beat while ask is active (null/clear when inactive — repairs a missed label edge; §4.3) | `ask` (existing machine key, user-facing `ask`, amber/orange, native `?`) |
|
|
212
212
|
| Pi in-process `tool_execution_start` opens / `tool_execution_end` / `tool_result` closes (by `toolCallId`; a `tool_call` proposal alone never opens) for the exact tools `gentle_review_capture`, `gentle_review_capture_group` with `reviewerRunAcknowledged: true` in the runtime args; `correctionLines` (native planning, never a reviewer), forecast-only calls, `gentle_review` (any operation), `gentle_review_scope`, and all sidebar/hook signals never enter — unknown legacy shapes stay dark (conservative) | `herdr:blocked` label `review:<reviewId>` | `review` (machine key `review`) — during a capture-group run the single parent capture-group call stays in flight across the whole multi-reviewer span, so that one call alone holds the label. Bounded approximation: the acknowledged capture interval contains preparation and admission; no exact reviewer internal events exist today |
|
|
213
213
|
| the agent run itself stops on an error (an assistant message whose `stopReason` is `error` — the same signal Pi derives `turn_end.outcome === "error"` from) | durable `gentle_error_v1=<hash>:run-failed:<exp>` on every beat while the leg stands (null/clear the beat it releases, §4.3) + `herdr:blocked` label `error:run-failed`; no native state is derived from it (the pane stays on its lifecycle state — `working` — while the leg stands, so the host raises no NeedsAttention toast or sound) | `error` (row word `blocked`) — never a native `blocked` |
|
|
214
214
|
| a tool call fails, a delegate record ends `failed`, or a beat transport fails | nothing — detection only (a counter and a debug line under `GENTLE_HERDR_DEBUG=1`) | nothing: no label, no native state, no finish hold, no notification |
|
|
@@ -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`,
|
|
@@ -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.
|
|
@@ -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,7 +1244,7 @@ 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
|
|
package/README.md
CHANGED
|
@@ -35,11 +35,14 @@ display untouched),
|
|
|
35
35
|
executed `ask_user_question`/`ask_user_choice` tool calls (execution opens, end/result closes;
|
|
36
36
|
proposals never block), tool-gated `ui_prompt` dialog spans (a `custom` panel — agents view, ODD
|
|
37
37
|
viewer, changes view, design canvas — never counts: opening a panel is navigation, not a
|
|
38
|
-
question
|
|
38
|
+
question; a span the agent proves it is not waiting on — a new top-level tool execution (never a
|
|
39
|
+
nested `codemode` call, which starts while a sibling dialog is still awaited) or a finished
|
|
40
|
+
assistant message arriving while it is open — never counts either, so a Gentle Shell command
|
|
41
|
+
menu opened mid-work leaves the row on the agent's real activity), and
|
|
39
42
|
permission waiting; `gentle_review` starts never speculate ask, amber/orange `?`), `blocked`, `done`, `idle`) plus compact
|
|
40
|
-
changes segments
|
|
43
|
+
changes segments (nonempty ` +N`/` -N`
|
|
41
44
|
with leading spaces, symbols color-distinguished by `contains` rules: ` +` green for added,
|
|
42
|
-
` -` red for deleted
|
|
45
|
+
` -` red for deleted — added stays green, deleted stays red),
|
|
43
46
|
reduced from `gentle_*`
|
|
44
47
|
pane-metadata tokens. It coexists with `herdr-pi-tree` through a single-writer handoff: while
|
|
45
48
|
this plugin owns a pane, `herdr-pi-tree` stays disabled for that pane, so the
|
|
@@ -203,11 +206,11 @@ the native `state_icon`, is Herdr-native and not plugin-controlled); row 2
|
|
|
203
206
|
wires the eleven presence-encoded `gentle_title_*` state cells (state word
|
|
204
207
|
only, one current title per frame, each in its state's semantic color as
|
|
205
208
|
base fg with no rules; role words carry a running-count suffix above one)
|
|
206
|
-
followed by the
|
|
207
|
-
change-segment tokens (added green `+N`, deleted red `-N`,
|
|
209
|
+
followed by the two
|
|
210
|
+
change-segment tokens (added green `+N`, deleted red `-N`,
|
|
208
211
|
each its own color cell with no rules, never swapped). The review leg
|
|
209
212
|
renders the user-facing word `rdd` in blue `#89b4fa` (same as
|
|
210
|
-
explorer
|
|
213
|
+
explorer; internal TaskStore role slug stays `rdd`, machine display key
|
|
211
214
|
and token names stay `review` — review execution is silent, never a
|
|
212
215
|
notification; only an actual waiting prompt renders `ask` (desktop attention
|
|
213
216
|
is Herdr's native `blocked` toast); the judge delegate role renders `judge` in
|
|
@@ -231,8 +234,8 @@ for compatibility but are wired into no visible row.
|
|
|
231
234
|
Only one `gentle_title_*` token carries a value per frame (presence
|
|
232
235
|
encoding), so row 2 shows the current state word plus any nonempty change
|
|
233
236
|
segments while the rest render empty; native separators on row 2 are
|
|
234
|
-
acceptable. Row 1 holds 3 native cells and row 2 holds
|
|
235
|
-
+
|
|
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).
|
|
236
239
|
The `gs` label of an isolated Gentle Shell pane needs no key here: `gs` is not
|
|
237
240
|
one of Herdr's canonical agents, so `rows_by_agent.gs` is a configuration error
|
|
238
241
|
rather than an inert key. Only the daemon's label ladder (DESIGN.md §5.5)
|
|
@@ -244,7 +247,7 @@ makes that row appear, and `rows_by_agent` stays keyed by the canonical `pi`.
|
|
|
244
247
|
# row 1 native state_icon + workspace + agent, row 2 state word + changes.
|
|
245
248
|
# The parent [ui.sidebar.agents] table is user-owned and never touched here.
|
|
246
249
|
[ui.sidebar.agents.rows_by_agent]
|
|
247
|
-
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" }]]
|
|
248
251
|
# END herdr-gentle-agents
|
|
249
252
|
```
|
|
250
253
|
|
|
@@ -252,11 +255,11 @@ The
|
|
|
252
255
|
single row-1 heading cell mirrors the Gentle Shell SessionChanges model semantics
|
|
253
256
|
(write/edit tool outcomes, never `git status`, never an approximate
|
|
254
257
|
reaggregation): files keyed by `(root, path)` with snapshot-continuity and
|
|
255
|
-
unavailable counts (unavailable files stay in the file count with 0/0)
|
|
256
|
-
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`,
|
|
257
259
|
`gentle_changes_summary`, and the segment
|
|
258
|
-
tokens (`gentle_changes_added`/`_deleted
|
|
259
|
-
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
|
|
260
263
|
`orchestrating`, pink palette unchanged) is the
|
|
261
264
|
only user-facing `gentle`: it renders while the principal session actively
|
|
262
265
|
works — even with zero subagents, with or without a fresh root marker — and
|
|
@@ -354,8 +357,8 @@ role word such as `worker`, `explorer`,
|
|
|
354
357
|
once the principal itself is idle — and also while a
|
|
355
358
|
task-mode subagent call blocks the principal's turn, until it returns), that
|
|
356
359
|
a row never reads `gentle` on an idle pane; row 1
|
|
357
|
-
shows the single heading cell (`● <project>` plus ` +N`/` -N
|
|
358
|
-
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 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
|
|
360
|
+
shows the single heading cell (`● <project>` plus ` +N`/` -N` inline, zero `·`) after edits; then `ask` on an open
|
|
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
|
|
359
362
|
`HERDR_CONFIG_PATH` on a temp file for apply/uninstall checks.
|
|
360
363
|
|
|
361
364
|
## Core Workflow
|
|
@@ -397,7 +400,7 @@ producer's own beat is 15 s by default and
|
|
|
397
400
|
TTL. Reports in one window collapse into one frame, and refresh-driven frames
|
|
398
401
|
are floored at 250 ms, so a burst can never spin the daemon. Polling stays the
|
|
399
402
|
fallback for every lifecycle signal and the only source for what no Herdr event
|
|
400
|
-
carries (the
|
|
403
|
+
carries (the presence prefix), so a
|
|
401
404
|
missed, undelivered, or rejected event never sticks. Read-only
|
|
402
405
|
supervision triage ships beside it: the `doctor` and `whois` plugin actions
|
|
403
406
|
(`node bin/gentle-doctor.js`, `node bin/gentle-whois.js`) plus the explicit-pane
|
|
@@ -437,13 +440,14 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
437
440
|
NeedsAttention toast and sound, so the sidebar carries the error on the
|
|
438
441
|
durable `gentle_error_v1` token while the pane stays quiet on `working`,
|
|
439
442
|
and no phone envelope is sent).
|
|
440
|
-
- Single-cell row-1 heading (`<icon> <project>` plus ` +N`/` -N
|
|
443
|
+
- Single-cell row-1 heading (`<icon> <project>` plus ` +N`/` -N`
|
|
441
444
|
inline, exactly one nonempty cell so zero `·` separators; white base with
|
|
442
445
|
`contains` rules keeping ` +` green (added), ` -` red (deleted,
|
|
443
|
-
leading-space match)
|
|
446
|
+
leading-space match)) mirroring the Gentle Shell
|
|
444
447
|
SessionChanges model semantics over Gentle tool outcomes, never `git`
|
|
445
448
|
status and never an approximate reaggregation (root+path continuity and
|
|
446
|
-
unavailable counts)
|
|
449
|
+
unavailable counts). The changes row carries no ahead/behind marker
|
|
450
|
+
relative to the branch.
|
|
447
451
|
Session-change tokens are refreshed/cleared from the current Gentle Shell
|
|
448
452
|
session model and never carried across sessions.
|
|
449
453
|
- Single-writer coexistence with `herdr-pi-tree`: no shared token names, no
|
|
@@ -179,7 +179,21 @@
|
|
|
179
179
|
// ask only when it opens while at least one tool
|
|
180
180
|
// execution is active, so commands/widgets that prompt
|
|
181
181
|
// while idle never become ask; nested/duplicate
|
|
182
|
-
// lifecycle coalesces into one boolean leg.
|
|
182
|
+
// lifecycle coalesces into one boolean leg. A command
|
|
183
|
+
// menu (`/rdd`, `/warp` list, the `customize` fallback)
|
|
184
|
+
// renders through `ctx.ui.select` -> `kind: "select"`,
|
|
185
|
+
// the same kind a real question uses, and the host
|
|
186
|
+
// gives no origin signal — so the span withdraws the
|
|
187
|
+
// moment the agent proves it was never waiting on it:
|
|
188
|
+
// a top-level `tool_execution_start` (never a nested
|
|
189
|
+
// `codemode` call, which starts while a sibling dialog
|
|
190
|
+
// is still awaited) or an assistant-role `message_end`
|
|
191
|
+
// while the span is open, and only then
|
|
192
|
+
// (`tool_execution_update` never withdraws: live
|
|
193
|
+
// background jobs emit it while a real ask may be
|
|
194
|
+
// open). Entry stays immediate so a real ask is never
|
|
195
|
+
// missed; `ui_prompt_end` clears both flags, so the
|
|
196
|
+
// next span starts fresh.
|
|
183
197
|
// Boundary: this leg observes only what Pi emits as a
|
|
184
198
|
// `tool_execution_start` event in this root extension.
|
|
185
199
|
// A host-side ask UI that emits no execution for those names
|
|
@@ -2799,8 +2813,26 @@ export default function (pi) {
|
|
|
2799
2813
|
// and a false ask on every panel open is worse than missing one dialog.
|
|
2800
2814
|
// Nested or duplicate prompt lifecycle coalesces into one boolean leg,
|
|
2801
2815
|
// cleared on the matching `ui_prompt_end`, session reset, and shutdown.
|
|
2816
|
+
// Withdrawal (odd/tasks/ui-prompt-ask-origin): the host emits no origin
|
|
2817
|
+
// signal, so a Gentle Shell slash command rendering its option menu through
|
|
2818
|
+
// `ctx.ui.select` (`/rdd`, `/warp` list, the `customize` fallback — all
|
|
2819
|
+
// `kind: "select"`) is indistinguishable from a real question at entry.
|
|
2820
|
+
// Entry therefore stays immediate (a real ask is never missed), and the leg
|
|
2821
|
+
// withdraws on the asymmetry a run genuinely blocked on its own dialog
|
|
2822
|
+
// cannot produce: starting new TOP-LEVEL tool executions, or finishing
|
|
2823
|
+
// assistant messages. A top-level `tool_execution_start` or an
|
|
2824
|
+
// assistant-role `message_end` proves the span was never waited on, so
|
|
2825
|
+
// `uiPromptWithdrawn` stands for the rest of that span and only
|
|
2826
|
+
// `ui_prompt_end` clears it. A nested call (`parentToolCallId`) never
|
|
2827
|
+
// withdraws: codemode's `ctx.executeTool` starts a sibling execution while
|
|
2828
|
+
// another tool's dialog is still awaited, so it proves nothing.
|
|
2829
|
+
// `tool_execution_update` never withdraws: live
|
|
2830
|
+
// background jobs (`bash_background` / `monitor`) emit updates while a real
|
|
2831
|
+
// ask may legitimately be open. The rule keys on signals only — no
|
|
2832
|
+
// command-name list and no title matching.
|
|
2802
2833
|
const runningTools = new Set(); // toolCallId -> in-flight tool execution
|
|
2803
2834
|
let uiPromptActive = false;
|
|
2835
|
+
let uiPromptWithdrawn = false;
|
|
2804
2836
|
let askIntentId;
|
|
2805
2837
|
let askCounter = 0;
|
|
2806
2838
|
|
|
@@ -3258,6 +3290,13 @@ export default function (pi) {
|
|
|
3258
3290
|
} catch { /* best effort: a failure here is non-fatal */ }
|
|
3259
3291
|
}
|
|
3260
3292
|
|
|
3293
|
+
// A generic UI prompt span contributes to ask only until the agent proves
|
|
3294
|
+
// it is not waiting on it (see the withdrawal rule next to
|
|
3295
|
+
// `uiPromptWithdrawn`); every other leg below is untouched.
|
|
3296
|
+
function uiPromptAskActive() {
|
|
3297
|
+
return uiPromptActive && !uiPromptWithdrawn;
|
|
3298
|
+
}
|
|
3299
|
+
|
|
3261
3300
|
function askActiveNow() {
|
|
3262
3301
|
return (
|
|
3263
3302
|
choiceActive ||
|
|
@@ -3265,10 +3304,22 @@ export default function (pi) {
|
|
|
3265
3304
|
questionnaireActive ||
|
|
3266
3305
|
permissionPending.size > 0 ||
|
|
3267
3306
|
askToolCalls.size > 0 ||
|
|
3268
|
-
|
|
3307
|
+
uiPromptAskActive()
|
|
3269
3308
|
);
|
|
3270
3309
|
}
|
|
3271
3310
|
|
|
3311
|
+
// Withdrawal of the generic prompt leg (odd/tasks/ui-prompt-ask-origin):
|
|
3312
|
+
// called from the two signals that prove the run was never blocked on the
|
|
3313
|
+
// open span — a new top-level tool execution and a finished assistant
|
|
3314
|
+
// message. The span stops contributing to ask and to the beat until
|
|
3315
|
+
// `ui_prompt_end`.
|
|
3316
|
+
function withdrawUiPromptAsk() {
|
|
3317
|
+
if (!uiPromptAskActive()) return;
|
|
3318
|
+
uiPromptWithdrawn = true;
|
|
3319
|
+
updateBlocker();
|
|
3320
|
+
schedulePublish();
|
|
3321
|
+
}
|
|
3322
|
+
|
|
3272
3323
|
function desiredLabel() {
|
|
3273
3324
|
if (errorCode) return `error:${errorCode}`;
|
|
3274
3325
|
if (askActiveNow()) return `ask:${askIntentId}`;
|
|
@@ -3814,7 +3865,9 @@ export default function (pi) {
|
|
|
3814
3865
|
// task-mode role publishes even while the authoritative count is 0.
|
|
3815
3866
|
// A pending ask tool call likewise keeps the beat alive so `ask:`
|
|
3816
3867
|
// publishes while the call is in flight; the generic UI prompt leg
|
|
3817
|
-
// holds the beat the same way while its span is open
|
|
3868
|
+
// holds the beat the same way while its span is open and has not been
|
|
3869
|
+
// withdrawn (a withdrawn span proves the agent is working, so the
|
|
3870
|
+
// ordinary activity legs keep the beat). Effective
|
|
3818
3871
|
// review (executing acknowledged capture/group calls) keeps the beat
|
|
3819
3872
|
// alive so `review:` and the durable review token publish — NO GRACE:
|
|
3820
3873
|
// the leg drops when the last execution ends or resolves. A live
|
|
@@ -3827,7 +3880,7 @@ export default function (pi) {
|
|
|
3827
3880
|
pendingCalls.size > 0 ||
|
|
3828
3881
|
freshRunningJobCount() > 0 ||
|
|
3829
3882
|
askToolCalls.size > 0 ||
|
|
3830
|
-
|
|
3883
|
+
uiPromptAskActive() ||
|
|
3831
3884
|
reviewActive ||
|
|
3832
3885
|
// The standing run error keeps a beat alive so its durable token stays
|
|
3833
3886
|
// republished (and TTL-fresh) until the leg releases, even after the
|
|
@@ -4305,6 +4358,7 @@ export default function (pi) {
|
|
|
4305
4358
|
askToolCalls.clear();
|
|
4306
4359
|
runningTools.clear();
|
|
4307
4360
|
uiPromptActive = false;
|
|
4361
|
+
uiPromptWithdrawn = false;
|
|
4308
4362
|
askIntentId = undefined;
|
|
4309
4363
|
reviewCalls.clear();
|
|
4310
4364
|
reviewActive = false;
|
|
@@ -4390,6 +4444,15 @@ export default function (pi) {
|
|
|
4390
4444
|
if (!rootSession || !isRecord(event) || typeof event.toolCallId !== "string") return;
|
|
4391
4445
|
noteActivity();
|
|
4392
4446
|
runningTools.add(event.toolCallId);
|
|
4447
|
+
// A new TOP-LEVEL execution cannot start inside a run blocked on a
|
|
4448
|
+
// dialog: if a generic UI prompt span is open, it was never waited on (a
|
|
4449
|
+
// Gentle Shell command menu keeps the agent working), so the span
|
|
4450
|
+
// withdraws for the rest of its life. A nested call proves the opposite of
|
|
4451
|
+
// nothing: codemode's `ctx.executeTool` emits its start immediately, even
|
|
4452
|
+
// before its own queue wait, while a sibling tool's dialog is still
|
|
4453
|
+
// awaited (verified: 1 finding, false negative on a real confirmation), so
|
|
4454
|
+
// nested starts never withdraw.
|
|
4455
|
+
if (event.parentToolCallId === undefined) withdrawUiPromptAsk();
|
|
4393
4456
|
// Structured ask tools open ONLY on genuine execution (never on
|
|
4394
4457
|
// `tool_call` proposal), keyed by call id so the matching end or
|
|
4395
4458
|
// result closes them.
|
|
@@ -4463,6 +4526,9 @@ export default function (pi) {
|
|
|
4463
4526
|
pi.on("ui_prompt_end", () => {
|
|
4464
4527
|
if (!rootSession || !uiPromptActive) return;
|
|
4465
4528
|
uiPromptActive = false;
|
|
4529
|
+
// A fresh span (nested or later) starts un-withdrawn: the withdrawal is
|
|
4530
|
+
// per-span evidence, never session-wide.
|
|
4531
|
+
uiPromptWithdrawn = false;
|
|
4466
4532
|
updateBlocker();
|
|
4467
4533
|
});
|
|
4468
4534
|
|
|
@@ -4698,6 +4764,11 @@ export default function (pi) {
|
|
|
4698
4764
|
const message = event.message;
|
|
4699
4765
|
if (!isRecord(message)) return;
|
|
4700
4766
|
if (message.role === "assistant") {
|
|
4767
|
+
// A finished assistant message while a generic UI prompt span is open
|
|
4768
|
+
// proves the run was never blocked on it (same asymmetry as a new
|
|
4769
|
+
// top-level tool execution), so the span withdraws for the rest of its
|
|
4770
|
+
// life.
|
|
4771
|
+
withdrawUiPromptAsk();
|
|
4701
4772
|
// The one real error state. Pi derives `turn_end.outcome === "error"`
|
|
4702
4773
|
// from exactly this stopReason, so a run that stopped on an error is
|
|
4703
4774
|
// visible here without a second handler; any other assistant message
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "herdr-gentle-shell",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.7.0",
|
|
4
4
|
"description": "Pi package for Herdr sidebar states: the Pi extension sidecar that publishes session facts as Herdr pane-metadata tokens, the optional Moshi notification channel, and the Pi-side helpers the Herdr Gentle Shell plugin drives.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"pi-package",
|