pi-herdsman 0.45.0 → 0.46.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 CHANGED
@@ -1,5 +1,45 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.46.0](https://github.com/boadij/pi-herdsman/compare/v0.45.0...v0.46.0) (2026-11-13)
4
+
5
+
6
+ ### Features
7
+
8
+ * **agents:** extend generic bootstrap and remove PCC integration ([#951](https://github.com/boadij/pi-herdsman/issues/951)) ([da8ade3](https://github.com/boadij/pi-herdsman/commit/da8ade376656599e7186cb38b8a6ab2db0855364)), closes [#637](https://github.com/boadij/pi-herdsman/issues/637)
9
+ * **config:** support array modifiers in definition overlays ([#941](https://github.com/boadij/pi-herdsman/issues/941)) ([53b5df9](https://github.com/boadij/pi-herdsman/commit/53b5df946216c5c2d793cd03c399d3758dcf648e))
10
+ * **container:** support persistent native Pi self-updates ([#945](https://github.com/boadij/pi-herdsman/issues/945)) ([c95877a](https://github.com/boadij/pi-herdsman/commit/c95877a5a02cb81d7820c502bdd6188409bb37de))
11
+ * **dev:** add one-command setup for worktree hooks ([#947](https://github.com/boadij/pi-herdsman/issues/947)) ([6af00b4](https://github.com/boadij/pi-herdsman/commit/6af00b4b7ecd20a0f1d157768d34b6c9e8ffdd51))
12
+ * **ui:** inspect effective instruction composition in Details ([#946](https://github.com/boadij/pi-herdsman/issues/946)) ([ec84045](https://github.com/boadij/pi-herdsman/commit/ec840458c57c09b4469f54f4f1cf89ef8636ad73)), closes [#942](https://github.com/boadij/pi-herdsman/issues/942)
13
+
14
+
15
+ ### Fixes
16
+
17
+ * **dev:** repair hook setup in copied repositories ([#957](https://github.com/boadij/pi-herdsman/issues/957)) ([9bf4466](https://github.com/boadij/pi-herdsman/commit/9bf4466d8782dcc819f4973e462f6d74ced0f60b))
18
+ * **ui:** present effective instructions as sequential Markdown sections ([#956](https://github.com/boadij/pi-herdsman/issues/956)) ([0519349](https://github.com/boadij/pi-herdsman/commit/0519349e4998bed90cfc2e6435f22c16bf26a82a))
19
+ * **ui:** restore chat scrolling for effective instruction details ([#953](https://github.com/boadij/pi-herdsman/issues/953)) ([556e9c2](https://github.com/boadij/pi-herdsman/commit/556e9c2df47f82963d56f10315e16c790ad7e961))
20
+
21
+
22
+ ### Documentation
23
+
24
+ * introduce emergent agentic workflows ([#959](https://github.com/boadij/pi-herdsman/issues/959)) ([9d1b078](https://github.com/boadij/pi-herdsman/commit/9d1b078a29604ac04f59d28214865a914d97b701))
25
+ * refresh community contributor acknowledgments ([#964](https://github.com/boadij/pi-herdsman/issues/964)) ([8e9f371](https://github.com/boadij/pi-herdsman/commit/8e9f3713543452399924b1125c6462b1a4a86927))
26
+ * streamline README onboarding and mobile layout ([#960](https://github.com/boadij/pi-herdsman/issues/960)) ([278d5d2](https://github.com/boadij/pi-herdsman/commit/278d5d2ba6fe82b0e156952a4fd4c6f382168d80))
27
+
28
+
29
+ ### Tests
30
+
31
+ * **ci:** require minimal ordinary Lead federation acceptance ([#954](https://github.com/boadij/pi-herdsman/issues/954)) ([35418b4](https://github.com/boadij/pi-herdsman/commit/35418b452731f8433bb4dbc92a5ad2e618ce4d06))
32
+ * **ci:** use minimal Manager federation acceptance ([#948](https://github.com/boadij/pi-herdsman/issues/948)) ([57c5a4f](https://github.com/boadij/pi-herdsman/commit/57c5a4f6f304df2aec791c144f8a1dae7b190774)), closes [#588](https://github.com/boadij/pi-herdsman/issues/588)
33
+ * **ci:** verify Manager activation through live authority ([#962](https://github.com/boadij/pi-herdsman/issues/962)) ([534aea1](https://github.com/boadij/pi-herdsman/commit/534aea13bde5d27c2241da91d3baa4682ec031e0)), closes [#934](https://github.com/boadij/pi-herdsman/issues/934)
34
+
35
+
36
+ ### Other Changes
37
+
38
+ * **deps:** update ghcr.io/jdx/mise docker tag to v2026.11.8 ([#958](https://github.com/boadij/pi-herdsman/issues/958)) ([17e680b](https://github.com/boadij/pi-herdsman/commit/17e680b175a6449d8b1d8a3976279a370b0b33dc))
39
+ * **deps:** update npm non-major updates ([#935](https://github.com/boadij/pi-herdsman/issues/935)) ([6193198](https://github.com/boadij/pi-herdsman/commit/6193198849f37049e9038dc6bbe159ef10ed5aed))
40
+ * **deps:** update tailscale/tailscale docker tag to v1.104.7 ([#949](https://github.com/boadij/pi-herdsman/issues/949)) ([f6e8ff9](https://github.com/boadij/pi-herdsman/commit/f6e8ff953acc993dde4945fb08d3e5042868068b))
41
+ * **types:** enforce strict checking across all TypeScript sources ([#961](https://github.com/boadij/pi-herdsman/issues/961)) ([1955406](https://github.com/boadij/pi-herdsman/commit/1955406254edc2f0b8b6158fb75c2afd3c1e22ee))
42
+
3
43
  ## [0.45.0](https://github.com/boadij/pi-herdsman/compare/v0.44.0...v0.45.0) (2026-11-12)
4
44
 
5
45
 
package/README.md CHANGED
@@ -9,12 +9,25 @@
9
9
 
10
10
  **The orchestration layer between [Pi](https://github.com/earendil-works/pi) and [herdr](https://github.com/herdrdev/herdr).**
11
11
 
12
- Pi Herdsman lets your AI coding assistant delegate tasks to background Agents
13
- while your main conversation stays interactive. Start with one Agent, or
14
- coordinate parallel, branch-based project work across independent Leads.
12
+ Pi Herdsman lets your AI coding assistant delegate work to background Agents
13
+ while your conversation stays interactive, or coordinate larger projects across
14
+ independent, branch-based Leads. Pi handles model conversations, herdr manages
15
+ terminal sessions and workspaces, and Herdsman coordinates delegation,
16
+ ownership, and supervision.
15
17
 
16
- Pi runs the coding-agent conversations; herdr manages their terminal sessions
17
- and workspaces; Herdsman coordinates delegation, ownership, and supervision.
18
+ ## Emergent agentic workflows
19
+
20
+ **Define the boundaries, not the workflow.**
21
+
22
+ Fixed agent pipelines prescribe the next handoff. Pi Herdsman instead lets models
23
+ decide how to split work, delegate to permitted Agents or Leads, and sequence or
24
+ parallelize tasks as results arrive. The execution path emerges at runtime,
25
+ while Herdsman enforces delegation permissions, ownership, project assignments,
26
+ and supervision.
27
+
28
+ You can still bring your own workflow and Agent definitions. See
29
+ [Coordination](docs/concepts/coordination.md#emergent-workflows-explicit-boundaries)
30
+ for the underlying model.
18
31
 
19
32
  ## Demo
20
33
 
@@ -22,16 +35,6 @@ _Advanced orchestration: a live Manager → Lead → Agent workflow._
22
35
 
23
36
  [![Live demo](https://github.com/user-attachments/assets/e1355ace-aaba-418e-a1d0-1246f1840fc6)](https://github.com/user-attachments/assets/d6ee6687-a96d-493e-ae75-429f586be393)
24
37
 
25
- ## What Pi Herdsman gives you
26
-
27
- - **Background Agents.** Delegate bounded work without blocking the Lead conversation.
28
- - **Parallel and nested delegation.** Run independent work concurrently and let explicitly enabled Agents delegate their own bounded subtasks.
29
- - **Project orchestration.** A Manager coordinates durable branch-based work across independent Leads and their Agent trees.
30
- - **Direct supervision.** Chief, Manager, Lead, and Agent responsibilities stay explicit instead of collapsing into one global controller.
31
- - **Peer communication.** Leads can message eligible peers locally; unassigned ordinary Leads and Managers can also collaborate across connected machines.
32
- - **Owned usage visibility.** Inspect Pi-native token usage and cost for the current session and its transitively owned managed Agents. An active Manager also sees the Leads in its current durable project assignments and their owned Agent trees.
33
- - **Your workflow stays yours.** Bring your own Agent definitions, models, tools, skills, extensions, and development process.
34
-
35
38
  ## Quick start
36
39
 
37
40
  **Linux/macOS:**
@@ -46,57 +49,39 @@ curl -fsSL https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.sh
46
49
  irm https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.ps1 | iex
47
50
  ```
48
51
 
49
- **Already using Pi and Herdr?**
52
+ **Already using Pi and herdr?**
50
53
 
51
54
  ```sh
52
55
  pi install npm:pi-herdsman
53
56
  herdr integration install pi
54
57
  ```
55
58
 
56
- **Docker Compose (prebuilt SSH environment):** Requires Docker Compose and an
57
- SSH public key.
58
-
59
- ```sh
60
- mkdir -p pi-herdsman && cd pi-herdsman
61
- curl -fsSLO https://raw.githubusercontent.com/boadij/pi-herdsman/main/compose.yaml
62
- SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" docker compose up -d
63
- ssh -p 2222 herdsman@localhost
64
- ```
65
-
66
- The included [Compose file](compose.yaml) uses a prebuilt image and persistent
67
- Docker volumes. Herdr opens on SSH login; select a workspace and run `pi`.
68
- Replace `localhost` with the Docker host address for remote access. SSH port
69
- 2222 is published on host interfaces by default; see
70
- [Container deployment](docs/guides/container-deployment.md) for networking,
71
- storage, and update options.
72
-
73
- For a native installation, start herdr in your project directory, then Pi in its pane:
74
-
75
- ```sh
76
- herdr
77
- pi
78
- ```
79
-
80
- If Pi needs model authentication, use `/login`. Then try a read-only first task:
59
+ Start `herdr` in your project directory, then run `pi` in its pane. Try:
81
60
 
82
61
  ```text
83
62
  Use scout to identify this repository's main entry points.
84
- Explain how the application starts. Don't change any files.
63
+ Explain how the application starts.
85
64
  ```
86
65
 
87
- The Agent works independently and sends its result back to the conversation
88
- that delegated the task. Discover Agent management and other capabilities with:
66
+ The Agent works asynchronously and returns its result to your Pi conversation.
67
+ Use `/herdsman` to discover controls. See [Getting started](docs/getting-started.md)
68
+ for prerequisites, model login, and troubleshooting, or
69
+ [Container deployment](docs/guides/container-deployment.md) for Docker Compose.
89
70
 
90
- ```text
91
- /herdsman
92
- ```
71
+ ## What Pi Herdsman gives you
93
72
 
94
- See [Getting started](docs/getting-started.md) for prerequisites and
95
- troubleshooting.
73
+ - **Background Agents.** Delegate bounded work without blocking your conversation.
74
+ - **Parallel and nested delegation.** Run independent work concurrently; permitted Agents can delegate their own subtasks.
75
+ - **Project orchestration.** A Manager coordinates durable, branch-based work across independent Leads.
76
+ - **Explicit authority.** Chief, Manager, Lead, and Agent responsibilities have distinct supervision and ownership boundaries.
77
+ - **Peer communication.** Eligible sessions can exchange messages locally and, where supported, across connected machines.
78
+ - **Usage visibility.** Inspect Pi-native token and cost records for owned Agents and, for an active Manager, assigned Leads.
79
+ - **Your tools, your workflow.** Bring your own Agent definitions, Coordinator profiles, models, tools, skills, extensions, and development process.
96
80
 
97
81
  ## From one Agent to a project
98
82
 
99
- A normal Pi session is a **Lead**. It owns the Agents it delegates:
83
+ A normal Pi session is a **Lead**. It can own Agents, including permitted
84
+ nested Agents:
100
85
 
101
86
  ```text
102
87
  You ↔ Lead
@@ -106,7 +91,8 @@ You ↔ Lead
106
91
  ```
107
92
 
108
93
  For independent project work, an eligible Lead can enter **Manager** mode.
109
- Managers coordinate Leads instead of implementing through Agents themselves:
94
+ The Manager assigns branch-based objectives to Leads, which direct their own
95
+ Agent trees:
110
96
 
111
97
  ```text
112
98
  You ↔ Manager
@@ -114,70 +100,44 @@ You ↔ Manager
114
100
  └─ Lead → Agents
115
101
  ```
116
102
 
117
- A **Chief** is an optional runtime-wide supervisor above Managers. Without an
118
- active Manager for a project, Chief can directly supervise its ordinary Leads.
119
-
120
- The important boundaries are:
121
-
122
- ```text
123
- supervision: Chief → Manager → Lead
124
- ownership: Lead → Agent → Agent
125
- ```
126
-
127
- Project work is durable by Git branch. It does not belong to the Manager session
128
- that happened to start it, so assignments can be paused, resumed, or retired
129
- across Manager turnover.
130
-
131
- Manager-created project Leads are dedicated Managed Lead sessions: identity stays
132
- with the exact Pi session, while only a current project assignment authorizes
133
- execution. Unavailable or retired assignments never enable ordinary Lead tools.
134
- Use native Pi `/fork` or `/clone` for independent ordinary continuation with copied
135
- history, not a separate checkout or fresh process configuration. See
136
- [Project orchestration](docs/guides/project-orchestration.md#dedicated-sessions-and-independent-continuation).
103
+ An optional **Chief** supervises Managers and eligible ordinary Leads without
104
+ an active project Manager. These roles define authority, not a mandatory task
105
+ sequence. Project assignments remain durable across Manager turnover.
137
106
 
138
- See [Coordination](docs/concepts/coordination.md) for the mental model and
139
- [Project orchestration](docs/guides/project-orchestration.md) for the Manager
140
- workflow.
107
+ See [Coordination](docs/concepts/coordination.md) for role boundaries and
108
+ [Project orchestration](docs/guides/project-orchestration.md) for assignments,
109
+ recovery, and integration.
141
110
 
142
111
  ## Project status & roadmap
143
112
 
144
- Pi Herdsman is actively evolving. Core orchestration workflows are available today,
145
- while other areas are being refined or expanded.
113
+ Pi Herdsman is pre-1.0. These capabilities are available today:
146
114
 
147
- | Area | Status | What to expect |
148
- | -------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------- |
149
- | **Lead & Agent orchestration** | ✅ **Core complete** | Background and nested delegation, result handoffs, and local peer communication. Ongoing reliability fixes. |
150
- | **Manager orchestration** | ✨ **Polishing** | Branch-based delegation, supervision, and integration are implemented. Refining recovery and usability. |
151
- | **Chief coordination** | 🚧 **In progress** | Supervision is available. Repository provisioning and Manager lifecycle orchestration are being developed. |
152
- | **Federated peer communication** | 🚧 **In progress** | Cross-machine Manager/ordinary Lead messaging and durable replies work. Reverse initiation is planned. |
115
+ - **Lead & Agent orchestration.** Background and nested delegation, result handoffs, and local peer communication.
116
+ - **Manager orchestration.** Branch-based work assignments, supervision, pause/resume, and authorized local integration.
117
+ - **Chief supervision.** Supervises current Managers and eligible ordinary Leads within one herdr runtime.
118
+ - **Federated peer messaging.** Eligible Managers and ordinary Leads can communicate across connected machines, with durable replies.
153
119
 
154
- **Federation limitations:** Independent discovery and initiation currently require
155
- an SSH route from the initiating machine. Replies work over an existing
156
- correspondence without reverse SSH. See [#790](https://github.com/boadij/pi-herdsman/issues/790)
157
- for bidirectional initiation and [#688](https://github.com/boadij/pi-herdsman/issues/688)
158
- for cross-build messaging interoperability.
120
+ **Current federation limitations:** Independent discovery and initiation require
121
+ an SSH route from the initiating machine; an existing correspondence allows
122
+ replies without reverse SSH. Different Herdsman builds cannot yet exchange
123
+ ordinary messages. See [Peer communication](docs/reference/peer.md).
159
124
 
160
- **On the roadmap:** [Coordination profiles](https://github.com/boadij/pi-herdsman/issues/734)
161
- (replacing the current role-definition terminology),
162
- [cross-build messaging](https://github.com/boadij/pi-herdsman/issues/688), and
163
- [portable project state](https://github.com/boadij/pi-herdsman/issues/755).
125
+ **Open proposals:** [bidirectional initiation over one-way connections (#790)](https://github.com/boadij/pi-herdsman/issues/790),
126
+ [cross-build messaging (#688)](https://github.com/boadij/pi-herdsman/issues/688),
127
+ and [portable repository runtime (#755)](https://github.com/boadij/pi-herdsman/issues/755).
164
128
 
165
- **Early-stage project:** Core features are usable today, but pre-1.0 releases may
166
- introduce breaking changes as configuration and runtime conventions evolve.
167
- See the [changelog](CHANGELOG.md) for release changes and migration guidance.
129
+ **Early-stage project:** Pre-1.0 releases may introduce breaking changes.
130
+ See the [changelog](CHANGELOG.md) for release and migration guidance.
168
131
 
169
132
  ## Choose your next step
170
133
 
171
- | Goal | Start here |
172
- | ------------------------------------------ | ------------------------------------------------------------- |
173
- | Install and delegate your first task | [Getting started](docs/getting-started.md) |
174
- | Run independent branch-based project work | [Project orchestration](docs/guides/project-orchestration.md) |
175
- | Communicate with other Pi sessions | [Peer communication](docs/reference/peer.md) |
176
- | Understand roles, ownership, and authority | [Coordination](docs/concepts/coordination.md) |
177
- | Customize Agents | [Agent definitions](docs/guides/agent-definitions.md) |
178
- | Build against the model-facing tools | [Coordination API](docs/coordination-api.md) |
179
- | Deploy an SSH-ready environment | [Container deployment](docs/guides/container-deployment.md) |
180
- | Contribute to Pi Herdsman | [Contributing](CONTRIBUTING.md) |
134
+ Browse the [documentation index](docs/README.md), or jump to:
135
+
136
+ - **Start:** [Getting started](docs/getting-started.md)
137
+ - **Orchestrate:** [Project orchestration](docs/guides/project-orchestration.md) and [Coordination](docs/concepts/coordination.md)
138
+ - **Customize:** [Agent definitions](docs/guides/agent-definitions.md)
139
+ - **Integrate:** [Coordination API](docs/coordination-api.md) and [Peer communication](docs/reference/peer.md)
140
+ - **Contribute:** [Contributing](CONTRIBUTING.md)
181
141
 
182
142
  ## Community
183
143