@narumitw/pi-herdr 0.1.1 → 0.3.0
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 +40 -23
- package/package.json +51 -52
- package/skills/herdr/SKILL.md +12 -0
- package/src/herdr-agent-state.ts +406 -404
- package/src/herdr-client.ts +236 -238
- package/src/herdr-menu.ts +54 -0
- package/src/herdr-metadata.ts +46 -52
- package/src/herdr-observer.ts +334 -372
- package/src/herdr-protocol.ts +185 -187
- package/src/herdr-settings-controller.ts +129 -0
- package/src/herdr-widget.ts +204 -217
- package/src/settings.ts +188 -0
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@ Connect Pi's interactive lifecycle to Herdr and bootstrap the operating guidance
|
|
|
8
8
|
|
|
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
|
-
- Shows recognized sibling agents from the current Herdr workspace in a passive widget above Pi's editor
|
|
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
|
- Updates the widget from Herdr pane lifecycle and agent-status events 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.
|
|
@@ -56,6 +56,38 @@ rm -rf ~/.agents/skills/herdr
|
|
|
56
56
|
|
|
57
57
|
Run `/reload` or restart Pi after changing the installed resources.
|
|
58
58
|
|
|
59
|
+
## 🧠 Skills
|
|
60
|
+
|
|
61
|
+
The bundled `herdr` skill loads version-matched operating guidance after an explicit Herdr request.
|
|
62
|
+
It treats panes created for background work as temporary and attempts to close them after collecting the required output.
|
|
63
|
+
Ask Pi explicitly to keep a pane open after the task when you want to inspect or use it later.
|
|
64
|
+
Automatic cleanup runs only when the installed Herdr guidance provides a conditional close that atomically confirms the recorded pane ownership and acceptable agent or shell state; otherwise Pi leaves the pane open and reports the limitation.
|
|
65
|
+
|
|
66
|
+
## 💬 Commands
|
|
67
|
+
|
|
68
|
+
`/herdr` opens a menu to toggle the agent widget and view status or help, inspired by `/tool`.
|
|
69
|
+
It accepts no arguments and is available inside Herdr in TUI and RPC modes; print and JSON modes reject it.
|
|
70
|
+
RPC can save the preference but does not display the widget.
|
|
71
|
+
Changes apply immediately and closing the menu does not undo saved changes.
|
|
72
|
+
|
|
73
|
+
## ⚙️ Settings
|
|
74
|
+
|
|
75
|
+
Toggle **Agent widget** in `/herdr`, or edit `<getAgentDir()>/pi-herdr.json` (normally `~/.pi/agent/pi-herdr.json`):
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
{
|
|
79
|
+
"widget": false
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`widget` accepts only `true` or `false` and defaults to `true` when absent.
|
|
84
|
+
Only user settings are supported; project files are not read.
|
|
85
|
+
Manual edits apply after `/reload` or the next session start.
|
|
86
|
+
Missing files are not created until an explicit save. Invalid files trigger a warning, use defaults, and block saves until repaired.
|
|
87
|
+
Saves preserve unknown fields and use atomic temporary-file-plus-rename publication, with reads and writes ordered within one Pi process, not across processes.
|
|
88
|
+
Failed saves restore the previous effective value and leave the existing file untouched.
|
|
89
|
+
Turning the widget off closes its subscription and pending requests without disabling lifecycle or metadata reporting.
|
|
90
|
+
|
|
59
91
|
## 🔄 Lifecycle reporting
|
|
60
92
|
|
|
61
93
|
The extension reports only interactive TUI sessions because Herdr displays agents attached to terminal panes.
|
|
@@ -135,39 +167,24 @@ Command recipes, approval handling, and other operating safety rules come from t
|
|
|
135
167
|
## 🚧 Limitations
|
|
136
168
|
|
|
137
169
|
- Lifecycle reporting, metadata reporting, and the agent widget are disabled in RPC, JSON, and print modes.
|
|
138
|
-
- The widget has no settings for placement, workspace scope,
|
|
170
|
+
- The widget has no settings for placement, workspace scope, or row count.
|
|
139
171
|
- The widget cannot show blocked prompt text because Herdr does not expose it through public pane responses.
|
|
140
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.
|
|
141
173
|
- Integration requires a running compatible Herdr session and valid injected environment variables.
|
|
142
174
|
- Model control requires an installed Herdr CLI that supports `herdr --skill`.
|
|
143
175
|
- Socket failures are intentionally silent after the bounded retry.
|
|
176
|
+
- Skill cleanup tracking exists only in the active model context, so compaction, session replacement, `/reload`, or shutdown can leave temporary panes open.
|
|
144
177
|
- The package does not install, start, update, or configure Herdr itself.
|
|
145
178
|
|
|
146
179
|
## 🗂️ Package layout
|
|
147
180
|
|
|
148
181
|
```text
|
|
149
182
|
packages/pi-herdr/
|
|
150
|
-
├──
|
|
151
|
-
│
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
│ ├── herdr-client.ts # Bounded Herdr socket transport
|
|
156
|
-
│ ├── herdr-metadata.ts # Token normalization and request helpers
|
|
157
|
-
│ ├── herdr-observer.ts # Read-only event subscription lifecycle
|
|
158
|
-
│ ├── herdr-protocol.ts # Narrow response and event validation
|
|
159
|
-
│ └── herdr-widget.ts # Agent state model and presentation
|
|
160
|
-
├── test/
|
|
161
|
-
│ ├── herdr-agent-state.test.ts
|
|
162
|
-
│ ├── herdr-client.test.ts
|
|
163
|
-
│ ├── herdr-metadata.test.ts
|
|
164
|
-
│ ├── herdr-observer.test.ts
|
|
165
|
-
│ ├── herdr-skill.test.ts
|
|
166
|
-
│ └── herdr-widget.test.ts
|
|
167
|
-
├── package.json # Pi extension and skill declarations
|
|
168
|
-
├── tsconfig.json
|
|
169
|
-
├── README.md
|
|
170
|
-
└── LICENSE
|
|
183
|
+
├── src/ # Authoritative implementation and helpers
|
|
184
|
+
│ ├── index.ts # Thin Pi entrypoint
|
|
185
|
+
│ └── herdr-agent-state.ts # Herdr lifecycle integration
|
|
186
|
+
├── skills/herdr/ # Published bootstrap for CLI-owned guidance
|
|
187
|
+
└── test/ # Behavior and lifecycle coverage
|
|
171
188
|
```
|
|
172
189
|
|
|
173
190
|
## 🔎 Keywords
|
package/package.json
CHANGED
|
@@ -1,54 +1,53 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
}
|
|
2
|
+
"name": "@narumitw/pi-herdr",
|
|
3
|
+
"version": "0.3.0",
|
|
4
|
+
"description": "Herdr agent-state integration and operating skill for Pi.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"private": false,
|
|
8
|
+
"keywords": [
|
|
9
|
+
"pi-package",
|
|
10
|
+
"pi-extension",
|
|
11
|
+
"pi",
|
|
12
|
+
"herdr",
|
|
13
|
+
"terminal-multiplexer",
|
|
14
|
+
"agent-orchestration"
|
|
15
|
+
],
|
|
16
|
+
"files": [
|
|
17
|
+
"src",
|
|
18
|
+
"skills",
|
|
19
|
+
"README.md",
|
|
20
|
+
"LICENSE"
|
|
21
|
+
],
|
|
22
|
+
"pi": {
|
|
23
|
+
"extensions": [
|
|
24
|
+
"./src/index.ts"
|
|
25
|
+
],
|
|
26
|
+
"skills": [
|
|
27
|
+
"./skills"
|
|
28
|
+
]
|
|
29
|
+
},
|
|
30
|
+
"scripts": {
|
|
31
|
+
"check": "biome check . && npm run typecheck",
|
|
32
|
+
"format": "biome check --write .",
|
|
33
|
+
"typecheck": "tsc --noEmit"
|
|
34
|
+
},
|
|
35
|
+
"dependencies": {
|
|
36
|
+
"@narumitw/pi-tui-kit": "^0.60.0"
|
|
37
|
+
},
|
|
38
|
+
"peerDependencies": {
|
|
39
|
+
"@earendil-works/pi-coding-agent": "*",
|
|
40
|
+
"@earendil-works/pi-tui": "*"
|
|
41
|
+
},
|
|
42
|
+
"devDependencies": {
|
|
43
|
+
"@earendil-works/pi-coding-agent": "0.85.1",
|
|
44
|
+
"@earendil-works/pi-tui": "0.85.1",
|
|
45
|
+
"@types/node": "26.4.1",
|
|
46
|
+
"typescript": "7.0.2"
|
|
47
|
+
},
|
|
48
|
+
"repository": {
|
|
49
|
+
"type": "git",
|
|
50
|
+
"url": "https://github.com/narumiruna/pi-extensions",
|
|
51
|
+
"directory": "packages/pi-herdr"
|
|
52
|
+
}
|
|
54
53
|
}
|
package/skills/herdr/SKILL.md
CHANGED
|
@@ -20,3 +20,15 @@ herdr --skill
|
|
|
20
20
|
If the environment check or command fails, report the error and stop.
|
|
21
21
|
Read the returned skill completely and follow it as the authoritative operating instructions for the installed Herdr version.
|
|
22
22
|
Run it again only after compaction removes those instructions or when the user explicitly asks to refresh them.
|
|
23
|
+
|
|
24
|
+
Apply this cleanup policy in addition to those version-specific instructions:
|
|
25
|
+
|
|
26
|
+
- Maintain an in-context cleanup ledger with each pane ID you create, its intended lifetime, and every stable pane-generation, terminal, and shell identity that Herdr exposes; for an agent pane, also record the assigned agent and stable agent-session or occupant-process identity.
|
|
27
|
+
- Mark a pane as retained only when the user explicitly asks it to remain open after the task for later inspection or use, or when its continued existence is itself part of the requested result, and never close a retained pane automatically.
|
|
28
|
+
- For a temporary pane, collect the required output, decide that no follow-up is needed, and attempt cleanup as soon as its work is no longer needed.
|
|
29
|
+
- Automatically close a pane only through an operation documented by the loaded instructions that atomically checks the recorded pane and occupant identity together with an acceptable live state at mutation time.
|
|
30
|
+
- For an agent pane, the atomic guard must match the assigned agent and every recorded stable identity and require `idle` or `done`; for a returned shell, it must match the recorded pane-generation, terminal, and shell identities and require no replacement occupant or foreground process.
|
|
31
|
+
- A separate state read followed by an unconditional close is unsafe; if the installed Herdr version provides no suitable guarded close, leave the pane open and report that limitation.
|
|
32
|
+
- Keep unresolved temporary entries after cancellation or interruption while the current model context survives, retry guarded cleanup at the next recovery boundary before further Herdr work, and sweep them again before the final response.
|
|
33
|
+
- Never close the calling pane, a pre-existing pane, or a pane created by the user or another agent.
|
|
34
|
+
- If guarded closure fails, keep the ledger entry and report the pane ID and reason.
|