pi-herdsman 0.3.2 → 0.5.0

package/docs/reference/agent.md

@@ -2,11 +2,12 @@
 
 [Documentation index](../README.md) · [supervision reference](supervision.md)
 
-`agent` is the structured model-facing API for managed agents. It has exactly six actions:
+`agent` is the structured model-facing API for managed agents. It has seven actions:
 
 ```text
 list
 delegate
+continue
 steer
 reply
 close
@@ -19,12 +20,6 @@ controllers.
 
 ## `delegate`
 
-Delegation has exactly two strict variants. The required field (`definition` or
-`session`) selects the variant; there is no target discriminator.
-Every variant rejects additional properties.
-
-### Definition
-
 ```json
 {
   "action": "delegate",
@@ -42,39 +37,38 @@ the source for a new derived context; otherwise a new Pi session is launched.
 Each accepted definition delegation creates one agent generation for one
 assignment. The terminal result is delivered once and the agent is cleaned up.
 
-### Session
+## `continue`
 
 ```json
 {
-  "action": "delegate",
+  "action": "continue",
   "session": "<exact .jsonl path or full UUID>",
   "task": "Continue the investigation"
 }
 ```
 
-Allowed fields are `action`, `session`, `task`, optional `label`, `files`, and
-`timeoutMs`. The exact saved session supplies its cwd, definition identity, and
-historical Pi context. Session delegation always creates a new agent generation
+Allowed fields are `action`, `session`, `task`, optional `files`, and
+`timeoutMs`. The exact saved session path or full UUID supplies its cwd,
+definition identity, and historical Pi context. Continuation always creates a new agent generation
 for one assignment with a live label; it never assigns work to an existing
-agent. The saved definition must currently resolve to an enabled, authorized
-effective definition, whose current configuration is used for the new
-generation.
+agent. `continue` does not accept `cwd` or `fork`; the cwd comes from the saved
+session. The saved definition is resolved again from current configuration and
+must currently be enabled and authorized; its current effective configuration
+is used for the new generation.
 Concurrent or otherwise conflicting managed representations of the exact
-session fail closed. The controller's own active Pi session cannot be delegated
-to itself; use definition delegation with `fork` when a separate derived
-context is required.
-
-`label` is optional on both delegation variants and identifies the live
-generation, not the continuation session. When omitted, Herdsman chooses a
-fresh available label derived from the effective agent definition. An explicit
-label is used exactly as the live label; if that label is occupied, delegation
-fails with `agent_label_exists`.
-
-All successful delegation results use `action: "delegate"` and include
-`agent`, `definition`, request, session, and startup evidence where available.
-Delegation returns after durable acceptance, not completion. A terminal result
-also makes the exact session identity prominent so it can be used with a later
-`delegate.session` call.
+session fail closed. The controller's own active Pi session cannot be continued
+to itself; use `delegate` with `fork` when a separate derived context is
+required.
+
+The saved session's logical label is inherited exactly for the continued
+generation. A caller cannot provide a continuation label; if the inherited
+label is occupied, continuation fails with `agent_label_exists`.
+
+Successful `delegate` results use `action: "delegate"`; successful `continue`
+results use `action: "continue"`. Both include `agent`, `definition`, request,
+session, and startup evidence where available. Both return after durable
+acceptance, not completion. A terminal result makes the exact session identity
+prominent for a later `continue` call.
 
 ## `list`
 
@@ -105,8 +99,9 @@ Each actionable live agent record includes:
 `available_actions` is authoritative model guidance for the current snapshot.
 Do not infer eligibility from `state`. Active work may list `steer`; a valid
 correlated pending `ask_owner` may list `reply`; exact direct ownership may list
-`close`. `available_actions` never lists `delegate`: an agent cannot receive a
-second assignment. Descendant visibility does not grant control. Lead orphan
+`close`. `available_actions` never lists `delegate` or `continue`: these are
+controller operations, not controls on an already-live agent. An agent cannot
+receive a second assignment. Descendant visibility does not grant control. Lead orphan
 recovery may expose only `close`. Unknown and recovery-only records are
 non-actionable. Every operation rechecks identity, ownership, mailbox state, and
 lifecycle immediately before mutation.
@@ -146,15 +141,15 @@ mailbox records, lifecycle, or available controls.
 
 ## `files` and `timeoutMs`
 
-`files` is valid on all `delegate` variants and on `steer` and `reply`; it is not
+`files` is valid on `delegate` and `continue`, and on `steer` and `reply`; it is not
 valid on `list` or `close`. Paths are resolved from the controller cwd, checked
 as readable regular files, canonicalized with `realpath`, and embedded only
 when the exact message limit permits. Otherwise they remain canonical references.
 
-`timeoutMs` is valid on definition and session delegation and must be an integer
+`timeoutMs` is valid on `delegate` and `continue` and must be an integer
 from `5001` through `300000`. The startup budget reserves one bounded diagnostic
-window. Current message limits are governed by global/default
-settings and the fixed mailbox protocol ceiling. Managed mailbox records use
+window. Current message limits are governed by the Herdsman config file and its
+defaults, plus the fixed mailbox protocol ceiling. Managed mailbox records use
 protocol V4 in the `mailboxes-v4` namespace, and control requests use the marker prefix
 `__PI_HERDSMAN_AGENT_V4__:`.
 
@@ -216,7 +211,7 @@ and has one correlated final result. Delivery goes to the exact owning Pi
 session and occurs exactly once. Model-visible completion wording uses
 `agent=<agent>`, `definition=<definition>`, `session=<id>`,
 `request=<id>`, and status. Details retain durable `agentLabel`,
-`agentDefinition`, `piSessionId`, `piSessionFile`, result paths, elapsed time,
+`agentDefinition`, `piSessionId`, `piSessionFile`, result references, elapsed time,
 context usage, truncation, and persistence-error evidence. The agent is cleaned
 up after the terminal result is delivered; the Pi session remains available for
 continuation.

package/docs/reference/commands.md

@@ -19,18 +19,18 @@ Commands require a lead Pi session with UI.
 
 The plain command opens a native Pi selection menu with `Running`,
 `Definitions`, `Layout`, `Message limits`, and `Stop all…` destinations. The
-Message limits view edits the independent global inline attachment and mailbox
-payload limits. It is available only to a lead Pi session with UI. Current
+Message limits view edits the user-wide inline attachment and mailbox payload
+limits. It is available only to a lead Pi session with UI. Current
 values and presets show a rough token equivalent using four UTF-8 bytes per
 token. The enforced limits are bytes, not tokens.
 
 ## `/agents definitions`
 
 Opens the native Definitions menu for the effective bundled, project, and
-global roster. Project definitions are included only when the trusted project
-setting `piHerdsman.projectAgents` is `true`. Project participation is marked
-`[project]`; a global override adds `*` (so `[project] *` means both layers
-contribute). Edits write global overrides only.
+global roster. Project definitions are included when Pi considers the project
+trusted. Project participation is marked `[project]`; a global override adds
+`*` (so `[project] *` means both layers contribute). Edits write global
+overrides only.
 
 The details view can show:
 
@@ -78,7 +78,7 @@ Details re-resolves the selected definition when opened, so it reflects current
 overlays and body references even if the menu remained open while configuration
 changed.
 
-Changes apply to future definition delegations and session continuations, not
+Changes apply to future `delegate` assignments and `continue` assignments, not
 already-running agents or the lead Pi session.
 
 Standalone global definitions are editable too. Removing a field from one uses

package/docs/reference/configuration.md

@@ -2,137 +2,77 @@
 
 [Documentation index](../README.md)
 
-Pi Herdsman intentionally has very little settings state.
-
-Agent behavior lives in Markdown definitions. The extension settings currently
-own agent placement.
-
-## Agent placement
-
-Settings shape:
-
-```json
-{
-  "piHerdsman": {
-    "spawnPlacement": "subtree"
-  }
-}
-```
-
-Supported values:
+Pi Herdsman keeps its configuration in one flat, user-wide file:
 
 ```text
-tab
-subtree
-split
+<Pi agent directory>/pi-herdsman/config.json
 ```
 
-Default:
+The default location is `~/.pi/agent/pi-herdsman/config.json`. Pi's native
+`getAgentDir()` determines the agent directory, so setting
+`PI_CODING_AGENT_DIR` relocates the file to
+`$PI_CODING_AGENT_DIR/pi-herdsman/config.json`.
 
-```text
-subtree
-```
-
-When no `spawnPlacement` value is configured, it resolves to `subtree`.
-Unrecognized values remain invalid and resolve to `tab`.
-
-`tab` places future direct agents owned by a lead in one dedicated agents tab.
+Project trust and project settings do not affect Herdsman configuration.
+Agent definitions remain a separate feature and continue to use the bundled,
+project-local, and user agent-definition locations described in the
+[agent-definition guide](../guides/agent-definitions.md).
 
-`subtree` gives each future lead-direct agent its own tab. Descendants always
-split inside their owner's current tab.
+## Schema and defaults
 
-`split` places future lead-direct agents by splitting from the caller's current
-pane. Descendants always split inside their owner's current tab.
-
-This affects future starts, not existing agents.
-
-## Message limits
-
-Pi Herdsman uses two independent byte settings:
+The file contains only explicitly configured overrides. The accepted flat
+schema is:
 
 ```json
 {
-  "piHerdsman": {
-    "inlineAttachmentLimitBytes": 131072,
-    "mailboxPayloadLimitBytes": 131072
-  }
+  "spawnPlacement": "subtree",
+  "inlineAttachmentLimitBytes": 131072,
+  "mailboxPayloadLimitBytes": 131072
 }
 ```
 
-Each accepts an integer from 1024 bytes (1 KiB) through 1048576 bytes (1 MiB)
-and defaults to 131072 bytes (128 KiB). The inline limit applies per file;
-eligible complete strict UTF-8 files are embedded in caller order only when
-the exact serialized mailbox record fits. Other files remain canonical
-references. The mailbox limit is the exact serialized `RequestRecord`,
-`AskRecord`, or text-only chief supervision record admission size. Chief
-supervision also has an existing fixed 8 KiB record ceiling, so its effective
-admission limit is the smaller of the configured mailbox limit and 8 KiB.
-
-Only valid global values affect runtime behavior. Invalid global values are
-ignored rather than clamped, and project-local values for these two keys are
-inert. Configure the global values through `/agents` → `Message limits`; the
-fixed 1 MiB protocol safety ceiling remains in force for reading existing
-mailbox records.
-
-## Settings scope
-
-Pi Herdsman reads Pi settings through Pi's settings manager.
-
-Global settings are stored in the Pi agent directory's `settings.json`
-(default `~/.pi/agent/settings.json`).
-
-Project settings are stored in:
-
-```text
-<project>/.pi/settings.json
-```
-
-A project placement value is effective only when:
-
-- the project is trusted by Pi; and
-- the project setting is `tab`, `subtree`, or `split`.
+An absent file means these defaults:
 
-If no valid trusted project placement is active, the global value is used.
+| Field                        |            Default | Allowed values                                    |
+| ---------------------------- | -----------------: | ------------------------------------------------- |
+| `spawnPlacement`             |          `subtree` | `tab`, `subtree`, `split`                         |
+| `inlineAttachmentLimitBytes` | `131072` (128 KiB) | integer from 1024 (1 KiB) through 1048576 (1 MiB) |
+| `mailboxPayloadLimitBytes`   | `131072` (128 KiB) | integer from 1024 (1 KiB) through 1048576 (1 MiB) |
 
-`/agents placement` opens a native selector showing the effective value and
-offering `tab`, `subtree`, or `split`. Selecting a value writes to the current effective
-scope and verifies the value after writing; the confirmation reports whether
-that scope is `project` or `global`.
+Malformed JSON, a non-object root, unknown fields, and invalid known values
+are errors. Reads do not create the directory or file. Configuration changes
+through `/agents` update this single file atomically.
 
-## Agent definitions are not extension settings
+`inlineAttachmentLimitBytes` applies per file. Eligible complete strict UTF-8
+files are embedded only when the exact serialized mailbox record fits; other
+files remain canonical references. `mailboxPayloadLimitBytes` limits the exact
+serialized request, ask, or chief message record. Chief messages also retain
+their fixed 8 KiB protocol ceiling.
 
-Do not put per-agent model, thinking, tool, skill, extension, body, or
-delegation policy in `piHerdsman`.
+Placement affects future starts, not existing agents. `tab` uses one lead-owned
+agents tab, `subtree` gives each lead-direct agent its own tab, and `split`
+splits from the caller's pane. Nested delegation always splits in its owner's
+current tab.
 
-Those belong in Markdown agent definitions.
+## Reset
 
-Trusted project-local definitions can be enabled with this project-only
-discovery gate in `<cwd>/.pi/settings.json`:
+Stop active Pi and Herdsman processes first; running processes may recreate
+runtime state. Then delete the complete Herdsman directory at this canonical
+location:
 
-```json
-{ "piHerdsman": { "projectAgents": true } }
+```text
+<resolved Pi agent directory>/pi-herdsman/
 ```
 
-The default is disabled, and a global `projectAgents` value has no effect.
-This setting enables discovery only; agent models, tools, bodies, extensions,
-and delegation remain in Markdown definitions.
-
-See:
-
-- [Agent definitions](../guides/agent-definitions.md)
-- [Agent-definition schema](agent-definition-schema.md)
-
-## herdr integration
-
-The required Pi integration is installed separately:
-
-```sh
-herdr integration install pi
-herdr integration status
-```
+`<resolved Pi agent directory>` means the result of Pi's native
+`getAgentDir()`. With a custom `PI_CODING_AGENT_DIR`, Pi resolves that value
+(including values such as `~`) before appending `pi-herdsman`; do not construct
+the path by concatenating the raw environment variable yourself. Use the
+native file-management operation for the current platform to delete that
+directory.
 
-Pi Herdsman requires integration version `2` or newer for supported native session
-identity/restore behavior.
+The next process starts with the defaults and recreates only the runtime state
+it needs.
 
 ## See also
 

package/docs/reference/errors.md

@@ -38,7 +38,7 @@ must not be presented as exhausted cleanup.
 | Category                   | Meaning                                                                             |
 | -------------------------- | ----------------------------------------------------------------------------------- |
 | `not_running_inside_herdr` | Required herdr environment is missing.                                              |
-| `agent_label_exists`       | Requested/generated live label conflicts with an existing agent.                    |
+| `agent_label_exists`       | Requested, inherited, or generated live label conflicts with an existing agent.     |
 | `pane_not_ready`           | Agent pane/startup did not reach the required readiness boundary.                   |
 | `target_not_found`         | Exact requested identity or ownership evidence was not found.                       |
 | `target_ambiguous`         | More than one live candidate matched an identity that must be exact.                |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdsman",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "type": "module",
   "description": "Asynchronous Pi agent orchestration with nested delegation, parallel execution, and supervision in herdr.",
   "license": "Apache-2.0",
@@ -41,17 +41,18 @@
     "image": "https://raw.githubusercontent.com/boadij/pi-herdsman/main/docs/assets/thumbnail.webp"
   },
   "scripts": {
-    "test": "node --experimental-test-module-mocks --test --test-timeout=10000",
+    "test": "node --experimental-test-module-mocks --import=./scripts/test-env.mjs --test --test-timeout=10000",
     "check": "node scripts/check.mjs",
     "build": "node scripts/build.mjs",
     "package:audit": "node scripts/package-audit.mjs",
-    "release:check": "npm run check && npm run build && npm run package:audit && npm publish --dry-run --ignore-scripts",
+    "validate": "npm run check && npm run build && npm run package:audit",
+    "release:check": "npm run validate && npm publish --dry-run --ignore-scripts",
     "prepack": "npm run build"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-ai": ">=0.84.2 <0.86.0",
+    "@earendil-works/pi-coding-agent": ">=0.84.2 <0.86.0",
+    "@earendil-works/pi-tui": ">=0.84.2 <0.86.0",
     "typebox": "*"
   },
   "devDependencies": {