pi-herdsman 0.47.0 → 0.48.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.
@@ -90,6 +90,14 @@ Definition frontmatter remains the supported configuration surface
90
90
  for launch policy and capabilities. Custom user instructions remain
91
91
  subject to the established definition composition rules.
92
92
 
93
+ Bundled Coordinator profile bodies should begin with operating
94
+ instructions rather than repeat runtime-owned role headings or
95
+ identity declarations.
96
+
97
+ Bundled Agent bodies may use a brief identity and specialization
98
+ statement before their operating instructions. Such statements
99
+ describe specialization, not runtime authority or ownership.
100
+
93
101
  ## Fix ambiguity at the source
94
102
 
95
103
  When behavior is confusing or error-prone, identify the earliest source of ambiguity and correct it there.
@@ -49,6 +49,24 @@ coordination does not imply persistence of external state.
49
49
  Expand Herdsman's ownership only when the additional responsibility is
50
50
  inherently part of Herdsman's job.
51
51
 
52
+ ## Specialize responsibility, compose capabilities
53
+
54
+ Prefer focused Agents when a bounded task benefits from a distinct
55
+ responsibility, capability set, or execution policy. A general-purpose Agent
56
+ or direct execution is appropriate when additional delegation adds no value.
57
+
58
+ Agent definitions compose responsibility and expected outcomes with model
59
+ settings, instructions, optional skills, tool policies, and Pi extensions.
60
+ Share expertise through preloaded instructions when always needed or through
61
+ skills when on-demand loading is useful. Pi extensions can customize supported
62
+ Agent-level harness behavior without moving it into Herdsman. Herdsman
63
+ coordinates the work without owning domain-specific execution.
64
+
65
+ Sharing expertise does not share Agent responsibility or authority. Instructions
66
+ and skills do not grant permissions, and a model-facing tool allowlist does not
67
+ sandbox loaded extension code. Enforce access and isolation in the systems
68
+ responsible for execution.
69
+
52
70
  ## Keep optional capabilities optional
53
71
 
54
72
  External integrations must not become required dependencies of normal Herdsman
@@ -240,11 +240,23 @@ verified; `npm run smoke` defaults to `core`.
240
240
 
241
241
  Required peer-federation CI runs the shared core acceptance independently for
242
242
  real containerized Managers (`manager-core`) and ordinary Leads (`lead-core`).
243
- Each verifies one successful request, the exact correlated reply persisted
244
- once, and A's assistant completion after that reply without another prompt.
243
+ The Manager core enables the existing native Manager auto-activation before Pi
244
+ starts and verifies authoritative Manager identity without submitting
245
+ `/manager`. The ordinary Lead core starts one Pi session per machine directly
246
+ in each root pane; it starts no Managers and performs no pane splits.
247
+
248
+ Both phases retain the same authoritative role/session checks, remote peer
249
+ discovery, correlated request/reply exchange, durable correspondence,
250
+ acknowledgment, autonomous assistant completion, and cleanup. Core startup
251
+ omits the comprehensive-only result importer, artifact files, and managed-Lead
252
+ and researcher profiles.
253
+
245
254
  The comprehensive ordinary-Lead acceptance remains manually available as the
246
- `delivery` phase; it covers managed-Lead exclusion and delivery/recovery checks
247
- not included in the focused CI gate.
255
+ `delivery` phase; it retains concurrent Managers and Ordinary Leads, explicit
256
+ `/manager` activation, pane splits, and its artifact, exclusion, delivery, and
257
+ recovery checks. The default comprehensive Manager recovery phase likewise
258
+ retains explicit `/manager` activation and its existing lifecycle coverage.
259
+ Neither comprehensive scenario is replaced by the focused core gate.
248
260
 
249
261
  Run the focused phases with
250
262
  `PEER_SMOKE_PHASE=manager-core node scripts/peer-federation-smoke.mjs` and
@@ -279,6 +279,69 @@ does not need extension-provided capabilities.
279
279
  The `name` is authoritative; the filename itself is not the public definition
280
280
  name.
281
281
 
282
+ ## Compose specialist Agents
283
+
284
+ Different Agents can share procedures while retaining distinct responsibilities,
285
+ model choices, tools, and Pi extension behavior. When the same instructions are
286
+ always needed, preload them through body `@file` references instead of making
287
+ the Agent discover and read a skill. For example, assume the shared file
288
+ `.pi/skills/release-conventions/SKILL.md` exists in the project.
289
+
290
+ `.pi/agents/release-drafter.md`:
291
+
292
+ ```markdown
293
+ ---
294
+ name: release-drafter
295
+ description: Draft release notes from supplied change evidence; do not publish
296
+ tools: [read, ls, find, grep, write]
297
+ noSkills: true
298
+ noExtensions: true
299
+ ---
300
+
301
+ Use these shared release conventions:
302
+
303
+ @../skills/release-conventions/SKILL.md
304
+
305
+ Write a draft from the supplied evidence. Flag unsupported claims.
306
+ ```
307
+
308
+ `.pi/agents/release-auditor.md`:
309
+
310
+ ```markdown
311
+ ---
312
+ name: release-auditor
313
+ description: Check release notes against supplied inline evidence; do not edit
314
+ tools: []
315
+ noSkills: true
316
+ noExtensions: true
317
+ extensions: ["/absolute/path/to/release-audit.ts"]
318
+ ---
319
+
320
+ Use these shared release conventions:
321
+
322
+ @../skills/release-conventions/SKILL.md
323
+
324
+ Check the notes against evidence provided in the assignment text.
325
+ Report unsupported claims and omissions without editing files.
326
+ ```
327
+
328
+ Herdsman expands each whole-line `@file` reference into the Agent's system
329
+ prompt at launch. This reuses the file's text, not Pi's native skill-discovery
330
+ mechanism; `noSkills: true` disables automatic discovery. The content is
331
+ included up front, including any skill frontmatter, and nested file references
332
+ or scripts are not loaded automatically. For larger or optional procedures,
333
+ use native `skills` instead to permit on-demand loading.
334
+
335
+ The auditor has no ordinary callable tools, so its evidence must be available
336
+ in the assignment text. Its optional `release-audit.ts` path illustrates a
337
+ user-provided Pi extension that can specialize supported session hooks or
338
+ model behavior; omit it if unneeded, or replace it with an existing accessible
339
+ extension. `noExtensions: true` disables ordinary discovery, not explicitly
340
+ listed `extensions`. Loading extension code is independent of model-callable
341
+ `tools`; an empty tool allowlist is not an extension or process sandbox.
342
+ See the [agent-definition schema](../reference/agent-definition-schema.md) and
343
+ [Handoffs and files](handoffs.md) for the exact contracts.
344
+
282
345
  ## Allow direct agents
283
346
 
284
347
  ```markdown
@@ -19,8 +19,26 @@ mkdir -p pi-herdsman && cd pi-herdsman
19
19
  curl -fsSLO https://raw.githubusercontent.com/boadij/pi-herdsman/main/compose.yaml
20
20
  ```
21
21
 
22
- Choose [Tailscale](#use-tailscale) or a [host bind mount](#use-a-host-bind-mount)
23
- before first start if needed, to avoid changing networking or migrating data
22
+ For guided setup on Linux or macOS, clone the repository and run:
23
+
24
+ ```sh
25
+ git clone https://github.com/boadij/pi-herdsman.git
26
+ cd pi-herdsman
27
+ bash scripts/docker-setup.sh
28
+ ```
29
+
30
+ The script selects standard Docker, Tailscale, or Tailscale with a bind-mounted
31
+ home. It saves the selected Compose files in `.env`, preserves existing settings,
32
+ uses your local SSH public key for initial inbound access, requests a Tailscale
33
+ auth key when registration is needed, and verifies startup. It uses `sudo` for
34
+ Docker access if necessary. Run it as your normal user, including for bind mounts.
35
+ For a bind-mounted home, it initializes the directory with your UID/GID but does
36
+ not change the ownership of existing data. Tailscale credentials entered through
37
+ the prompt are not written to `.env` and are removed from the sidecar environment
38
+ after successful registration.
39
+
40
+ For manual setup, choose [Tailscale](#use-tailscale) or a
41
+ [host bind mount](#use-a-host-bind-mount) before first start if needed, to avoid changing networking or migrating data
24
42
  later. The default named volumes require no permission setup. Optional deployments
25
43
  record their Compose file selection in a local `.env`, so subsequent commands
26
44
  use the same networking and storage configuration.
@@ -158,6 +176,20 @@ not share `docker compose config` output while a key is configured: it can
158
176
  expose container environment values. The key-free recreate does not erase
159
177
  copies of credentials previously stored outside the active container.
160
178
 
179
+ The Tailscale overlay accepts tailnet DNS settings by default
180
+ (`TS_ACCEPT_DNS=true`). With MagicDNS enabled in the tailnet, processes
181
+ inside Herdsman can resolve other tailnet machines by hostname. This also
182
+ makes DNS behavior follow the tailnet configuration instead of Docker's
183
+ defaults, which may affect Docker service-name resolution.
184
+
185
+ From the Docker host, verify both tailnet and public DNS (replace
186
+ `other-host` with another machine on your tailnet):
187
+
188
+ ```sh
189
+ docker compose exec herdsman getent hosts other-host
190
+ docker compose exec herdsman getent hosts github.com
191
+ ```
192
+
161
193
  Connect (with Tailscale and MagicDNS working on the client):
162
194
 
163
195
  ```sh
@@ -173,6 +205,21 @@ herdr machine add ssh://herdsman@pi-herdsman --label my-herd
173
205
 
174
206
  Tailscale provides networking only. SSH remains normal OpenSSH.
175
207
 
208
+ On first start, the container also generates a passphrase-free Ed25519 SSH
209
+ **client** key if no client key pair exists. The private key stays in the
210
+ persistent `/home/herdsman/.ssh` directory and is never regenerated on
211
+ restarts. To authorize outbound SSH access on another machine, obtain the
212
+ public key from the Docker host:
213
+
214
+ ```sh
215
+ docker compose exec herdsman cat /home/herdsman/.ssh/id_ed25519.pub
216
+ ```
217
+
218
+ Add that key to the destination's `authorized_keys`. Never copy the private
219
+ key. The container recovers a missing public key from an existing unencrypted
220
+ private key, but does not overwrite incomplete or unusable identities. Protect
221
+ the persistent home volume because the client private key has no passphrase.
222
+
176
223
  ## Update
177
224
 
178
225
  To update the Pi runtime inside the container, finish active coordination
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-herdsman",
3
- "version": "0.47.0",
3
+ "version": "0.48.0",
4
4
  "type": "module",
5
5
  "description": "Asynchronous Pi subagents and agent fleet orchestration for parallel coding agents with nested delegation, background work, and supervision in herdr.",
6
6
  "license": "Apache-2.0",