pi-herdsman 0.1.0

package/docs/guides/handoffs.md

@@ -0,0 +1,224 @@
+# Handoffs and files
+
+[Documentation index](../README.md)
+
+Pi Herdsman has two text-file mechanisms with different purposes:
+
+- `files` supplies evidence to delegate (definition or session), steer, reply,
+  or ask_owner.
+- whole-line body `@file` references put definition-owned text into the worker
+  system prompt when a new worker generation is built.
+
+Strict UTF-8 text is embedded when it fits; non-text and non-fitting files are
+canonical local references and are not copied or snapshotted.
+
+## Message `files`
+
+For `delegate` with `definition`, `delegate` with `session`, `steer`, and
+`reply`, pass supporting artifacts, including
+applicable instruction or skill files, through `files` instead of mentioning
+only their paths in the task or message; explain each file's relevance in the
+accompanying text, and do not reattach skills already supplied by the selected
+agent definition.
+
+Example:
+
+```json
+{
+  "action": "delegate",
+  "definition": "reviewer",
+  "task": "Review the implementation against the approved plan.",
+  "files": [".pi-herdsman/plan.md", "/tmp/implementation-result"]
+}
+```
+
+`files` is supported by `delegate` with `definition`, `delegate` with `session`,
+`steer`, `reply`, and `ask_owner`. For
+controller actions, relative paths resolve from the calling controller's cwd;
+for `ask_owner`, they resolve from the managed worker's cwd. Every accepted
+path is displayed using its canonical absolute path.
+
+Supplied paths must resolve to readable regular files. Missing, broken,
+unreadable, and non-regular paths reject the whole operation. Canonical
+duplicates are represented once, with the first occurrence winning.
+
+For `delegate` with `definition`, deterministic validation and known-input sizing happen
+before mutation. The final durable envelope can be sized only after herdr
+returns the authoritative pane ID; if the configured `mailboxPayloadLimitBytes`
+is then exceeded, `delegate` with `definition` returns `invalid_request` without delivering a task and
+rolls back the exact startup attempt (`rollbackOccurred: true` when
+applicable).
+
+For each regular file:
+
+- complete strict UTF-8 text without NUL bytes is embedded when the complete
+  message fits the effective configured `mailboxPayloadLimitBytes` boundary;
+- invalid UTF-8, NUL-containing, binary, and non-fitting files are represented
+  only by a canonical local path and observed byte size.
+
+The fixed 1 MiB mailbox protocol safety ceiling is a separate read limit for
+mailbox records; it does not replace the configured admission limit for new
+messages.
+
+No file is partially embedded. Embedded text is a submission-time snapshot.
+Reference-only files are not copied or snapshotted; their contents may change
+or disappear after submission, and the recipient must already have local
+filesystem/tool access to inspect them. `files` supplies evidence and does not
+grant runtime capabilities.
+
+Files are read through their canonical `realpath` target.
+
+## Canonical deduplication
+
+Within any message's `files`, the first canonical occurrence wins.
+
+These can therefore represent one attachment:
+
+```text
+./notes.md
+/project/notes.md
+./symlink-to-notes.md
+```
+
+when they resolve to the same physical canonical path. The same canonical path
+in caller-supplied `delegate.files` also takes precedence over a definition body
+`@file` reference, including when the caller file is reference-only.
+
+Later duplicates are omitted.
+
+## Body `@file` references
+
+Inside an agent body, a line is a file reference only when the trimmed complete
+line has one of these shapes:
+
+```text
+@./relative.md
+@../relative.md
+@/absolute/path.md
+```
+
+These remain literal text:
+
+```text
+@alice
+Use @./policy.md when needed
+```
+
+Relative body references are resolved from the Markdown definition that
+declared them **before** bundled/global body composition.
+
+Expansion then happens once, in body order, when a new worker generation is
+constructed.
+
+Included file contents are not recursively parsed for more `@file` references.
+
+## Cross-mechanism precedence
+
+Caller assignment files win overlap with definition body references.
+
+If the same canonical file appears in both:
+
+```text
+delegate.files
+body @file
+```
+
+the assignment keeps its user-message copy and the body reference is omitted.
+
+The combined rule is:
+
+```text
+duplicates inside delegate.files
+    → first caller occurrence wins
+
+duplicates inside body @file references
+    → first body occurrence wins
+
+same canonical file in both
+    → caller attachment wins
+```
+
+## Immutable prompt transport
+
+A definition body is expanded into text before worker lifecycle mutation.
+
+The final expanded body and shared herdr worker guidance are written to private
+temporary snapshots (`0600` files under private `0700` directories), passed to
+Pi, and removed after the delegation attempt.
+
+Original body source paths are never handed to Pi as system-prompt paths.
+
+Each worker generation builds its system prompt once for its single assignment.
+Session continuation builds a new generation with the current effective
+definition configuration while preserving the saved Pi session context.
+
+## Result handoff
+
+Successful worker completion may expose a private `resultPath`.
+
+For dependent work, pass the exact result path through `files` rather than
+copying a large result manually:
+
+```json
+{
+  "action": "delegate",
+  "definition": "reviewer",
+  "task": "Review the implementation described in the supplied result.",
+  "files": ["/exact/resultPath"]
+}
+```
+
+Successful worker completions persist their complete output at the canonical
+`resultPath`; they do not receive a separate completion overflow path.
+Oversized non-completion registered-tool output may additionally expose
+`full_output_path` when overflow persistence succeeds. Model-visible content
+remains bounded in both cases.
+
+## Project-local coordination workspace
+
+Use the project-local `.pi-herdsman/` directory for temporary coordination artifacts
+used by agents working on the repository.
+
+Typical contents include implementation plans, scope and non-goals,
+specifications, accepted decisions, investigation notes, review scope or
+acceptance criteria, validation notes, and handoff state.
+
+Prefer one current artifact per coordinated objective. Reuse and update an
+adequate artifact rather than creating multiple competing descriptions of the
+same work.
+
+Keep the default structure flat:
+
+```
+.pi-herdsman/
+  task.md
+  runtime-contract.md
+  plugin-remapping-ui.md
+```
+
+Create subdirectories only when real artifact volume makes the flat layout
+unwieldy.
+
+These files are coordination state, not product state. Do not use `.pi-herdsman/`
+for product source, permanent user documentation, application data, build
+output, caches, or generated artifacts.
+
+Read-only workers may consume existing coordination artifacts but do not gain
+permission to modify them.
+
+When dependent work uses an artifact, pass the same path through `files` on the
+message that creates or updates the dependency: `delegate.files` for a new
+worker, `steer.files` for an active worker, `ask_owner.files` for supporting
+evidence in a question, or `reply.files` for the owner's answer. Update the
+artifact before submission. Small text is embedded at submission time; a
+reference-only artifact remains a live canonical local path.
+
+Required textual instructions or evidence may be passed through `files`.
+`files` does not add runtime capability; use a capable definition when an
+actual runtime capability is required.
+
+## See also
+
+- [`worker` API](../reference/worker.md)
+- [Agent-definition schema](../reference/agent-definition-schema.md)
+- [Delegation](../concepts/delegation.md)

package/docs/guides/recovery.md

@@ -0,0 +1,156 @@
+# Recovery
+
+[Documentation index](../README.md)
+
+Recovery is identity-safe and conservative. Use the public state and returned
+structured error before attempting another mutation.
+
+## Worker is `blocked`
+
+A blocked worker still has an active assignment.
+
+If the worker is waiting for an owner answer, use `reply` with its exact worker.
+
+Otherwise resolve the reported external/attention condition. Do not delegate new
+task to a blocked worker.
+
+## Worker is `settling`
+
+`settling` means assignment convergence is incomplete. Typical causes include:
+
+- task handoff acknowledgement;
+- result delivery;
+- bounded result-persistence recovery;
+- delegating-worker/worker completion gating;
+- launch handoff;
+- one-shot cleanup.
+
+Do not delegate another task yet.
+
+If nothing independent remains, end the turn normally and let result/attention
+delivery returns attention to the owner. Refresh `list` only when there is a reason to take
+another control action.
+
+If `list` reports `result_error`, the worker's result could not be persisted
+after bounded retries. The condition retains the run, request, owner, worker,
+and failure category. Do not delegate over it: resolve the mailbox persistence
+problem, then close the exact worker before delegating new work. The condition
+marks retry as unsafe and exact-owner cleanup as safe.
+
+## Worker is `unknown`
+
+`unknown` means the system cannot prove a safe control state from current exact
+evidence.
+
+Do not guess from pane IDs, process appearance, elapsed time, or stale metadata.
+
+Refresh `list` and resolve the identity/lifecycle condition. If a cleanup or
+recovery error is present, inspect its exact details.
+
+## Inactivity advisory
+
+A `working` worker with an exact active assignment can become advisory `stale`
+after ten minutes without observed Pi turn, message, or tool activity.
+
+Possible list fields:
+
+- `stale: true`
+- `inactive_ms`
+- `last_activity_at`
+
+This is not proof that the worker is hung, dead, safe to terminate, or safe to
+replace.
+
+Do not close solely because of inactivity.
+
+## Startup failure
+
+Fresh and historical-session delegation startup is bounded.
+
+When herdr returns a structured failure, Pi Herdsman preserves it. When startup
+returns empty or malformed output and no better structured error is available,
+the implementation can capture one bounded exact-pane diagnostic snapshot
+within the startup budget.
+
+Failures report the known stage and identities when available.
+
+Ownership-safe rollback removes only resources whose identity can be proved.
+If ownership cannot be proved, cleanup intentionally fails closed and preserves
+evidence.
+
+Do not "fix" this by manually deleting guessed panes or mailboxes.
+
+## `pane_not_ready`
+
+A pane-readiness failure means the managed worker did not reach the required
+safe startup boundary.
+
+The normal response is to inspect the returned stage/diagnostic and the current
+herdr environment. Do not add client-side polling or arbitrary sleeps as an
+operator workaround.
+
+## Cleanup or rollback failure
+
+A `rollback_failure` can contain both:
+
+- the primary launch/control failure;
+- the cleanup failure.
+
+Preserve both. The `nextAction` field may direct you to inspect cleanup evidence
+before retrying.
+
+A later attempt should not reuse a label or resource whose ownership is still
+uncertain.
+
+## Close failure
+
+Normal `worker close` targets one exact directly owned live worker.
+
+Closing a delegating worker cascades through its owned workers first. If a
+worker cannot be proved or closed safely, the delegating worker remains rather
+than being destructively guessed away.
+
+For lead-only human emergency cleanup, `/workers stop` operates on the proven
+owned tree and reports discarded active work or durable pending results. It is
+not the normal model orchestration interface.
+
+## Historical session failure
+
+A `delegate` with `session` requires an exact session path or full UUID.
+
+The saved session header must contain a non-empty working directory. Session
+delegation uses that saved cwd and does not accept a caller-supplied `cwd`.
+
+The saved agent-definition name is resolved against the current effective
+definition roster. If it no longer exists, session delegation fails instead of guessing a
+replacement. The definition must also be enabled and authorized for the current
+controller, and its current effective configuration is used for the new worker
+generation.
+
+An exact session that is already represented by active or unresolved managed
+work cannot be activated concurrently. The session-start exclusion applies to
+the canonical session path, so an exact UUID and its exact path identify the
+same target. Wait for the existing assignment to finish and clean up, or close
+its exact live worker when abandoning it, then retry. Do not delegate another
+task through a worker label.
+
+## Before retrying
+
+Check:
+
+1. exact error category;
+2. operation;
+3. worker identity;
+4. known pane/session IDs;
+5. startup stage when present;
+6. primary cause;
+7. cleanup cause;
+8. `rollbackOccurred`;
+9. `nextAction`;
+10. current `worker list`.
+
+## See also
+
+- [Errors](../reference/errors.md)
+- [Worker states](../reference/worker-states.md)
+- [Workers and identity](../concepts/workers.md)

package/docs/reference/agent-definition-schema.md

@@ -0,0 +1,272 @@
+# Agent-definition schema
+
+[Documentation index](../README.md)
+
+This page is the canonical public schema for Markdown agent definitions.
+
+## File format
+
+A definition requires frontmatter beginning on the first line and a closing
+frontmatter delimiter:
+
+```markdown
+---
+name: scout
+thinking: medium
+tools: ["read", "bash"]
+---
+
+Prompt body.
+```
+
+Known string arrays use inline JSON arrays. YAML block sequences are not
+supported.
+
+Unknown frontmatter fields fail validation.
+
+Malformed files fail discovery; Pi Herdsman does not silently drop one invalid
+definition and return a partial roster.
+
+## Sources and precedence
+
+Bundled definitions:
+
+```text
+dist/agent-definitions/
+```
+
+Global definitions by default:
+
+```text
+~/.pi/agent/agents/
+```
+
+A matching project or global name overlays the lower-precedence definition.
+
+An unmatched project or global definition is standalone. Project definitions
+are loaded from `<cwd>/.pi/agents/` only when trusted project settings set
+`piHerdsman.projectAgents` to `true`. Precedence is `bundled < project < global`.
+
+All effective definitions are sorted and validated together, including every
+`workers` reference.
+
+`enabled` controls definition availability. A disabled definition remains in the
+lead roster so it can be enabled again, but owner-visible definition lists omit
+it. Definition and session delegations reject a disabled definition. An already
+active worker may finish and remains controllable according to its current
+available actions; disabling a definition does not mutate that assignment.
+
+## Fields
+
+| Field                   | Accepted value                                                        | Omitted/default behavior                                          | Runtime/composition behavior                                                                           |
+| ----------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `name`                  | non-empty string                                                      | required                                                          | Effective definition identity.                                                                         |
+| `enabled`               | boolean                                                               | `true`                                                            | `false` makes definition and session delegation unavailable; it does not mutate an active worker.      |
+| `description`           | string                                                                | absent                                                            | Display/selection description.                                                                         |
+| `model`                 | non-empty string                                                      | Pi default/current launch behavior                                | Passed as Pi model selection.                                                                          |
+| `thinking`              | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, or `false` | Pi default/current launch behavior                                | `false` launches as `off`.                                                                             |
+| `systemPromptMode`      | `append` or `replace`                                                 | `append` only for definition name `delegate`; otherwise `replace` | Controls effective body versus Pi base system prompt.                                                  |
+| `bodyMode`              | `append` or `replace`                                                 | `replace` for non-empty matching overlay body                     | Valid only when overlaying an existing lower-precedence definition; consumed during body composition.  |
+| `noTools`               | boolean                                                               | Pi normal tool policy                                             | `true` emits `--no-tools`; managed `ask_owner` remains infrastructure.                                 |
+| `noBuiltinTools`        | boolean                                                               | Pi normal built-in tool policy                                    | `true` emits `--no-builtin-tools`.                                                                     |
+| `tools`                 | inline array of non-empty strings                                     | no explicit allowlist                                             | Passed to Pi as a source-agnostic tool-name allowlist; matching overlay replaces whole array.          |
+| `excludeTools`          | inline array of non-empty strings                                     | no explicit exclusions                                            | Passed to Pi as source-agnostic tool-name exclusions; matching override replaces whole array.          |
+| `noSkills`              | boolean                                                               | skills disabled unless `inheritSkills: true`                      | Controls Pi native skill discovery; explicit `skills` values are still passed separately.              |
+| `inheritSkills`         | boolean                                                               | does not enable by itself unless `true`                           | `true` changes omitted `noSkills` default so native skills remain available. Explicit `noSkills` wins. |
+| `skills`                | inline array of non-empty strings                                     | no explicit skill arguments                                       | Each value is passed unchanged as a Pi skill path/resource.                                            |
+| `noExtensions`          | boolean                                                               | Pi normal extension policy                                        | `true` emits `--no-extensions`. Required herdr worker infrastructure remains injected by the launcher. |
+| `extensions`            | inline array of non-empty strings                                     | no extra extension arguments                                      | Each value is passed unchanged to Pi.                                                                  |
+| `workers`               | inline array of unique non-empty definition names                     | no direct workers                                                 | Names direct definitions this worker may delegate to; every name must exist.                           |
+| `inheritProjectContext` | boolean                                                               | `true` only for definition name `delegate`; otherwise `false`     | Controls project context-file inheritance.                                                             |
+| `inheritGlobalContext`  | boolean                                                               | follows effective `inheritProjectContext`                         | Controls global context-file inheritance.                                                              |
+
+Arrays supplied by an override replace the complete inherited array, including
+an explicit `[]`.
+
+When a delegating worker declares a worker in `workers`, that worker must be enabled.
+A delegating worker referencing a disabled worker can remain discoverable, but is rejected
+during assignment or fresh worker startup with an explicit disabled-worker error
+rather than being silently removed from the delegating worker definition.
+
+Skill and extension paths are passed to Pi unchanged. herdr does not resolve
+them relative to the definition file.
+
+Tool names are governed by Pi's native name-based policy, regardless of
+whether a tool is built in, registered by an extension, or supplied as a
+custom/SDK tool. When both fields apply, an exclusion wins over an allowlist.
+Names do not need to exist when a definition is discovered: unknown names are
+accepted and can match a tool registered later. Pi Herdsman does not provide
+source-qualified permissions, such as an extension path plus tool name.
+
+An explicit `tools` allowlist takes precedence over the default-selection
+switches `noTools` and `noBuiltinTools`; `excludeTools` still removes matching
+names. Thus a managed worker may receive both `--no-tools` and an explicit
+`--tools ask_owner`. Pi Herdsman protects that mandatory `ask_owner` capability in
+managed launches and removes it from explicit exclusions. Unmanaged Pi
+launches do not receive this exception.
+
+Loading extension code and exposing its tools are separate concerns. An
+extension listed in `extensions` is loaded, while its registered tools still
+must pass `tools` and `excludeTools` to be model-callable. Tool filtering is
+not extension sandboxing: loaded extensions may still run handlers, commands,
+shortcuts, providers, initialization, and other non-tool behavior.
+
+Pi's native tool policy is the callable boundary verified for the documented
+integration. A provider or conversion integration may add its own presentation
+layer, so provider-visible tool descriptions should not be treated as a Pi
+Herdsman permission registry or as proof that extension code is sandboxed. Pi Herdsman
+passes the native policy through; it does not independently guarantee every
+provider presentation boundary.
+
+Tools with the same name are not independently permissionable by source, and
+the winner for a name collision is not a supported ordering contract.
+
+`noExtensions` disables ordinary extension discovery, but launcher-injected
+Pi Herdsman worker and Herdr-state extensions remain mandatory infrastructure.
+Explicit `extensions` entries remain separate launch inputs and are passed to
+Pi normally. Launcher-injected infrastructure remains separate from the
+definition's extension and tool policy.
+
+## Tool inference for `workers`
+
+A non-empty `workers` list declares potential worker definitions; effective
+delegation also requires permitted `worker` capability and a controller depth
+that allows delegation.
+
+This capability is projected by controller depth. Lead-launched definitions
+retain their declared worker allowlist and effective `worker` tool. A
+worker-launched worker receives no worker allowlist and no effective `worker`,
+even when its definition is delegation-enabled at the lead. Explicit tool
+allowlists, empty arrays, `noTools`, and exclusions remain fail-closed.
+
+When it has an explicit non-empty `tools` allowlist and does not already contain
+`worker`, Pi Herdsman appends `worker` to the effective allowlist unless denied.
+
+Rules:
+
+| Configuration                                    | Effective inference                                                       |
+| ------------------------------------------------ | ------------------------------------------------------------------------- |
+| `workers` omitted or `[]`                        | no inferred `worker`                                                      |
+| non-empty `workers`, `tools` omitted             | keep Pi default tool policy; do not materialize a `worker`-only allowlist |
+| non-empty `workers`, explicit non-empty `tools`  | append `worker`                                                           |
+| `excludeTools` contains `worker`                 | explicit denial wins                                                      |
+| `noTools: true`, no explicit `worker` in `tools` | no inferred `worker`                                                      |
+| `noTools: true`, explicit `tools: ["worker"]`    | explicit allow is preserved                                               |
+| explicit allow plus explicit exclusion           | exclusion wins                                                            |
+
+`ask_owner` is separate mandatory managed-worker infrastructure and is not this
+inference rule.
+
+## Body composition
+
+The body is text after the closing `---`, trimmed at its outer boundaries.
+
+For matching project and global overlays:
+
+```text
+empty overlay body
+    → lower-layer body
+
+non-empty overlay body, bodyMode omitted/replace
+    → overlay body
+
+non-empty overlay body, bodyMode append
+    → lower-layer body + "\n\n" + overlay body
+```
+
+Standalone definitions cannot declare `bodyMode`.
+
+## Body file references
+
+A body line is a reference only when the complete trimmed line matches:
+
+```text
+@./relative/path
+@../relative/path
+@/absolute/path
+```
+
+Before bundled/global body composition, relative references are resolved from
+the definition file that declared them.
+
+When a new worker generation is constructed:
+
+1. references are processed in body order;
+2. targets are canonicalized with `realpath`;
+3. each canonical file is included once;
+4. a caller `delegate.files` canonical overlap wins and removes the body copy;
+5. each accepted source must be a bounded readable regular UTF-8 file without
+   NUL bytes;
+6. included text replaces that reference line;
+7. included text is not recursively expanded.
+
+Every new worker generation expands the effective body and its file references
+once at launch. Session continuation preserves the Pi session history while
+using the current effective definition configuration.
+
+## Runtime prompt order
+
+For a newly constructed managed worker, the effective launch composition is:
+
+```text
+Pi base system prompt
+    ↓ effective body via systemPromptMode
+selected project/global context-file additions
+    ↓
+shared herdr worker guidance
+```
+
+The final effective body and shared guidance are delivered through private
+temporary prompt snapshots.
+
+## Complete override example
+
+```markdown
+---
+name: reviewer
+description: Review implementation changes
+model: openai-codex/gpt-5.6-luna
+thinking: high
+bodyMode: append
+systemPromptMode: replace
+noTools: false
+noBuiltinTools: false
+tools: ["read", "bash"]
+excludeTools: []
+noSkills: false
+inheritSkills: true
+skills: ["/absolute/path/to/code-review/SKILL.md"]
+noExtensions: false
+extensions: ["/absolute/path/to/local-extension.ts"]
+workers: ["scout"]
+inheritProjectContext: true
+inheritGlobalContext: false
+---
+
+Additional local review instructions.
+
+@./prompts/review-policy.md
+```
+
+Because `workers` is non-empty and the explicit `tools` list does not deny it,
+the effective tools include `worker`.
+
+To disable a bundled role without copying its definition, use a minimal global
+override:
+
+```markdown
+---
+name: reviewer
+enabled: false
+---
+```
+
+The `/workers agents` menu exposes the same enable and disable operations.
+Removing the `enabled` line inherits the bundled value; when no source declares
+the field, the effective value is `true`.
+
+## See also
+
+- [Customizing bundled agents](../guides/customizing-agents.md)
+- [Handoffs and files](../guides/handoffs.md)
+- [Delegation](../concepts/delegation.md)