@howaboua/pi-shepherdr 0.2.22 → 0.2.24
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 +16 -18
- package/README.md +79 -58
- package/biome.json +1 -1
- package/index.ts +7 -3
- package/package.json +14 -9
- package/src/agents-discovery.ts +42 -27
- package/src/agents-focus.ts +2 -2
- package/src/agents-reply.ts +1 -1
- package/src/agents-spawn.ts +143 -137
- package/src/agents-tool.ts +3 -3
- package/src/agents-work.ts +33 -9
- 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 +2 -3
- package/src/board/host.ts +2 -2
- package/src/board/membership.ts +1 -1
- package/src/{control-panel-actions.ts → control-panel/actions.ts} +2 -2
- package/src/{control-panel.ts → control-panel/index.ts} +4 -4
- package/src/{control-panel-items.ts → control-panel/items.ts} +3 -3
- package/src/{control-panel-view.ts → control-panel/view.ts} +3 -3
- package/src/controller.ts +6 -3
- package/src/fleet/index.ts +384 -0
- package/src/fleet/inspection.ts +141 -0
- package/src/fleet/machine.ts +52 -0
- package/src/fleet/monitor.ts +71 -0
- package/src/fleet/persistence.ts +42 -0
- package/src/fleet/reconnect.ts +75 -0
- package/src/fleet/setup.ts +92 -0
- package/src/launch.ts +14 -2
- package/src/messages/attachments.ts +39 -0
- package/src/messages/attribution.ts +75 -0
- package/src/messages/event-details.ts +69 -0
- package/src/messages/events.ts +189 -0
- package/src/messages/focus.ts +38 -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-extension-messages.ts +14 -1
- package/src/monitor.ts +4 -2
- package/src/peer-inbox.ts +2 -2
- package/src/profile-prompt.ts +32 -0
- package/src/profiles.ts +5 -25
- 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/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} +23 -233
- package/src/shared-context-host.ts +33 -11
- package/src/shared-context.ts +10 -4
- package/src/spawn-context.ts +20 -17
- package/src/voice-handoff.ts +1 -1
- package/src/worker-role.ts +83 -0
- package/src/worker-service.ts +74 -89
- package/src/fleet.ts +0 -702
- package/src/messages.ts +0 -629
- package/src/remote-client.ts +0 -751
package/CHANGELOG.md
CHANGED
|
@@ -1,15 +1,29 @@
|
|
|
1
1
|
# @howaboua/pi-shepherdr
|
|
2
2
|
|
|
3
|
+
## 0.2.24
|
|
4
|
+
|
|
5
|
+
- - **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.
|
|
6
|
+
- Agent guidance now directs controllers to close finished workers without preceding acknowledgement messages.
|
|
7
|
+
- Attached note reads keep private routing details out of results while preserving read-only and stale-checkpoint warnings. Attachment acknowledgements omit internal bookkeeping.
|
|
8
|
+
- GPT mode uses note-style agent help and Board briefings.
|
|
9
|
+
|
|
10
|
+
## 0.2.23
|
|
11
|
+
|
|
12
|
+
- - 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.
|
|
13
|
+
- Fixed broken remote connections causing unhandled pipe errors and leaving requests pending.
|
|
14
|
+
- Worker-notice warnings now identify the affected machine and explain how to reconnect.
|
|
15
|
+
- GPT-mode Board briefings use denser guidance.
|
|
16
|
+
- Blocking agent calls can run in parallel while the controller waits for their results.
|
|
17
|
+
- Launched workers identify themselves to compatible extensions so human-only features can stay off.
|
|
18
|
+
|
|
3
19
|
## 0.2.22
|
|
4
20
|
|
|
5
21
|
- **Worker integrations**
|
|
6
|
-
|
|
7
22
|
- Fresh workers now share their parent's cache routing with compatible Codex Conversion. Shared notes remain optional, and native sessions and histories remain separate.
|
|
8
23
|
- Fresh workers inherit the live Board setting before their first request, keeping Board tools and guidance available from startup.
|
|
9
24
|
- Added an optional Pulses runner with persistent workers, saved-session reuse and completion reports that wake the parent.
|
|
10
25
|
|
|
11
26
|
**Agent tools and guidance**
|
|
12
|
-
|
|
13
27
|
- Expanded tool calls now show outgoing tasks, messages, replies and focus handoffs in full.
|
|
14
28
|
- Added compact agent help and hosted Board briefings for PCC GPT prompt mode.
|
|
15
29
|
- Agent discovery now uses the same help contract across native, Code and Notebook tools.
|
|
@@ -23,7 +37,6 @@
|
|
|
23
37
|
## 0.2.20
|
|
24
38
|
|
|
25
39
|
- Requires Pi 1.2.0 or newer.
|
|
26
|
-
|
|
27
40
|
- Idle assignments and completion reports now apply Pi's full prompt and tool preparation.
|
|
28
41
|
- Fixed local and remote spawns failing during session startup.
|
|
29
42
|
- Supervision reminders now distinguish other agents' tasks from the current task after compaction.
|
|
@@ -37,7 +50,6 @@
|
|
|
37
50
|
## 0.2.18
|
|
38
51
|
|
|
39
52
|
- Replaced the Ask-specific `answer` action with `reply` for extension replies. Update and reload Ask and Shepherdr together on controllers and workers.
|
|
40
|
-
|
|
41
53
|
- Assignments now update running agents without losing pending results or replacing existing waiters. Messages and assignments also reach blocked workers.
|
|
42
54
|
- 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.
|
|
43
55
|
- Pending extension messages remain visible until their producer closes them. Blocking messages arrive with the blocked result. Nonblocking messages notify separately once.
|
|
@@ -76,7 +88,6 @@
|
|
|
76
88
|
## 0.2.14
|
|
77
89
|
|
|
78
90
|
- Delegated agents keep reporting after task completion, including follow-up work.
|
|
79
|
-
|
|
80
91
|
- Added shared-board awareness across native, Code and Notebook modes.
|
|
81
92
|
- Preserves orchestration guidance across compaction and context rollover.
|
|
82
93
|
- Restores running workers' targets and full tasks after compaction or context rollover to prevent duplicate delegation.
|
|
@@ -109,7 +120,6 @@
|
|
|
109
120
|
## 0.2.10
|
|
110
121
|
|
|
111
122
|
- Requires Pi 1.0.0 or later.
|
|
112
|
-
|
|
113
123
|
- Added optional agent-tree message boards with channels, replies, search, subscriptions and persistent folder-local history. Boards require Node.js 22.13 or later.
|
|
114
124
|
- Added session, exact-folder and global board settings under `/herdr board`. Board notifications reach running turns without waking idle agents.
|
|
115
125
|
- 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.
|
|
@@ -123,14 +133,12 @@
|
|
|
123
133
|
## 0.2.8
|
|
124
134
|
|
|
125
135
|
- Agent profiles now control delegation waiting and shared context.
|
|
126
|
-
|
|
127
136
|
- 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.
|
|
128
137
|
- Added `share_context: false` for independent subagent notes and history. Existing installed profiles remain unchanged.
|
|
129
138
|
|
|
130
139
|
## 0.2.7
|
|
131
140
|
|
|
132
141
|
- Added opt-in shared notes and history for spawned agents with Pi Codex Conversion.
|
|
133
|
-
|
|
134
142
|
- New and nested workers receive distinct, persistent context identities before their first task.
|
|
135
143
|
- 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.
|
|
136
144
|
- Sharing follows **Share subagent context** under `/codex context` and affects new spawns only. Existing agents and ordinary delegation remain unchanged.
|
|
@@ -142,7 +150,6 @@
|
|
|
142
150
|
## 0.2.6
|
|
143
151
|
|
|
144
152
|
- Fixed exact Ask answer confirmation and retry reconciliation without resending input.
|
|
145
|
-
|
|
146
153
|
- Keep answers pending while the original Ask is still open.
|
|
147
154
|
- Preserve accepted receipts when the worker's reply fails.
|
|
148
155
|
- Report dismissed Asks as rejected.
|
|
@@ -150,7 +157,6 @@
|
|
|
150
157
|
## 0.2.5
|
|
151
158
|
|
|
152
159
|
- GPT-6 Sol and Luna now share Astra's Codex support.
|
|
153
|
-
|
|
154
160
|
- Removed `/terra`; use `/luna` instead.
|
|
155
161
|
- Added Responses Lite, non-destructive reasoning changes and terse context guidance for GPT-6 Sol and Luna.
|
|
156
162
|
- Image descriptions now use GPT-6 Luna directly instead of preferring older mini models.
|
|
@@ -164,7 +170,6 @@
|
|
|
164
170
|
## 0.2.3
|
|
165
171
|
|
|
166
172
|
- Fixed context continuity, voice replies, and patch preservation.
|
|
167
|
-
|
|
168
173
|
- 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.
|
|
169
174
|
- Worker updates now accept up to 8 KiB without truncation announcements or offers to read the rest.
|
|
170
175
|
- Reasoning-summary forwarding now recognizes GPT-6 models.
|
|
@@ -186,14 +191,12 @@
|
|
|
186
191
|
## 0.2.1
|
|
187
192
|
|
|
188
193
|
- Deliver peer messages directly to Pi without submitting unsent human drafts.
|
|
189
|
-
|
|
190
194
|
- Preserve slash-command arguments and use the target session's skill and prompt-template expansion.
|
|
191
195
|
- Return submission-only acknowledgements for registered extension commands instead of waiting for an assistant reply.
|
|
192
196
|
|
|
193
197
|
Requires Pi 0.84.4 or newer. Update and reload Shepherdr on both controllers and workers, and Pi Codex Conversion where installed.
|
|
194
198
|
|
|
195
199
|
- Fixed idle agent reports and manual checkpoint requests to preserve prompt preparation, coalesce concurrent continuations, and process reports arriving during turn settlement.
|
|
196
|
-
|
|
197
200
|
- 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.
|
|
198
201
|
- 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.
|
|
199
202
|
- 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.
|
|
@@ -202,7 +205,6 @@
|
|
|
202
205
|
## 0.2.0
|
|
203
206
|
|
|
204
207
|
- 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.
|
|
205
|
-
|
|
206
208
|
- Agent prompts and reports identify their source workspace, tab and pane, including current names.
|
|
207
209
|
- Attributed messages to running Pi Codex agents use developer steering. Idle tasks retain normal user kickoff and extension preparation.
|
|
208
210
|
- `send` delivers peer messages without blocking or subscribing; use `assign` to delegate work to an existing agent.
|
|
@@ -211,7 +213,6 @@
|
|
|
211
213
|
## 0.1.6
|
|
212
214
|
|
|
213
215
|
- Deliver blocked-agent handoffs even when transcripts are unavailable.
|
|
214
|
-
|
|
215
216
|
- Reviewer spawns wait for their result before the controller continues.
|
|
216
217
|
- Implementation subagents are instructed to work directly rather than delegate implementation again.
|
|
217
218
|
- Discover and answer Pi Ask questions called inside Code and Notebook Mode.
|
|
@@ -226,14 +227,12 @@
|
|
|
226
227
|
## 0.1.4
|
|
227
228
|
|
|
228
229
|
- Preserve extension-owned messages while delivering true developer-role policy through compatible Pi Codex Responses adapters.
|
|
229
|
-
|
|
230
230
|
- Add an optional custom-message API that retains caller rendering and restoration fields.
|
|
231
231
|
- Route Shepherdr's unclaimed worker events and orchestration toggles through it, preserving ordinary Pi delivery when unavailable.
|
|
232
232
|
- Send review preface/triage policy and realtime voice start/end guidance as developer messages without elevating raw reviewer findings, spoken delegations, or transcript tails.
|
|
233
233
|
- Keep persisted developer messages in context across model switches, using ordinary Pi conversion on incompatible models.
|
|
234
234
|
|
|
235
235
|
- Fix worker settlement, custom model preservation, and prompt-only image generation.
|
|
236
|
-
|
|
237
236
|
- Settle Shepherdr workers after Pi expands skill or prompt-template invocations.
|
|
238
237
|
- Preserve custom Codex models and `models.json` overrides, including after refresh.
|
|
239
238
|
- Keep optional tool arguments optional in Codex Responses requests while preserving explicit strict sampling.
|
|
@@ -244,7 +243,6 @@
|
|
|
244
243
|
## 0.1.3
|
|
245
244
|
|
|
246
245
|
- Replaced Shepherdr's fire-and-forget tool with persistent blocking and asynchronous agents in normal Pi, Code Mode, and Notebook Mode.
|
|
247
|
-
|
|
248
246
|
- Start, steer, inspect, and answer multiple agents through the `agents` tool.
|
|
249
247
|
- Customize the bundled general, explorer, and reviewer profiles or add your own.
|
|
250
248
|
- Activate orchestration mode with `/herdr` when the main session should coordinate agent work.
|
package/README.md
CHANGED
|
@@ -52,23 +52,25 @@ Remote machines connect over noninteractive SSH. The target needs `node` on its
|
|
|
52
52
|
|
|
53
53
|
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
54
|
|
|
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
|
|
55
|
+
| Action | Result |
|
|
56
|
+
| --------- | ------------------------------------------------------------------------------------- |
|
|
57
|
+
| `help` | Live profiles, request shapes, coordination rules and the advanced Herdr escape hatch |
|
|
58
|
+
| `list` | Profiles, machines and matching Pi agents |
|
|
59
|
+
| `find` | Agents matching a query or status |
|
|
60
|
+
| `spawn` | Spawn a profiled Pi agent and send its initial task |
|
|
61
|
+
| `send` | Send a peer message without waiting or subscribing |
|
|
62
|
+
| `assign` | Delegate a task to an existing agent |
|
|
63
|
+
| `attach` | Share context or join a board with an existing idle agent |
|
|
64
|
+
| `detach` | Leave selected membership and retain read-only counterpart checkpoints |
|
|
65
|
+
| `read` | Read the latest assistant reply or bounded terminal output |
|
|
66
|
+
| `reply` | Deliver an opaque reply to a worker's extension |
|
|
67
|
+
| `watch` | Push future settlement from an existing Pi agent |
|
|
68
|
+
| `unwatch` | Stop reporting an agent |
|
|
69
69
|
|
|
70
70
|
`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
71
|
|
|
72
|
+
Blocking calls can run in parallel. In Code or Notebook, use `await Promise.allSettled([...])` to start independent calls together and wait for every result, including failures. Keep blocking enabled when the controller must wait, such as for parallel reviews. Consecutive `await` calls still run one after another; `Promise.all` can exit early on failure.
|
|
73
|
+
|
|
72
74
|
Nonblocking extension messages notify the controller once; blocking messages arrive with the worker's blocked result. Both remain visible in `read` and later task reports until the producer closes them. Each replyable message includes a ready `reply` call with its machine, target, extension and message ID. Fill in the extension's reply template. `send` does not resolve an extension message.
|
|
73
75
|
|
|
74
76
|
`reply` returns the extension's receipt after semantic delivery. Blocking messages also wait for resumed work unless another call already owns that wait. Nonblocking replies do not wait for the worker's task to finish. Shepherdr forwards strings unchanged. The producing extension owns their meaning, validation and retries.
|
|
@@ -81,7 +83,7 @@ Every `spawn` needs an `agent_type` and a concise `label`. The label names both
|
|
|
81
83
|
|
|
82
84
|
Cancelling a blocking call does not kill its worker. The waiter detaches and the eventual result returns through normal asynchronous delivery.
|
|
83
85
|
|
|
84
|
-
After Pi compaction or
|
|
86
|
+
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.
|
|
85
87
|
|
|
86
88
|
Prompts sent through `agents` identify peer messages versus delegated tasks and include the sender's host, session, workspace, tab and pane identity, with current names. Reports include source workspace and tab names too. Raw `herdr agent prompt` calls bypass this attribution. These are runtime locations, not the desktop window showing a pane.
|
|
87
89
|
|
|
@@ -95,24 +97,24 @@ Call `agents` with `{ commands: true }` to list this session's available slash c
|
|
|
95
97
|
|
|
96
98
|
These built-in commands are available through agent messages without an allowlist:
|
|
97
99
|
|
|
98
|
-
| Command
|
|
99
|
-
|
|
|
100
|
-
| `/quit`
|
|
101
|
-
| `/model <provider/model>` | Change the model
|
|
102
|
-
| `/thinking <level>`
|
|
103
|
-
| `/name <name>`
|
|
104
|
-
| `/new`
|
|
105
|
-
| `/reload`
|
|
106
|
-
| `/resume <path>`
|
|
107
|
-
| `/compact [instructions]` | Compact the session with optional instructions
|
|
100
|
+
| Command | Result |
|
|
101
|
+
| ------------------------- | ------------------------------------------------ |
|
|
102
|
+
| `/quit` | Shut down Pi gracefully and close its Herdr pane |
|
|
103
|
+
| `/model <provider/model>` | Change the model |
|
|
104
|
+
| `/thinking <level>` | Change the thinking level |
|
|
105
|
+
| `/name <name>` | Rename the session |
|
|
106
|
+
| `/new` | Start a new session |
|
|
107
|
+
| `/reload` | Reload Pi resources |
|
|
108
|
+
| `/resume <path>` | Resume the session at the supplied path |
|
|
109
|
+
| `/compact [instructions]` | Compact the session with optional instructions |
|
|
108
110
|
|
|
109
111
|
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:
|
|
110
112
|
|
|
111
113
|
```json
|
|
112
114
|
{
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
115
|
+
"extensionCommands": {
|
|
116
|
+
"my-command": "Run my custom extension action"
|
|
117
|
+
}
|
|
116
118
|
}
|
|
117
119
|
```
|
|
118
120
|
|
|
@@ -128,13 +130,13 @@ An extension can publish a durable message without importing Shepherdr:
|
|
|
128
130
|
|
|
129
131
|
```ts
|
|
130
132
|
pi.appendEntry("shepherdr-extension-message", {
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
133
|
+
version: 1,
|
|
134
|
+
extension: "your-extension",
|
|
135
|
+
id: "unique-message-id",
|
|
136
|
+
state: "pending",
|
|
137
|
+
message: "Extension-authored text for the controller",
|
|
138
|
+
reply: "Extension-authored reply template", // optional
|
|
139
|
+
blocking: false,
|
|
138
140
|
});
|
|
139
141
|
```
|
|
140
142
|
|
|
@@ -143,10 +145,10 @@ Use a unique ID per message within the extension. `blocking` says whether replyi
|
|
|
143
145
|
Register the reply handler on Pi's event bus:
|
|
144
146
|
|
|
145
147
|
```ts
|
|
146
|
-
pi.events.on("@howaboua/pi-shepherdr/extension-reply/v1", event => {
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
148
|
+
pi.events.on("@howaboua/pi-shepherdr/extension-reply/v1", (event) => {
|
|
149
|
+
const { extension, id, message, respond } = event;
|
|
150
|
+
if (extension !== "your-extension") return;
|
|
151
|
+
respond(handleReply(id, message));
|
|
150
152
|
});
|
|
151
153
|
```
|
|
152
154
|
|
|
@@ -159,24 +161,27 @@ Replies use the authenticated peer connection, including across machines, and ca
|
|
|
159
161
|
Use `attach` before delegating when an independently started agent needs shared notes, history or board membership:
|
|
160
162
|
|
|
161
163
|
```js
|
|
162
|
-
await tools.agents({
|
|
164
|
+
await tools.agents({
|
|
165
|
+
action: "attach",
|
|
166
|
+
target: "<target from find>",
|
|
167
|
+
context: true,
|
|
168
|
+
board: true,
|
|
169
|
+
});
|
|
163
170
|
```
|
|
164
171
|
|
|
165
172
|
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.
|
|
166
173
|
|
|
167
|
-
Context attachment requires
|
|
174
|
+
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.
|
|
168
175
|
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
`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 and with Remote context storage.
|
|
176
|
+
`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.
|
|
172
177
|
|
|
173
178
|
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.
|
|
174
179
|
|
|
175
|
-
Attachments survive resume, not forks.
|
|
180
|
+
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.
|
|
176
181
|
|
|
177
|
-
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
|
|
182
|
+
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.
|
|
178
183
|
|
|
179
|
-
If an attached owner closes
|
|
184
|
+
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.
|
|
180
185
|
|
|
181
186
|
## Message board
|
|
182
187
|
|
|
@@ -196,20 +201,19 @@ Child board calls use the owning Pi sessions and existing SSH connections, not a
|
|
|
196
201
|
|
|
197
202
|
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.
|
|
198
203
|
|
|
199
|
-
With
|
|
204
|
+
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.
|
|
200
205
|
|
|
201
206
|
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.
|
|
202
207
|
|
|
203
208
|
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.
|
|
204
209
|
|
|
205
|
-
|
|
210
|
+
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.
|
|
206
211
|
|
|
207
|
-
|
|
212
|
+
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`.
|
|
208
213
|
|
|
209
214
|
## Profiles
|
|
210
215
|
|
|
211
216
|
On first load, Shepherdr installs three editable profiles:
|
|
212
|
-
|
|
213
217
|
- `general` uses `openai-codex/gpt-6-sol` with `high` thinking for implementation
|
|
214
218
|
- `explorer` uses `openai-codex/gpt-6-luna` with `high` thinking for read-only discovery
|
|
215
219
|
- `reviewer` uses `openai-codex/gpt-6-luna` with `xhigh` thinking for generic read-only review
|
|
@@ -226,19 +230,18 @@ That directory is authoritative after initialization. Edit a profile to change i
|
|
|
226
230
|
|
|
227
231
|
```json
|
|
228
232
|
{
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
233
|
+
"description": "Read-only dependency review",
|
|
234
|
+
"model": "provider/model",
|
|
235
|
+
"thinking": "high",
|
|
236
|
+
"prompt": "prompt.md",
|
|
237
|
+
"accepts": ["base"],
|
|
238
|
+
"pi_args": []
|
|
235
239
|
}
|
|
236
240
|
```
|
|
237
241
|
|
|
238
242
|
`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.
|
|
239
243
|
|
|
240
244
|
Optional profile settings:
|
|
241
|
-
|
|
242
245
|
- `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.
|
|
243
246
|
- `share_context`: `false` opts new spawns out of shared notes and history. Omission or `true` follows the controller setting.
|
|
244
247
|
|
|
@@ -250,6 +253,24 @@ Ordinary delegation stays inside `agents`. For workspace, tab, pane, process, fo
|
|
|
250
253
|
|
|
251
254
|
Herdr still owns terminals, layout, agent processes and restored sessions. Shepherdr owns event subscriptions, remote routing, the fleet widget and purple settlement messages.
|
|
252
255
|
|
|
256
|
+
## Worker role integration
|
|
257
|
+
|
|
258
|
+
Every Shepherdr launch carries `--shepherdr-worker`, including remote workers, profiles without prompts and resumed workers. The role survives session resume after the first task. Forks do not inherit the saved role, but a fork opened inside a flagged worker process is still a worker. Existing agents reached through `assign` or `attach` are not automatically classified as workers. Pi Codex Conversion is not required.
|
|
259
|
+
|
|
260
|
+
Other extensions can query the current role synchronously through public Pi events, including during `session_start`:
|
|
261
|
+
|
|
262
|
+
```ts
|
|
263
|
+
let worker = false;
|
|
264
|
+
pi.events.emit("shepherdr:worker-role:v1", {
|
|
265
|
+
sessionManager: ctx.sessionManager,
|
|
266
|
+
reply: (value: boolean) => {
|
|
267
|
+
worker = value;
|
|
268
|
+
},
|
|
269
|
+
});
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
No reply means Shepherdr is unavailable. The query adds no model instructions or tools. Worker launch flags describe the process, so new sessions opened inside that process remain workers.
|
|
273
|
+
|
|
253
274
|
## Pulse runner
|
|
254
275
|
|
|
255
276
|
Shepherdr implements Pulses' optional detached-runner contract through Pi events. Pulses owns scheduling. Each worker runs in a separate Pi process, so the main agent remains available. Its final response returns through the same monitored waking delivery as asynchronous `agents` calls, including ordinary kickoff preparation and rollover admission. There is no passive-result or blocking execution mode.
|
package/biome.json
CHANGED
package/index.ts
CHANGED
|
@@ -6,13 +6,15 @@ 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
8
|
import { registerDeveloperDelivery } from "./src/delivery.js";
|
|
9
|
-
import { AgentFleet } from "./src/fleet.js";
|
|
10
|
-
import { registerAgentEventRenderer } from "./src/messages.js";
|
|
9
|
+
import { AgentFleet } from "./src/fleet/index.js";
|
|
10
|
+
import { registerAgentEventRenderer } from "./src/messages/render.js";
|
|
11
11
|
import { createPeerCommands } from "./src/peer-commands.js";
|
|
12
12
|
import { registerPeerInbox } from "./src/peer-inbox.js";
|
|
13
|
+
import { registerProfilePrompt } from "./src/profile-prompt.js";
|
|
13
14
|
import { installAgentProfiles } from "./src/profiles.js";
|
|
14
15
|
import { registerSharedAgentContext } from "./src/shared-context-host.js";
|
|
15
16
|
import { registerVoiceFocusReceiver } from "./src/voice-handoff.js";
|
|
17
|
+
import { registerWorkerRole } from "./src/worker-role.js";
|
|
16
18
|
import { registerWorkerService } from "./src/worker-service.js";
|
|
17
19
|
|
|
18
20
|
const CODE_MODE_PACKAGE = "@howaboua/pi-codex-conversion";
|
|
@@ -21,9 +23,11 @@ const CODE_MODE_MODULE = `${CODE_MODE_PACKAGE}/code-mode`;
|
|
|
21
23
|
export default async function shepherdrExtension(
|
|
22
24
|
pi: ExtensionAPI,
|
|
23
25
|
): Promise<void> {
|
|
26
|
+
const workerRole = registerWorkerRole(pi);
|
|
24
27
|
registerPackageChangelog(pi);
|
|
25
28
|
|
|
26
29
|
await installAgentProfiles();
|
|
30
|
+
registerProfilePrompt(pi);
|
|
27
31
|
registerDeveloperDelivery(pi);
|
|
28
32
|
const peerCommands = createPeerCommands(pi);
|
|
29
33
|
const fleet = new AgentFleet(pi);
|
|
@@ -34,7 +38,7 @@ export default async function shepherdrExtension(
|
|
|
34
38
|
const board = AgentBoard.create(pi, fleet);
|
|
35
39
|
registerPeerInbox(pi, peerCommands, fleet, (ctx) => board.promptCatchup(ctx));
|
|
36
40
|
const sharedContext = await registerSharedAgentContext(pi, fleet, board);
|
|
37
|
-
registerWorkerService(pi, fleet, sharedContext, board);
|
|
41
|
+
registerWorkerService(pi, fleet, sharedContext, board, workerRole);
|
|
38
42
|
let promptMode: { readonly active: boolean } | undefined;
|
|
39
43
|
const tool = createAgentsTool(
|
|
40
44
|
fleet,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@howaboua/pi-shepherdr",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.24",
|
|
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.10",
|
|
47
|
+
"@howaboua/pi-codex-conversion": ">=4.0.5",
|
|
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.10",
|
|
66
|
+
"@howaboua/pi-codex-conversion": "4.0.5",
|
|
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-discovery.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { AgentsParams, READ_SOURCES } from "./agents-contract.js";
|
|
2
|
-
import type { AgentFleet, ConnectedMachine } from "./fleet.js";
|
|
2
|
+
import type { AgentFleet, ConnectedMachine } from "./fleet/index.js";
|
|
3
3
|
import { type AgentProfile, loadAgentProfiles } from "./profiles.js";
|
|
4
4
|
import type { AgentStatus, PaneInfo, SessionSnapshot } from "./types.js";
|
|
5
5
|
|
|
@@ -30,7 +30,7 @@ export async function agentsHelp(
|
|
|
30
30
|
const profiles = await loadAgentProfiles();
|
|
31
31
|
return {
|
|
32
32
|
commands: gpt
|
|
33
|
-
? "commands:true lists slash commands/descriptions,
|
|
33
|
+
? "commands:true lists slash commands/descriptions, NEVER executes; default=this session; target/machine→another"
|
|
34
34
|
: "commands: true lists available slash commands with descriptions; defaults to this session, target and machine optionally select another session; does not execute commands",
|
|
35
35
|
actions: {
|
|
36
36
|
help: "",
|
|
@@ -51,46 +51,61 @@ export async function agentsHelp(
|
|
|
51
51
|
},
|
|
52
52
|
rules: {
|
|
53
53
|
reply: gpt
|
|
54
|
-
? "
|
|
54
|
+
? "Extension report/read template required; send≠resolve; blocking waits resumed work; others return after semantic delivery"
|
|
55
55
|
: "Use the extension-authored template from its report/read; send does not resolve it. Blocking messages wait for resumed work; other replies return after semantic delivery",
|
|
56
|
-
machine:
|
|
57
|
-
"
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
56
|
+
machine: gpt
|
|
57
|
+
? "machine omitted=local Pi host; list/find omitted=all machines; remote=list profile ID, NOT label/hostname"
|
|
58
|
+
: "Omit for local (host running Pi); list/find omit for all machines. Remote: profile ID from list, not label/hostname",
|
|
59
|
+
target: gpt
|
|
60
|
+
? "spawn/find target EXACT; /root=this family live root"
|
|
61
|
+
: "Use spawn/find target exactly; /root selects this family's live root",
|
|
62
|
+
label: gpt
|
|
63
|
+
? "Short tab/session name; two words IF useful"
|
|
64
|
+
: "Short tab/session name; prefer two words when useful",
|
|
61
65
|
...(boardAvailable
|
|
62
66
|
? {
|
|
63
|
-
board_thread_id:
|
|
64
|
-
"Existing
|
|
67
|
+
board_thread_id: gpt
|
|
68
|
+
? "Existing board thread→child read ref"
|
|
69
|
+
: "Existing shared-board thread; child receives a read reference",
|
|
65
70
|
}
|
|
66
71
|
: {}),
|
|
67
|
-
send:
|
|
72
|
+
send: gpt
|
|
73
|
+
? "/quit next→NO preceding message; sends wake idle agents; NO wait/watch"
|
|
74
|
+
: "When closing an agent, send /quit without another message first. Messages wake idle agents. No waiting or watching.",
|
|
68
75
|
assign: gpt
|
|
69
|
-
? "Delegate/update work
|
|
76
|
+
? "Delegate/update work; active→share pending result, NEVER replace wait"
|
|
70
77
|
: "Delegate or update work; active updates share its pending result, never replace an existing wait",
|
|
71
78
|
focus: gpt
|
|
72
|
-
? "Running session; passive arrival+return call,
|
|
79
|
+
? "Running session; passive arrival+return call, NO task/watch; voice default false, true=async active mic transfer; handoff=context; remote=target Herdr session≠client machine"
|
|
73
80
|
: "Select a running session; passive arrival with return call, no task/watch. voice defaults false; true carries the active microphone asynchronously. handoff adds context. Remote focus selects the target's Herdr session, not the client's machine",
|
|
74
81
|
attach: boardAvailable
|
|
75
|
-
?
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
82
|
+
? gpt
|
|
83
|
+
? "Idle target; context/board=independent sharing/membership; NO task/watch"
|
|
84
|
+
: "Idle target; context/board booleans choose shared access and board membership independently; no task/watch"
|
|
85
|
+
: gpt
|
|
86
|
+
? "Idle target; context=shared notes/history; boards unavailable→board:false; NO task/watch"
|
|
87
|
+
: "Idle target; context shares notes/history; use board:false while shared boards are unavailable; no task/watch",
|
|
88
|
+
detach: gpt
|
|
89
|
+
? "Idle target; stop selected membership; counterpart checkpoints remain readonly"
|
|
90
|
+
: "Stop selected membership; retain counterpart checkpoints read-only; idle target",
|
|
79
91
|
blocking: gpt
|
|
80
|
-
? "spawn/assign default true; profile overrides spawn
|
|
81
|
-
: "spawn/assign default true; profile blocking overrides spawn.
|
|
82
|
-
share_context:
|
|
83
|
-
"Profile false
|
|
84
|
-
|
|
85
|
-
|
|
92
|
+
? "spawn/assign default true; profile overrides spawn; JS parallel+wait: await Promise.allSettled; false ONLY if other work continues; completion/blockage AFTER reply; NO poll/sleep"
|
|
93
|
+
: "spawn/assign default true; profile blocking overrides spawn. In JavaScript cells, use await Promise.allSettled for parallel calls that wait for every result, including failures. Use false only to continue other work; completion/blockage arrives after your reply. No polling or sleep waits",
|
|
94
|
+
share_context: gpt
|
|
95
|
+
? "Profile false→isolated notes/history; otherwise→controller sharing setting"
|
|
96
|
+
: "Profile false isolates notes/history; otherwise follows controller sharing setting",
|
|
97
|
+
watch: gpt
|
|
98
|
+
? "Delegation/watch→report subsequent work UNTIL unwatch/close"
|
|
99
|
+
: "Delegation and watch keep reporting subsequent work until unwatch or close",
|
|
86
100
|
prompt: gpt
|
|
87
|
-
? "Distinct
|
|
101
|
+
? "Distinct scope/outcome/project context/issue refs; define success, NOT forbidden investigations"
|
|
88
102
|
: "Give each worker a distinct scope, desired outcome, relevant project context and issue references. Describe success rather than lists of forbidden investigations",
|
|
89
103
|
slash: gpt
|
|
90
|
-
? "Leading / routes target commands/skills/templates
|
|
104
|
+
? "Leading / routes target commands/skills/templates; commands skip task wait EVEN assign/spawn; blocked→choices; /quit exits Pi+closes pane"
|
|
91
105
|
: "Leading / routes target commands/skills/templates. Commands skip task waiting, even with assign/spawn; blocked commands return available choices. /quit shuts down Pi and closes its pane",
|
|
92
|
-
reuse:
|
|
93
|
-
"Reuse
|
|
106
|
+
reuse: gpt
|
|
107
|
+
? "Reuse ONLY same investigation; reviews independent; new scope=new agent"
|
|
108
|
+
: "Reuse only same investigation; reviews independent; new scope = new agent",
|
|
94
109
|
...(profiles.has("general")
|
|
95
110
|
? {
|
|
96
111
|
general: "Only when requested/orchestrating",
|
package/src/agents-focus.ts
CHANGED
|
@@ -7,7 +7,7 @@ import {
|
|
|
7
7
|
recordContextBriefing,
|
|
8
8
|
registerContextBriefing,
|
|
9
9
|
} from "@howaboua/pi-agent-board/integration";
|
|
10
|
-
import type { AgentFleet, ConnectedMachine } from "./fleet.js";
|
|
10
|
+
import type { AgentFleet, ConnectedMachine } from "./fleet/index.js";
|
|
11
11
|
import {
|
|
12
12
|
getAgent,
|
|
13
13
|
getCurrentPane,
|
|
@@ -15,7 +15,7 @@ import {
|
|
|
15
15
|
sessionPath,
|
|
16
16
|
} from "./herdr.js";
|
|
17
17
|
import { isDispatchRejected } from "./herdr-client.js";
|
|
18
|
-
import { focusArrivalContent } from "./messages.js";
|
|
18
|
+
import { focusArrivalContent } from "./messages/focus.js";
|
|
19
19
|
import type { FocusRequest, PaneInfo } from "./types.js";
|
|
20
20
|
import { activeVoiceService, observeVoiceTransfer } from "./voice-handoff.js";
|
|
21
21
|
|