herdr-gentle-shell 1.5.0 → 1.5.2
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 +113 -54
- package/README.md +71 -42
- package/extensions/gentle-herdr-state.ts +344 -48
- package/package.json +1 -1
package/DESIGN.md
CHANGED
|
@@ -17,11 +17,15 @@ explicitly in §10 and are not decided here.
|
|
|
17
17
|
- Herdr sidebar (`[ui.sidebar.agents]` + `[ui.sidebar.spaces]` blocks): shows
|
|
18
18
|
one state label per pane plus an optional session-changes badge.
|
|
19
19
|
- The human operator watching Pi + Gentle Shell agents: needs to distinguish
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
20
|
+
the principal session's own pink `gentle` (machine key `orchestrating` —
|
|
21
|
+
its working status and its generic status) from a delegate's own word: the
|
|
22
|
+
active TaskStore role abbreviation (`explorer`, `worker`, `verify`,
|
|
23
|
+
`judge`, `rdd`) or, for a non-contemplated subagent, that subagent's
|
|
24
|
+
sanitized name on the amber `working` cell — plus `ask` (blocked on user
|
|
25
|
+
input), `blocked` (the row word for the `error` key), `done`, and `idle` at
|
|
26
|
+
a glance. No visible text ever carries a subagent count, exactly one
|
|
27
|
+
user-facing `gentle` exists (the pink one), the amber `working` cell never
|
|
28
|
+
renders that word, and `gentle` never renders on an idle session.
|
|
25
29
|
|
|
26
30
|
### Current boundary and interaction
|
|
27
31
|
|
|
@@ -201,13 +205,13 @@ Sidecar only: ships beside `herdr-agent-state.ts`, never modifies it.
|
|
|
201
205
|
|
|
202
206
|
| Producer event (source) | Tokens written | v1 state contribution |
|
|
203
207
|
|---|---|---|
|
|
204
|
-
| `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 | `gentle` (machine key `
|
|
208
|
+
| `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 |
|
|
205
209
|
| TaskStore `running` non-empty (G3; queued/waiting never execute) | `gentle_work_v1=<hash>:<count>:<exp>` (running total of delegates — 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 |
|
|
206
210
|
| `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 `?`) |
|
|
207
211
|
| 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 |
|
|
208
212
|
| 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` |
|
|
209
213
|
| 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 |
|
|
210
|
-
| `agent_settled` + 0 active subs | `gentle_work_v1=<hash>:0:<exp>`; clear `blocked` labels | `done` |
|
|
214
|
+
| `agent_settled` + 0 active subs | `gentle_work_v1=<hash>:0:<exp>`; clear `blocked` labels | `done` — an observed turn only: the settle the beat reconciles from the host's live truth mints no finish (§4.5) |
|
|
211
215
|
| `SESSION_CHANGE_ENTRY` `gentle-pi.session-change/v1` tool outcome (G1/G2) | `gentle_changes_v2=<hash>:<files>:<added>:<deleted>:<exp>` (+ legacy `gentle_changes_v1` dual-emit, §4.3) | change segments only (orthogonal to state) |
|
|
212
216
|
|
|
213
217
|
`waiting`/`finished` TaskStore entries never count as active, and `queued`
|
|
@@ -234,11 +238,12 @@ exact `gentle-ai-worker` → `worker`, exact `gentle-ai-verify` → `verify`,
|
|
|
234
238
|
`jd-fix-` families) → the distinct `judge` slug (never `rdd`), and a
|
|
235
239
|
review agent / `gentle-ai-review*` / any role containing `review` → `rdd`;
|
|
236
240
|
any other agent keeps its original sanitized name (lowercase `[a-z0-9_-]`
|
|
237
|
-
slug, 32-char bound — never a generic collapse; unsalvageable shapes
|
|
238
|
-
|
|
241
|
+
slug, 32-char bound — never a generic collapse; unsalvageable shapes and the
|
|
242
|
+
reserved slugs `gentle`, `working`, and `subagent` read
|
|
243
|
+
the pink generic `gentle`, machine key `orchestrating`).
|
|
239
244
|
The consumer displays the oldest role word (known short word or unknown
|
|
240
245
|
sanitized name) whenever the principal itself is not working, regardless of
|
|
241
|
-
how many delegates run; a working principal renders `gentle` instead.
|
|
246
|
+
how many delegates run; a working principal renders the pink `gentle` instead.
|
|
242
247
|
Role labels carry the total running-delegate count in parentheses when greater
|
|
243
248
|
than one. Role order is immutable first-seen (progress reads never reorder;
|
|
244
249
|
sound same-session presence createdAt/startedAt may correct a late local
|
|
@@ -250,7 +255,8 @@ flight with no TaskStore record until it returns `tool_result`, so the exact
|
|
|
250
255
|
agent name in the pending `tool_call` input is the only live role evidence;
|
|
251
256
|
counting it would inflate the normative `gentle_work_v1` total with an
|
|
252
257
|
estimate, while publishing its role slug as a bounded-CSV hint keeps the
|
|
253
|
-
sidebar on the active role (`worker`, never
|
|
258
|
+
sidebar on the active role (`worker`, never the amber `working` cell —
|
|
259
|
+
generic activity reads the pink `gentle`) with the count
|
|
254
260
|
authoritative at 0. The hint merges with authoritative active TaskStore roles
|
|
255
261
|
(oldest-first) and clears when the tool result arrives, the call is
|
|
256
262
|
cancelled, or the agent settles. On a tool
|
|
@@ -264,7 +270,7 @@ launch outcomes keep `running` (and its agent) against `queued`/`waiting`/
|
|
|
264
270
|
re-resolve oldest-first — so a working principal with live delegates keeps
|
|
265
271
|
`gentle`, and a settle with running delegates keeps the oldest role word
|
|
266
272
|
instead of settling to `idle`/`done`. A sanitized unknown slug exactly equal to
|
|
267
|
-
`working` degrades to no role (generic `gentle`) on both the producer
|
|
273
|
+
`working` degrades to no role (the pink generic `gentle`) on both the producer
|
|
268
274
|
(`agentToRole`) and the consumer (`roleToDisplay`) sides. No local
|
|
269
275
|
age/staleness timeout is applied — Gentle Shell owns lifecycle/status truth.
|
|
270
276
|
Finished/failed/cancelled records may linger in the map but never count;
|
|
@@ -276,10 +282,11 @@ coverage while the authoritative active list is non-empty or any
|
|
|
276
282
|
once the main session settles — settled, or any non-root session. The marker carries no
|
|
277
283
|
count and changes neither the work total nor the roles CSV: it is a pure
|
|
278
284
|
freshness-bound presence flag (`<hash>:<exp>`, same binding/TTL style as
|
|
279
|
-
gentle_work_v1) that the consumer reduces to `
|
|
280
|
-
|
|
281
|
-
terminal `done`/native-`blocked`, and
|
|
282
|
-
|
|
285
|
+
gentle_work_v1) that the consumer reduces to the same pink `gentle` the
|
|
286
|
+
principal's own activity renders, only with no role word above it (§5.2):
|
|
287
|
+
below attention (error/ask/review), terminal `done`/native-`blocked`, and
|
|
288
|
+
role words; ahead of the positive-count generic fallback only, which renders
|
|
289
|
+
that same pink `gentle`.
|
|
283
290
|
The root session also emits `gentle_principal_v1` while its own agent is
|
|
284
291
|
active (`agentActive`) and clears it (null) the moment the principal
|
|
285
292
|
settles, keeping the same binding/TTL discipline. This is the principal-only
|
|
@@ -290,7 +297,7 @@ principal itself works. The native status keeps that aggregate meaning for
|
|
|
290
297
|
Herdr's own pane state; the row's working-vs-idle decision reads only
|
|
291
298
|
`gentle_principal_v1` (§5.2). It carries no count and alters neither the work
|
|
292
299
|
total nor the roles CSV. `agentActive` alone would render that blocked call
|
|
293
|
-
as generic `gentle`.
|
|
300
|
+
as the pink generic `gentle`.
|
|
294
301
|
The root session additionally emits `gentle_pending_v1` (`<hash>:<role>:<exp>`)
|
|
295
302
|
while a synchronous (task mode) `subagent_run`/`subagent_continue` tool call
|
|
296
303
|
is still in flight: such a call blocks the principal's own turn, so the
|
|
@@ -326,7 +333,10 @@ role = "explorer" / "worker" / "verify" / "judge" / "rdd" / passthrou
|
|
|
326
333
|
; stays distinct, never `rdd`)
|
|
327
334
|
; passthrough = 1*32 lowercase [a-z0-9_-], leading [a-z0-9]
|
|
328
335
|
; (unknown delegation keeps its sanitized original name —
|
|
329
|
-
; never a generic collapse; producer truncates to 32
|
|
336
|
+
; never a generic collapse; producer truncates to 32;
|
|
337
|
+
; the reserved words `gentle`, `working`, and `subagent`
|
|
338
|
+
; resolve to no role on both sides — producer and reducer —
|
|
339
|
+
; so they degrade to the pink generic `gentle`)
|
|
330
340
|
gentle_roles_v1 = role *("," role) ; total <= 512 UTF-8 bytes; null (clear)
|
|
331
341
|
; when no delegation is active (no role words)
|
|
332
342
|
gentle_orchestrating_v1 = sessionHash ":" expiry
|
|
@@ -435,17 +445,19 @@ explorers with count 3 → `explorer (3)`; 5 files
|
|
|
435
445
|
`● myproj +110 -22` (` +` green for added, ` -` red for deleted with a
|
|
436
446
|
leading-space match, zero `·` separators because exactly one heading cell
|
|
437
447
|
is nonempty).
|
|
438
|
-
A review label renders `rdd` with a blue `●` (`#89b4fa`, same as explorer/pull). A
|
|
439
|
-
`gentle_orchestrating_v1` marker renders pink `gentle` (machine display
|
|
440
|
-
`orchestrating`, pink palette unchanged)
|
|
441
|
-
|
|
442
|
-
attention (`ask`/`review`/`blocked`) and terminal `done` states.
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
`gentle`
|
|
448
|
+
A review label renders `rdd` with a blue `●` (`#89b4fa`, same as explorer/pull). A
|
|
449
|
+
`gentle_orchestrating_v1` marker renders the pink `gentle` (machine display
|
|
450
|
+
key `orchestrating`, pink palette unchanged): it covers the principal's
|
|
451
|
+
queued/running subs and pending launches, and it yields to a delegate role
|
|
452
|
+
word and to attention (`ask`/`review`/`blocked`) and terminal `done` states.
|
|
453
|
+
The marker is not a principal-working signal: it stays live while the
|
|
454
|
+
principal is idle with queued or running delegates, so it never decides the
|
|
455
|
+
working state. That state comes from `gentle_principal_v1` alone, and it is
|
|
456
|
+
the same pink `gentle` with or without a fresh root marker: the amber
|
|
457
|
+
`working` cell is never the principal's own. With no fresh principal marker
|
|
458
|
+
the pane shows the oldest role word, the pink generic `gentle` when a running
|
|
459
|
+
delegate has no resolvable name, or `idle` — but never an amber generic
|
|
460
|
+
because delegates run.
|
|
449
461
|
|
|
450
462
|
### 4.5 Publication and chunking
|
|
451
463
|
|
|
@@ -470,6 +482,27 @@ principal marker the pane shows the oldest role word (or `idle`), never
|
|
|
470
482
|
- Writes are idempotent full-state snapshots per pane (all gentle tokens
|
|
471
483
|
re-emitted each beat), never deltas — a lost report is repaired by the next
|
|
472
484
|
beat.
|
|
485
|
+
- The producer beats every 15 s by default; `GENTLE_HERDR_BEAT_MS` overrides
|
|
486
|
+
the cadence for tests and debugging (clamped to [100, 300000]). The
|
|
487
|
+
override changes no TTL: the write horizon stays `now+60000` (§8).
|
|
488
|
+
- Every beat first reconciles the settle from the host's own live truth: with
|
|
489
|
+
no turn active and no work evidence (no running/queued delegate, no pending
|
|
490
|
+
launch, no live background job), the retained context's `isIdle()` flips
|
|
491
|
+
`settled`, so a run whose `agent_settled` never reached the producer still
|
|
492
|
+
reaches native `idle` instead of republishing a fresh count-0 work token
|
|
493
|
+
forever. A turn this producer saw start is never overridden from there.
|
|
494
|
+
When the host offers no truth at all, a producer that observed no turn stops
|
|
495
|
+
beating after a bounded budget (three beats) instead of publishing a native
|
|
496
|
+
state the host never confirmed; a turn this producer saw start is never
|
|
497
|
+
bounded, so the budget cannot trade a truthful `working` for a false `idle`
|
|
498
|
+
on a host with no truth to settle on. The beat is re-armed by the edges that
|
|
499
|
+
schedule a publish (ask, review, launch, session changes, jobs), while an
|
|
500
|
+
ordinary tool edge reaches the row through the host's own truth rather than
|
|
501
|
+
by re-arming it. A settle recovered this way is not an observed turn, so it
|
|
502
|
+
mints no `gentle_done_v1` and sends no finish notification.
|
|
503
|
+
- The settle-time pending latch (`pendingCount`) is bounded by the finish hold
|
|
504
|
+
of the settle that raised it: past that hold a launch that never reports
|
|
505
|
+
back stops counting, so it cannot pin the native report at `working`.
|
|
473
506
|
- Session-change tokens are refreshed/cleared from the current Gentle Shell
|
|
474
507
|
session model every beat and never carried across sessions: zero changed
|
|
475
508
|
files publishes a clear (null over socket metadata, `--clear-token <name>`
|
|
@@ -532,17 +565,20 @@ blockingRole := fresh gentle_pending_v1 (session-bound, TTL-fresh) whose
|
|
|
532
565
|
principalWorking := fresh gentle_principal_v1 (session-bound, TTL-fresh) —
|
|
533
566
|
the principal's OWN activity, never the delegate count and
|
|
534
567
|
never the aggregate native status (which reads working for
|
|
535
|
-
any running delegate or pending launch); renders
|
|
536
|
-
`orchestrating`
|
|
537
|
-
|
|
568
|
+
any running delegate or pending launch); renders the pink
|
|
569
|
+
`gentle` (machine key `orchestrating`) with or without a
|
|
570
|
+
fresh gentle_orchestrating_v1; outranks every delegate role
|
|
538
571
|
word; stale, foreign, or absent falls through to the
|
|
539
572
|
branches below
|
|
540
573
|
role := gentle_work_v1 fresh AND gentle_roles_v1 yields a
|
|
541
574
|
recognized role (oldest first, incl. the in-flight pending
|
|
542
575
|
role hint at count = 0 for task-mode launches with no
|
|
543
576
|
TaskStore record yet) — the principal is not working, so the
|
|
544
|
-
delegate word wins
|
|
545
|
-
|
|
577
|
+
delegate word wins. A non-contemplated subagent renders on
|
|
578
|
+
the `working` display, whose label is that subagent's own
|
|
579
|
+
sanitized name (never `gentle`). Role and name labels append
|
|
580
|
+
the total when at least two delegates run. Tool-only review
|
|
581
|
+
has no suffix.
|
|
546
582
|
orchestrating := gentle_orchestrating_v1 fresh with no role word above
|
|
547
583
|
(root-only per §4.2: fresh while the main session actively
|
|
548
584
|
works, even with zero subagents, retaining running/queued-sub,
|
|
@@ -550,8 +586,11 @@ orchestrating := gentle_orchestrating_v1 fresh with no role word above
|
|
|
550
586
|
falls through to the
|
|
551
587
|
branches below; attention, terminal `done`/native-`blocked`,
|
|
552
588
|
a working principal, and role words stay higher)
|
|
553
|
-
|
|
554
|
-
|
|
589
|
+
generic := gentle_work_v1 fresh AND count > 0 with no role word —
|
|
590
|
+
renders the pink `gentle` (machine key `orchestrating`), the
|
|
591
|
+
principal session's generic status; a count = 0 beat asserts
|
|
592
|
+
no activity — it reaches `done` only through the terminal
|
|
593
|
+
gate, otherwise `idle`
|
|
555
594
|
done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
|
|
556
595
|
fresh with count = 0 (no running delegates) AND no roles AND
|
|
557
596
|
no fresh gentle_orchestrating_v1 AND no fresh
|
|
@@ -565,7 +604,7 @@ done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
|
|
|
565
604
|
idle := otherwise (native fallback; also all-gentle-tokens-missing-or-expired)
|
|
566
605
|
```
|
|
567
606
|
|
|
568
|
-
Priority: `error > ask > review > done > blockingRole > principal working > role > orchestrating >
|
|
607
|
+
Priority: `error > ask > review > done > blockingRole > principal working > role > orchestrating > generic > idle`.
|
|
569
608
|
`done` is matched before the principal/role branches in the reducer; it is
|
|
570
609
|
listed here below the activity branches only so its settled-and-empty
|
|
571
610
|
precondition reads together.
|
|
@@ -574,11 +613,15 @@ precondition reads together.
|
|
|
574
613
|
(error/ask/review) and the terminal `done` state always outrank principal
|
|
575
614
|
status and activity roles. Below them the principal's own activity decides,
|
|
576
615
|
never the delegate count and never the aggregate native status: a **working
|
|
577
|
-
principal** renders `gentle` (
|
|
578
|
-
|
|
579
|
-
|
|
616
|
+
principal** renders the pink `gentle` (machine key `orchestrating`, fresh
|
|
617
|
+
root marker or not) and outranks every delegate role word; an **idle
|
|
618
|
+
principal** shows the oldest running role word
|
|
580
619
|
(`explorer`, `worker`, `verify`, `judge`, or `rdd` when it is the oldest)
|
|
581
|
-
however many delegates run
|
|
620
|
+
however many delegates run, and falls back to that same pink `gentle` when a
|
|
621
|
+
running delegate has no resolvable name (that row is not idle: a delegate
|
|
622
|
+
runs). A live count-0 work token asserts no activity: it reaches `done` only
|
|
623
|
+
through the terminal gate above, otherwise `idle`, so `gentle` never renders
|
|
624
|
+
on an idle session. The one exception sits between them and is
|
|
582
625
|
evidence-based, never a precedence guess: while a **synchronous**
|
|
583
626
|
`subagent_run`/`subagent_continue` call is in flight the principal's own turn
|
|
584
627
|
is blocked on the child, so the fresh `gentle_pending_v1` role word decides
|
|
@@ -606,10 +649,13 @@ marker, and only after the minted finish hold lapses does it recede to
|
|
|
606
649
|
The visible second row is structural, with no rules: the eleven
|
|
607
650
|
presence-encoded
|
|
608
651
|
`gentle_title_<working|orchestrating|explorer|worker|verify|judge|ask|review|error|done|idle>`
|
|
609
|
-
state tokens (state word only: `
|
|
652
|
+
state tokens (a state word only: `gentle` (pink, machine key
|
|
610
653
|
`orchestrating`) / `explorer` / `worker` /
|
|
611
|
-
`verify` / `judge` / `ask` / `blocked` / `done` / `idle` / `review
|
|
612
|
-
|
|
654
|
+
`verify` / `judge` / `ask` / `blocked` / `done` / `idle` / `review` — with
|
|
655
|
+
the one exception that the amber `working` cell carries a
|
|
656
|
+
non-contemplated subagent's own sanitized name, never the word `working`
|
|
657
|
+
and never `gentle`; role and name words carry a running-count suffix above
|
|
658
|
+
one).
|
|
613
659
|
Only the current display's title token carries a value; the rest are null.
|
|
614
660
|
Each state cell carries its state's semantic color as its base fg with
|
|
615
661
|
no rules — working/worker golden `#f9e2af`, orchestrating pink fuchsia
|
|
@@ -625,13 +671,17 @@ marker, and only after the minted finish hold lapses does it recede to
|
|
|
625
671
|
tokens plus the row-2 title and change-segment tokens to
|
|
626
672
|
the pi-only `rows_by_agent` override (E10); exact block wiring is
|
|
627
673
|
install configuration, not protocol.
|
|
628
|
-
- Label shapes: `gentle`
|
|
629
|
-
principal's own working
|
|
630
|
-
with or without
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
root-session marker
|
|
634
|
-
|
|
674
|
+
- Label shapes: exactly one `gentle` — pink `#f5c2e7`, machine key
|
|
675
|
+
`orchestrating`: the principal session's own working status (asserted by a
|
|
676
|
+
fresh `gentle_principal_v1`, with or without a fresh root marker and with
|
|
677
|
+
or without delegated roles) and its generic status (a positive running
|
|
678
|
+
count with no resolvable name, only unsalvageable role shapes, or a fresh
|
|
679
|
+
root-session marker covering queued/running subs and pending launches);
|
|
680
|
+
never rendered on an idle session | the amber `working` cell (`#f9e2af`)
|
|
681
|
+
carries a non-contemplated subagent's own sanitized name from
|
|
682
|
+
`gentle_roles_v1` / `gentle_pending_v1` — never the word `working` and
|
|
683
|
+
never `gentle`, so a bare `working` display fails closed to the pink
|
|
684
|
+
`gentle` | `explorer` / `worker` / `verify` / `judge` (oldest
|
|
635
685
|
TaskStore role word while the principal itself is idle, however many
|
|
636
686
|
delegates run) | `ask` | `rdd` (user-facing word for the `review`
|
|
637
687
|
machine key; a delegated rdd and a tool-only review both render `rdd` —
|
|
@@ -782,7 +832,9 @@ gentle-ai concern and explicitly out of scope for this plugin.
|
|
|
782
832
|
next landed beat resets the counter. The one real error leg — the run
|
|
783
833
|
itself stopping on an error — is released by the next non-error beat
|
|
784
834
|
(`agent_start`, any tool activity, or a non-error assistant message), never
|
|
785
|
-
latched; no exception path ever stops the producer beat
|
|
835
|
+
latched; no exception path ever stops the producer beat (a quiet producer
|
|
836
|
+
with no host truth and no work evidence ends its own bounded budget instead,
|
|
837
|
+
§4.5). While the leg
|
|
786
838
|
stands it publishes the durable `gentle_error_v1` token on every beat, so
|
|
787
839
|
an error the sidebar missed on one beat is repaired by the next, and the
|
|
788
840
|
release beat clears it (the missed-beat discipline of the ask/review
|
|
@@ -804,6 +856,10 @@ gentle-ai concern and explicitly out of scope for this plugin.
|
|
|
804
856
|
the poll after the native one for the same question, a systematic
|
|
805
857
|
duplication. The ask token still drives the sidebar ask display; sounds,
|
|
806
858
|
suppression, and delay stay Herdr's.
|
|
859
|
+
- Herdr's own done/ask attention — the finished and needs-attention pop-ups and
|
|
860
|
+
their sound — is Herdr's native behavior, configured in Herdr itself (its
|
|
861
|
+
config and its settings). This package deliberately offers no switch for it;
|
|
862
|
+
its only notification surface is the optional Moshi channel.
|
|
807
863
|
- `review` and `error` never emit a plugin notification: `review` attention
|
|
808
864
|
stays in-flow/native; `error` is sidebar state only — our own `error:` label
|
|
809
865
|
with the pane left on native `working`, so neither the `NeedsAttention`
|
|
@@ -877,7 +933,7 @@ report after a Pi restart or `/new` (both recreate the extension runtime)
|
|
|
877
933
|
lose, freezing the pane's `agent_session` binding at the old session while
|
|
878
934
|
the producer keeps beating for the new one — the consumer then rejects those
|
|
879
935
|
fresh tokens as a session-hash mismatch and the pane stays on `idle` until a
|
|
880
|
-
report with a higher seq lands. Parity contract: `working` carries the specific working role in the message (oldest running role word from the same roles resolution — known short word, unknown sanitized name, or `gentle` with no delegation; never bare generic `working`; machine keys unchanged); terminal `idle` 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 with no re-emit on repeat settles). Live background jobs come from Gentle Shell's own bus event `gentle-ai:jobs-sidebar` (`bash_background` / `monitor`), session-scoped and emitted on job edges only, so a snapshot counts only while it is fresh — a stale or foreign snapshot is zero jobs; an absent Gentle Shell simply reports none (today's behavior). Only an entry with no `status` is pending work: Gentle Shell keeps a finished job in the array as a result tail (`status: exited|stopped|failed`), and counting that tail is what pinned the row on the pink generic `gentle` — and blocked `done` — while the panel read no running job. One `unref()`-ed timer per live snapshot publishes a single beat at the instant the snapshot goes stale, so a missed exit event cannot leave the settle without a beat. While such a job waits with the principal settled and no delegate running or launching, the producer keeps the root marker live so the row stays on the pink generic `gentle` (§5.2) and the finish is held back; the wait ends on the beat the principal resumes, a delegate starts, the last job ends, or the snapshot ages past its staleness bound. `blocked` only for an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent); an error never claims native `blocked` — while our `error:` label stands the pane reports `working`, the only native state that raises no host attention, and returns to the lifecycle state on the next non-error beat. The native status keeps its aggregate meaning (it reads `working` while any delegate runs, which is what Herdr's own pane state means): the sidebar row's working-vs-idle decision reads the principal-only `gentle_principal_v1` instead (§5.2), so an idle principal with a running delegate shows
|
|
936
|
+
report with a higher seq lands. Parity contract: `working` carries the specific working role in the message (oldest running role word from the same roles resolution — known short word, unknown sanitized name, or the pink generic `gentle` with no delegation; never bare generic `working`; machine keys unchanged); terminal `idle` 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 with no re-emit on repeat settles). A settle the producer missed is recovered from the host's own live truth: a beat with nothing active and no work evidence reconciles `settled` from `isIdle()`, a quiet producer the host never answers stops beating after a bounded budget instead of republishing a count-0 work token forever, and only an observed turn mints `done`, so a reconciled settle announces nothing. Live background jobs come from Gentle Shell's own bus event `gentle-ai:jobs-sidebar` (`bash_background` / `monitor`), session-scoped and emitted on job edges only, so a snapshot counts only while it is fresh — a stale or foreign snapshot is zero jobs; an absent Gentle Shell simply reports none (today's behavior). Only an entry with no `status` is pending work: Gentle Shell keeps a finished job in the array as a result tail (`status: exited|stopped|failed`), and counting that tail is what pinned the row on the pink generic `gentle` — and blocked `done` — while the panel read no running job. One `unref()`-ed timer per live snapshot publishes a single beat at the instant the snapshot goes stale, so a missed exit event cannot leave the settle without a beat. While such a job waits with the principal settled and no delegate running or launching, the producer keeps the root marker live so the row stays on the pink generic `gentle` (§5.2) and the finish is held back; the wait ends on the beat the principal resumes, a delegate starts, the last job ends, or the snapshot ages past its staleness bound. `blocked` only for an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent); an error never claims native `blocked` — while our `error:` label stands the pane reports `working`, the only native state that raises no host attention, and returns to the lifecycle state on the next non-error beat. The native status keeps its aggregate meaning (it reads `working` while any delegate runs, which is what Herdr's own pane state means): the sidebar row's working-vs-idle decision reads the principal-only `gentle_principal_v1` instead (§5.2), so an idle principal with a running delegate shows that delegate's own role word or name rather than the principal's `gentle`. Single publisher by design: the managed native extension file is excluded
|
|
881
937
|
reversibly (`-extensions/herdr-agent-state.ts` in Pi settings, bytes
|
|
882
938
|
preserved on disk, never auto-loaded next to ours). `node
|
|
883
939
|
bin/gentle-sidebar.js (enable|disable|status|toggle)` selects the
|
|
@@ -1050,7 +1106,10 @@ exactly one mechanism writes each piece of state.
|
|
|
1050
1106
|
user-facing value is `blocked` (§5.3). `gentle_title_review` likewise
|
|
1051
1107
|
keeps its machine-key-derived token name; only its user-facing value is
|
|
1052
1108
|
now `rdd` (aligned from `review` by the native-owner T1). `gentle_title_orchestrating` likewise keeps its machine-key-derived
|
|
1053
|
-
token name; only its user-facing value is `gentle`.
|
|
1109
|
+
token name; only its user-facing value is `gentle`. `gentle_title_working`
|
|
1110
|
+
likewise keeps its machine-key-derived token name; its user-facing value is
|
|
1111
|
+
a non-contemplated subagent's own sanitized name, never the word `working`.
|
|
1112
|
+
The retired `*_working_subs` token family (the old `working (n)`
|
|
1054
1113
|
count display) is swept, never written.
|
|
1055
1114
|
- Coexistence: `herdr-pi-tree` stays installed but disabled for gentle-owned
|
|
1056
1115
|
panes (O1). No uninstall, no token migration, no dual-run merge — ownership
|
package/README.md
CHANGED
|
@@ -6,21 +6,23 @@ Local Herdr plugin so the sidebar recognises Pi + Gentle Shell agents.
|
|
|
6
6
|
|
|
7
7
|
## What It Does
|
|
8
8
|
|
|
9
|
-
Reports per-pane agent state (`gentle`
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
`
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
the
|
|
22
|
-
|
|
23
|
-
|
|
9
|
+
Reports per-pane agent state (exactly one user-facing `gentle` — pink
|
|
10
|
+
`#f5c2e7`, machine key `orchestrating`: the principal session's own working
|
|
11
|
+
status and its generic status; a non-contemplated subagent renders its own
|
|
12
|
+
sanitized name on the amber `working` cell `#f9e2af` — never the word
|
|
13
|
+
`working`, never `gentle` — and a recognized gentle role keeps its
|
|
14
|
+
abbreviation — `explorer`, `worker`,
|
|
15
|
+
`verify`, `judge`, `rdd` — with the total running count in parentheses when
|
|
16
|
+
two or more subagents run, for example `explorer (3)`). The principal's own
|
|
17
|
+
activity marker (`gentle_principal_v1`, published while the principal session
|
|
18
|
+
itself works and cleared when it settles) decides the row — never the
|
|
19
|
+
delegate count, and never Herdr's aggregate native status (which reads
|
|
20
|
+
`working` whenever any delegate runs): the default is still the principal's
|
|
21
|
+
own state, so while the principal works its own turn it reads pink `gentle`,
|
|
22
|
+
with or without a fresh root marker, and no delegate word wins; while the
|
|
23
|
+
principal is idle the oldest running delegate role shows, or that subagent's
|
|
24
|
+
own name when no role word is recognized. `gentle` never renders on an idle
|
|
25
|
+
session. The single exception is a
|
|
24
26
|
blocking synchronous subagent call (`gentle_pending_v1`): a task-mode
|
|
25
27
|
`subagent_run`/`subagent_continue` holds the principal's turn open until the
|
|
26
28
|
child returns, so the principal is waiting on that child rather than working
|
|
@@ -214,8 +216,10 @@ sidebar-only, DESIGN §7; it rides the durable session-bound
|
|
|
214
216
|
`gentle_error_v1` token, republished on every beat while the run-error leg
|
|
215
217
|
stands and cleared the beat it releases, so a beat the sidebar missed is
|
|
216
218
|
repaired by the next one); the orchestrating
|
|
217
|
-
leg renders the user-facing
|
|
218
|
-
`orchestrating`, pink `#f5c2e7`)
|
|
219
|
+
leg renders the one user-facing `gentle` (machine key stays
|
|
220
|
+
`orchestrating`, pink `#f5c2e7`), while the `working` leg (amber `#f9e2af`)
|
|
221
|
+
carries a non-contemplated subagent's own sanitized name and never renders
|
|
222
|
+
the word `gentle` or `working`. Remaining state colors:
|
|
219
223
|
working/worker amber `#f9e2af`, explorer blue `#89b4fa`, verify teal
|
|
220
224
|
`#94e2d5`, ask orange `#fab387`, error red `#f38ba8`, done green `#a6e3a1`,
|
|
221
225
|
idle grey `#7c7f93`. Added stays green and deleted stays red; the mapping
|
|
@@ -250,26 +254,34 @@ unavailable counts (unavailable files stay in the file count with 0/0); `↑N` s
|
|
|
250
254
|
branch is behind its upstream (branch-ab status only, no diff). `gentle_project`,
|
|
251
255
|
`gentle_changes_summary`, and the segment
|
|
252
256
|
tokens (`gentle_changes_added`/`_deleted`/`_pull`) stay published for
|
|
253
|
-
compatibility but render no visible row. `gentle`
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
257
|
+
compatibility but render no visible row. Pink `gentle` (machine key
|
|
258
|
+
`orchestrating`, pink palette unchanged) is the
|
|
259
|
+
only user-facing `gentle`: it renders while the principal session actively
|
|
260
|
+
works — even with zero subagents, with or without a fresh root marker — and
|
|
261
|
+
as its generic status when a running delegate has no resolvable name, when
|
|
262
|
+
only unsalvageable role shapes remain, or when the root marker covers a
|
|
263
|
+
queued/running sub or a pending launch; it never renders on an idle session.
|
|
264
|
+
A non-contemplated subagent renders its own sanitized name on the amber
|
|
265
|
+
`working` cell instead, and a recognized gentle role keeps its abbreviation
|
|
266
|
+
(`explorer`, `worker`, `verify`, `judge`, `rdd`). The principal's own
|
|
258
267
|
activity decides the row, never the delegate count and never Herdr's
|
|
259
268
|
aggregate native status (the work token counts running delegates, and the
|
|
260
269
|
native status reads `working` for any running delegate or pending launch — so
|
|
261
270
|
neither can say the principal works): the dedicated
|
|
262
271
|
`gentle_principal_v1` marker is published while the principal session itself
|
|
263
272
|
works and cleared when it settles. That is the default: a **working
|
|
264
|
-
principal** reads `gentle` —
|
|
265
|
-
|
|
273
|
+
principal** reads the pink `gentle` — machine key `orchestrating`, fresh root
|
|
274
|
+
marker or not — and no delegate role word
|
|
266
275
|
wins; an **idle principal** shows the oldest running TaskStore role
|
|
267
276
|
(`explorer`, `worker`, `verify`, `judge`, `rdd`), however many delegates run.
|
|
268
277
|
The one exception is a blocking synchronous subagent call: while a task-mode
|
|
269
278
|
`subagent_run`/`subagent_continue` is in flight the principal's own turn is
|
|
270
279
|
blocked on the child, so the producer publishes that child's role in
|
|
271
280
|
`gentle_pending_v1` and it renders instead of `gentle`, for as long as the
|
|
272
|
-
call lasts.
|
|
281
|
+
call lasts. A resume (`subagent_continue`) carries no agent, so its role is
|
|
282
|
+
the tracked task record's agent for its `task_id`; when neither the input nor
|
|
283
|
+
a record names one, the call publishes no role and the row keeps its generic
|
|
284
|
+
display. Background launches resolve their tool call immediately, so a
|
|
273
285
|
queued or running background delegate publishes no such marker and leaves
|
|
274
286
|
the principal's own display untouched. These yield to `ask`/`rdd`/`blocked`
|
|
275
287
|
and terminal `done` — where `done` needs
|
|
@@ -281,15 +293,17 @@ work total is a direct projection of the
|
|
|
281
293
|
Gentle Shell TaskStore `running` records (only `running` counts as
|
|
282
294
|
executing; queued/waiting never count), never a calculated
|
|
283
295
|
pending-call estimate: pending tool calls are role-only display hints (exact
|
|
284
|
-
in-flight subagent agent -> role slug,
|
|
296
|
+
in-flight subagent agent -> role slug, resolved from the tool input or, for a
|
|
297
|
+
resume, from the tracked task record, so task-mode launches show the active
|
|
285
298
|
role even at count 0) plus label correlation, and
|
|
286
299
|
true concurrent tasks all count. A live `running` record is never regressed
|
|
287
300
|
by a racy non-final status read (only the authoritative launch outcomes,
|
|
288
301
|
completions, and presence terminals move it), so principal activity with
|
|
289
302
|
live delegates keeps `gentle` while an idle principal keeps the role word; a
|
|
290
303
|
sanitized unknown slug exactly
|
|
291
|
-
equal to `working` degrades to `gentle` (
|
|
292
|
-
renders
|
|
304
|
+
equal to `working` or `subagent` degrades to the pink `gentle` (neither bare word ever
|
|
305
|
+
renders; `subagent` is the producer's launch-correlation placeholder, never
|
|
306
|
+
an agent name).
|
|
293
307
|
Background launches (`subagent_run` with `mode: background`) announce
|
|
294
308
|
lifecycle over `message_end` custom results: an ACTIVE status promotes the
|
|
295
309
|
start into the tasks map like a task-mode record, so an active background
|
|
@@ -318,10 +332,13 @@ herdr server reload-config
|
|
|
318
332
|
Live check: with the daemon running and the override applied, open a Pi pane
|
|
319
333
|
and confirm row 2 shows pink `gentle` (machine key
|
|
320
334
|
`orchestrating`) while
|
|
321
|
-
the principal session actively works — even with zero subagents
|
|
322
|
-
`gentle` while its delegates run (a
|
|
323
|
-
|
|
324
|
-
|
|
335
|
+
the principal session actively works — even with zero subagents, and with or
|
|
336
|
+
without a fresh root marker — and keeps `gentle` while its delegates run (a
|
|
337
|
+
role word such as `worker`, `explorer`,
|
|
338
|
+
`verify`, `judge`, or a non-contemplated subagent's own name in amber, shows
|
|
339
|
+
once the principal itself is idle — and also while a
|
|
340
|
+
task-mode subagent call blocks the principal's turn, until it returns), that
|
|
341
|
+
a row never reads `gentle` on an idle pane; row 1
|
|
325
342
|
shows the single heading cell (`● <project>` plus ` +N`/` -N`/` ↑N` inline, zero `·`) after edits / when behind upstream; then `ask` on an open
|
|
326
343
|
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
|
|
327
344
|
`HERDR_CONFIG_PATH` on a temp file for apply/uninstall checks.
|
|
@@ -348,7 +365,10 @@ coalesced refresh after every landed token beat, so a status change
|
|
|
348
365
|
it publishes is drawn at once, and the daemon caps each sleep at the nearest
|
|
349
366
|
live `done` expiry, so a settled row reaches `idle` when its short hold (5 s by
|
|
350
367
|
default, `GENTLE_HERDR_DONE_HOLD_MS`-overridable) lapses instead of one poll
|
|
351
|
-
later.
|
|
368
|
+
later. The producer's own beat is 15 s by default and
|
|
369
|
+
`GENTLE_HERDR_BEAT_MS`-overridable for tests and debugging (clamped to
|
|
370
|
+
[100, 300000]); the override changes the cadence only, never the 60 s token
|
|
371
|
+
TTL. Reports in one window collapse into one frame, and refresh-driven frames
|
|
352
372
|
are floored at 250 ms, so a burst can never spin the daemon. Polling stays the
|
|
353
373
|
fallback for every lifecycle signal and the only source for what no Herdr event
|
|
354
374
|
carries (the git-derived `+N/-N` and `↑N` row data and the presence prefix), so a
|
|
@@ -362,10 +382,12 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
362
382
|
## Key Features You Should Know About
|
|
363
383
|
|
|
364
384
|
- Full v1 state matrix including the root-session `orchestrating` marker
|
|
365
|
-
(pink `●` + user-facing word `gentle`,
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
385
|
+
(pink `●` + the one user-facing word `gentle`, the principal session's
|
|
386
|
+
working and generic status: it shows while the principal actively works —
|
|
387
|
+
even with zero subagents and with or without a fresh root marker — and
|
|
388
|
+
covers queued/running subagents and pending launches; yielding only to
|
|
389
|
+
`ask`/`rdd`/`blocked` and terminal `done` (done needs settled-plus-empty);
|
|
390
|
+
never on an idle session) and the authoritative TaskStore role signal
|
|
369
391
|
(`explorer` / `worker` / `verify` / `judge` / `rdd` from `TaskRecord.agent`,
|
|
370
392
|
oldest running first by immutable first-seen, shown while the principal
|
|
371
393
|
itself is idle — a working principal's own turn keeps `gentle`, asserted by
|
|
@@ -374,10 +396,12 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
374
396
|
synchronous `subagent_run`/`subagent_continue` call holds the principal's
|
|
375
397
|
turn open, so the in-flight child's role shows instead (the
|
|
376
398
|
`gentle_pending_v1` role marker) until that call resolves, while a
|
|
377
|
-
background delegate never takes that path;
|
|
378
|
-
key `working`) for the principal's own working state; an unknown delegation
|
|
399
|
+
background delegate never takes that path; an unknown delegation
|
|
379
400
|
keeps its original sanitized name, 32-char bound — never a generic
|
|
380
|
-
collapse
|
|
401
|
+
collapse (the reserved words `gentle`, `working`, and `subagent` are no name
|
|
402
|
+
and degrade to the pink generic) — and renders on the amber `working` cell,
|
|
403
|
+
which never carries the
|
|
404
|
+
word `gentle`), with a running-count suffix on role labels when two or more
|
|
381
405
|
delegates run, `ask` on blocked user input,
|
|
382
406
|
`rdd` during native review execution (machine key stays `review`; execution
|
|
383
407
|
is silent — desktop attention fires only for a waiting `ask` intent, as
|
|
@@ -423,7 +447,7 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
423
447
|
nothing and logs one line per reason. The gs pane's own live state stays
|
|
424
448
|
unobservable until the isolated install forwards `HERDR_ENV` to its agent (a
|
|
425
449
|
gentle-ai concern, out of scope here).
|
|
426
|
-
- 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 an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent). `blocked` is never derived from an error: native `blocked` is what fires the host's NeedsAttention toast and sound, so a failed run shows our own `error` state — the durable, session-bound `gentle_error_v1` token (republished every beat while the leg stands, cleared when it releases) that the sidebar reduces to the `error` row word — while the pane stays on `working`, and a failed tool call (or a delegate that ended `failed`, or a failed beat transport) changes nothing at all: it is detected and logged, never published, and never reaches the error token. 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
|
|
450
|
+
- 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 the pink generic `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). A settle is reconciled from the host's own live truth (`isIdle()`) whenever nothing is active and no work evidence remains, so a run whose settle never reached the producer still reaches `idle` instead of freezing the pane on native `working`; a quiet producer the host never answers stops beating after a bounded budget instead of republishing a count-0 work token forever — but only when it observed no turn, while a turn it saw start keeps beating so the budget never trades a truthful `working` for a false `idle` on a truth-less host; the beat is re-armed by the edges that schedule a publish (ask, review, launch, session changes, jobs), while an ordinary tool edge reaches the row through the host's own truth rather than by re-arming it; the settle-time pending latch is bounded by that settle's finish hold. A reconciled settle is not an observed turn, so it mints no `done` and sends no `task_complete`. 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 an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent). `blocked` is never derived from an error: native `blocked` is what fires the host's NeedsAttention toast and sound, so a failed run shows our own `error` state — the durable, session-bound `gentle_error_v1` token (republished every beat while the leg stands, cleared when it releases) that the sidebar reduces to the `error` row word — while the pane stays on `working`, and a failed tool call (or a delegate that ended `failed`, or a failed beat transport) changes nothing at all: it is detected and logged, never published, and never reaches the error token. 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 that delegate's own role word or name instead of the principal's `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.
|
|
427
451
|
- Sidebar switch (`enable` / `disable` / `status` / `toggle`):
|
|
428
452
|
`node bin/gentle-sidebar.js <verb>` picks between this plugin's sidebar rows
|
|
429
453
|
and the native Herdr sidebar. `status` is read-only; `enable` converges the
|
|
@@ -449,7 +473,12 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
449
473
|
shows the single `Sidebar agent rows` row, and the only Moshi switch is the
|
|
450
474
|
`Notifications` row under `Moshi notifications`. The two are never mixed —
|
|
451
475
|
`Sidebar agent rows` neither reads nor writes `gentle-moshi.json`, so turning
|
|
452
|
-
the agent rows off never turns the notification channel off.
|
|
476
|
+
the agent rows off never turns the notification channel off. Herdr's own
|
|
477
|
+
done/ask attention (the finished and needs-attention pop-ups and their
|
|
478
|
+
sound) is Herdr's native behavior, configured in Herdr itself — its config
|
|
479
|
+
and its settings — and this package deliberately offers no switch for it:
|
|
480
|
+
the optional Moshi channel below is the only notification surface the
|
|
481
|
+
package owns. The plain
|
|
453
482
|
two-step menu stays as the fallback
|
|
454
483
|
when the TUI helpers or `ctx.ui.custom` are unavailable.
|
|
455
484
|
`Sidebar agent rows` drives the Herdr plugin's own `bin/configure.js`
|
|
@@ -73,10 +73,13 @@
|
|
|
73
73
|
// gentle_names_v1 = CSV of TaskRecord.label/agent (sanitized, ≤64 chars
|
|
74
74
|
// each, oldest-first, total ≤ 512 UTF-8 BYTES; excess
|
|
75
75
|
// advisory names are dropped whole, never chunked — the
|
|
76
|
-
// §4.5 #p= overflow form never triggers by construction
|
|
76
|
+
// §4.5 #p= overflow form never triggers by construction;
|
|
77
|
+
// a record whose label and agent are both absent has no
|
|
78
|
+
// identity to publish and is skipped, never replaced by a
|
|
79
|
+
// placeholder or a stringified absent value)
|
|
77
80
|
// Compatibility transport only: the consumer renders
|
|
78
81
|
// roles, never names. Null (clear) when the active
|
|
79
|
-
// TaskStore list has no
|
|
82
|
+
// TaskStore list has no names; null change tokens when the session model has
|
|
80
83
|
// zero changed files — refreshed/cleared from the live
|
|
81
84
|
// session model, never carried across sessions.
|
|
82
85
|
// gentle_ask_v1 = <hash>:<intentId>:<expiry>
|
|
@@ -728,6 +731,23 @@ const paneId = process.env.HERDR_PANE_ID;
|
|
|
728
731
|
|
|
729
732
|
const TTL_MS = 60000;
|
|
730
733
|
const BEAT_MS = 15000;
|
|
734
|
+
const BEAT_MIN_MS = 100;
|
|
735
|
+
const BEAT_MAX_MS = 300000;
|
|
736
|
+
const BEAT_ENV = "GENTLE_HERDR_BEAT_MS";
|
|
737
|
+
// Bounded budget of quiet beats a producer may publish while it has no work
|
|
738
|
+
// evidence and no host truth to settle on (`quietWithoutTruth` in the
|
|
739
|
+
// factory): three beats, one BEAT_MS each. See the comment there.
|
|
740
|
+
const QUIET_BEAT_LIMIT = 3;
|
|
741
|
+
// Consecutive beats a producer must see the lost-settle contradiction (it
|
|
742
|
+
// believes a turn is running, the host answers `isIdle() === true`, and
|
|
743
|
+
// nothing else keeps the session busy) before it applies the settle the host
|
|
744
|
+
// already reports (`reconcileSettled` in the factory). One beat is not enough:
|
|
745
|
+
// the host flips to idle at the very end of a run, so a genuine `agent_settled`
|
|
746
|
+
// can reach the producer one host tick later, and a single sample would repaint
|
|
747
|
+
// a still-settling turn as idle. Two consecutive samples — 30 s of
|
|
748
|
+
// host-confirmed idle at the 15 s beat — cannot be that race, and a lost edge
|
|
749
|
+
// still recovers within one beat period after the window closes.
|
|
750
|
+
const LOST_SETTLE_BEATS = 2;
|
|
731
751
|
// Synthesized finish signal (DESIGN §4.3, S2/D2). The host never reports
|
|
732
752
|
// `done`, so the producer mints the finish itself: one session-bound
|
|
733
753
|
// `<hash>:<expiry>` token per finish at the settled-and-empty edge, carrying
|
|
@@ -928,6 +948,20 @@ export function doneHoldMs(raw = process.env[DONE_HOLD_ENV]) {
|
|
|
928
948
|
return Math.min(DONE_HOLD_MAX_MS, Math.max(DONE_HOLD_MIN_MS, Math.round(parsed)));
|
|
929
949
|
}
|
|
930
950
|
|
|
951
|
+
// Beat cadence override, the same discipline as doneHoldMs: an absent or
|
|
952
|
+
// unparseable value keeps the 15 s default and anything outside the band is
|
|
953
|
+
// clamped, so a debugging session (or a test that cannot wait 15 s per beat)
|
|
954
|
+
// can shorten the beat without touching the 60 s token TTL or the transport's
|
|
955
|
+
// own 500/1500 ms bounds. The 100 ms floor keeps every beat far slower than a
|
|
956
|
+
// single send.
|
|
957
|
+
function beatMs(raw = process.env[BEAT_ENV]) {
|
|
958
|
+
const text = typeof raw === "string" ? raw.trim() : "";
|
|
959
|
+
if (text.length === 0) return BEAT_MS;
|
|
960
|
+
const parsed = Number(text);
|
|
961
|
+
if (!Number.isFinite(parsed)) return BEAT_MS;
|
|
962
|
+
return Math.min(BEAT_MAX_MS, Math.max(BEAT_MIN_MS, Math.round(parsed)));
|
|
963
|
+
}
|
|
964
|
+
|
|
931
965
|
// Cap a label at MAX_LABEL_CHARS UTF-16 units — the same unit the consumer's
|
|
932
966
|
// `parseNames` checks, so a label the producer writes is never one the
|
|
933
967
|
// consumer drops — while backing off one unit when the cut would split a
|
|
@@ -1137,6 +1171,15 @@ function cliFallback(patch) {
|
|
|
1137
1171
|
// unverified) and no new imports (self-contained single file). Do NOT
|
|
1138
1172
|
// reinstall the native publisher from Herdr: two publishers for the same
|
|
1139
1173
|
// pane collide (dual-publish).
|
|
1174
|
+
//
|
|
1175
|
+
// T2 (the pane must never freeze at `working`): the settle this owner gates on
|
|
1176
|
+
// is reconciled from the host's own live truth on every beat instead of being
|
|
1177
|
+
// inferred — including when a turn was seen to start but its settle edge was
|
|
1178
|
+
// lost, which needs a bounded window of contradictory beats rather than a
|
|
1179
|
+
// single sample; a quiet producer the host never confirms stops beating after a
|
|
1180
|
+
// bounded budget instead of republishing a count-0 work token forever; and the
|
|
1181
|
+
// settle-time pending latch stops counting once the finish hold that raised it
|
|
1182
|
+
// expires.
|
|
1140
1183
|
// ---------------------------------------------------------------------------
|
|
1141
1184
|
|
|
1142
1185
|
export const NATIVE_STATES = ["working", "blocked", "idle"];
|
|
@@ -1157,6 +1200,11 @@ const NATIVE_MAX_ATTEMPTS = 2;
|
|
|
1157
1200
|
// done/finished (only working|blocked|idle) and never a notification
|
|
1158
1201
|
// method — the host owns finished text plus toast/sound, and desktop ask
|
|
1159
1202
|
// attention (including toast dedup) is host-owned (DESIGN §7).
|
|
1203
|
+
//
|
|
1204
|
+
// The `settled` input is never inferred here: the beat reconciles it from the
|
|
1205
|
+
// host's own live truth (`ctx.isIdle()`), so a missed `agent_settled` cannot
|
|
1206
|
+
// leave this producer unable to reach `idle` — not when no turn was observed,
|
|
1207
|
+
// and not when a turn this producer saw start never delivered its settle edge.
|
|
1160
1208
|
export function computeNativeState({
|
|
1161
1209
|
agentActive,
|
|
1162
1210
|
settled,
|
|
@@ -2438,17 +2486,21 @@ async function applyCustomizeSwitch(id, value, ctx) {
|
|
|
2438
2486
|
if (result.needsReload && typeof ctx?.reload === "function") await ctx.reload();
|
|
2439
2487
|
}
|
|
2440
2488
|
|
|
2441
|
-
// The single apply path shared by the overlay and the menu fallback.
|
|
2442
|
-
//
|
|
2443
|
-
//
|
|
2444
|
-
//
|
|
2445
|
-
//
|
|
2446
|
-
//
|
|
2447
|
-
|
|
2448
|
-
|
|
2449
|
-
|
|
2489
|
+
// The single apply path shared by the overlay and the menu fallback. The choice
|
|
2490
|
+
// the panel resolves names the switch it drives (`switchId`) and the value to
|
|
2491
|
+
// apply; that switch id is the only thing read here, so a row can never apply a
|
|
2492
|
+
// switch its category does not own. An inconclusive sidebar verdict is never a
|
|
2493
|
+
// refusal: choosing On still attempts the repair and reports the apply step's
|
|
2494
|
+
// own error, exactly like the baseline menu did.
|
|
2495
|
+
const CUSTOMIZE_SWITCH_IDS = ["sidebar", "moshi"];
|
|
2496
|
+
|
|
2497
|
+
async function applyCustomizeChoice(choice, ctx) {
|
|
2498
|
+
if (!isRecord(choice)) return;
|
|
2499
|
+
const switchId = choice.switchId;
|
|
2500
|
+
const valueId = choice.valueId;
|
|
2501
|
+
if (!CUSTOMIZE_SWITCH_IDS.includes(switchId)) return;
|
|
2450
2502
|
if (valueId !== "on" && valueId !== "off") return;
|
|
2451
|
-
await applyCustomizeSwitch(
|
|
2503
|
+
await applyCustomizeSwitch(switchId, valueId, ctx);
|
|
2452
2504
|
}
|
|
2453
2505
|
|
|
2454
2506
|
// The former plain menu, kept as the fallback when the TUI helpers or
|
|
@@ -2477,7 +2529,7 @@ async function runCustomizeFallback(ctx) {
|
|
|
2477
2529
|
choice = undefined;
|
|
2478
2530
|
}
|
|
2479
2531
|
if (choice !== CUSTOMIZE_ON && choice !== CUSTOMIZE_OFF) return;
|
|
2480
|
-
await applyCustomizeChoice(id, choice === CUSTOMIZE_ON ? "on" : "off", ctx);
|
|
2532
|
+
await applyCustomizeChoice({ switchId: id, valueId: choice === CUSTOMIZE_ON ? "on" : "off" }, ctx);
|
|
2481
2533
|
}
|
|
2482
2534
|
|
|
2483
2535
|
async function executeCustomize(rawArgs, ctx) {
|
|
@@ -2548,7 +2600,7 @@ async function executeCustomize(rawArgs, ctx) {
|
|
|
2548
2600
|
// Esc (null) does nothing at all: no notification, no write, no reload.
|
|
2549
2601
|
// Anything else runs the single apply path once the overlay is disposed.
|
|
2550
2602
|
if (!choice || typeof choice !== "object") return;
|
|
2551
|
-
await applyCustomizeChoice(choice
|
|
2603
|
+
await applyCustomizeChoice(choice, ctx);
|
|
2552
2604
|
return;
|
|
2553
2605
|
}
|
|
2554
2606
|
await runCustomizeFallback(ctx);
|
|
@@ -2590,7 +2642,7 @@ export default function (pi) {
|
|
|
2590
2642
|
// Finished/failed/cancelled/waiting entries may linger in the map but
|
|
2591
2643
|
// never count; the map is cleared only on session reset (plus the
|
|
2592
2644
|
// bounded-map guard) — never by a local staleness timeout.
|
|
2593
|
-
const pendingCalls = new Map(); // toolCallId -> { agent, label, at }
|
|
2645
|
+
const pendingCalls = new Map(); // toolCallId -> { agent, label, at }; agent/label are undefined when no agent is resolvable
|
|
2594
2646
|
const tasks = new Map(); // taskId -> { agent, label, status, at }
|
|
2595
2647
|
|
|
2596
2648
|
// Blocker legs. ask combines choice + native questionnaire + legacy
|
|
@@ -2628,6 +2680,10 @@ export default function (pi) {
|
|
|
2628
2680
|
// opened the current ask episode.
|
|
2629
2681
|
let moshiContext;
|
|
2630
2682
|
let moshiCtxRef;
|
|
2683
|
+
// Last context the host handed us, retained so a beat can ask the host's own
|
|
2684
|
+
// live truth (`isIdle()`) instead of inferring a settle. Kept apart from
|
|
2685
|
+
// `moshiCtxRef`, whose capture leg owns that reference.
|
|
2686
|
+
let settleCtx;
|
|
2631
2687
|
let lastAskToolName;
|
|
2632
2688
|
|
|
2633
2689
|
// Live background jobs (Gentle Shell `bash_background` / `monitor`) from the
|
|
@@ -2687,6 +2743,7 @@ export default function (pi) {
|
|
|
2687
2743
|
// freshness bound measures from.
|
|
2688
2744
|
function onJobsSnapshot(value) {
|
|
2689
2745
|
if (!isRecord(value) || !isRecord(value.snapshot) || !Array.isArray(value.snapshot.jobs)) return;
|
|
2746
|
+
noteActivity();
|
|
2690
2747
|
const jobs = value.snapshot.jobs.filter(
|
|
2691
2748
|
(entry) => isRecord(entry) && typeof entry.id === "string" && entry.id.length > 0,
|
|
2692
2749
|
);
|
|
@@ -2823,6 +2880,13 @@ export default function (pi) {
|
|
|
2823
2880
|
let presenceReconciler = createPresenceReconciler();
|
|
2824
2881
|
let transportFails = 0;
|
|
2825
2882
|
let beatTimer;
|
|
2883
|
+
// Consecutive quiet beats published without host truth (see
|
|
2884
|
+
// `quietWithoutTruth`); bounded by QUIET_BEAT_LIMIT and reset by work.
|
|
2885
|
+
let quietBeats = 0;
|
|
2886
|
+
// Consecutive beats that contradict a turn this producer saw start (see
|
|
2887
|
+
// `lostSettleContradiction`); bounded by LOST_SETTLE_BEATS and reset by any
|
|
2888
|
+
// activity edge.
|
|
2889
|
+
let lostSettleBeats = 0;
|
|
2826
2890
|
let publishQueued = false;
|
|
2827
2891
|
let publishInFlight = false;
|
|
2828
2892
|
// Native owner queue (always on): monotonic seq per logical report,
|
|
@@ -2845,7 +2909,17 @@ export default function (pi) {
|
|
|
2845
2909
|
// beat arriving mid-send is describing.
|
|
2846
2910
|
let nativeSending = null;
|
|
2847
2911
|
let nativeLastOk = undefined;
|
|
2912
|
+
// T2 native-only terminal guard: agent_settled clears the metadata
|
|
2913
|
+
// pending-launch hint below, but a settle that observes in-flight launches
|
|
2914
|
+
// retains pending evidence here so native idle gating stays working until
|
|
2915
|
+
// those launches resolve. Metadata/tasks untouched; the guard clears when a
|
|
2916
|
+
// launch resolves, on agent_start, with the session, and — when a launch
|
|
2917
|
+
// never reports back — at `nativeSettledPendingUntil`, the finish-hold
|
|
2918
|
+
// deadline of the settle that raised it. Past that hold the evidence stops
|
|
2919
|
+
// counting, so a lost launch result can never pin the native report at
|
|
2920
|
+
// `working` for good (seq itself never resets).
|
|
2848
2921
|
let nativeSettledPending = false;
|
|
2922
|
+
let nativeSettledPendingUntil = 0;
|
|
2849
2923
|
// Finish-hold episode (S2): minted once at the settled-and-empty edge so the
|
|
2850
2924
|
// row reads `done`, then republished unchanged (never refreshed) until the
|
|
2851
2925
|
// hold expires. `donePending` carries the unannounced finish to the beat
|
|
@@ -2855,6 +2929,12 @@ export default function (pi) {
|
|
|
2855
2929
|
let doneExpiry;
|
|
2856
2930
|
let donePending = false;
|
|
2857
2931
|
let sawActivity = false;
|
|
2932
|
+
// Whether the settle this row sits in came from an observed turn
|
|
2933
|
+
// (`agent_settled`) rather than from the host-truth reconcile: only an
|
|
2934
|
+
// observed turn can mint a finish, so non-turn activity (an ask, a review, a
|
|
2935
|
+
// job) on a producer that never saw a turn can never announce `done` or the
|
|
2936
|
+
// phone's `task_complete`.
|
|
2937
|
+
let turnSettled = false;
|
|
2858
2938
|
// LIVE-1 startup latency: the session binding is still INITIATED on
|
|
2859
2939
|
// session_start (so Herdr can attribute the pane from the first frame), but
|
|
2860
2940
|
// the host no longer waits for it. The host awaits every session_start
|
|
@@ -2864,12 +2944,117 @@ export default function (pi) {
|
|
|
2864
2944
|
// unchanged, only the host's startup return is freed. Reset with the session
|
|
2865
2945
|
// so a stale binding can never gate the next one.
|
|
2866
2946
|
let sessionReportPending = null;
|
|
2867
|
-
|
|
2868
|
-
//
|
|
2869
|
-
//
|
|
2870
|
-
//
|
|
2871
|
-
|
|
2872
|
-
|
|
2947
|
+
|
|
2948
|
+
// Retain the host context the settle reconcile reads (`isIdle()`), next to
|
|
2949
|
+
// the Moshi capture reference it already replaced. A lifecycle event that
|
|
2950
|
+
// arrives without a context must not erase the last truth we hold.
|
|
2951
|
+
function retainContext(ctx) {
|
|
2952
|
+
moshiCtxRef = ctx;
|
|
2953
|
+
if (ctx) settleCtx = ctx;
|
|
2954
|
+
}
|
|
2955
|
+
|
|
2956
|
+
function clearSettledPending() {
|
|
2957
|
+
nativeSettledPending = false;
|
|
2958
|
+
nativeSettledPendingUntil = 0;
|
|
2959
|
+
}
|
|
2960
|
+
|
|
2961
|
+
// Past the finish hold of the settle that raised it, the retained pending
|
|
2962
|
+
// evidence stops counting: the hold is the span it exists to cover.
|
|
2963
|
+
function settledPendingHeld() {
|
|
2964
|
+
return nativeSettledPending && Date.now() < nativeSettledPendingUntil;
|
|
2965
|
+
}
|
|
2966
|
+
|
|
2967
|
+
// The settle state `agent_settled` applies, shared with the reconcile below
|
|
2968
|
+
// so both paths agree on every field except the finish episode.
|
|
2969
|
+
function applySettled(fromTurn) {
|
|
2970
|
+
agentActive = false;
|
|
2971
|
+
settled = true;
|
|
2972
|
+
turnSettled = fromTurn === true;
|
|
2973
|
+
lostSettleBeats = 0;
|
|
2974
|
+
clearSettledPending();
|
|
2975
|
+
}
|
|
2976
|
+
|
|
2977
|
+
// Every activity edge restarts the lost-settle window: a tool call, a
|
|
2978
|
+
// delegate, a job, an ask/review/error leg (the contradiction predicate reads
|
|
2979
|
+
// those legs directly) or a new `agent_start`. Only consecutive beats that
|
|
2980
|
+
// still contradict the host may settle.
|
|
2981
|
+
function noteActivity() {
|
|
2982
|
+
lostSettleBeats = 0;
|
|
2983
|
+
}
|
|
2984
|
+
|
|
2985
|
+
// Nothing observable keeps this session busy: no authoritative
|
|
2986
|
+
// running|queued delegate, no launch in flight, no live background job.
|
|
2987
|
+
// `agentActive` is not part of this evidence: it is this producer's own
|
|
2988
|
+
// inference from turn events, so the reconcile guards it separately and
|
|
2989
|
+
// never overrides a turn it saw start.
|
|
2990
|
+
function noWorkEvidence() {
|
|
2991
|
+
return (
|
|
2992
|
+
activeSubs().length === 0 &&
|
|
2993
|
+
pendingCalls.size === 0 &&
|
|
2994
|
+
freshRunningJobCount() === 0
|
|
2995
|
+
);
|
|
2996
|
+
}
|
|
2997
|
+
|
|
2998
|
+
// Live host truth for the settle decision: the retained context's `isIdle()`.
|
|
2999
|
+
// `undefined` means the host offers no truth (no context yet, or one without
|
|
3000
|
+
// the method); `false` means the host still considers the agent busy, which
|
|
3001
|
+
// is never this producer's to override.
|
|
3002
|
+
function hostIdleTruth() {
|
|
3003
|
+
const probe = settleCtx?.isIdle;
|
|
3004
|
+
if (typeof probe !== "function") return undefined;
|
|
3005
|
+
try {
|
|
3006
|
+
return probe.call(settleCtx) === true;
|
|
3007
|
+
} catch {
|
|
3008
|
+
return undefined;
|
|
3009
|
+
}
|
|
3010
|
+
}
|
|
3011
|
+
|
|
3012
|
+
// The lost-settle contradiction: this producer still believes its turn runs,
|
|
3013
|
+
// the host answers that nothing is processing, and no work evidence or
|
|
3014
|
+
// owning leg keeps the session busy. Both sides are live truth re-read on
|
|
3015
|
+
// every beat, so the contradiction is never remembered from a stale sample.
|
|
3016
|
+
function lostSettleContradiction() {
|
|
3017
|
+
return (
|
|
3018
|
+
agentActive &&
|
|
3019
|
+
hostIdleTruth() === true &&
|
|
3020
|
+
noWorkEvidence() &&
|
|
3021
|
+
!askActiveNow() &&
|
|
3022
|
+
!reviewActive &&
|
|
3023
|
+
errorCode === undefined
|
|
3024
|
+
);
|
|
3025
|
+
}
|
|
3026
|
+
|
|
3027
|
+
// Recover a settle this producer missed. `settled` flips only in
|
|
3028
|
+
// `agent_settled`, which early-returns unless the host already reports idle,
|
|
3029
|
+
// so a session first observed while idle — or an aborted or failed run whose
|
|
3030
|
+
// `agent_settled` never arrived — leaves `settled` false: `computeNativeState`
|
|
3031
|
+
// returns undefined and the pane keeps the last native `working`. The host
|
|
3032
|
+
// answers the same question `agent_settled` asks, so read its live truth here
|
|
3033
|
+
// instead of inferring a terminal from a timeout or from a count.
|
|
3034
|
+
function reconcileSettled() {
|
|
3035
|
+
if (!rootSession || settled) return;
|
|
3036
|
+
// No turn edge was ever observed: nothing local contradicts the host, so
|
|
3037
|
+
// its answer settles the producer on the same beat.
|
|
3038
|
+
if (!agentActive) {
|
|
3039
|
+
if (!noWorkEvidence()) return;
|
|
3040
|
+
if (hostIdleTruth() !== true) return;
|
|
3041
|
+
applySettled(false);
|
|
3042
|
+
return;
|
|
3043
|
+
}
|
|
3044
|
+
// A turn the producer itself saw start is local evidence of a running
|
|
3045
|
+
// agent, and `isIdle()` turns true at the end of the run — so a genuine
|
|
3046
|
+
// settle edge can still be in flight. Only a bounded window of consecutive
|
|
3047
|
+
// contradictory beats proves the edge was lost.
|
|
3048
|
+
if (!lostSettleContradiction()) {
|
|
3049
|
+
lostSettleBeats = 0;
|
|
3050
|
+
return;
|
|
3051
|
+
}
|
|
3052
|
+
lostSettleBeats += 1;
|
|
3053
|
+
if (lostSettleBeats < LOST_SETTLE_BEATS) return;
|
|
3054
|
+
// `fromTurn` false: a recovered settle is never a turn, so it can mint no
|
|
3055
|
+
// finish episode (no `gentle_done_v1`, no finish notification).
|
|
3056
|
+
applySettled(false);
|
|
3057
|
+
}
|
|
2873
3058
|
|
|
2874
3059
|
function refreshSessionRef(ctx) {
|
|
2875
3060
|
try {
|
|
@@ -3082,7 +3267,20 @@ export default function (pi) {
|
|
|
3082
3267
|
const parts = [];
|
|
3083
3268
|
let length = 0;
|
|
3084
3269
|
for (const sub of subs) {
|
|
3085
|
-
|
|
3270
|
+
// An entry whose label and agent are both absent has no name to publish:
|
|
3271
|
+
// a record can carry no identity at all (an observation without an agent
|
|
3272
|
+
// and no previous record), and `sanitizeLabel` stringifies whatever
|
|
3273
|
+
// fallback it is handed, so passing the absence through would put the
|
|
3274
|
+
// literal `undefined` on the wire as a name.
|
|
3275
|
+
const label =
|
|
3276
|
+
typeof sub.label === "string" && sub.label.length > 0 ? sub.label : undefined;
|
|
3277
|
+
const subAgent =
|
|
3278
|
+
typeof sub.agent === "string" && sub.agent.length > 0 ? sub.agent : undefined;
|
|
3279
|
+
if (label === undefined && subAgent === undefined) continue;
|
|
3280
|
+
// Label first, agent as fallback, unchanged for every entry that has
|
|
3281
|
+
// either; the fallback is never absent here, so the sanitizer always has
|
|
3282
|
+
// a real string to fall back to.
|
|
3283
|
+
const name = sanitizeLabel(label, subAgent ?? label);
|
|
3086
3284
|
if (parts.includes(name)) continue;
|
|
3087
3285
|
const add = (parts.length === 0 ? 0 : 1) + utf8Bytes(name);
|
|
3088
3286
|
if (length + add > MAX_TOKEN_BYTES) break;
|
|
@@ -3130,11 +3328,15 @@ export default function (pi) {
|
|
|
3130
3328
|
) {
|
|
3131
3329
|
return "rdd";
|
|
3132
3330
|
}
|
|
3133
|
-
// The bare visible
|
|
3134
|
-
// exactly equal to
|
|
3135
|
-
// in metadata roles and the native message alike.
|
|
3331
|
+
// The bare visible words `working`, `subagent`, and `gentle` are banned: a
|
|
3332
|
+
// sanitized unknown slug exactly equal to one of them degrades to no role
|
|
3333
|
+
// (generic `gentle`) in metadata roles and the native message alike.
|
|
3334
|
+
// `subagent` is the launch-correlation placeholder, never an agent name, so
|
|
3335
|
+
// it must never reach the wire as a role word. `gentle` is the pink
|
|
3336
|
+
// generic's own word (S1), so an agent literally named `gentle` must not
|
|
3337
|
+
// become a second one on the amber cell.
|
|
3136
3338
|
const slug = sanitizeAgentSlug(agent);
|
|
3137
|
-
return slug === "working" ? undefined : slug;
|
|
3339
|
+
return slug === "working" || slug === "subagent" || slug === "gentle" ? undefined : slug;
|
|
3138
3340
|
}
|
|
3139
3341
|
|
|
3140
3342
|
// Bounded CSV of role words, oldest-first (subs already arrive
|
|
@@ -3278,7 +3480,7 @@ export default function (pi) {
|
|
|
3278
3480
|
sawActivity = true;
|
|
3279
3481
|
doneExpiry = undefined;
|
|
3280
3482
|
donePending = false;
|
|
3281
|
-
} else if (settled) {
|
|
3483
|
+
} else if (settled && turnSettled) {
|
|
3282
3484
|
if (doneExpiry === undefined && sawActivity) {
|
|
3283
3485
|
doneExpiry = Date.now() + doneHoldMs();
|
|
3284
3486
|
donePending = true;
|
|
@@ -3349,16 +3551,73 @@ export default function (pi) {
|
|
|
3349
3551
|
if (beatTimer || !rootSession) return;
|
|
3350
3552
|
if (!interesting() && settled) return;
|
|
3351
3553
|
beatTimer = setInterval(() => {
|
|
3554
|
+
// A tick with nothing interesting to publish has nothing to do. Stopping
|
|
3555
|
+
// here (instead of only after a landed publish) is what keeps a slow
|
|
3556
|
+
// send from re-arming the interval through `publishQueued` and spinning
|
|
3557
|
+
// a beat nobody needs.
|
|
3558
|
+
if (!interesting()) {
|
|
3559
|
+
stopBeat();
|
|
3560
|
+
return;
|
|
3561
|
+
}
|
|
3562
|
+
// T2 quiet bound: a beat with no work evidence, no host truth, and no
|
|
3563
|
+
// leg that still owns the row has nothing confirmed to publish — every
|
|
3564
|
+
// such beat republishes a fresh count-0 `gentle_work_v1`, and that
|
|
3565
|
+
// eternal fresh work token is what keeps the row from ever reaching
|
|
3566
|
+
// idle. The beat spends a bounded budget of quiet beats (one BEAT_MS
|
|
3567
|
+
// each) and then stops. Stopping is the honest outcome: a native state
|
|
3568
|
+
// the host never confirmed must not be published in its place. The
|
|
3569
|
+
// bound never applies to a turn this producer saw start (see
|
|
3570
|
+
// `quietWithoutTruth`), so it cannot leave live work unpainted; the
|
|
3571
|
+
// edges that schedule a publish (ask, review, launch, session changes,
|
|
3572
|
+
// jobs) re-arm the beat, while an ordinary tool edge reaches the row
|
|
3573
|
+
// through the host's own truth rather than by re-arming it.
|
|
3574
|
+
if (quietWithoutTruth()) {
|
|
3575
|
+
quietBeats += 1;
|
|
3576
|
+
if (quietBeats >= QUIET_BEAT_LIMIT) {
|
|
3577
|
+
stopBeat();
|
|
3578
|
+
return;
|
|
3579
|
+
}
|
|
3580
|
+
} else {
|
|
3581
|
+
quietBeats = 0;
|
|
3582
|
+
}
|
|
3352
3583
|
void publishNow();
|
|
3353
|
-
},
|
|
3584
|
+
}, beatMs());
|
|
3354
3585
|
if (beatTimer.unref) beatTimer.unref();
|
|
3355
3586
|
}
|
|
3356
3587
|
|
|
3588
|
+
function stopBeat() {
|
|
3589
|
+
if (!beatTimer) return;
|
|
3590
|
+
clearInterval(beatTimer);
|
|
3591
|
+
beatTimer = undefined;
|
|
3592
|
+
}
|
|
3593
|
+
|
|
3357
3594
|
function maybeStopBeat() {
|
|
3358
|
-
if (beatTimer && !interesting())
|
|
3359
|
-
|
|
3360
|
-
|
|
3361
|
-
|
|
3595
|
+
if (beatTimer && !interesting()) stopBeat();
|
|
3596
|
+
}
|
|
3597
|
+
|
|
3598
|
+
// T2 quiet bound predicate (see the budget applied inside `ensureBeat`): the
|
|
3599
|
+
// host offers no truth at all, nothing is active by evidence, and no leg
|
|
3600
|
+
// still owns the row. A host that answers `false` is not quiet — it says the
|
|
3601
|
+
// agent is still running — and a host that answers `true` settles through
|
|
3602
|
+
// `reconcileSettled` instead. No native state is ever inferred here.
|
|
3603
|
+
//
|
|
3604
|
+
// `agentActive` is excluded on purpose: a turn this producer saw start is
|
|
3605
|
+
// live work, and the host offers no way to confirm its settle. Bounding that
|
|
3606
|
+
// beat would stop painting a running turn, which is exactly the pin the bound
|
|
3607
|
+
// exists to avoid (S2) — the bound must never trade a truthful "still
|
|
3608
|
+
// working" for a false `idle`. It therefore covers only a producer with no
|
|
3609
|
+
// observed turn behind it and no host truth to settle on.
|
|
3610
|
+
function quietWithoutTruth() {
|
|
3611
|
+
return (
|
|
3612
|
+
!agentActive &&
|
|
3613
|
+
!settled &&
|
|
3614
|
+
hostIdleTruth() === undefined &&
|
|
3615
|
+
noWorkEvidence() &&
|
|
3616
|
+
!askActiveNow() &&
|
|
3617
|
+
!reviewActive &&
|
|
3618
|
+
errorCode === undefined &&
|
|
3619
|
+
doneExpiry === undefined
|
|
3620
|
+
);
|
|
3362
3621
|
}
|
|
3363
3622
|
|
|
3364
3623
|
// N1 parity report: state + message. Working carries the SPECIFIC
|
|
@@ -3385,7 +3644,7 @@ export default function (pi) {
|
|
|
3385
3644
|
agentActive,
|
|
3386
3645
|
settled,
|
|
3387
3646
|
activeCount: activeSubs().length,
|
|
3388
|
-
pendingCount: pendingCalls.size + (
|
|
3647
|
+
pendingCount: pendingCalls.size + (settledPendingHeld() ? 1 : 0),
|
|
3389
3648
|
askActive: askActiveNow(),
|
|
3390
3649
|
reviewActive,
|
|
3391
3650
|
});
|
|
@@ -3600,6 +3859,9 @@ export default function (pi) {
|
|
|
3600
3859
|
// flight publishes nothing: `rootSession` is re-read after the wait.
|
|
3601
3860
|
await awaitSessionBinding();
|
|
3602
3861
|
if (!rootSession || !sidebarPublishingEnabled()) return;
|
|
3862
|
+
// Host truth first: a settle this producer missed must be visible to both
|
|
3863
|
+
// the native report and the tokens built below.
|
|
3864
|
+
reconcileSettled();
|
|
3603
3865
|
reconcilePresence();
|
|
3604
3866
|
queueNative();
|
|
3605
3867
|
const tokens = buildTokens();
|
|
@@ -3751,10 +4013,11 @@ export default function (pi) {
|
|
|
3751
4013
|
nativePending = null;
|
|
3752
4014
|
nativeSending = null;
|
|
3753
4015
|
nativeLastOk = undefined;
|
|
3754
|
-
|
|
4016
|
+
clearSettledPending();
|
|
3755
4017
|
doneExpiry = undefined;
|
|
3756
4018
|
donePending = false;
|
|
3757
4019
|
sawActivity = false;
|
|
4020
|
+
turnSettled = false;
|
|
3758
4021
|
jobsSnapshot = undefined;
|
|
3759
4022
|
clearJobsExpiry();
|
|
3760
4023
|
errorCode = undefined;
|
|
@@ -3764,9 +4027,13 @@ export default function (pi) {
|
|
|
3764
4027
|
liveQueued = false;
|
|
3765
4028
|
sessionReportPending = null;
|
|
3766
4029
|
sessionCwd = undefined;
|
|
4030
|
+
settleCtx = undefined;
|
|
4031
|
+
quietBeats = 0;
|
|
4032
|
+
lostSettleBeats = 0;
|
|
3767
4033
|
changes = { files: 0, added: 0, deleted: 0 };
|
|
3768
4034
|
agentActive = false;
|
|
3769
4035
|
settled = false;
|
|
4036
|
+
turnSettled = false;
|
|
3770
4037
|
}
|
|
3771
4038
|
|
|
3772
4039
|
function clearEmittedLabel() {
|
|
@@ -3821,6 +4088,7 @@ export default function (pi) {
|
|
|
3821
4088
|
|
|
3822
4089
|
pi.on("tool_execution_start", (event) => {
|
|
3823
4090
|
if (!rootSession || !isRecord(event) || typeof event.toolCallId !== "string") return;
|
|
4091
|
+
noteActivity();
|
|
3824
4092
|
runningTools.add(event.toolCallId);
|
|
3825
4093
|
// Structured ask tools open ONLY on genuine execution (never on
|
|
3826
4094
|
// `tool_call` proposal), keyed by call id so the matching end or
|
|
@@ -3923,17 +4191,30 @@ export default function (pi) {
|
|
|
3923
4191
|
|
|
3924
4192
|
// -- subagent activity -----------------------------------------------------
|
|
3925
4193
|
|
|
4194
|
+
// `subagent_run` carries the agent in its input, but `subagent_continue`
|
|
4195
|
+
// carries only `task_id`/`prompt`/`label`/`mode`: a resume names the task
|
|
4196
|
+
// whose record already holds the child's agent. Neither source means no
|
|
4197
|
+
// role evidence at all — the pending call still covers the blocking/
|
|
4198
|
+
// orchestrating marker, but it contributes no role and no name, and it
|
|
4199
|
+
// must never publish the launch-correlation placeholder as a role word.
|
|
3926
4200
|
function launchInput(input) {
|
|
3927
4201
|
if (!isRecord(input)) return undefined;
|
|
3928
|
-
const
|
|
3929
|
-
const
|
|
3930
|
-
|
|
4202
|
+
const taskId = typeof input.task_id === "string" ? input.task_id : undefined;
|
|
4203
|
+
const inputAgent =
|
|
4204
|
+
typeof input.agent === "string" && input.agent.length > 0 ? input.agent : undefined;
|
|
4205
|
+
const agent =
|
|
4206
|
+
inputAgent ?? (taskId !== undefined ? tasks.get(taskId)?.agent : undefined);
|
|
4207
|
+
const labelSource =
|
|
4208
|
+
typeof input.label === "string" && input.label.length > 0 ? input.label : agent;
|
|
4209
|
+
const label = labelSource === undefined ? undefined : sanitizeLabel(labelSource, labelSource);
|
|
4210
|
+
return { agent: agent === undefined ? undefined : truncateChars(agent, MAX_LABEL_CHARS), label };
|
|
3931
4211
|
}
|
|
3932
4212
|
|
|
3933
4213
|
pi.on("tool_call", (event) => {
|
|
3934
4214
|
if (!rootSession || !isRecord(event) || typeof event.toolName !== "string") return;
|
|
3935
4215
|
// A tool starting proves a run is alive: an error left over from a run that
|
|
3936
4216
|
// already died is released here rather than sticking until the next turn.
|
|
4217
|
+
noteActivity();
|
|
3937
4218
|
clearRunError();
|
|
3938
4219
|
// Structured ask proposals never open ask (execution does); subagent
|
|
3939
4220
|
// launch correlation below is unchanged.
|
|
@@ -3963,6 +4244,7 @@ export default function (pi) {
|
|
|
3963
4244
|
|
|
3964
4245
|
pi.on("tool_result", (event) => {
|
|
3965
4246
|
if (!rootSession || !isRecord(event) || typeof event.toolName !== "string") return;
|
|
4247
|
+
noteActivity();
|
|
3966
4248
|
clearRunError();
|
|
3967
4249
|
if (typeof event.toolCallId === "string" && askToolCalls.delete(event.toolCallId)) {
|
|
3968
4250
|
updateBlocker();
|
|
@@ -3979,7 +4261,7 @@ export default function (pi) {
|
|
|
3979
4261
|
// outcome is now covered by the task record (working via activeSubs),
|
|
3980
4262
|
// the error latch (blocked), or genuine emptiness (idle on next beat).
|
|
3981
4263
|
if (event.toolName === "subagent_run" || event.toolName === "subagent_continue") {
|
|
3982
|
-
|
|
4264
|
+
clearSettledPending();
|
|
3983
4265
|
}
|
|
3984
4266
|
if (typeof event.toolCallId === "string" ? reviewCalls.delete(event.toolCallId) : false) {
|
|
3985
4267
|
// The ended id was a known acknowledged execution; remaining tracked
|
|
@@ -4051,10 +4333,13 @@ export default function (pi) {
|
|
|
4051
4333
|
: undefined;
|
|
4052
4334
|
// A stale read's agent is distrusted with its status, and a missing
|
|
4053
4335
|
// agent keeps the previous record's agent (never reset to a guess).
|
|
4336
|
+
// With neither source the record has no agent at all: `subagent` is the
|
|
4337
|
+
// launch-correlation placeholder, never an identity, so inventing it here
|
|
4338
|
+
// would publish that word as the record's name.
|
|
4054
4339
|
const agent =
|
|
4055
4340
|
staleRead && previous?.agent
|
|
4056
4341
|
? previous.agent
|
|
4057
|
-
: (incomingAgent ?? previous?.agent
|
|
4342
|
+
: (incomingAgent ?? previous?.agent);
|
|
4058
4343
|
const now = Date.now();
|
|
4059
4344
|
tasks.set(details.taskId, {
|
|
4060
4345
|
agent,
|
|
@@ -4086,6 +4371,7 @@ export default function (pi) {
|
|
|
4086
4371
|
// never passes through `tool_result` details.
|
|
4087
4372
|
pi.on("message_end", (event) => {
|
|
4088
4373
|
if (!rootSession || !isRecord(event)) return;
|
|
4374
|
+
noteActivity();
|
|
4089
4375
|
const message = event.message;
|
|
4090
4376
|
if (!isRecord(message)) return;
|
|
4091
4377
|
if (message.role === "assistant") {
|
|
@@ -4105,10 +4391,13 @@ export default function (pi) {
|
|
|
4105
4391
|
if (typeof details.status !== "string") return;
|
|
4106
4392
|
if (!FINAL_TASK.has(details.status) && !ACTIVE_TASK.has(details.status)) return;
|
|
4107
4393
|
const previous = tasks.get(details.taskId);
|
|
4394
|
+
// Same rule as the tool_result path: an observation without an agent keeps
|
|
4395
|
+
// the previous record's agent, and with neither there is no agent at all —
|
|
4396
|
+
// the launch-correlation placeholder must never become a record identity.
|
|
4108
4397
|
const agent =
|
|
4109
4398
|
typeof details.agent === "string" && details.agent.length > 0
|
|
4110
4399
|
? truncateChars(details.agent, MAX_LABEL_CHARS)
|
|
4111
|
-
:
|
|
4400
|
+
: previous?.agent;
|
|
4112
4401
|
// Record identity is immutable per taskId: firstSeen never moves (T2b
|
|
4113
4402
|
// ordering only) whether this observation promotes a background start
|
|
4114
4403
|
// or replaces the record with its terminal status; completion still
|
|
@@ -4145,7 +4434,7 @@ export default function (pi) {
|
|
|
4145
4434
|
rootSession = true;
|
|
4146
4435
|
sessionManager = ctx.sessionManager;
|
|
4147
4436
|
refreshSessionRef(ctx);
|
|
4148
|
-
|
|
4437
|
+
retainContext(ctx);
|
|
4149
4438
|
if (moshiEnabled()) moshiEnsureContext();
|
|
4150
4439
|
// LIVE-1: bind the session before any state beat so Herdr attributes the
|
|
4151
4440
|
// pane from the first frame (mirrors the managed publisher). The binding is
|
|
@@ -4163,14 +4452,17 @@ export default function (pi) {
|
|
|
4163
4452
|
pi.on("agent_start", (_event, ctx) => {
|
|
4164
4453
|
if (!rootSession) return;
|
|
4165
4454
|
refreshSessionRef(ctx);
|
|
4166
|
-
|
|
4455
|
+
retainContext(ctx);
|
|
4167
4456
|
// LIVE-1: re-bind the session like the managed publisher did, so a
|
|
4168
4457
|
// restart or re-announcement never leaves the pane binding-less while
|
|
4169
4458
|
// metadata beats flow.
|
|
4170
4459
|
void reportSession();
|
|
4171
4460
|
agentActive = true;
|
|
4172
4461
|
settled = false;
|
|
4173
|
-
|
|
4462
|
+
turnSettled = false;
|
|
4463
|
+
clearSettledPending();
|
|
4464
|
+
quietBeats = 0;
|
|
4465
|
+
noteActivity();
|
|
4174
4466
|
clearRunError();
|
|
4175
4467
|
refreshChanges();
|
|
4176
4468
|
schedulePublish();
|
|
@@ -4178,13 +4470,17 @@ export default function (pi) {
|
|
|
4178
4470
|
|
|
4179
4471
|
pi.on("agent_settled", (_event, ctx) => {
|
|
4180
4472
|
if (!rootSession || ctx?.isIdle?.() !== true) return;
|
|
4181
|
-
|
|
4182
|
-
agentActive = false;
|
|
4183
|
-
settled = true;
|
|
4473
|
+
retainContext(ctx);
|
|
4184
4474
|
// Retain settle-time pending evidence for native gating before the
|
|
4185
|
-
// metadata hint clears (see nativeSettledPending above)
|
|
4186
|
-
|
|
4475
|
+
// metadata hint clears (see nativeSettledPending above), bounded by the
|
|
4476
|
+
// finish hold this settle opens.
|
|
4477
|
+
const pendingAtSettle = pendingCalls.size > 0;
|
|
4187
4478
|
pendingCalls.clear();
|
|
4479
|
+
applySettled(true);
|
|
4480
|
+
if (pendingAtSettle) {
|
|
4481
|
+
nativeSettledPending = true;
|
|
4482
|
+
nativeSettledPendingUntil = Date.now() + doneHoldMs();
|
|
4483
|
+
}
|
|
4188
4484
|
// S62 turn-end: the working tree may have changed without transcript
|
|
4189
4485
|
// evidence (external/untracked edits), so re-scan before publishing.
|
|
4190
4486
|
refreshChanges();
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "herdr-gentle-shell",
|
|
3
|
-
"version": "1.5.
|
|
3
|
+
"version": "1.5.2",
|
|
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",
|