@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 +24 -11
- package/dist/chunks/herdr-menu-IUPFF5YK.ts +56 -0
- package/dist/chunks/herdr-menu-IUPFF5YK.ts.map +7 -0
- package/dist/index.ts +1495 -0
- package/dist/index.ts.map +7 -0
- package/package.json +10 -6
- package/src/herdr-agent-state.ts +38 -21
- package/src/herdr-client.ts +44 -53
- package/src/herdr-observer.ts +62 -108
- package/src/herdr-protocol.ts +21 -32
- package/src/herdr-widget.ts +1 -55
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
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
101
|
-
|
|
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
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
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,
|
|
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
|
-
-
|
|
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
|
|
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
|
+
}
|