@howaboua/pi-shepherdr 0.2.23 → 0.2.25
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/CHANGELOG.md +20 -18
- package/README.md +80 -69
- package/biome.json +1 -1
- package/index.ts +4 -2
- package/package.json +14 -9
- package/src/agents-contract.ts +9 -6
- package/src/agents-discovery.ts +78 -37
- package/src/agents-focus.ts +17 -11
- package/src/agents-reply.ts +1 -1
- package/src/agents-spawn.ts +24 -8
- package/src/agents-tool.ts +26 -8
- package/src/agents-work.ts +5 -5
- package/src/attachment-notes.ts +14 -2
- package/src/attachment-protocol.ts +21 -4
- package/src/attachment-routing.ts +1 -1
- package/src/attachment-target.ts +5 -2
- package/src/attachment.ts +4 -3
- package/src/board/host.ts +5 -3
- package/src/board/membership.ts +1 -1
- package/src/close-idle.ts +89 -0
- package/src/{control-panel-actions.ts → control-panel/actions.ts} +2 -2
- package/src/{control-panel.ts → control-panel/index.ts} +7 -5
- package/src/{control-panel-items.ts → control-panel/items.ts} +17 -5
- package/src/{control-panel-view.ts → control-panel/view.ts} +9 -5
- package/src/controller.ts +17 -5
- package/src/core/AGENTS.md +5 -0
- package/src/core/backend.ts +266 -0
- package/src/core/client.ts +249 -0
- package/src/core/context-relay.mjs +111 -0
- package/src/core/focus-channel-helper.mjs +165 -0
- package/src/core/focus-channel-stream.ts +140 -0
- package/src/core/focus-channel-wire.mjs +160 -0
- package/src/core/focus-channel.ts +213 -0
- package/src/core/focus-window.ts +192 -0
- package/src/core/pi-executable.mjs +34 -0
- package/src/core/protocol.ts +116 -0
- package/src/core/registration.ts +51 -0
- package/src/core/remote-endpoint.ts +119 -0
- package/src/core/remote-exec.ts +122 -0
- package/src/core/remote-helper.mjs +244 -0
- package/src/core/remote-reader.ts +67 -0
- package/src/core/remote-relay.ts +191 -0
- package/src/core/request.ts +124 -0
- package/src/core/spawn.ts +177 -0
- package/src/core/status.ts +68 -0
- package/src/core/terminal.ts +103 -0
- package/src/fleet/catalog.ts +83 -0
- package/src/fleet/connection.ts +111 -0
- package/src/fleet/index.ts +413 -0
- package/src/fleet/inspection.ts +159 -0
- package/src/fleet/machine.ts +55 -0
- package/src/fleet/monitor.ts +85 -0
- package/src/fleet/persistence.ts +65 -0
- package/src/fleet/reconnect.ts +75 -0
- package/src/fleet/setup.ts +133 -0
- package/src/herdr.ts +25 -5
- package/src/launch-contract.ts +48 -0
- package/src/launch-location.ts +151 -0
- package/src/launch.ts +30 -183
- package/src/messages/attachments.ts +39 -0
- package/src/messages/attribution.ts +84 -0
- package/src/messages/event-details.ts +69 -0
- package/src/messages/events.ts +195 -0
- package/src/messages/focus.ts +47 -0
- package/src/messages/guidance.ts +83 -0
- package/src/messages/render.ts +89 -0
- package/src/messages/voice-announcements.ts +79 -0
- package/src/monitor-record.ts +9 -6
- package/src/monitor.ts +33 -2
- package/src/peer-commands.ts +11 -0
- package/src/peer-inbox-delivery.ts +171 -0
- package/src/peer-inbox-focus.ts +113 -0
- package/src/peer-inbox.ts +127 -209
- package/src/remote/client.ts +127 -0
- package/src/remote/context-relay.ts +84 -0
- package/src/remote/deployment.ts +179 -0
- package/src/remote/focus-channels.ts +89 -0
- package/src/remote/shepherdr-context.mjs +1 -1
- package/src/remote/shepherdr-peer.mjs +18 -5
- package/src/remote/shepherdr-session.mjs +9 -2
- package/src/remote/shepherdr.mjs +1 -1
- package/src/remote/transport.ts +369 -0
- package/src/settlement/collector.ts +122 -0
- package/src/settlement/delivery.ts +144 -0
- package/src/{settlement.ts → settlement/index.ts} +35 -233
- package/src/shared-context-host.ts +40 -14
- package/src/shared-context.ts +44 -6
- package/src/spawn-context.ts +24 -17
- package/src/spawn-ownership.ts +91 -0
- package/src/types.ts +9 -5
- package/src/voice-handoff.ts +1 -1
- package/src/worker-ownership.ts +92 -0
- package/src/worker-service.ts +14 -83
- package/src/fleet.ts +0 -702
- package/src/messages.ts +0 -637
- package/src/remote-client.ts +0 -761
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,25 @@
|
|
|
1
1
|
# @howaboua/pi-shepherdr
|
|
2
2
|
|
|
3
|
+
## 0.2.25
|
|
4
|
+
|
|
5
|
+
- When switching from the older Herdr TUI or another Core instance, reselect local watches.
|
|
6
|
+
- Added Herdr Core and Herdr app support for local and remote delegation, focus, voice transfers, shared Notes and boards, including Windows hosts.
|
|
7
|
+
- Added Core session discovery by terminal title, with spaces, hyphens and underscores treated alike.
|
|
8
|
+
- Added `/herdr close-idle` to close idle children spawned by the current session branch, leaving attached and busy sessions open.
|
|
9
|
+
- Spawn results now return `contextAgent` and `boardAgent` inside `sharing` instead of at the top level. The agent `target` is unchanged.
|
|
10
|
+
- Reduced resume delays in sessions with many delegated agents, including closed children.
|
|
11
|
+
- Remote sharing helpers now start only when sharing is used or restored, avoiding idle polling on unrelated machines.
|
|
12
|
+
- Fixed intermediate tool calls being reported as completed agent work.
|
|
13
|
+
- Agent guidance now distinguishes automatic background reports from blocking calls that must be awaited.
|
|
14
|
+
- Agent tool declarations now accept action fields discovered through help, including in native codemode.
|
|
15
|
+
|
|
16
|
+
## 0.2.24
|
|
17
|
+
|
|
18
|
+
- - **BREAKING CHANGE:** Shared notes and history now use Notes instead of PCC. Install `@howaboua/pi-notes-compaction` and update participating hosts together to retain sharing. PCC remains optional for native parent linkage and cache affinity. Ordinary agent management requires neither extension.
|
|
19
|
+
- Agent guidance now directs controllers to close finished workers without preceding acknowledgement messages.
|
|
20
|
+
- Attached note reads keep private routing details out of results while preserving read-only and stale-checkpoint warnings. Attachment acknowledgements omit internal bookkeeping.
|
|
21
|
+
- GPT mode uses note-style agent help and Board briefings.
|
|
22
|
+
|
|
3
23
|
## 0.2.23
|
|
4
24
|
|
|
5
25
|
- - Worker roles now follow shared project instructions, preserving a longer common startup prefix and exact role whitespace across machines. Update and reload Shepherdr on controllers and worker hosts together.
|
|
@@ -12,13 +32,11 @@
|
|
|
12
32
|
## 0.2.22
|
|
13
33
|
|
|
14
34
|
- **Worker integrations**
|
|
15
|
-
|
|
16
35
|
- Fresh workers now share their parent's cache routing with compatible Codex Conversion. Shared notes remain optional, and native sessions and histories remain separate.
|
|
17
36
|
- Fresh workers inherit the live Board setting before their first request, keeping Board tools and guidance available from startup.
|
|
18
37
|
- Added an optional Pulses runner with persistent workers, saved-session reuse and completion reports that wake the parent.
|
|
19
38
|
|
|
20
39
|
**Agent tools and guidance**
|
|
21
|
-
|
|
22
40
|
- Expanded tool calls now show outgoing tasks, messages, replies and focus handoffs in full.
|
|
23
41
|
- Added compact agent help and hosted Board briefings for PCC GPT prompt mode.
|
|
24
42
|
- Agent discovery now uses the same help contract across native, Code and Notebook tools.
|
|
@@ -32,7 +50,6 @@
|
|
|
32
50
|
## 0.2.20
|
|
33
51
|
|
|
34
52
|
- Requires Pi 1.2.0 or newer.
|
|
35
|
-
|
|
36
53
|
- Idle assignments and completion reports now apply Pi's full prompt and tool preparation.
|
|
37
54
|
- Fixed local and remote spawns failing during session startup.
|
|
38
55
|
- Supervision reminders now distinguish other agents' tasks from the current task after compaction.
|
|
@@ -46,7 +63,6 @@
|
|
|
46
63
|
## 0.2.18
|
|
47
64
|
|
|
48
65
|
- Replaced the Ask-specific `answer` action with `reply` for extension replies. Update and reload Ask and Shepherdr together on controllers and workers.
|
|
49
|
-
|
|
50
66
|
- Assignments now update running agents without losing pending results or replacing existing waiters. Messages and assignments also reach blocked workers.
|
|
51
67
|
- Extension messages and reply templates now travel between local and remote agents. Replies reach the owning extension without an extra model turn, including while a worker is busy or blocked.
|
|
52
68
|
- Pending extension messages remain visible until their producer closes them. Blocking messages arrive with the blocked result. Nonblocking messages notify separately once.
|
|
@@ -85,7 +101,6 @@
|
|
|
85
101
|
## 0.2.14
|
|
86
102
|
|
|
87
103
|
- Delegated agents keep reporting after task completion, including follow-up work.
|
|
88
|
-
|
|
89
104
|
- Added shared-board awareness across native, Code and Notebook modes.
|
|
90
105
|
- Preserves orchestration guidance across compaction and context rollover.
|
|
91
106
|
- Restores running workers' targets and full tasks after compaction or context rollover to prevent duplicate delegation.
|
|
@@ -118,7 +133,6 @@
|
|
|
118
133
|
## 0.2.10
|
|
119
134
|
|
|
120
135
|
- Requires Pi 1.0.0 or later.
|
|
121
|
-
|
|
122
136
|
- Added optional agent-tree message boards with channels, replies, search, subscriptions and persistent folder-local history. Boards require Node.js 22.13 or later.
|
|
123
137
|
- Added session, exact-folder and global board settings under `/herdr board`. Board notifications reach running turns without waking idle agents.
|
|
124
138
|
- Board history is stored as plaintext in `.pi/agent-message-board.sqlite` and remains after disabling boards. Keep this archive out of version control and restricted to its intended readers.
|
|
@@ -132,14 +146,12 @@
|
|
|
132
146
|
## 0.2.8
|
|
133
147
|
|
|
134
148
|
- Agent profiles now control delegation waiting and shared context.
|
|
135
|
-
|
|
136
149
|
- Removed reviewer-name blocking rules. Optional profile `blocking` forces blocking or asynchronous spawns, and help and list report the configured policy with the profile description.
|
|
137
150
|
- Added `share_context: false` for independent subagent notes and history. Existing installed profiles remain unchanged.
|
|
138
151
|
|
|
139
152
|
## 0.2.7
|
|
140
153
|
|
|
141
154
|
- Added opt-in shared notes and history for spawned agents with Pi Codex Conversion.
|
|
142
|
-
|
|
143
155
|
- New and nested workers receive distinct, persistent context identities before their first task.
|
|
144
156
|
- Local and Tree context stays in its owning sessions and routes through live controllers and existing SSH connections. Remote storage sharing requires the same Codex account.
|
|
145
157
|
- Sharing follows **Share subagent context** under `/codex context` and affects new spawns only. Existing agents and ordinary delegation remain unchanged.
|
|
@@ -151,7 +163,6 @@
|
|
|
151
163
|
## 0.2.6
|
|
152
164
|
|
|
153
165
|
- Fixed exact Ask answer confirmation and retry reconciliation without resending input.
|
|
154
|
-
|
|
155
166
|
- Keep answers pending while the original Ask is still open.
|
|
156
167
|
- Preserve accepted receipts when the worker's reply fails.
|
|
157
168
|
- Report dismissed Asks as rejected.
|
|
@@ -159,7 +170,6 @@
|
|
|
159
170
|
## 0.2.5
|
|
160
171
|
|
|
161
172
|
- GPT-6 Sol and Luna now share Astra's Codex support.
|
|
162
|
-
|
|
163
173
|
- Removed `/terra`; use `/luna` instead.
|
|
164
174
|
- Added Responses Lite, non-destructive reasoning changes and terse context guidance for GPT-6 Sol and Luna.
|
|
165
175
|
- Image descriptions now use GPT-6 Luna directly instead of preferring older mini models.
|
|
@@ -173,7 +183,6 @@
|
|
|
173
183
|
## 0.2.3
|
|
174
184
|
|
|
175
185
|
- Fixed context continuity, voice replies, and patch preservation.
|
|
176
|
-
|
|
177
186
|
- V2 compaction preserves the preceding request's reasoning configuration, then starts a fresh baseline without stale overrides. Astra's temporary effort survives continued work across context windows.
|
|
178
187
|
- Worker updates now accept up to 8 KiB without truncation announcements or offers to read the rest.
|
|
179
188
|
- Reasoning-summary forwarding now recognizes GPT-6 models.
|
|
@@ -195,14 +204,12 @@
|
|
|
195
204
|
## 0.2.1
|
|
196
205
|
|
|
197
206
|
- Deliver peer messages directly to Pi without submitting unsent human drafts.
|
|
198
|
-
|
|
199
207
|
- Preserve slash-command arguments and use the target session's skill and prompt-template expansion.
|
|
200
208
|
- Return submission-only acknowledgements for registered extension commands instead of waiting for an assistant reply.
|
|
201
209
|
|
|
202
210
|
Requires Pi 0.84.4 or newer. Update and reload Shepherdr on both controllers and workers, and Pi Codex Conversion where installed.
|
|
203
211
|
|
|
204
212
|
- Fixed idle agent reports and manual checkpoint requests to preserve prompt preparation, coalesce concurrent continuations, and process reports arriving during turn settlement.
|
|
205
|
-
|
|
206
213
|
- Manual Compact reuses notes saved in the last completed turn for Local, Tree, and Remote notes-only windows, avoiding a redundant checkpoint turn. Explicit compaction instructions still request a checkpoint.
|
|
207
214
|
- Compact tool output now offers Off, On, and Minimal. Minimal keeps nested tool results and an expand hint while hiding the trailing Code / Notebook text preview until expanded. Existing Off and On settings keep their behavior.
|
|
208
215
|
- Shepherdr help makes local routing explicit: agent calls default to the host running Pi, while unfiltered discovery searches all machines. Remote calls use profile IDs, not machine labels or hostnames.
|
|
@@ -211,7 +218,6 @@
|
|
|
211
218
|
## 0.2.0
|
|
212
219
|
|
|
213
220
|
- Shepherdr now reads existing Herdr machine profiles and requires Herdr 0.9 or newer. Manage profiles in Herdr; `shepherdr.json`, old machine aliases and their saved watches are no longer used.
|
|
214
|
-
|
|
215
221
|
- Agent prompts and reports identify their source workspace, tab and pane, including current names.
|
|
216
222
|
- Attributed messages to running Pi Codex agents use developer steering. Idle tasks retain normal user kickoff and extension preparation.
|
|
217
223
|
- `send` delivers peer messages without blocking or subscribing; use `assign` to delegate work to an existing agent.
|
|
@@ -220,7 +226,6 @@
|
|
|
220
226
|
## 0.1.6
|
|
221
227
|
|
|
222
228
|
- Deliver blocked-agent handoffs even when transcripts are unavailable.
|
|
223
|
-
|
|
224
229
|
- Reviewer spawns wait for their result before the controller continues.
|
|
225
230
|
- Implementation subagents are instructed to work directly rather than delegate implementation again.
|
|
226
231
|
- Discover and answer Pi Ask questions called inside Code and Notebook Mode.
|
|
@@ -235,14 +240,12 @@
|
|
|
235
240
|
## 0.1.4
|
|
236
241
|
|
|
237
242
|
- Preserve extension-owned messages while delivering true developer-role policy through compatible Pi Codex Responses adapters.
|
|
238
|
-
|
|
239
243
|
- Add an optional custom-message API that retains caller rendering and restoration fields.
|
|
240
244
|
- Route Shepherdr's unclaimed worker events and orchestration toggles through it, preserving ordinary Pi delivery when unavailable.
|
|
241
245
|
- Send review preface/triage policy and realtime voice start/end guidance as developer messages without elevating raw reviewer findings, spoken delegations, or transcript tails.
|
|
242
246
|
- Keep persisted developer messages in context across model switches, using ordinary Pi conversion on incompatible models.
|
|
243
247
|
|
|
244
248
|
- Fix worker settlement, custom model preservation, and prompt-only image generation.
|
|
245
|
-
|
|
246
249
|
- Settle Shepherdr workers after Pi expands skill or prompt-template invocations.
|
|
247
250
|
- Preserve custom Codex models and `models.json` overrides, including after refresh.
|
|
248
251
|
- Keep optional tool arguments optional in Codex Responses requests while preserving explicit strict sampling.
|
|
@@ -253,7 +256,6 @@
|
|
|
253
256
|
## 0.1.3
|
|
254
257
|
|
|
255
258
|
- Replaced Shepherdr's fire-and-forget tool with persistent blocking and asynchronous agents in normal Pi, Code Mode, and Notebook Mode.
|
|
256
|
-
|
|
257
259
|
- Start, steer, inspect, and answer multiple agents through the `agents` tool.
|
|
258
260
|
- Customize the bundled general, explorer, and reviewer profiles or add your own.
|
|
259
261
|
- Activate orchestration mode with `/herdr` when the main session should coordinate agent work.
|
package/README.md
CHANGED
|
@@ -14,7 +14,9 @@ With Pi Codex's compatible custom developer-message API active, asynchronous wor
|
|
|
14
14
|
pi install npm:@howaboua/pi-shepherdr
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
Requires Pi 1.2.0 or newer
|
|
17
|
+
Requires Pi 1.2.0 or newer and Node.js 22.18 or newer. Run Pi inside Herdr Core 0.1.14 or newer, or the Herdr app, to use the new Herdr backend. Shepherdr reports Pi status to Core and discovers other Pi sessions with Shepherdr installed.
|
|
18
|
+
|
|
19
|
+
For the older Herdr TUI, install its Pi integration:
|
|
18
20
|
|
|
19
21
|
```bash
|
|
20
22
|
herdr integration install pi
|
|
@@ -24,6 +26,10 @@ Do not load Pi Codex's example `agents.toml` custom tool alongside Shepherdr; th
|
|
|
24
26
|
|
|
25
27
|
Pi Codex is optional. Without it, Shepherdr remains a normal Pi extension.
|
|
26
28
|
|
|
29
|
+
Herdr Core workers start as background terminals by default. Explicit new-tab and new-workspace placements appear when an app connected to that Core adopts them. Focus requires a Herdr app window connected to the target Core. Existing Herdr TUI sessions cannot be moved into Core.
|
|
30
|
+
|
|
31
|
+
For remote Core workers, add machines with `hc machine add` and install Node.js, Herdr Core and Shepherdr on each target. Delegation, supervision, shared context and boards work across those machines.
|
|
32
|
+
|
|
27
33
|
## Control panel
|
|
28
34
|
|
|
29
35
|
The agent tool is always available in Pi, Code Mode and Notebook Mode. Run Pi inside Herdr to connect the fleet and start monitoring automatically. Open the control panel with:
|
|
@@ -32,17 +38,19 @@ The agent tool is always available in Pi, Code Mode and Notebook Mode. Run Pi in
|
|
|
32
38
|
/herdr
|
|
33
39
|
```
|
|
34
40
|
|
|
35
|
-
**Settings** contains orchestration preferences, agent command guidance and the global config path. **Status** shows machine connections and reconnect actions. **Connections** adds SSH machines
|
|
41
|
+
**Settings** contains orchestration preferences, agent command guidance and the global config path. **Status** shows machine connections and reconnect actions. **Connections** adds SSH machines for the older Herdr TUI. Agents handle discovery, attachment and detachment through the `agents` tool, not this panel.
|
|
42
|
+
|
|
43
|
+
Run `/herdr close-idle` to close idle child sessions spawned by the current session branch. Attached or assigned existing sessions are never included. Busy, blocked, unavailable or unverified children stay open. Children spawned before this feature was installed have no ownership receipt and stay open too. Pi shuts down gracefully before its pane closes.
|
|
36
44
|
|
|
37
45
|
`/herdr` is Shepherdr's only entry point. Outside the TUI, it reports status without changing it. An orchestration change records one visible guidance message without triggering a turn. Resumed sessions restore their last mode; new sessions start with normal guidance. The current guidance returns when a new model context no longer contains it, including turns started by worker messages. Tool availability and monitoring do not depend on this mode.
|
|
38
46
|
|
|
39
|
-
|
|
47
|
+
For the older Herdr TUI, add a machine by entering an SSH target or alias, a label and an optional remote session under **Connections**. Herdr performs setup in the terminal and asks before installing or replacing its remote server. OpenSSH owns authentication; Shepherdr does not store credentials. Profiles remain in Herdr's existing catalog, where they can also be renamed, disabled or removed.
|
|
40
48
|
|
|
41
|
-
Shepherdr connects enabled profiles at session startup. **Status** refreshes the catalog and retries failed connections or incomplete monitoring without dropping working connections. A catalog refresh stops watches for disabled or removed profiles without stopping remote agents.
|
|
49
|
+
With the older TUI, Shepherdr connects enabled profiles at session startup. **Status** refreshes the catalog and retries failed connections or incomplete monitoring without dropping working connections. A catalog refresh stops watches for disabled or removed profiles without stopping remote agents.
|
|
42
50
|
|
|
43
51
|
Profiles belong to the host running Pi, not the machine displaying its terminal. Omit `machine` for local agent calls. `list` and `find` search all machines unless filtered. Explicit `local` also means the host running Pi. For remote calls, use the opaque profile ID returned by `list`, not its label or hostname. Renaming a profile changes its label, not its routing identity.
|
|
44
52
|
|
|
45
|
-
|
|
53
|
+
With the older TUI, remote machines connect over noninteractive SSH. The target needs `node` on its SSH PATH, Herdr 0.9 or newer, the Herdr Pi integration and a running Herdr session. Shepherdr installs managed transport helpers under `~/.pi/agent` on each remote, runs them only for the connection lifetime and leaves no remote daemon behind. Herdr's multi-machine UI does not expose a cross-machine automation socket, so Shepherdr still owns its remote transport and Pi transcript reads.
|
|
46
54
|
|
|
47
55
|
### Migrating from separate Shepherdr machines
|
|
48
56
|
|
|
@@ -52,20 +60,20 @@ Remote machines connect over noninteractive SSH. The target needs `node` on its
|
|
|
52
60
|
|
|
53
61
|
Call `agents` with `{}` before first use, alone, then send flat request objects with `action`. Code and Notebook Mode use `await tools.agents()`. Explicit `action: "help"` also returns help.
|
|
54
62
|
|
|
55
|
-
| Action
|
|
56
|
-
|
|
|
57
|
-
| `help`
|
|
58
|
-
| `list`
|
|
59
|
-
| `find`
|
|
60
|
-
| `spawn`
|
|
61
|
-
| `send`
|
|
62
|
-
| `assign`
|
|
63
|
-
| `attach`
|
|
64
|
-
| `detach`
|
|
65
|
-
| `read`
|
|
66
|
-
| `reply`
|
|
67
|
-
| `watch`
|
|
68
|
-
| `unwatch` | Stop reporting an agent
|
|
63
|
+
| Action | Result |
|
|
64
|
+
| --------- | ------------------------------------------------------------------------------------- |
|
|
65
|
+
| `help` | Live profiles, request shapes, coordination rules and the advanced Herdr escape hatch |
|
|
66
|
+
| `list` | Profiles, machines and matching Pi agents |
|
|
67
|
+
| `find` | Agents matching a query or status |
|
|
68
|
+
| `spawn` | Spawn a profiled Pi agent and send its initial task |
|
|
69
|
+
| `send` | Send a peer message without waiting or subscribing |
|
|
70
|
+
| `assign` | Delegate a task to an existing agent |
|
|
71
|
+
| `attach` | Share context or join a board with an existing idle agent |
|
|
72
|
+
| `detach` | Leave selected membership and retain read-only counterpart checkpoints |
|
|
73
|
+
| `read` | Read the latest assistant reply or bounded terminal output |
|
|
74
|
+
| `reply` | Deliver an opaque reply to a worker's extension |
|
|
75
|
+
| `watch` | Push future settlement from an existing Pi agent |
|
|
76
|
+
| `unwatch` | Stop reporting an agent |
|
|
69
77
|
|
|
70
78
|
`spawn` and `assign` block by default. Set `blocking: false` when the controller should continue other work immediately. A profile's `blocking` setting overrides the call for `spawn`. Task completion and blockage are then delivered automatically.
|
|
71
79
|
|
|
@@ -79,15 +87,15 @@ Use `send` for messages and work updates without waiting or adding supervision.
|
|
|
79
87
|
|
|
80
88
|
Delegation and explicit `watch` keep reporting subsequent work until `unwatch` or the agent's pane closes. Finishing or failing a task clears that task, not its watch. Follow-up messages through `send` retain completion reporting without replacing the task.
|
|
81
89
|
|
|
82
|
-
Every `spawn` needs an `agent_type` and a concise `label`. The label names
|
|
90
|
+
Every `spawn` needs an `agent_type` and a concise `label`. The label names the Pi session, and also names the tab in the older Herdr TUI. The routing `name` remains optional and is derived from the label when omitted.
|
|
83
91
|
|
|
84
92
|
Cancelling a blocking call does not kill its worker. The waiter detaches and the eventual result returns through normal asynchronous delivery.
|
|
85
93
|
|
|
86
|
-
After Pi compaction or
|
|
94
|
+
After Pi compaction or Notes context rollover, the controller receives its supervised agents' exact machine and target, submitted tasks and follow-up instructions, and last observed status, including settled and blocked workers. Read a target for its reply or pending extension messages. This reminder does not start a turn or bypass normal turn preparation.
|
|
87
95
|
|
|
88
|
-
Prompts sent through `agents` identify peer messages versus delegated tasks and include the sender's host
|
|
96
|
+
Prompts sent through `agents` identify peer messages versus delegated tasks and include the sender's host and session identity. The older TUI also includes workspace, tab and pane details. Core reports use terminal addresses and include app location IDs when available. These are runtime locations, not the desktop window showing a pane.
|
|
89
97
|
|
|
90
|
-
Messages sent through `agents` bypass the receiving Pi editor, preserving unsent drafts. Update and reload Shepherdr on receiving agents as well as controllers. If a receiver is unavailable, delivery fails without pasting into its terminal.
|
|
98
|
+
Messages sent through `agents` bypass the receiving Pi editor, preserving unsent drafts. Update and reload Shepherdr on receiving agents as well as controllers. If a receiver is unavailable, delivery fails without pasting into its terminal. On the older TUI, raw `herdr agent prompt` still uses terminal input and does not provide this protection.
|
|
91
99
|
|
|
92
100
|
Messages beginning with `/` use the target Pi session's command, skill and prompt-template expansion, with sender attribution kept out of the arguments. Skills and templates retain normal task waiting. Prompt templates remain supported, but you must tell your agent which templates exist separately. When Pi Codex Conversion is installed, update and reload it too.
|
|
93
101
|
|
|
@@ -97,24 +105,24 @@ Call `agents` with `{ commands: true }` to list this session's available slash c
|
|
|
97
105
|
|
|
98
106
|
These built-in commands are available through agent messages without an allowlist:
|
|
99
107
|
|
|
100
|
-
| Command
|
|
101
|
-
|
|
|
102
|
-
| `/quit`
|
|
103
|
-
| `/model <provider/model>` | Change the model
|
|
104
|
-
| `/thinking <level>`
|
|
105
|
-
| `/name <name>`
|
|
106
|
-
| `/new`
|
|
107
|
-
| `/reload`
|
|
108
|
-
| `/resume <path>`
|
|
109
|
-
| `/compact [instructions]` | Compact the session with optional instructions
|
|
108
|
+
| Command | Result |
|
|
109
|
+
| ------------------------- | ------------------------------------------------ |
|
|
110
|
+
| `/quit` | Shut down Pi gracefully and close its Herdr pane |
|
|
111
|
+
| `/model <provider/model>` | Change the model |
|
|
112
|
+
| `/thinking <level>` | Change the thinking level |
|
|
113
|
+
| `/name <name>` | Rename the session |
|
|
114
|
+
| `/new` | Start a new session |
|
|
115
|
+
| `/reload` | Reload Pi resources |
|
|
116
|
+
| `/resume <path>` | Resume the session at the supplied path |
|
|
117
|
+
| `/compact [instructions]` | Compact the session with optional instructions |
|
|
110
118
|
|
|
111
119
|
Custom extension commands must be both registered in the receiving Pi session and allowed in its global user config. **Settings → Agent commands** shows the actual config path. The file is `pi-shepherdr.json` in Pi's agent directory, normally `~/.pi/agent`. Add `extensionCommands`, preserving any existing fields:
|
|
112
120
|
|
|
113
121
|
```json
|
|
114
122
|
{
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
123
|
+
"extensionCommands": {
|
|
124
|
+
"my-command": "Run my custom extension action"
|
|
125
|
+
}
|
|
118
126
|
}
|
|
119
127
|
```
|
|
120
128
|
|
|
@@ -130,13 +138,13 @@ An extension can publish a durable message without importing Shepherdr:
|
|
|
130
138
|
|
|
131
139
|
```ts
|
|
132
140
|
pi.appendEntry("shepherdr-extension-message", {
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
141
|
+
version: 1,
|
|
142
|
+
extension: "your-extension",
|
|
143
|
+
id: "unique-message-id",
|
|
144
|
+
state: "pending",
|
|
145
|
+
message: "Extension-authored text for the controller",
|
|
146
|
+
reply: "Extension-authored reply template", // optional
|
|
147
|
+
blocking: false,
|
|
140
148
|
});
|
|
141
149
|
```
|
|
142
150
|
|
|
@@ -145,10 +153,10 @@ Use a unique ID per message within the extension. `blocking` says whether replyi
|
|
|
145
153
|
Register the reply handler on Pi's event bus:
|
|
146
154
|
|
|
147
155
|
```ts
|
|
148
|
-
pi.events.on("@howaboua/pi-shepherdr/extension-reply/v1", event => {
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
156
|
+
pi.events.on("@howaboua/pi-shepherdr/extension-reply/v1", (event) => {
|
|
157
|
+
const { extension, id, message, respond } = event;
|
|
158
|
+
if (extension !== "your-extension") return;
|
|
159
|
+
respond(handleReply(id, message));
|
|
152
160
|
});
|
|
153
161
|
```
|
|
154
162
|
|
|
@@ -161,24 +169,27 @@ Replies use the authenticated peer connection, including across machines, and ca
|
|
|
161
169
|
Use `attach` before delegating when an independently started agent needs shared notes, history or board membership:
|
|
162
170
|
|
|
163
171
|
```js
|
|
164
|
-
await tools.agents({
|
|
172
|
+
await tools.agents({
|
|
173
|
+
action: "attach",
|
|
174
|
+
target: "<target from find>",
|
|
175
|
+
context: true,
|
|
176
|
+
board: true,
|
|
177
|
+
});
|
|
165
178
|
```
|
|
166
179
|
|
|
167
180
|
Supply both booleans and enable at least one. `context` shares notes and history through aliases without changing either session's original context identity or moving its notes. `contextAgent` addresses the target from the controller; `controllerContextAgent` addresses the controller from the target. Use these paths as `history`'s `agent_name` or as `<agent>/notes/<path>` for notes. Each agent's relative note paths remain its own. The target receives its controller alias without starting a turn.
|
|
168
181
|
|
|
169
|
-
Context attachment requires
|
|
170
|
-
|
|
171
|
-
An account mismatch rejects context sharing. Each agent keeps its own notes and history. If the account changes after attachment, pinned Remote notes become unavailable, including native Remote notes. Notes do not move to a new account or another store. Use messages to exchange the context the other agent needs.
|
|
182
|
+
Context attachment requires compatible Notes Compaction in both sessions. Each owner keeps its original identity and local notes. Optional encrypted historical reads require compatible PCC transport and the original account and backend. The explicit `context: true` choice does not depend on the controller's spawn-sharing setting. If attachment changes context access during an exec cell, start a new cell before using notes or history.
|
|
172
183
|
|
|
173
|
-
`board: true` requires Pi Agent Board loaded in both sessions. It joins the controller's enabled board and returns `boardAgent` for subscriptions and notifications. The target's previous board archive stays untouched. If the folders differ, that archive remains in its original folder rather than becoming part of the controller's archive. Board-only attachment works without Codex Conversion
|
|
184
|
+
`board: true` requires Pi Agent Board loaded in both sessions. It joins the controller's enabled board and returns `boardAgent` for subscriptions and notifications. The target's previous board archive stays untouched. If the folders differ, that archive remains in its original folder rather than becoming part of the controller's archive. Board-only attachment works without Notes or Codex Conversion.
|
|
174
185
|
|
|
175
186
|
The target must be idle and both Pi sessions must be saved. Existing shared-context members and controllers with context children cannot be context targets. Existing board members and roots with board children cannot switch boards. A target supports one controller and one fixed set of attachment choices. Attachment starts no task or watch; `assign` and `send` never attach implicitly.
|
|
176
187
|
|
|
177
|
-
Attachments survive resume, not forks.
|
|
188
|
+
Attachments survive resume, not forks. Live notes and history access needs the owning Pi processes and machine connections. After an interrupted attachment, resume the original sessions and retry the same target and choices. Retries reuse the original aliases and membership.
|
|
178
189
|
|
|
179
|
-
To detach, call `agents` with `action: "detach"`, the same target, and both booleans. Enable each membership you want to leave. Context detach retains counterpart notes under the existing aliases read-only. Local
|
|
190
|
+
To detach, call `agents` with `action: "detach"`, the same target, and both booleans. Enable each membership you want to leave. Context detach retains counterpart notes under the existing aliases read-only. Local notes use captured checkpoints. Historical Remote references retain their original authenticated address, not a plaintext snapshot. Counterpart history and writes stop at detach. Native identities remain unchanged. Board detach restores the target's previous board without deleting either archive. Board members with children cannot detach. Reattachment is unsupported.
|
|
180
191
|
|
|
181
|
-
If an attached owner closes
|
|
192
|
+
If an attached owner closes, local note reads use its latest saved checkpoints when the source machine and session file remain reachable. Otherwise they return the timestamped attachment snapshot, marked stale with the access failure. This never writes to the owner's session. Historical encrypted reads require their original account and backend. Backend failures remain visible. An incomplete detach fails with a retry instruction rather than claiming success.
|
|
182
193
|
|
|
183
194
|
## Message board
|
|
184
195
|
|
|
@@ -198,20 +209,19 @@ Child board calls use the owning Pi sessions and existing SSH connections, not a
|
|
|
198
209
|
|
|
199
210
|
With compatible Pi Codex Conversion on both ends, Shepherdr marks fresh spawned workers before their first task with their immediate parent's native Pi session ID and `subagentKind: "collab_spawn"`. Workers also inherit the parent's effective cache routing identity, including nested and remote spawns. Each worker keeps its own native session, sockets and history. Cache routing works with shared notes disabled and does not grant notes access or copy the parent's transcript. Only matching prompt prefixes can benefit. Resume preserves the relationship; forks and profiles selecting existing sessions do not acquire it. Older PCC versions retain ordinary delegation and any supported parent linkage. The [extension API guide](../../docs/extension-apis.md#parent-and-worker-relationships) documents PCC's service contract for other orchestrators. Shepherdr owns transport, not a separate public relationship RPC API.
|
|
200
211
|
|
|
201
|
-
With
|
|
212
|
+
With Notes Compaction on both ends, enable **Share subagent context** under `/notes` in the controller. It is off by default. Shared `spawn` gives each child a unique context identity before its first turn; `contextAgent` identifies its notes and history. Nested spawns stay in the same family. Turning sharing off affects new spawns only. Existing identity survives resume. `assign` and independently started agents remain unchanged.
|
|
202
213
|
|
|
203
214
|
Set `"share_context": false` in a profile to keep its new workers' notes and history independent even when controller sharing is enabled. Omission or `true` follows the controller setting, never turns sharing on itself. This separates context, not filesystem permissions or information included in the task.
|
|
204
215
|
|
|
205
216
|
Pi creates each worker session normally. The worker records its shared identity before Shepherdr delivers the first task; no pre-created session file or launch override is needed.
|
|
206
217
|
|
|
207
|
-
|
|
218
|
+
Shared notes route through their owning Pi sessions and existing SSH connections. Those owners and intermediate controllers must be running. Resume the owner and reconnect under `/herdr` → **Status** after a connection loss. No note store is copied or silently substituted. New writes stay local; optional hybrid lookup is read-only.
|
|
208
219
|
|
|
209
|
-
|
|
220
|
+
Shepherdr works without Notes or PCC. A target without active Notes sharing still starts independently with a warning. Invalid bindings fail before task delivery. Profiles selecting existing sessions cannot participate in shared `spawn`; use `attach`, then `assign`.
|
|
210
221
|
|
|
211
222
|
## Profiles
|
|
212
223
|
|
|
213
224
|
On first load, Shepherdr installs three editable profiles:
|
|
214
|
-
|
|
215
225
|
- `general` uses `openai-codex/gpt-6-sol` with `high` thinking for implementation
|
|
216
226
|
- `explorer` uses `openai-codex/gpt-6-luna` with `high` thinking for read-only discovery
|
|
217
227
|
- `reviewer` uses `openai-codex/gpt-6-luna` with `xhigh` thinking for generic read-only review
|
|
@@ -228,19 +238,18 @@ That directory is authoritative after initialization. Edit a profile to change i
|
|
|
228
238
|
|
|
229
239
|
```json
|
|
230
240
|
{
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
241
|
+
"description": "Read-only dependency review",
|
|
242
|
+
"model": "provider/model",
|
|
243
|
+
"thinking": "high",
|
|
244
|
+
"prompt": "prompt.md",
|
|
245
|
+
"accepts": ["base"],
|
|
246
|
+
"pi_args": []
|
|
237
247
|
}
|
|
238
248
|
```
|
|
239
249
|
|
|
240
250
|
`prompt` is read as system-prompt text. An optional `prepare` module may export `prepare({ cwd, message, base, local })` and return the worker message. Preparation runs on the controlling machine before dispatch; `local` says whether that machine also hosts the worker.
|
|
241
251
|
|
|
242
252
|
Optional profile settings:
|
|
243
|
-
|
|
244
253
|
- `blocking`: `true` forces blocking spawns, `false` forces asynchronous spawns. Omission respects the call's `blocking` value, which defaults to `true`. This does not affect `assign` to existing agents.
|
|
245
254
|
- `share_context`: `false` opts new spawns out of shared notes and history. Omission or `true` follows the controller setting.
|
|
246
255
|
|
|
@@ -248,7 +257,7 @@ Optional profile settings:
|
|
|
248
257
|
|
|
249
258
|
## Advanced Herdr control
|
|
250
259
|
|
|
251
|
-
Ordinary delegation stays inside `agents`. For
|
|
260
|
+
Ordinary delegation stays inside `agents`. For terminal operations on Core, run `hc --skill`. For window operations, use `herdr-app --skill`. The older TUI provides its own guide through `herdr --skill`.
|
|
252
261
|
|
|
253
262
|
Herdr still owns terminals, layout, agent processes and restored sessions. Shepherdr owns event subscriptions, remote routing, the fleet widget and purple settlement messages.
|
|
254
263
|
|
|
@@ -261,8 +270,10 @@ Other extensions can query the current role synchronously through public Pi even
|
|
|
261
270
|
```ts
|
|
262
271
|
let worker = false;
|
|
263
272
|
pi.events.emit("shepherdr:worker-role:v1", {
|
|
264
|
-
|
|
265
|
-
|
|
273
|
+
sessionManager: ctx.sessionManager,
|
|
274
|
+
reply: (value: boolean) => {
|
|
275
|
+
worker = value;
|
|
276
|
+
},
|
|
266
277
|
});
|
|
267
278
|
```
|
|
268
279
|
|
package/biome.json
CHANGED
package/index.ts
CHANGED
|
@@ -5,9 +5,10 @@ import { acceptFocus, registerFocusArrivals } from "./src/agents-focus.js";
|
|
|
5
5
|
import { createAgentsTool } from "./src/agents-tool.js";
|
|
6
6
|
import { AgentBoard } from "./src/board/host.js";
|
|
7
7
|
import { registerAgentController } from "./src/controller.js";
|
|
8
|
+
import { registerCoreStatus } from "./src/core/status.js";
|
|
8
9
|
import { registerDeveloperDelivery } from "./src/delivery.js";
|
|
9
|
-
import { AgentFleet } from "./src/fleet.js";
|
|
10
|
-
import { registerAgentEventRenderer } from "./src/messages.js";
|
|
10
|
+
import { AgentFleet } from "./src/fleet/index.js";
|
|
11
|
+
import { registerAgentEventRenderer } from "./src/messages/render.js";
|
|
11
12
|
import { createPeerCommands } from "./src/peer-commands.js";
|
|
12
13
|
import { registerPeerInbox } from "./src/peer-inbox.js";
|
|
13
14
|
import { registerProfilePrompt } from "./src/profile-prompt.js";
|
|
@@ -23,6 +24,7 @@ const CODE_MODE_MODULE = `${CODE_MODE_PACKAGE}/code-mode`;
|
|
|
23
24
|
export default async function shepherdrExtension(
|
|
24
25
|
pi: ExtensionAPI,
|
|
25
26
|
): Promise<void> {
|
|
27
|
+
registerCoreStatus(pi);
|
|
26
28
|
const workerRole = registerWorkerRole(pi);
|
|
27
29
|
registerPackageChangelog(pi);
|
|
28
30
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@howaboua/pi-shepherdr",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.25",
|
|
4
4
|
"description": "Persistent blocking and asynchronous Pi agents through Herdr.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -43,28 +43,33 @@
|
|
|
43
43
|
"pack:dry": "npm pack --dry-run"
|
|
44
44
|
},
|
|
45
45
|
"peerDependencies": {
|
|
46
|
-
"@howaboua/pi-
|
|
46
|
+
"@howaboua/pi-notes-compaction": ">=0.0.12",
|
|
47
|
+
"@howaboua/pi-codex-conversion": ">=4.0.6",
|
|
47
48
|
"@earendil-works/pi-ai": ">=1.1.0",
|
|
48
49
|
"@earendil-works/pi-coding-agent": ">=1.2.0",
|
|
49
50
|
"@earendil-works/pi-tui": ">=1.1.0",
|
|
50
51
|
"typebox": "*"
|
|
51
52
|
},
|
|
52
53
|
"peerDependenciesMeta": {
|
|
54
|
+
"@howaboua/pi-notes-compaction": {
|
|
55
|
+
"optional": true
|
|
56
|
+
},
|
|
53
57
|
"@howaboua/pi-codex-conversion": {
|
|
54
58
|
"optional": true
|
|
55
59
|
}
|
|
56
60
|
},
|
|
57
61
|
"dependencies": {
|
|
58
|
-
"@howaboua/pi-agent-board": "0.0.
|
|
62
|
+
"@howaboua/pi-agent-board": "0.0.4"
|
|
59
63
|
},
|
|
60
64
|
"devDependencies": {
|
|
61
|
-
"@howaboua/pi-
|
|
62
|
-
"@
|
|
63
|
-
"@
|
|
64
|
-
"@earendil-works/pi-
|
|
65
|
-
"@earendil-works/pi-
|
|
65
|
+
"@howaboua/pi-notes-compaction": "0.0.12",
|
|
66
|
+
"@howaboua/pi-codex-conversion": "4.0.6",
|
|
67
|
+
"@biomejs/biome": "^2.6.3",
|
|
68
|
+
"@earendil-works/pi-ai": "1.4.0",
|
|
69
|
+
"@earendil-works/pi-coding-agent": "1.4.0",
|
|
70
|
+
"@earendil-works/pi-tui": "1.4.0",
|
|
66
71
|
"@types/node": "^26.6.5",
|
|
67
|
-
"typebox": "1.3
|
|
72
|
+
"typebox": "1.4.3",
|
|
68
73
|
"typescript": "^7.0.2"
|
|
69
74
|
},
|
|
70
75
|
"pi": {
|
package/src/agents-contract.ts
CHANGED
|
@@ -97,12 +97,15 @@ const AgentsRequest = Type.Object(
|
|
|
97
97
|
{ additionalProperties: false },
|
|
98
98
|
);
|
|
99
99
|
|
|
100
|
-
export const AgentsParameters = Type.Object(
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
100
|
+
export const AgentsParameters = Type.Object(
|
|
101
|
+
{
|
|
102
|
+
action: Type.Optional(StringEnum(ACTIONS)),
|
|
103
|
+
commands: Type.Optional(Type.Literal(true)),
|
|
104
|
+
target: Type.Optional(Type.String()),
|
|
105
|
+
machine: Type.Optional(Type.String()),
|
|
106
|
+
},
|
|
107
|
+
{ additionalProperties: true },
|
|
108
|
+
);
|
|
106
109
|
|
|
107
110
|
export type AgentsParams = Static<typeof AgentsRequest>;
|
|
108
111
|
export type AgentsToolParams = Static<typeof AgentsParameters>;
|