@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 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, visibility, or row count.
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
- ├── skills/herdr/
151
- │ └── SKILL.md # Thin bootstrap for CLI-owned operating guidance
152
- ├── src/
153
- │ ├── index.ts # Thin Pi entrypoint
154
- │ ├── herdr-agent-state.ts # Pi lifecycle and integration ownership
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
- "name": "@narumitw/pi-herdr",
3
- "version": "0.1.1",
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
- "@biomejs/biome": "2.5.11",
44
- "@earendil-works/pi-coding-agent": "0.84.4",
45
- "@earendil-works/pi-tui": "0.84.4",
46
- "@types/node": "26.4.0",
47
- "typescript": "7.0.2"
48
- },
49
- "repository": {
50
- "type": "git",
51
- "url": "https://github.com/narumiruna/pi-extensions",
52
- "directory": "packages/pi-herdr"
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
  }
@@ -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.