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.
- package/CHANGELOG.md +29 -0
- package/README.md +6 -3
- package/dist/coordinators/chief.md +0 -2
- package/dist/coordinators/manager.md +0 -2
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/docs/development/instruction-interface-design.md +8 -0
- package/docs/development/product-philosophy.md +18 -0
- package/docs/development/smoke-testing.md +16 -4
- package/docs/guides/agent-definitions.md +63 -0
- package/docs/guides/container-deployment.md +49 -2
- package/package.json +1 -1
|
@@ -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
|
-
|
|
244
|
-
|
|
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
|
|
247
|
-
|
|
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
|
-
|
|
23
|
-
|
|
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.
|
|
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",
|