@howaboua/pi-shepherdr 0.2.28-core.11.1.gc09f7abbc5a5 → 1.0.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/CHANGELOG.md +24 -0
- package/README.md +47 -14
- package/biome.json +1 -1
- package/index.ts +5 -2
- package/package.json +19 -21
- package/src/agents-contract.ts +89 -70
- package/src/agents-discovery.ts +28 -18
- package/src/agents-focus.ts +9 -15
- package/src/agents-reply.ts +3 -12
- package/src/agents-spawn.ts +46 -8
- package/src/agents-tool.ts +57 -20
- package/src/agents-work.ts +9 -4
- package/src/ancestry-record.ts +116 -0
- package/src/attachment-notes.ts +11 -9
- package/src/attachment-protocol.ts +126 -70
- package/src/attachment-routing.ts +1 -1
- package/src/attachment-target.ts +18 -25
- package/src/attachment.ts +11 -10
- package/src/board/discovery.ts +67 -0
- package/src/board/host.ts +92 -62
- package/src/board/membership.ts +16 -11
- package/src/board/records.ts +199 -0
- package/src/close-idle.ts +2 -2
- package/src/context-briefing.ts +230 -0
- package/src/context-routing.ts +1 -1
- package/src/controller.ts +54 -63
- package/src/core/AGENTS.md +1 -1
- package/src/core/backend.ts +32 -15
- package/src/core/helper-bootstrap.mjs +1 -1
- package/src/core/helper-core.mjs +4 -3
- package/src/core/helper-lifetime.mjs +199 -0
- package/src/core/remote-endpoint.ts +10 -3
- package/src/core/remote-helper.ts +42 -31
- package/src/core/remote-service.mjs +14 -7
- package/src/core/remote-transport.ts +11 -1
- package/src/core/spawn.ts +1 -1
- package/src/core/terminal-peer.mjs +26 -5
- package/src/core/terminal.ts +2 -1
- package/src/delivery.ts +39 -0
- package/src/fleet/connection.ts +4 -0
- package/src/fleet/index.ts +24 -3
- package/src/launch-contract.ts +1 -0
- package/src/launch.ts +40 -3
- package/src/messages/attachments.ts +1 -1
- package/src/messages/attribution.ts +14 -2
- package/src/messages/focus.ts +4 -3
- package/src/messages/guidance.ts +2 -43
- package/src/messages/peer-sharing.ts +147 -0
- package/src/monitor-events.ts +10 -10
- package/src/monitor-extension-messages.ts +1 -0
- package/src/monitor.ts +5 -5
- package/src/notes-discovery.ts +67 -0
- package/src/profiles.ts +1 -8
- package/src/remote/notes-reader.mjs +67 -0
- package/src/remote/shepherdr-checkpoints.mjs +1 -3
- package/src/remote/shepherdr-session.mjs +61 -7
- package/src/saved-context.ts +1 -1
- package/src/settlement/delivery.ts +32 -14
- package/src/settlement/index.ts +13 -0
- package/src/shared-context-host.ts +14 -36
- package/src/shared-context.ts +33 -106
- package/src/spawn-ancestry.ts +103 -0
- package/src/spawn-context.ts +2 -2
- package/src/spawn-ownership.ts +93 -5
- package/src/types.ts +1 -0
- package/src/voice-handoff.ts +1 -1
- package/src/worker-ownership.ts +41 -32
- package/src/worker-resume.ts +231 -0
- package/src/worker-role.ts +9 -35
- package/src/worker-service.ts +98 -60
- package/worker-api.ts +38 -0
- package/src/profile-prompt.ts +0 -32
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,29 @@
|
|
|
1
1
|
# @howaboua/pi-shepherdr
|
|
2
2
|
|
|
3
|
+
## 1.0.0
|
|
4
|
+
|
|
5
|
+
### Breaking changes
|
|
6
|
+
|
|
7
|
+
- Removed the legacy Herdr backend and SSH bridge. Requires Herdr Core 0.1.18+, Pi 1.5+ and Node.js 22.19+. Legacy Herdr TUI is unsupported. Its last supported release, Shepherdr 0.2.27, is unmaintained, with [source available for forks](https://github.com/IgorWarzocha/howaboua-pi-stuff/tree/5ede06bdc32da2b513f0709966af1f32908f243c/packages/pi-shepherdr). Update and restart controllers and workers together. Start fresh Core terminals for older Herdr sessions and reselect watches when changing Core namespaces. Replace pane placement with terminal, new-tab or new-workspace placement.
|
|
8
|
+
- Shepherdr now runs without other extensions. Optional sharing supports Agent Comms or standalone Notes Compaction and Agent Board, preserving saved notes and boards.
|
|
9
|
+
- Agent calls now accept current Core machine names or stable IDs. Saved routes and watches survive renames. Connections adds machines through `hc machine add`.
|
|
10
|
+
- Remote supervision and sharing now use persistent Core attachments. Saved checkpoints remain readable after workers and intermediate controllers close, including older sessions across connected machines.
|
|
11
|
+
- Concurrent Pi sessions now share machine-local launch and saved-session read limits, with calls remaining pending until their normal result is available.
|
|
12
|
+
- Ordinary workers now end with their parent's program. Active remote connections enforce cross-machine cleanup. Detached workers remain independent.
|
|
13
|
+
- Added a public worker API with saved-session reuse and caller-selected detached lifetime.
|
|
14
|
+
- `/root` now follows saved spawn ancestry independently of sharing. Older workers without saved ancestry must use exact session references.
|
|
15
|
+
- Sending or assigning work to a closed, owned worker now resumes its saved Pi session before delivery.
|
|
16
|
+
- The widget now shows watched peers without repeating supervised workers. Monitoring warnings remain visible. Shells retaining old Pi labels no longer appear as live agents.
|
|
17
|
+
- Fixed completed replies being hidden by empty notice turns, and closed agents causing collection warnings or settlement retries.
|
|
18
|
+
- Agent replies now return when the extension accepts the answer instead of blocking later questions until resumed work finishes.
|
|
19
|
+
- Attachment and detachment now accept context or Board sharing independently. Incoming messages identify sender access, distinguishing machine IDs from Pi agent references.
|
|
20
|
+
- Monitoring notices now describe delayed or unavailable agent updates and automatic retry without duplicate internal errors during Core restarts.
|
|
21
|
+
- Agent help now asks callers to trust worker judgement instead of over-prescribing restrictions or narrowing the task unnecessarily.
|
|
22
|
+
- Worker profiles now brief only the initial assignment instead of pinning restrictions in the standing prompt. Later assignments and model-role changes can reuse the same agent and its notes.
|
|
23
|
+
- Agent help now keeps each agent available until its task is verified complete, with corrections returned to the same agent before closing it.
|
|
24
|
+
- Agent help now directs callers to skip acknowledgements, status-only updates and standby reminders that needlessly wake idle agents.
|
|
25
|
+
- Removed the TypeBox installation requirement.
|
|
26
|
+
|
|
3
27
|
## 0.2.27
|
|
4
28
|
|
|
5
29
|
- New remote workers retain their Core parent link for sidebar nesting.
|
package/README.md
CHANGED
|
@@ -14,18 +14,22 @@ 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.5 or newer, Node.js 22.
|
|
17
|
+
Requires Pi 1.5 or newer, Node.js 22.19 or newer and Herdr Core 0.1.18 or newer. Run Pi in a Core terminal, through `hc` or a Herdr app connected to that Core. Shepherdr reports Pi status to Core and discovers other Pi sessions with Shepherdr installed. No separate Pi integration is needed.
|
|
18
18
|
|
|
19
19
|
Do not load Pi Codex's example `agents.toml` custom tool alongside Shepherdr; they own the same agent surface.
|
|
20
20
|
|
|
21
|
-
Pi Codex
|
|
21
|
+
Shepherdr installs and runs on its own. Pi Codex, shared Notes and boards are optional. Delegation, supervision, messages, focus and orchestration work without them. Shared Notes require Notes Compaction 0.0.15 or newer; boards require Agent Board 0.0.5 or newer. [Agent Comms](../pi-agent-comms) also provides both integrations when loaded. Enable each shared feature in every participating session.
|
|
22
22
|
|
|
23
23
|
Workers start as background Core terminals by default. Use `placement: "new_workspace"` for a new app workspace, or `placement: "new_tab"` with a `workspace` ID advertised by a live terminal on the target Core. A connected Herdr app adopts these terminals. Pane placement is no longer supported. Focus requires a Herdr app window running on the target Core's machine and connected to that Core.
|
|
24
24
|
|
|
25
|
+
Ordinary workers end when their parent's program exits. Active remote connections also verify Core's parent links and close ordinary children when Core misses cross-machine cleanup. Detached workers remain independent. Restoring a Pi session preserves its saved worker identity. `/root` follows saved spawn ancestry, not shared Notes or Board membership. Older workers without saved ancestry must use exact session references for messages.
|
|
26
|
+
|
|
25
27
|
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.
|
|
26
28
|
|
|
27
29
|
### Migrating from the older Herdr TUI
|
|
28
30
|
|
|
31
|
+
Current Shepherdr is Core-native and is not backward-compatible with the legacy Herdr TUI. Shepherdr 0.2.27 was the last release supporting it. Its [source is available for forks](https://github.com/IgorWarzocha/howaboua-pi-stuff/tree/5ede06bdc32da2b513f0709966af1f32908f243c/packages/pi-shepherdr), but the legacy version is unmaintained.
|
|
32
|
+
|
|
29
33
|
Update and restart controllers and workers together. The older Herdr backend, SSH bridge, machine catalogue and legacy environment overrides are no longer used. Existing Herdr TUI sessions cannot migrate to Core. Start fresh Core terminals and configure remote machines with `hc machine add` on the host running Pi.
|
|
30
34
|
|
|
31
35
|
When switching from the older TUI or another Core namespace, explicitly select the agents you want to watch again. Saved addresses from the previous namespace are not transferable.
|
|
@@ -52,6 +56,8 @@ Machines belong to the host running Pi, not the machine displaying its terminal.
|
|
|
52
56
|
|
|
53
57
|
Remote file watches, Notes, shared-context calls and peer messages use a private Core-owned helper, started lazily and kept alive over a flow-controlled terminal attachment. Shepherdr does not install SSH bridge files or poll through `machine.exec`. Voice focus uses a separate private helper so large Notes transfers do not block its channel. Monitoring uses each Core's own snapshot rather than treating a missing machine in an aggregate terminal list as closed agents.
|
|
54
58
|
|
|
59
|
+
The same connection supervises native remote-parent lifetimes while active. A brief closing grace makes a best-effort check for Pi exiting. No separate background service is installed. A disconnected or unreachable parent is not treated as dead. Failed checks leave existing agents available and produce a warning while the connection is active. Reconnect the parent Core or close its children explicitly. Closing checks have no persistent warning report. This does not guarantee cleanup after an OS failure or a prolonged Pi shutdown.
|
|
60
|
+
|
|
55
61
|
## Agent calls
|
|
56
62
|
|
|
57
63
|
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.
|
|
@@ -81,6 +87,8 @@ Nonblocking extension messages notify the controller once; blocking messages arr
|
|
|
81
87
|
|
|
82
88
|
Use `send` for messages and work updates without adding supervision. Use `assign` to delegate work and receive its monitored result, automatically or through an explicit blocking call. It also accepts updates to running work, sharing that work's pending result rather than replacing it. If another call is already waiting, the update returns after submission and leaves that waiter intact. Close finished workers silently instead of waking them with completion acknowledgements or shutdown notices.
|
|
83
89
|
|
|
90
|
+
When a parent sends or assigns work to one of its closed workers, Shepherdr reopens that worker's saved Pi session before delivering the message. Use its session reference, previous terminal target or saved routing name. The result reports `resumed: true` and the current target. This applies only to children recorded in the parent's selected session branch, not arbitrary peers or attachments. The saved session and its original machine must remain accessible. `/quit` never reopens a closed worker.
|
|
91
|
+
|
|
84
92
|
Delegation and explicit `watch` keep reporting subsequent work until `unwatch` or the agent's terminal closes. Finishing or failing a task clears that task, not its watch. Follow-up messages through `send` retain completion reporting without replacing the task.
|
|
85
93
|
|
|
86
94
|
Every `spawn` needs an `agent_type` and a concise `label`. The label names the Pi session. The routing `name` remains optional and is derived from the label when omitted.
|
|
@@ -173,29 +181,29 @@ await tools.agents({
|
|
|
173
181
|
});
|
|
174
182
|
```
|
|
175
183
|
|
|
176
|
-
|
|
184
|
+
Enable one or both choices. Omitted choices are false. `context` shares notes and history through aliases without changing either session's original context identity or moving its notes. The returned `agent` is the target's Pi session reference. Use it 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 reference without starting a turn.
|
|
177
185
|
|
|
178
|
-
Context attachment requires
|
|
186
|
+
Context attachment requires active Notes in both sessions, through Notes Compaction or Agent Comms. 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.
|
|
179
187
|
|
|
180
|
-
`board: true` requires
|
|
188
|
+
`board: true` requires Agent Board or Agent Comms loaded in both sessions. It joins the controller's enabled board. Use the returned `agent` 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.
|
|
181
189
|
|
|
182
190
|
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.
|
|
183
191
|
|
|
184
192
|
Attachments survive resume, not forks. Saved checkpoints remain readable without the owning Pi process when its saved session and machine are accessible. Writes and live history access need the owner. After an interrupted attachment, resume the original sessions and retry the same target and choices. Retries reuse the original aliases and membership.
|
|
185
193
|
|
|
186
|
-
To detach, call `agents` with `action: "detach"`, the same target, and
|
|
194
|
+
To detach, call `agents` with `action: "detach"`, the same target, and each membership you want to leave set to true. Omitted memberships are unchanged. 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.
|
|
187
195
|
|
|
188
196
|
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.
|
|
189
197
|
|
|
190
198
|
## Message board
|
|
191
199
|
|
|
192
|
-
|
|
200
|
+
Install Agent Board in every participating Pi session, then reload:
|
|
193
201
|
|
|
194
202
|
```sh
|
|
195
203
|
pi install npm:@howaboua/pi-agent-board
|
|
196
204
|
```
|
|
197
205
|
|
|
198
|
-
The
|
|
206
|
+
The loaded Board extension owns the `board` tool, `/board` settings and read-only browser viewer. Agent Comms can provide the same integration instead of Agent Board, retaining discussions, subscriptions and saved history. Do not load both Board providers together. Shepherdr has no fallback board or board controls under `/herdr`. If a saved session board setting is on but its provider is missing, Shepherdr displays a warning once per session. Saved settings and archives remain untouched. Pi Codex Conversion is optional.
|
|
199
207
|
|
|
200
208
|
Shepherdr supplies family membership, attachments and remote routing. Children spawned while the board is enabled inherit its location and board ID even with another working directory. The spawn result's `agent` is their Pi session reference for subscriptions, notifications and shared notes. The `sharing` flags report which memberships are active. Independently started agents, existing `assign` targets and children spawned while it is off do not join automatically. Use explicit `attach` to join an existing agent. Board identity is independent of orchestration mode, shared notes and `share_context`.
|
|
201
209
|
|
|
@@ -205,23 +213,30 @@ Child board calls use the owning Pi sessions and Core connections, not a separat
|
|
|
205
213
|
|
|
206
214
|
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.
|
|
207
215
|
|
|
208
|
-
|
|
216
|
+
Install Notes Compaction in every participating session and reload, or use Agent Comms' Notes feature. Do not load both Notes providers together. With Notes active 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; the returned `agent` 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.
|
|
217
|
+
|
|
218
|
+
```sh
|
|
219
|
+
pi install npm:@howaboua/pi-notes-compaction
|
|
220
|
+
```
|
|
209
221
|
|
|
210
222
|
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.
|
|
211
223
|
|
|
212
224
|
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.
|
|
213
225
|
|
|
214
|
-
Shared local checkpoints remain readable after workers or intermediate controllers close. Notes verifies saved family membership and reads the selected session branch. Cross-machine reads need a Core connection and access to the saved session, not a running Pi owner.
|
|
226
|
+
Shared local checkpoints remain readable after workers or intermediate controllers close. Notes verifies saved family membership and reads the selected session branch. Saved reads also require the Notes provider's public reader package installed alongside Shepherdr on the controller. Cross-machine reads need a Core connection and access to the saved session, not a running Pi owner. Older sessions without a saved parent location can find family checkpoints across connected machines through their Notes index or standard Pi session directory. Writes and optional hybrid lookup still use their owning services. Reconnect machines under `/herdr` → **Status** after a connection loss.
|
|
215
227
|
|
|
216
228
|
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`.
|
|
217
229
|
|
|
218
230
|
## Profiles
|
|
219
231
|
|
|
220
232
|
On first load, Shepherdr installs three editable profiles:
|
|
233
|
+
|
|
221
234
|
- `general` uses `openai-codex/gpt-6-sol` with `high` thinking for implementation
|
|
222
235
|
- `explorer` uses `openai-codex/gpt-6-luna` with `high` thinking for read-only discovery
|
|
223
236
|
- `reviewer` uses `openai-codex/gpt-6-luna` with `xhigh` thinking for generic read-only review
|
|
224
237
|
|
|
238
|
+
Profiles set starting defaults, not a permanent role. Their instructions accompany the initial assignment, so the same agent can take on different work later. Notes model roles can change its model and reasoning at context rollover without replacing the agent or discarding its saved notes.
|
|
239
|
+
|
|
225
240
|
Use `general` sparingly, mainly when requested or while orchestration is active. For work in the controller's repository, create and prepare a dedicated worktree, then pass it as `cwd`.
|
|
226
241
|
|
|
227
242
|
Profiles live under:
|
|
@@ -246,6 +261,7 @@ That directory is authoritative after initialization. Edit a profile to change i
|
|
|
246
261
|
`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.
|
|
247
262
|
|
|
248
263
|
Optional profile settings:
|
|
264
|
+
|
|
249
265
|
- `blocking`: `true` forces blocking spawns, `false` forces asynchronous spawns. Omission respects the call's `blocking` value, which defaults to `false`. This does not affect `assign` to existing agents.
|
|
250
266
|
- `share_context`: `false` opts new spawns out of shared notes and history. Omission or `true` follows the controller setting.
|
|
251
267
|
|
|
@@ -275,13 +291,30 @@ pi.events.emit("shepherdr:worker-role:v1", {
|
|
|
275
291
|
|
|
276
292
|
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.
|
|
277
293
|
|
|
278
|
-
##
|
|
294
|
+
## Worker API
|
|
295
|
+
|
|
296
|
+
Extensions can discover the worker service through Pi events. The public types are exported from `@howaboua/pi-shepherdr/worker-api`. A type-only import keeps Shepherdr optional:
|
|
297
|
+
|
|
298
|
+
```ts
|
|
299
|
+
import type { WorkerService } from "@howaboua/pi-shepherdr/worker-api";
|
|
300
|
+
|
|
301
|
+
const protocol: WorkerService["protocol"] = "@howaboua/pi-shepherdr/workers/v1";
|
|
302
|
+
let workers: WorkerService | undefined;
|
|
303
|
+
pi.events.emit(`${protocol}/request`, {
|
|
304
|
+
protocol,
|
|
305
|
+
accept: (service: WorkerService) => {
|
|
306
|
+
workers = service;
|
|
307
|
+
},
|
|
308
|
+
});
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
No reply means the service is unavailable. Discover again after extension reload. Start work after session startup and resource discovery in a TUI session. Callers own scheduling, eligibility and whether to use `isWorker(ctx)` to exclude workers from their workflow.
|
|
279
312
|
|
|
280
|
-
|
|
313
|
+
`start(ctx, { scope, key, requestId, title, prompt, cwd, workerId?, lifetime? })` submits one task and returns `{ workerId, state }`. Use a stable extension-specific `scope`, a reusable worker `key` and a fresh `requestId` per task. Repeating the latest acknowledged request ID returns its existing status without resending. Persist the receipt before attempting another request. A failed call may have submitted work unless its error has `dispatched: false`. Never retry an uncertain rejection, even with the same ID. Request IDs do not make failed calls replay-safe. Inspection helps establish the outcome but does not clear the uncertain admission.
|
|
281
314
|
|
|
282
|
-
The
|
|
315
|
+
The default lifetime is `parent`. Set `lifetime: "detached"` explicitly to keep the worker running after its parent exits. Lifetime and working directory cannot change for an existing key. `inspect(ctx, scope, workerId)` reports `working`, `idle` or `closed`; `subscribe(listener)` provides change notifications and returns an unsubscribe function. Ownership is restricted to the caller's selected native session branch and scope, not an access-control boundary between trusted extensions.
|
|
283
316
|
|
|
284
|
-
|
|
317
|
+
Workers run in separate Pi processes. Their final responses use the same monitored delivery as asynchronous `agents` calls, including normal kickoff preparation and rollover admission. The service reuses owned saved sessions and refuses overlapping work. Fresh workers use the `general` profile without its role prompt; resumed sessions retain their saved model, thinking level and name. Fresh workers inherit the family Board and optional shared Notes and cache affinity. Use ordinary Shepherdr controls to manage worker terminals. No automation extension is required.
|
|
285
318
|
|
|
286
319
|
## License
|
|
287
320
|
|
package/biome.json
CHANGED
package/index.ts
CHANGED
|
@@ -10,7 +10,6 @@ import { AgentFleet } from "./src/fleet/index.js";
|
|
|
10
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";
|
|
14
13
|
import { installAgentProfiles } from "./src/profiles.js";
|
|
15
14
|
import { registerSharedAgentContext } from "./src/shared-context-host.js";
|
|
16
15
|
import { registerVoiceFocusReceiver } from "./src/voice-handoff.js";
|
|
@@ -27,7 +26,11 @@ export default async function shepherdrExtension(
|
|
|
27
26
|
const workerRole = registerWorkerRole(pi);
|
|
28
27
|
|
|
29
28
|
await installAgentProfiles();
|
|
30
|
-
|
|
29
|
+
// Older saved launch commands may still carry this flag. It no longer pins a role.
|
|
30
|
+
pi.registerFlag("shepherdr-profile-prompt", {
|
|
31
|
+
type: "string",
|
|
32
|
+
description: "Legacy worker profile option (ignored)",
|
|
33
|
+
});
|
|
31
34
|
registerDeveloperDelivery(pi);
|
|
32
35
|
const peerCommands = createPeerCommands(pi);
|
|
33
36
|
const fleet = new AgentFleet(pi);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@howaboua/pi-shepherdr",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.0",
|
|
4
4
|
"description": "Persistent blocking and asynchronous Pi agents through Herdr.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -25,6 +25,7 @@
|
|
|
25
25
|
],
|
|
26
26
|
"files": [
|
|
27
27
|
"index.ts",
|
|
28
|
+
"worker-api.ts",
|
|
28
29
|
"src",
|
|
29
30
|
"profiles",
|
|
30
31
|
"README.md",
|
|
@@ -42,33 +43,24 @@
|
|
|
42
43
|
"pack:dry": "npm pack --dry-run"
|
|
43
44
|
},
|
|
44
45
|
"peerDependencies": {
|
|
45
|
-
"@howaboua/pi-
|
|
46
|
-
"@howaboua/pi-codex-conversion": ">=4.0.9",
|
|
46
|
+
"@howaboua/pi-codex-conversion": ">=4.0.10",
|
|
47
47
|
"@earendil-works/pi-ai": ">=1.1.0",
|
|
48
48
|
"@earendil-works/pi-coding-agent": ">=1.5.0",
|
|
49
|
-
"@earendil-works/pi-tui": ">=1.1.0"
|
|
50
|
-
"typebox": "*"
|
|
49
|
+
"@earendil-works/pi-tui": ">=1.1.0"
|
|
51
50
|
},
|
|
52
51
|
"peerDependenciesMeta": {
|
|
53
|
-
"@howaboua/pi-notes-compaction": {
|
|
54
|
-
"optional": true
|
|
55
|
-
},
|
|
56
52
|
"@howaboua/pi-codex-conversion": {
|
|
57
53
|
"optional": true
|
|
58
54
|
}
|
|
59
55
|
},
|
|
60
|
-
"dependencies": {
|
|
61
|
-
"@howaboua/pi-agent-board": "0.0.5"
|
|
62
|
-
},
|
|
63
56
|
"devDependencies": {
|
|
64
|
-
"@howaboua/pi-
|
|
65
|
-
"@howaboua/pi-codex-conversion": "4.0.
|
|
66
|
-
"@biomejs/biome": "^2.6.
|
|
67
|
-
"@earendil-works/pi-ai": "1.5.
|
|
68
|
-
"@earendil-works/pi-coding-agent": "1.5.
|
|
69
|
-
"@earendil-works/pi-tui": "1.5.
|
|
70
|
-
"@types/node": "^26.6.
|
|
71
|
-
"typebox": "1.4.3",
|
|
57
|
+
"@howaboua/pi-agent-comms": "0.0.1",
|
|
58
|
+
"@howaboua/pi-codex-conversion": "4.0.10",
|
|
59
|
+
"@biomejs/biome": "^2.6.6",
|
|
60
|
+
"@earendil-works/pi-ai": "1.5.2",
|
|
61
|
+
"@earendil-works/pi-coding-agent": "1.5.2",
|
|
62
|
+
"@earendil-works/pi-tui": "1.5.2",
|
|
63
|
+
"@types/node": "^26.6.6",
|
|
72
64
|
"typescript": "^7.0.2"
|
|
73
65
|
},
|
|
74
66
|
"pi": {
|
|
@@ -77,11 +69,17 @@
|
|
|
77
69
|
]
|
|
78
70
|
},
|
|
79
71
|
"engines": {
|
|
80
|
-
"node": ">=22.
|
|
72
|
+
"node": ">=22.19.0"
|
|
81
73
|
},
|
|
82
74
|
"main": "index.ts",
|
|
83
|
-
"exports":
|
|
75
|
+
"exports": {
|
|
76
|
+
".": "./index.ts",
|
|
77
|
+
"./worker-api": "./worker-api.ts"
|
|
78
|
+
},
|
|
84
79
|
"publishConfig": {
|
|
85
80
|
"access": "public"
|
|
81
|
+
},
|
|
82
|
+
"dependencies": {
|
|
83
|
+
"@earendil-works/pi-schema": "1.5.2"
|
|
86
84
|
}
|
|
87
85
|
}
|
package/src/agents-contract.ts
CHANGED
|
@@ -1,12 +1,17 @@
|
|
|
1
|
-
import {
|
|
2
|
-
|
|
1
|
+
import {
|
|
2
|
+
bool,
|
|
3
|
+
compile,
|
|
4
|
+
int,
|
|
5
|
+
lit,
|
|
6
|
+
obj,
|
|
7
|
+
oneOf,
|
|
8
|
+
opt,
|
|
9
|
+
type Static,
|
|
10
|
+
str,
|
|
11
|
+
} from "@earendil-works/pi-schema";
|
|
3
12
|
import { START_PLACEMENTS } from "./launch.js";
|
|
4
13
|
import { loadAgentProfileBlocking } from "./profiles.js";
|
|
5
14
|
|
|
6
|
-
function StringEnum<T extends readonly string[]>(values: T) {
|
|
7
|
-
return Type.Unsafe<T[number]>({ type: "string", enum: values });
|
|
8
|
-
}
|
|
9
|
-
|
|
10
15
|
const ACTIONS = [
|
|
11
16
|
"help",
|
|
12
17
|
"list",
|
|
@@ -53,58 +58,75 @@ const ACTION_FIELDS: Record<(typeof ACTIONS)[number], ReadonlySet<string>> = {
|
|
|
53
58
|
read: new Set(["action", "machine", "target", "source", "lines"]),
|
|
54
59
|
reply: new Set(["action", "machine", "target", "extension", "id", "message"]),
|
|
55
60
|
};
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
61
|
+
const AgentsRequest = obj({
|
|
62
|
+
action: {
|
|
63
|
+
...oneOf(ACTIONS),
|
|
64
|
+
type: "string",
|
|
65
|
+
},
|
|
66
|
+
commands: opt({
|
|
67
|
+
...lit(true),
|
|
68
|
+
type: "boolean",
|
|
69
|
+
}),
|
|
70
|
+
machine: opt(str()),
|
|
71
|
+
voice: opt(bool()),
|
|
72
|
+
handoff: opt(str()),
|
|
73
|
+
target: opt(str()),
|
|
74
|
+
agent_type: opt(str()),
|
|
75
|
+
name: opt(
|
|
76
|
+
str({
|
|
77
|
+
description: "Agent name; derived from label when omitted",
|
|
78
|
+
}),
|
|
79
|
+
),
|
|
80
|
+
label: opt(str()),
|
|
81
|
+
placement: opt({
|
|
82
|
+
...oneOf(START_PLACEMENTS),
|
|
83
|
+
type: "string",
|
|
84
|
+
}),
|
|
85
|
+
workspace: opt(str()),
|
|
86
|
+
cwd: opt(str()),
|
|
87
|
+
message: opt(str({ description: "Task, follow-up or extension reply" })),
|
|
88
|
+
base: opt(str({ description: "Review base branch" })),
|
|
89
|
+
blocking: opt(
|
|
90
|
+
bool({
|
|
91
|
+
description:
|
|
92
|
+
"Wait for delegated result; profile policy overrides spawn; default false",
|
|
93
|
+
}),
|
|
94
|
+
),
|
|
95
|
+
context: opt(bool()),
|
|
96
|
+
board: opt(bool()),
|
|
97
|
+
board_thread_id: opt(str({ minLength: 1 })),
|
|
98
|
+
query: opt(str()),
|
|
99
|
+
status: opt({
|
|
100
|
+
...oneOf(STATUSES),
|
|
101
|
+
type: "string",
|
|
102
|
+
}),
|
|
103
|
+
source: opt({
|
|
104
|
+
...oneOf(READ_SOURCES),
|
|
105
|
+
type: "string",
|
|
106
|
+
}),
|
|
107
|
+
lines: opt(int({ minimum: 1, maximum: 200 })),
|
|
108
|
+
extension: opt(str()),
|
|
109
|
+
id: opt(str()),
|
|
110
|
+
});
|
|
111
|
+
const checkAgentsRequest = compile(AgentsRequest).check;
|
|
112
|
+
export const AgentsParameters = {
|
|
113
|
+
...obj(
|
|
114
|
+
{
|
|
115
|
+
action: opt({
|
|
116
|
+
...oneOf(ACTIONS),
|
|
117
|
+
type: "string",
|
|
69
118
|
}),
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
workspace: Type.Optional(Type.String()),
|
|
74
|
-
cwd: Type.Optional(Type.String()),
|
|
75
|
-
message: Type.Optional(
|
|
76
|
-
Type.String({ description: "Task, follow-up or extension reply" }),
|
|
77
|
-
),
|
|
78
|
-
base: Type.Optional(Type.String({ description: "Review base branch" })),
|
|
79
|
-
blocking: Type.Optional(
|
|
80
|
-
Type.Boolean({
|
|
81
|
-
description:
|
|
82
|
-
"Wait for delegated result; profile policy overrides spawn; default false",
|
|
119
|
+
commands: opt({
|
|
120
|
+
...lit(true),
|
|
121
|
+
type: "boolean",
|
|
83
122
|
}),
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
lines: Type.Optional(Type.Integer({ minimum: 1, maximum: 200 })),
|
|
92
|
-
extension: Type.Optional(Type.String()),
|
|
93
|
-
id: Type.Optional(Type.String()),
|
|
94
|
-
},
|
|
95
|
-
{ additionalProperties: false },
|
|
96
|
-
);
|
|
97
|
-
|
|
98
|
-
export const AgentsParameters = Type.Object(
|
|
99
|
-
{
|
|
100
|
-
action: Type.Optional(StringEnum(ACTIONS)),
|
|
101
|
-
commands: Type.Optional(Type.Literal(true)),
|
|
102
|
-
target: Type.Optional(Type.String()),
|
|
103
|
-
machine: Type.Optional(Type.String()),
|
|
104
|
-
},
|
|
105
|
-
{ additionalProperties: true },
|
|
106
|
-
);
|
|
107
|
-
|
|
123
|
+
target: opt(str()),
|
|
124
|
+
machine: opt(str()),
|
|
125
|
+
},
|
|
126
|
+
{ open: true },
|
|
127
|
+
),
|
|
128
|
+
additionalProperties: true,
|
|
129
|
+
};
|
|
108
130
|
export type AgentsParams = Static<typeof AgentsRequest>;
|
|
109
131
|
export type AgentsToolParams = Static<typeof AgentsParameters>;
|
|
110
132
|
|
|
@@ -160,15 +182,15 @@ export function parseAgentsRequest(input: unknown): AgentsParams {
|
|
|
160
182
|
throw new Error(
|
|
161
183
|
"machine requires target for command discovery; omit both for this session",
|
|
162
184
|
);
|
|
163
|
-
if (
|
|
164
|
-
(
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
185
|
+
if (action === "attach" || action === "detach") {
|
|
186
|
+
for (const field of ["context", "board"]) {
|
|
187
|
+
if (field in request && typeof request[field] !== "boolean")
|
|
188
|
+
throw new Error(`${field} must be a boolean`);
|
|
189
|
+
}
|
|
190
|
+
if (request["context"] !== true && request["board"] !== true)
|
|
191
|
+
throw new Error(`${action} requires context:true or board:true`);
|
|
192
|
+
request = { context: false, board: false, ...request };
|
|
193
|
+
}
|
|
172
194
|
if (action === "reply") {
|
|
173
195
|
for (const field of ["extension", "id", "target"]) {
|
|
174
196
|
if (typeof request[field] !== "string" || !request[field].trim())
|
|
@@ -190,7 +212,7 @@ export function parseAgentsRequest(input: unknown): AgentsParams {
|
|
|
190
212
|
) {
|
|
191
213
|
throw new Error(`read source must be one of: ${READ_SOURCES.join(", ")}`);
|
|
192
214
|
}
|
|
193
|
-
if (!
|
|
215
|
+
if (!checkAgentsRequest(request)) {
|
|
194
216
|
throw new Error(
|
|
195
217
|
`invalid ${action} request; call agents help for its contract`,
|
|
196
218
|
);
|
|
@@ -208,10 +230,7 @@ export function isBlockingAgentsCall(input: unknown): boolean {
|
|
|
208
230
|
),
|
|
209
231
|
value.blocking,
|
|
210
232
|
);
|
|
211
|
-
return
|
|
212
|
-
value.action === "reply" ||
|
|
213
|
-
(value.action === "assign" && value.blocking === true)
|
|
214
|
-
);
|
|
233
|
+
return value.action === "assign" && value.blocking === true;
|
|
215
234
|
} catch {
|
|
216
235
|
return false;
|
|
217
236
|
}
|
package/src/agents-discovery.ts
CHANGED
|
@@ -46,21 +46,30 @@ export async function agentsHelp(
|
|
|
46
46
|
unwatch: "target machine?",
|
|
47
47
|
send: "target message machine?",
|
|
48
48
|
assign: "target message machine? blocking?",
|
|
49
|
-
attach: "target context board machine?",
|
|
50
|
-
detach: "target context board machine?",
|
|
49
|
+
attach: "target context? board? machine?",
|
|
50
|
+
detach: "target context? board? machine?",
|
|
51
51
|
read: "target machine? source=latest|visible|recent? lines?",
|
|
52
52
|
reply: "target extension id message machine?",
|
|
53
53
|
},
|
|
54
54
|
rules: {
|
|
55
|
+
peers: gpt
|
|
56
|
+
? "Existing session≠your sub-agent; send/watch need no attach. Contact≠shared Notes/Board; attach changes membership"
|
|
57
|
+
: "Existing sessions may be independent peers, not your sub-agents. Messaging and watching need no attachment. Contact does not imply shared Notes or Board membership; attach changes sharing",
|
|
58
|
+
read: gpt
|
|
59
|
+
? "latest(default)=last reply+pending extension messages; visible=current TUI screen; recent=TUI scrollback, lines default 40. Findings→returned Notes path if shared Notes available"
|
|
60
|
+
: "latest (default) returns the last reply and pending extension messages; visible reads the current TUI screen; recent reads TUI scrollback, lines default 40. For findings, read the returned Notes path when shared Notes is available",
|
|
55
61
|
reply: gpt
|
|
56
|
-
? "Extension report/read template required; send≠resolve;
|
|
57
|
-
: "Use the extension-authored template from its report/read; send does not resolve it.
|
|
62
|
+
? "Extension report/read template required; send≠resolve; returns after acceptance, never waits resumed work"
|
|
63
|
+
: "Use the extension-authored template from its report/read; send does not resolve it. Replies return after acceptance, without waiting for resumed work",
|
|
58
64
|
machine: gpt
|
|
59
65
|
? "machine omitted=local Pi host; list/find omitted=all machines; select current machine name or ID from list"
|
|
60
66
|
: "Omit for local (host running Pi); list/find omit for all machines. Select a current machine name or ID from list",
|
|
61
67
|
target: gpt
|
|
62
|
-
? "target=
|
|
63
|
-
: "Use
|
|
68
|
+
? "target=Pi session reference or terminal; /root=live spawn root"
|
|
69
|
+
: "Use the Pi session reference or terminal target; /root selects the live root of saved spawn ancestry",
|
|
70
|
+
resume: gpt
|
|
71
|
+
? "send/assign to owned closed worker→resume saved session; /quit never resumes"
|
|
72
|
+
: "Sending or assigning to a closed worker recorded by this parent resumes its saved session; /quit never resumes",
|
|
64
73
|
label: "Short Pi session name; app tabs use default names",
|
|
65
74
|
placement:
|
|
66
75
|
"terminal (default), new_tab, new_workspace; new_tab needs space ID",
|
|
@@ -72,8 +81,8 @@ export async function agentsHelp(
|
|
|
72
81
|
}
|
|
73
82
|
: {}),
|
|
74
83
|
send: gpt
|
|
75
|
-
? "
|
|
76
|
-
: "
|
|
84
|
+
? "Messages wake idle agents; send ONLY to change recipient next action, NO acknowledgements/status-only/standby. Close→/quit directly, NO preceding message or wait/watch"
|
|
85
|
+
: "Messages wake idle agents. Send only when it changes the recipient's next action; skip acknowledgements, status-only updates and standby reminders. Close with /quit directly, without another message first. No waiting or watching.",
|
|
77
86
|
assign: gpt
|
|
78
87
|
? "Delegate/update work; active→share pending result, NEVER replace wait"
|
|
79
88
|
: "Delegate or update work; active updates share its pending result, never replace an existing wait",
|
|
@@ -82,14 +91,14 @@ export async function agentsHelp(
|
|
|
82
91
|
: "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",
|
|
83
92
|
attach: boardAvailable
|
|
84
93
|
? gpt
|
|
85
|
-
? "Idle target; context/board=independent sharing/membership; NO task/watch"
|
|
86
|
-
: "Idle target; context/board
|
|
94
|
+
? "Idle target; context/board=independent sharing/membership; omitted=false, at least one true; NO task/watch"
|
|
95
|
+
: "Idle target; context/board choose shared access and board membership independently; omitted=false, at least one true; no task/watch"
|
|
87
96
|
: gpt
|
|
88
|
-
? "Idle target; context=shared notes/history; boards unavailable
|
|
89
|
-
: "Idle target; context shares notes/history;
|
|
97
|
+
? "Idle target; context:true=shared notes/history; boards unavailable; NO task/watch"
|
|
98
|
+
: "Idle target; context:true shares notes/history; shared boards unavailable; no task/watch",
|
|
90
99
|
detach: gpt
|
|
91
|
-
? "Idle target; stop
|
|
92
|
-
: "Stop
|
|
100
|
+
? "Idle target; stop context/board independently; omitted=false, at least one true; counterpart checkpoints remain readonly"
|
|
101
|
+
: "Stop context/board independently; omitted=false, at least one true; retain counterpart checkpoints read-only; idle target",
|
|
93
102
|
blocking: gpt
|
|
94
103
|
? "spawn/assign default false→dispatch then return; true→wait for result; profile overrides spawn. Parallel blocking calls: await Promise.allSettled. Background reports automatic→do other work/end turn, NO poll or await timers/extra Promises"
|
|
95
104
|
: "spawn/assign return after dispatch by default. Set blocking:true to wait for the result; profile blocking overrides spawn. Use await Promise.allSettled for parallel blocking calls, including failures. Background reports arrive automatically: do other work or end this turn, never poll or await timers or extra Promises for reports",
|
|
@@ -100,14 +109,14 @@ export async function agentsHelp(
|
|
|
100
109
|
? "Delegation/watch→report subsequent work UNTIL unwatch/close"
|
|
101
110
|
: "Delegation and watch keep reporting subsequent work until unwatch or close",
|
|
102
111
|
prompt: gpt
|
|
103
|
-
? "
|
|
104
|
-
: "Give
|
|
112
|
+
? "Task + necessary context; trust agent to choose approach. Avoid unnecessary restrictions and overly narrow scope"
|
|
113
|
+
: "Give the task and necessary context. Trust the agent to choose its approach. Avoid unnecessary restrictions and overly narrow scope",
|
|
105
114
|
slash: gpt
|
|
106
115
|
? "Leading / routes target commands/skills/templates; commands skip task wait EVEN assign/spawn; blocked→choices; /quit exits Pi+closes terminal"
|
|
107
116
|
: "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 terminal",
|
|
108
117
|
reuse: gpt
|
|
109
|
-
? "
|
|
110
|
-
: "
|
|
118
|
+
? "Keep each agent until task verified complete; corrections→same agent; then close. Unrelated task→new agent; reviews independent"
|
|
119
|
+
: "Keep each agent available until its task is verified complete; return corrections to it before closing. Use separate agents for unrelated work and independent reviews.",
|
|
111
120
|
...(profiles.has("general")
|
|
112
121
|
? {
|
|
113
122
|
general: "Only when requested/orchestrating",
|
|
@@ -240,6 +249,7 @@ export async function listFleetAgents(
|
|
|
240
249
|
({
|
|
241
250
|
snapshot: _snapshot,
|
|
242
251
|
monitoredPaneIds: _monitoredPaneIds,
|
|
252
|
+
session: _session,
|
|
243
253
|
...machine
|
|
244
254
|
}) => machine,
|
|
245
255
|
),
|