@narumitw/pi-herdr 0.3.0 → 0.3.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/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.
@@ -30,12 +30,15 @@ Try from npm without installing permanently:
30
30
  pi -e npm:@narumitw/pi-herdr
31
31
  ```
32
32
 
33
- Load a local checkout from the repository root:
33
+ Build and load a local checkout from the repository root:
34
34
 
35
35
  ```bash
36
+ npm --workspace @narumitw/pi-herdr run build
36
37
  pi --no-extensions -e ./packages/pi-herdr
37
38
  ```
38
39
 
40
+ An unbuilt local checkout has no generated entrypoint and cannot be loaded by package directory.
41
+
39
42
  Pi extensions and skills run with your user permissions.
40
43
  Install only trusted packages, and review the source and bundled instructions before loading this package.
41
44
 
@@ -97,8 +100,13 @@ Agent reports contain the same ownership fields plus the current lifecycle state
97
100
  Blocking extension prompts use their Pi-provided title as the label and fall back to the prompt kind.
98
101
 
99
102
  Local socket delivery is best-effort.
100
- A failed request is retried once with bounded timeouts, and reporting failures never stop Pi.
101
- 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.
102
110
 
103
111
  ## 🏷️ Pane metadata
104
112
 
@@ -141,17 +149,19 @@ The widget orders agents by `blocked`, `done`, `working`, `idle`, and `unknown`,
141
149
  A state label published through Herdr metadata can replace the raw state name.
142
150
  Herdr's public pane responses do not expose the blocked prompt message, so the widget cannot show that reason.
143
151
  The widget is read-only and does not focus panes, read terminal output, send prompts, or mark a background `done` state as seen.
144
- 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.
145
- Expected pane creation, movement, or agent detection rebuilds the pane-scoped subscriptions without consuming the bounded failure retry.
146
- Unexpected disconnection clears the widget before one bounded reconnect attempt, and a second failure leaves it hidden until the next Pi session or `/reload`.
147
- 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.
148
158
 
149
159
  ## 🔒 Security and privacy
150
160
 
151
161
  The extension connects only to the Unix socket or Windows named pipe provided by `HERDR_SOCKET_PATH`.
152
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.
153
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.
154
- 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.
155
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.
156
166
  Widget fields can include workspace, tab, pane, terminal, agent, display, name, title, label, state-label, and lifecycle identifiers supplied by Herdr.
157
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.
@@ -169,7 +179,8 @@ Command recipes, approval handling, and other operating safety rules come from t
169
179
  - Lifecycle reporting, metadata reporting, and the agent widget are disabled in RPC, JSON, and print modes.
170
180
  - The widget has no settings for placement, workspace scope, or row count.
171
181
  - The widget cannot show blocked prompt text because Herdr does not expose it through public pane responses.
172
- - 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.
173
184
  - Integration requires a running compatible Herdr session and valid injected environment variables.
174
185
  - Model control requires an installed Herdr CLI that supports `herdr --skill`.
175
186
  - Socket failures are intentionally silent after the bounded retry.
@@ -181,8 +192,10 @@ Command recipes, approval handling, and other operating safety rules come from t
181
192
  ```text
182
193
  packages/pi-herdr/
183
194
  ├── src/ # Authoritative implementation and helpers
184
- │ ├── index.ts # Thin Pi entrypoint
195
+ │ ├── index.ts # Thin repository entrypoint
185
196
  │ └── herdr-agent-state.ts # Herdr lifecycle integration
197
+ ├── dist/ # Generated TypeScript runtime loaded by Pi
198
+ ├── scripts/ # Deterministic runtime builder
186
199
  ├── skills/herdr/ # Published bootstrap for CLI-owned guidance
187
200
  └── test/ # Behavior and lifecycle coverage
188
201
  ```
@@ -0,0 +1,56 @@
1
+ // @generated by scripts/build-runtime.mjs; do not edit.
2
+ // @ts-nocheck -- generated JavaScript uses a .ts extension for Pi's Jiti loader.
3
+
4
+ // src/herdr-menu.ts
5
+ function createHerdrMenu(options) {
6
+ return {
7
+ start: "main",
8
+ screens: {
9
+ // One setting stays on the main menu, matching /tool rather than adding a submenu.
10
+ main: () => ({
11
+ kind: "actions",
12
+ title: "Herdr",
13
+ items: [
14
+ {
15
+ id: "widget",
16
+ label: `Agent widget: ${options.isEnabled() ? "On" : "Off"}`,
17
+ description: "Show or hide sibling agents above the editor",
18
+ action: "toggle"
19
+ },
20
+ { id: "status", label: "Status", to: "status" },
21
+ { id: "help", label: "Help", to: "help" },
22
+ { id: "close", label: "Close", close: true }
23
+ ],
24
+ hint: "close"
25
+ }),
26
+ status: () => ({
27
+ kind: "detail",
28
+ title: "Herdr Status",
29
+ lines: [
30
+ `Agent widget setting: ${options.isEnabled() ? "on" : "off"}`,
31
+ "The widget appears only in TUI mode with recognized sibling agents.",
32
+ "Lifecycle and metadata reporting are independent of this setting.",
33
+ `User settings file: ${options.settingsPath}`
34
+ ],
35
+ hint: "back"
36
+ }),
37
+ help: () => ({
38
+ kind: "detail",
39
+ title: "Herdr Help",
40
+ lines: [
41
+ "Toggle Agent widget from /herdr. Changes are saved immediately; closing does not undo them.",
42
+ "Manual pi-herdr.json changes apply after /reload or the next session start.",
43
+ "The widget defaults to on. Project overrides are not read."
44
+ ],
45
+ hint: "back"
46
+ })
47
+ },
48
+ actions: {
49
+ toggle: async ({ signal }) => await options.toggle(signal) ? { kind: "stay" } : { kind: "rejected" }
50
+ }
51
+ };
52
+ }
53
+ export {
54
+ createHerdrMenu
55
+ };
56
+ //# sourceMappingURL=herdr-menu-IUPFF5YK.ts.map
@@ -0,0 +1,7 @@
1
+ {
2
+ "version": 3,
3
+ "sources": ["../../src/herdr-menu.ts"],
4
+ "sourcesContent": ["import type { MenuDefinition } from \"@narumitw/pi-tui-kit\";\n\nexport function createHerdrMenu(options: {\n settingsPath: string;\n isEnabled(): boolean;\n toggle(signal: AbortSignal): Promise<boolean>;\n}): MenuDefinition<undefined, \"main\" | \"status\" | \"help\", \"toggle\"> {\n return {\n start: \"main\",\n screens: {\n // One setting stays on the main menu, matching /tool rather than adding a submenu.\n main: () => ({\n kind: \"actions\",\n title: \"Herdr\",\n items: [\n {\n id: \"widget\",\n label: `Agent widget: ${options.isEnabled() ? \"On\" : \"Off\"}`,\n description: \"Show or hide sibling agents above the editor\",\n action: \"toggle\",\n },\n { id: \"status\", label: \"Status\", to: \"status\" },\n { id: \"help\", label: \"Help\", to: \"help\" },\n { id: \"close\", label: \"Close\", close: true },\n ],\n hint: \"close\",\n }),\n status: () => ({\n kind: \"detail\",\n title: \"Herdr Status\",\n lines: [\n `Agent widget setting: ${options.isEnabled() ? \"on\" : \"off\"}`,\n \"The widget appears only in TUI mode with recognized sibling agents.\",\n \"Lifecycle and metadata reporting are independent of this setting.\",\n `User settings file: ${options.settingsPath}`,\n ],\n hint: \"back\",\n }),\n help: () => ({\n kind: \"detail\",\n title: \"Herdr Help\",\n lines: [\n \"Toggle Agent widget from /herdr. Changes are saved immediately; closing does not undo them.\",\n \"Manual pi-herdr.json changes apply after /reload or the next session start.\",\n \"The widget defaults to on. Project overrides are not read.\",\n ],\n hint: \"back\",\n }),\n },\n actions: {\n toggle: async ({ signal }) => ((await options.toggle(signal)) ? { kind: \"stay\" } : { kind: \"rejected\" }),\n },\n };\n}\n"],
5
+ "mappings": ";;;;AAEO,SAAS,gBAAgB,SAIoC;AAClE,SAAO;AAAA,IACL,OAAO;AAAA,IACP,SAAS;AAAA;AAAA,MAEP,MAAM,OAAO;AAAA,QACX,MAAM;AAAA,QACN,OAAO;AAAA,QACP,OAAO;AAAA,UACL;AAAA,YACE,IAAI;AAAA,YACJ,OAAO,iBAAiB,QAAQ,UAAU,IAAI,OAAO,KAAK;AAAA,YAC1D,aAAa;AAAA,YACb,QAAQ;AAAA,UACV;AAAA,UACA,EAAE,IAAI,UAAU,OAAO,UAAU,IAAI,SAAS;AAAA,UAC9C,EAAE,IAAI,QAAQ,OAAO,QAAQ,IAAI,OAAO;AAAA,UACxC,EAAE,IAAI,SAAS,OAAO,SAAS,OAAO,KAAK;AAAA,QAC7C;AAAA,QACA,MAAM;AAAA,MACR;AAAA,MACA,QAAQ,OAAO;AAAA,QACb,MAAM;AAAA,QACN,OAAO;AAAA,QACP,OAAO;AAAA,UACL,yBAAyB,QAAQ,UAAU,IAAI,OAAO,KAAK;AAAA,UAC3D;AAAA,UACA;AAAA,UACA,uBAAuB,QAAQ,YAAY;AAAA,QAC7C;AAAA,QACA,MAAM;AAAA,MACR;AAAA,MACA,MAAM,OAAO;AAAA,QACX,MAAM;AAAA,QACN,OAAO;AAAA,QACP,OAAO;AAAA,UACL;AAAA,UACA;AAAA,UACA;AAAA,QACF;AAAA,QACA,MAAM;AAAA,MACR;AAAA,IACF;AAAA,IACA,SAAS;AAAA,MACP,QAAQ,OAAO,EAAE,OAAO,MAAQ,MAAM,QAAQ,OAAO,MAAM,IAAK,EAAE,MAAM,OAAO,IAAI,EAAE,MAAM,WAAW;AAAA,IACxG;AAAA,EACF;AACF;",
6
+ "names": []
7
+ }