@narumitw/pi-herdr 0.3.1 → 0.3.3

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/README.md CHANGED
@@ -9,7 +9,7 @@ Connect Pi's interactive lifecycle to Herdr and bootstrap the operating guidance
9
9
  - Reports Pi session identity and `working`, `blocked`, and `idle` lifecycle states to the current Herdr pane.
10
10
  - Publishes bounded `model`, `provider`, `thinking`, `session`, and `context_usage` tokens for Herdr sidebar rows.
11
11
  - Shows recognized sibling agents from the current Herdr workspace in a passive widget above Pi's editor, with a saved visibility toggle in `/herdr`.
12
- - Updates the widget from Herdr pane lifecycle and agent-status events without polling the CLI.
12
+ - Refreshes the widget on Herdr pane, workspace-name, and agent-status updates without polling the CLI.
13
13
  - Coalesces rapid state changes and retries short-lived local socket failures without interrupting Pi.
14
14
  - Derives blocked state from Pi's public `ui_prompt_start` and `ui_prompt_end` lifecycle events.
15
15
  - Bundles a thin `herdr` bootstrap skill for explicit Herdr inspection and control requests.
@@ -100,8 +100,13 @@ Agent reports contain the same ownership fields plus the current lifecycle state
100
100
  Blocking extension prompts use their Pi-provided title as the label and fall back to the prompt kind.
101
101
 
102
102
  Local socket delivery is best-effort.
103
- A failed request is retried once with bounded timeouts, and reporting failures never stop Pi.
104
- Session shutdown aborts in-flight reporting and prevents stale session work from publishing later state.
103
+ Connection failures, malformed responses, and timeouts are retried once with bounded timeouts; explicit API rejections are not retried.
104
+ Only a complete success response with the matching request ID acknowledges a report. Herdr can acknowledge but ignore an old sequence, so acknowledgement does not guarantee a state change.
105
+ Reporting failures never stop Pi.
106
+ Session shutdown aborts and drains in-flight reporting and prevents stale session work from publishing later state.
107
+ Replacement aborts pending metadata cleanup.
108
+ Native quit cleanup remains Herdr-owned: the extension does not release native Pi identity or clear reporting authority and restore references.
109
+ Herdr ignores official-source release requests, while authority clearing also removes session restore data; neither operation is used during shutdown.
105
110
 
106
111
  ## 🏷️ Pane metadata
107
112
 
@@ -144,17 +149,19 @@ The widget orders agents by `blocked`, `done`, `working`, `idle`, and `unknown`,
144
149
  A state label published through Herdr metadata can replace the raw state name.
145
150
  Herdr's public pane responses do not expose the blocked prompt message, so the widget cannot show that reason.
146
151
  The widget is read-only and does not focus panes, read terminal output, send prompts, or mark a background `done` state as seen.
147
- The extension discovers the current workspace, pane list, and agent names, opens pane-scoped status subscriptions plus topology subscriptions, and then reloads those identities to reconcile changes made during initialization.
148
- Expected pane creation, movement, or agent detection rebuilds the pane-scoped subscriptions without consuming the bounded failure retry.
149
- Unexpected disconnection clears the widget before one bounded reconnect attempt, and a second failure leaves it hidden until the next Pi session or `/reload`.
150
- Session replacement and shutdown abort the subscription, pending requests, reconnect delay, and stale widget publication.
152
+ The extension discovers the current workspace, pane list, and agent names, opens pane-scoped status subscriptions plus pane-update and workspace-name subscriptions, and then reloads those identities.
153
+ Events trigger serialized, coalesced reads rather than replacing current state with event payloads. If an event arrives during a read, the extension reads again before publishing that result.
154
+ Agent names, workspace labels, and cleared presentation fields update from these authoritative reads.
155
+ Changes to the current pane, workspace, or recognized-agent set rebuild the pane-scoped subscriptions without consuming the bounded failure retry.
156
+ Unexpected disconnection or `events_lost` clears the widget before one bounded reconnect attempt, and a second failure leaves it hidden until the next Pi session or `/reload`.
157
+ Session replacement and shutdown abort the subscription, pending reads, reconnect delay, and stale widget publication.
151
158
 
152
159
  ## 🔒 Security and privacy
153
160
 
154
161
  The extension connects only to the Unix socket or Windows named pipe provided by `HERDR_SOCKET_PATH`.
155
162
  Lifecycle reporting sends the current Herdr pane ID, Pi session path or ID, lifecycle state, session start reason, and blocked label to that endpoint.
156
163
  Metadata reporting sends the current Herdr pane ID plus only the selected model ID, provider ID, effective Thinking level, explicit Pi session name, and rounded context-usage percentage.
157
- For the widget, it reads the canonical current pane, current workspace metadata, current workspace pane list, and session agent list, then subscribes to pane creation, closure, movement, exit, agent detection, and agent-status events.
164
+ For the widget, it reads the canonical current pane, current workspace metadata, current workspace pane list, and session agent list, then subscribes to pane creation, updates, closure, movement, exit, agent detection, agent-status changes, and workspace renames.
158
165
  The session agent list can contain agent metadata from other workspaces, but the extension retains names only for panes in the current workspace list.
159
166
  Widget fields can include workspace, tab, pane, terminal, agent, display, name, title, label, state-label, and lifecycle identifiers supplied by Herdr.
160
167
  The subscription can deliver matching pane events from other workspaces in the same Herdr session, and the extension ignores them after resolving the current workspace.
@@ -172,7 +179,8 @@ Command recipes, approval handling, and other operating safety rules come from t
172
179
  - Lifecycle reporting, metadata reporting, and the agent widget are disabled in RPC, JSON, and print modes.
173
180
  - The widget has no settings for placement, workspace scope, or row count.
174
181
  - The widget cannot show blocked prompt text because Herdr does not expose it through public pane responses.
175
- - Herdr exposes no rename event, so agent and pane renames appear after the next topology refresh, reconnect, Pi `/reload`, or session start rather than immediately.
182
+ - The widget requires compatible pane-update and workspace-name subscriptions; unsupported subscriptions hide the widget without disabling lifecycle or metadata reporting.
183
+ - A pane-label change appears on its next update event or authoritative refresh; an agent rename emits a pane-update event.
176
184
  - Integration requires a running compatible Herdr session and valid injected environment variables.
177
185
  - Model control requires an installed Herdr CLI that supports `herdr --skill`.
178
186
  - Socket failures are intentionally silent after the bounded retry.