herdr-gentle-shell 1.5.0 → 1.5.1

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 CHANGED
@@ -804,6 +804,10 @@ gentle-ai concern and explicitly out of scope for this plugin.
804
804
  the poll after the native one for the same question, a systematic
805
805
  duplication. The ask token still drives the sidebar ask display; sounds,
806
806
  suppression, and delay stay Herdr's.
807
+ - Herdr's own done/ask attention — the finished and needs-attention pop-ups and
808
+ their sound — is Herdr's native behavior, configured in Herdr itself (its
809
+ config and its settings). This package deliberately offers no switch for it;
810
+ its only notification surface is the optional Moshi channel.
807
811
  - `review` and `error` never emit a plugin notification: `review` attention
808
812
  stays in-flow/native; `error` is sidebar state only — our own `error:` label
809
813
  with the pane left on native `working`, so neither the `NeedsAttention`
package/README.md CHANGED
@@ -269,7 +269,10 @@ The one exception is a blocking synchronous subagent call: while a task-mode
269
269
  `subagent_run`/`subagent_continue` is in flight the principal's own turn is
270
270
  blocked on the child, so the producer publishes that child's role in
271
271
  `gentle_pending_v1` and it renders instead of `gentle`, for as long as the
272
- call lasts. Background launches resolve their tool call immediately, so a
272
+ call lasts. A resume (`subagent_continue`) carries no agent, so its role is
273
+ the tracked task record's agent for its `task_id`; when neither the input nor
274
+ a record names one, the call publishes no role and the row keeps its generic
275
+ display. Background launches resolve their tool call immediately, so a
273
276
  queued or running background delegate publishes no such marker and leaves
274
277
  the principal's own display untouched. These yield to `ask`/`rdd`/`blocked`
275
278
  and terminal `done` — where `done` needs
@@ -281,15 +284,17 @@ work total is a direct projection of the
281
284
  Gentle Shell TaskStore `running` records (only `running` counts as
282
285
  executing; queued/waiting never count), never a calculated
283
286
  pending-call estimate: pending tool calls are role-only display hints (exact
284
- in-flight subagent agent -> role slug, so task-mode launches show the active
287
+ in-flight subagent agent -> role slug, resolved from the tool input or, for a
288
+ resume, from the tracked task record, so task-mode launches show the active
285
289
  role even at count 0) plus label correlation, and
286
290
  true concurrent tasks all count. A live `running` record is never regressed
287
291
  by a racy non-final status read (only the authoritative launch outcomes,
288
292
  completions, and presence terminals move it), so principal activity with
289
293
  live delegates keeps `gentle` while an idle principal keeps the role word; a
290
294
  sanitized unknown slug exactly
291
- equal to `working` degrades to `gentle` (the bare word `working` never
292
- renders).
295
+ equal to `working` or `subagent` degrades to `gentle` (neither bare word ever
296
+ renders; `subagent` is the producer's launch-correlation placeholder, never
297
+ an agent name).
293
298
  Background launches (`subagent_run` with `mode: background`) announce
294
299
  lifecycle over `message_end` custom results: an ACTIVE status promotes the
295
300
  start into the tasks map like a task-mode record, so an active background
@@ -449,7 +454,12 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
449
454
  shows the single `Sidebar agent rows` row, and the only Moshi switch is the
450
455
  `Notifications` row under `Moshi notifications`. The two are never mixed —
451
456
  `Sidebar agent rows` neither reads nor writes `gentle-moshi.json`, so turning
452
- the agent rows off never turns the notification channel off. The plain
457
+ the agent rows off never turns the notification channel off. Herdr's own
458
+ done/ask attention (the finished and needs-attention pop-ups and their
459
+ sound) is Herdr's native behavior, configured in Herdr itself — its config
460
+ and its settings — and this package deliberately offers no switch for it:
461
+ the optional Moshi channel below is the only notification surface the
462
+ package owns. The plain
453
463
  two-step menu stays as the fallback
454
464
  when the TUI helpers or `ctx.ui.custom` are unavailable.
455
465
  `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 labels; null change tokens when the session model has
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>
@@ -2438,17 +2441,21 @@ async function applyCustomizeSwitch(id, value, ctx) {
2438
2441
  if (result.needsReload && typeof ctx?.reload === "function") await ctx.reload();
2439
2442
  }
2440
2443
 
2441
- // The single apply path shared by the overlay and the menu fallback. An
2442
- // inconclusive sidebar verdict is never a refusal: choosing On still attempts
2443
- // the repair and reports the apply step's own error, exactly like the baseline
2444
- // menu did. `switchId` names the switch a row drives, never the category it is
2445
- // painted under: each category now owns exactly one switch, so the sidebar rows
2446
- // can only ever resolve `sidebar` and the notification row only `moshi`.
2447
- async function applyCustomizeChoice(categoryId, valueId, ctx, switchId) {
2448
- const target = switchId === "sidebar" || switchId === "moshi" ? switchId : categoryId;
2449
- if (target !== "sidebar" && target !== "moshi") return;
2444
+ // The single apply path shared by the overlay and the menu fallback. The choice
2445
+ // the panel resolves names the switch it drives (`switchId`) and the value to
2446
+ // apply; that switch id is the only thing read here, so a row can never apply a
2447
+ // switch its category does not own. An inconclusive sidebar verdict is never a
2448
+ // refusal: choosing On still attempts the repair and reports the apply step's
2449
+ // own error, exactly like the baseline menu did.
2450
+ const CUSTOMIZE_SWITCH_IDS = ["sidebar", "moshi"];
2451
+
2452
+ async function applyCustomizeChoice(choice, ctx) {
2453
+ if (!isRecord(choice)) return;
2454
+ const switchId = choice.switchId;
2455
+ const valueId = choice.valueId;
2456
+ if (!CUSTOMIZE_SWITCH_IDS.includes(switchId)) return;
2450
2457
  if (valueId !== "on" && valueId !== "off") return;
2451
- await applyCustomizeSwitch(target, valueId, ctx);
2458
+ await applyCustomizeSwitch(switchId, valueId, ctx);
2452
2459
  }
2453
2460
 
2454
2461
  // The former plain menu, kept as the fallback when the TUI helpers or
@@ -2477,7 +2484,7 @@ async function runCustomizeFallback(ctx) {
2477
2484
  choice = undefined;
2478
2485
  }
2479
2486
  if (choice !== CUSTOMIZE_ON && choice !== CUSTOMIZE_OFF) return;
2480
- await applyCustomizeChoice(id, choice === CUSTOMIZE_ON ? "on" : "off", ctx);
2487
+ await applyCustomizeChoice({ switchId: id, valueId: choice === CUSTOMIZE_ON ? "on" : "off" }, ctx);
2481
2488
  }
2482
2489
 
2483
2490
  async function executeCustomize(rawArgs, ctx) {
@@ -2548,7 +2555,7 @@ async function executeCustomize(rawArgs, ctx) {
2548
2555
  // Esc (null) does nothing at all: no notification, no write, no reload.
2549
2556
  // Anything else runs the single apply path once the overlay is disposed.
2550
2557
  if (!choice || typeof choice !== "object") return;
2551
- await applyCustomizeChoice(choice.categoryId, choice.valueId, ctx, choice.switchId);
2558
+ await applyCustomizeChoice(choice, ctx);
2552
2559
  return;
2553
2560
  }
2554
2561
  await runCustomizeFallback(ctx);
@@ -2590,7 +2597,7 @@ export default function (pi) {
2590
2597
  // Finished/failed/cancelled/waiting entries may linger in the map but
2591
2598
  // never count; the map is cleared only on session reset (plus the
2592
2599
  // bounded-map guard) — never by a local staleness timeout.
2593
- const pendingCalls = new Map(); // toolCallId -> { agent, label, at }
2600
+ const pendingCalls = new Map(); // toolCallId -> { agent, label, at }; agent/label are undefined when no agent is resolvable
2594
2601
  const tasks = new Map(); // taskId -> { agent, label, status, at }
2595
2602
 
2596
2603
  // Blocker legs. ask combines choice + native questionnaire + legacy
@@ -3082,7 +3089,20 @@ export default function (pi) {
3082
3089
  const parts = [];
3083
3090
  let length = 0;
3084
3091
  for (const sub of subs) {
3085
- const name = sanitizeLabel(sub.label, sub.agent);
3092
+ // An entry whose label and agent are both absent has no name to publish:
3093
+ // a record can carry no identity at all (an observation without an agent
3094
+ // and no previous record), and `sanitizeLabel` stringifies whatever
3095
+ // fallback it is handed, so passing the absence through would put the
3096
+ // literal `undefined` on the wire as a name.
3097
+ const label =
3098
+ typeof sub.label === "string" && sub.label.length > 0 ? sub.label : undefined;
3099
+ const subAgent =
3100
+ typeof sub.agent === "string" && sub.agent.length > 0 ? sub.agent : undefined;
3101
+ if (label === undefined && subAgent === undefined) continue;
3102
+ // Label first, agent as fallback, unchanged for every entry that has
3103
+ // either; the fallback is never absent here, so the sanitizer always has
3104
+ // a real string to fall back to.
3105
+ const name = sanitizeLabel(label, subAgent ?? label);
3086
3106
  if (parts.includes(name)) continue;
3087
3107
  const add = (parts.length === 0 ? 0 : 1) + utf8Bytes(name);
3088
3108
  if (length + add > MAX_TOKEN_BYTES) break;
@@ -3130,11 +3150,13 @@ export default function (pi) {
3130
3150
  ) {
3131
3151
  return "rdd";
3132
3152
  }
3133
- // The bare visible word `working` is banned: a sanitized unknown slug
3134
- // exactly equal to `working` degrades to no role (generic `gentle`)
3135
- // in metadata roles and the native message alike.
3153
+ // The bare visible words `working` and `subagent` are banned: a sanitized
3154
+ // unknown slug exactly equal to either degrades to no role (generic
3155
+ // `gentle`) in metadata roles and the native message alike. `subagent` is
3156
+ // the launch-correlation placeholder, never an agent name, so it must
3157
+ // never reach the wire as a role word.
3136
3158
  const slug = sanitizeAgentSlug(agent);
3137
- return slug === "working" ? undefined : slug;
3159
+ return slug === "working" || slug === "subagent" ? undefined : slug;
3138
3160
  }
3139
3161
 
3140
3162
  // Bounded CSV of role words, oldest-first (subs already arrive
@@ -3923,11 +3945,23 @@ export default function (pi) {
3923
3945
 
3924
3946
  // -- subagent activity -----------------------------------------------------
3925
3947
 
3948
+ // `subagent_run` carries the agent in its input, but `subagent_continue`
3949
+ // carries only `task_id`/`prompt`/`label`/`mode`: a resume names the task
3950
+ // whose record already holds the child's agent. Neither source means no
3951
+ // role evidence at all — the pending call still covers the blocking/
3952
+ // orchestrating marker, but it contributes no role and no name, and it
3953
+ // must never publish the launch-correlation placeholder as a role word.
3926
3954
  function launchInput(input) {
3927
3955
  if (!isRecord(input)) return undefined;
3928
- const agent = typeof input.agent === "string" ? input.agent : "subagent";
3929
- const label = sanitizeLabel(typeof input.label === "string" ? input.label : agent, agent);
3930
- return { agent: truncateChars(agent, MAX_LABEL_CHARS), label };
3956
+ const taskId = typeof input.task_id === "string" ? input.task_id : undefined;
3957
+ const inputAgent =
3958
+ typeof input.agent === "string" && input.agent.length > 0 ? input.agent : undefined;
3959
+ const agent =
3960
+ inputAgent ?? (taskId !== undefined ? tasks.get(taskId)?.agent : undefined);
3961
+ const labelSource =
3962
+ typeof input.label === "string" && input.label.length > 0 ? input.label : agent;
3963
+ const label = labelSource === undefined ? undefined : sanitizeLabel(labelSource, labelSource);
3964
+ return { agent: agent === undefined ? undefined : truncateChars(agent, MAX_LABEL_CHARS), label };
3931
3965
  }
3932
3966
 
3933
3967
  pi.on("tool_call", (event) => {
@@ -4051,10 +4085,13 @@ export default function (pi) {
4051
4085
  : undefined;
4052
4086
  // A stale read's agent is distrusted with its status, and a missing
4053
4087
  // agent keeps the previous record's agent (never reset to a guess).
4088
+ // With neither source the record has no agent at all: `subagent` is the
4089
+ // launch-correlation placeholder, never an identity, so inventing it here
4090
+ // would publish that word as the record's name.
4054
4091
  const agent =
4055
4092
  staleRead && previous?.agent
4056
4093
  ? previous.agent
4057
- : (incomingAgent ?? previous?.agent ?? "subagent");
4094
+ : (incomingAgent ?? previous?.agent);
4058
4095
  const now = Date.now();
4059
4096
  tasks.set(details.taskId, {
4060
4097
  agent,
@@ -4105,10 +4142,13 @@ export default function (pi) {
4105
4142
  if (typeof details.status !== "string") return;
4106
4143
  if (!FINAL_TASK.has(details.status) && !ACTIVE_TASK.has(details.status)) return;
4107
4144
  const previous = tasks.get(details.taskId);
4145
+ // Same rule as the tool_result path: an observation without an agent keeps
4146
+ // the previous record's agent, and with neither there is no agent at all —
4147
+ // the launch-correlation placeholder must never become a record identity.
4108
4148
  const agent =
4109
4149
  typeof details.agent === "string" && details.agent.length > 0
4110
4150
  ? truncateChars(details.agent, MAX_LABEL_CHARS)
4111
- : (previous?.agent ?? "subagent");
4151
+ : previous?.agent;
4112
4152
  // Record identity is immutable per taskId: firstSeen never moves (T2b
4113
4153
  // ordering only) whether this observation promotes a background start
4114
4154
  // or replaces the record with its terminal status; completion still
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "herdr-gentle-shell",
3
- "version": "1.5.0",
3
+ "version": "1.5.1",
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",