pi-herdsman 0.1.0

package/docs/reference/ask-owner.md

@@ -0,0 +1,133 @@
+# `ask_owner` API
+
+[Documentation index](../README.md)
+
+`ask_owner` is mandatory managed-worker infrastructure for one direct-owner
+decision required to continue the current assignment.
+
+It is not a generic messaging channel.
+
+## Availability
+
+Every valid managed worker receives the `ask_owner` tool at launch.
+
+Normal definition `tools`, `excludeTools`, and `noTools` policy cannot remove
+this infrastructure capability.
+
+## Request
+
+```json
+{
+  "question": "Should I use option A or option B?",
+  "files": [".pi-herdsman/options.md", "diagram.png"]
+}
+```
+
+`question` must contain non-whitespace text.
+`files` supplies supporting evidence using the same rules as `worker`: complete
+strict UTF-8 text may be embedded, while other files are canonical local
+references and are not copied or snapshotted. Relative paths use the worker's
+working directory. This does not weaken the sole-final-tool-call rule.
+
+## Turn rule
+
+`ask_owner` must be:
+
+- the worker's only tool call in the turn;
+- the final tool call of the turn.
+
+The worker then stops and waits.
+
+A call made alongside another tool call is rejected.
+
+## Eligibility
+
+A worker can ask only while it has a valid active assignment and:
+
+- has no outstanding ask;
+- has no completed/final result pending;
+- has no pending state transition;
+- has no unacknowledged owner request;
+- has no ordinary unresolved direct-worker work.
+
+A delegation-enabled worker may ask its own owner when its unresolved direct
+workers are themselves validly blocked on owner questions. Ordinary active
+workers and pending worker results still block escalation.
+
+## Durable effect
+
+On acceptance, Pi Herdsman creates one correlated ask record and sets
+`pendingAskId` while preserving the original active assignment request ID.
+
+The tool result tells the worker that the assignment is blocked and returns
+details containing:
+
+```text
+askId
+assignmentRequestId
+```
+
+The worker public state projects as `blocked` after the turn settles.
+
+Final assignment settlement is disabled while the ask remains pending.
+
+## Owner delivery
+
+The exact direct owner receives the question through the existing owner-session
+delivery path.
+
+The system does not automatically forward a worker question through an ownership
+chain.
+
+If a delegating worker needs a lead decision, it independently calls `ask_owner`
+on its own direct ownership edge.
+
+## Reply
+
+The direct owner answers through the `worker` tool:
+
+```json
+{
+  "action": "reply",
+  "worker": "<exact worker>",
+  "message": "Use option B."
+}
+```
+
+The reply is correlated to:
+
+- ask ID;
+- original assignment request ID;
+- run ID;
+- owner session;
+- workspace;
+- worker label;
+- pane;
+- Pi session.
+
+A mismatched or stale reply fails closed.
+
+The worker clears the pending ask, acknowledges the reply request, and resumes
+the same assignment with the owner answer.
+
+## One outstanding question
+
+Only one `ask_owner` question may be outstanding per assignment at a time.
+
+There is no ask timeout.
+
+The worker must not guess the owner answer and complete while blocked.
+
+Rejected calls identify the known eligibility reason, such as no active
+assignment, an existing owner question, settling state, a pending control
+request, or active direct-worker work.
+
+## Close
+
+Closing the worker abandons the pending question as part of worker teardown.
+
+## See also
+
+- [`worker` `reply`](worker.md#reply)
+- [Lifecycle](../concepts/lifecycle.md)
+- [Delegation](../concepts/delegation.md)

package/docs/reference/commands.md

@@ -0,0 +1,121 @@
+# `/workers` commands
+
+[Documentation index](../README.md)
+
+`/workers` is the human-facing worker-management command namespace.
+
+It is separate from the structured model-facing `worker` API.
+
+Commands require a lead Pi session with UI.
+
+## Usage
+
+```text
+/workers
+/workers agents
+/workers placement [tab|split]
+/workers stop
+```
+
+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 inline attachment and mailbox
+payload limits at global or trusted-project scope. It is available only to a
+lead Pi session with UI.
+
+## `/workers agents`
+
+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.
+
+The details view can show:
+
+- name and description;
+- configured model and thinking;
+- declared tool policy represented by definition metadata (not a complete
+  runtime capability probe);
+- named skills;
+- declared direct delegation;
+- overridden/custom state;
+- override/custom source path when relevant.
+
+Bundled implementation paths are intentionally hidden from the human overview.
+
+Structured `worker list` keeps exact deterministic metadata, including exact
+source and skill paths when available.
+
+`/workers agents` does not probe runtime tool availability.
+
+Selecting a definition opens:
+
+```text
+Model
+Thinking
+Enabled
+Details…
+Back
+```
+
+Model selection refreshes Pi's registry and stores the canonical provider/model
+token. `Use default` removes the selected field. Thinking uses Pi's supported
+levels when the selected model is known.
+
+When Pi provides an explicit scoped-model list, that scope is used. Otherwise
+available models are offered.
+
+Thinking options use the effective model's supported levels when resolvable,
+or Pi Herdsman's validated vocabulary when not.
+
+The command edits only the selected top-level `model`, `thinking`, or `enabled`
+line in the global Markdown override. It preserves unrelated frontmatter and
+the complete body.
+
+Changes apply to future definition delegations and session continuations, not
+already-running workers or the lead Pi session.
+
+Standalone global definitions are editable too. Removing a field from one uses
+Pi's normal default; removing a field from a bundled override restores the
+bundled value.
+
+## `/workers` Running
+
+Select a live managed agent from the shared status projection to focus its pane.
+Pi Herdsman refreshes and verifies the exact label, pane, and session identity
+before issuing herdr's focus command. If the worker changed, no focus command
+is sent.
+
+## `/workers placement`
+
+Selecting Layout opens a native selector showing the effective setting.
+Explicit values continue to set directly:
+
+```text
+/workers placement tab
+/workers placement split
+```
+
+See [Configuration](configuration.md).
+
+## `/workers stop`
+
+Destructive lead-only emergency control.
+
+It aborts the current lead turn and attempts to close the exactly proven owned
+worker tree.
+
+It reports discarded active work or durable pending results when present.
+
+Cleanup uses existing exact ownership proofs and proceeds conservatively across
+independent failures.
+
+Use ordinary `worker close` for normal targeted model-driven control.
+
+## See also
+
+- [`/chief` and chief mode](supervision.md)
+- [`worker` API](worker.md)
+- [Configuration](configuration.md)
+- [Status widget](status-widget.md)

package/docs/reference/configuration.md

@@ -0,0 +1,130 @@
+# Configuration
+
+[Documentation index](../README.md)
+
+Pi Herdsman intentionally has very little settings state.
+
+Agent behavior lives in Markdown definitions. The extension settings currently
+own worker placement.
+
+## Worker placement
+
+Settings shape:
+
+```json
+{
+  "piHerdsman": {
+    "spawnPlacement": "tab"
+  }
+}
+```
+
+Supported values:
+
+```text
+tab
+split
+```
+
+Default:
+
+```text
+tab
+```
+
+`tab` places future workers in the managed worker-tab workflow.
+
+`split` places future workers by splitting from the caller's tab/pane placement
+boundary.
+
+This affects future starts, not existing workers.
+
+## Message limits
+
+Pi Herdsman uses two independent byte settings:
+
+```json
+{
+  "piHerdsman": {
+    "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` or
+`AskRecord` admission size.
+
+Valid trusted project values override valid global values. Invalid values are
+ignored rather than clamped. Configure these values through `/workers` →
+`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` or `split`.
+
+If no valid trusted project placement is active, the global value is used.
+
+`/workers placement` opens a native selector showing the effective value and
+offering `tab` 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`.
+
+## Agent definitions are not extension settings
+
+Do not put per-agent model, thinking, tool, skill, extension, body, or
+delegation policy in `piHerdsman`.
+
+Those belong in Markdown agent definitions.
+
+Trusted project-local definitions can be enabled with this project-only
+discovery gate in `<cwd>/.pi/settings.json`:
+
+```json
+{ "piHerdsman": { "projectAgents": true } }
+```
+
+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
+```
+
+Pi Herdsman requires integration version `2` or newer for supported native session
+identity/restore behavior.
+
+## See also
+
+- [`/workers` commands](commands.md)
+- [Getting started](../getting-started.md)

package/docs/reference/errors.md

@@ -0,0 +1,87 @@
+# Errors
+
+[Documentation index](../README.md)
+
+Normal public `worker` failures use structured error details.
+
+## Shape
+
+A structured error contains:
+
+```text
+category
+message
+operation
+rollbackOccurred
+retryAttempted
+```
+
+and may include:
+
+```text
+ids
+nextAction
+primary
+cleanup
+details
+```
+
+Do not discard `primary` when `cleanup` also failed.
+
+`retryAttempted` is true only after a retry or recovery attempt is scheduled or
+entered. It is preserved when a structured error is wrapped. Cleanup that is
+still pending remains represented by cleanup evidence and retry wording; it
+must not be presented as exhausted cleanup.
+
+## Categories
+
+| Category                   | Meaning                                                                             |
+| -------------------------- | ----------------------------------------------------------------------------------- |
+| `not_running_inside_herdr` | Required herdr environment is missing.                                              |
+| `worker_label_exists`      | Requested/generated live label conflicts with an existing worker.                   |
+| `pane_not_ready`           | Worker 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.                |
+| `rollback_failure`         | Primary operation failed and cleanup did not fully converge.                        |
+| `worker_busy`              | Worker state does not allow the requested control action.                           |
+| `invalid_request`          | Request fields, values, definition input, file input, or preconditions are invalid. |
+| `internal_failure`         | An invariant or underlying operation failed outside a narrower public category.     |
+
+## Identity failures
+
+`target_not_found` can intentionally mean "could not prove this exact target",
+not necessarily "nothing exists physically".
+
+`target_ambiguous` means Pi Herdsman refuses to choose among multiple candidates.
+
+Both are fail-closed behavior.
+
+## Rollback
+
+When a worker launch fails, exact resources created by that attempt are cleaned
+only when ownership is proved.
+
+A `rollback_failure` can preserve:
+
+- primary startup/control error;
+- cleanup error;
+- known label/pane/tab/session evidence;
+- stage;
+- next action.
+
+Inspect these fields before another destructive attempt.
+
+Model-facing error text surfaces available identity, stage, primary cause,
+cleanup cause, and next action without discarding the structured details.
+
+## Model-visible truncation
+
+Very large tool output can be bounded for model delivery. When full output is
+persisted, tool details may include a `full_output_path`.
+
+This is output presentation behavior, not an error category.
+
+## See also
+
+- [Recovery](../guides/recovery.md)
+- [`worker` API](worker.md)

package/docs/reference/status-widget.md

@@ -0,0 +1,148 @@
+# Status widget
+
+[Documentation index](../README.md)
+
+The TUI status widget is a local, display-only projection of exact managed
+workers plus controller-local transient starting assignments.
+
+It does not replace mailbox assignment/result authority.
+
+An active chief receives a separate leads-only widget. It shows the
+supervision projection, not managed worker rows. Its complete
+overview, peek, and focus behavior is documented in the
+[supervision reference](supervision.md). The two widgets are never combined.
+
+The ambient supervision rows use `├─` for non-final visible leads and `└─` for the
+final visible lead. Lead state glyphs remain separate (`◐` needs you, `●`
+working, and `○` ordinary/idle). Workspace labels are presentation text inside
+each lead row, not additional hierarchy nodes. The widget always retains
+attention leads, caps ordinary leads, and shows omitted leads in a final
+`└─ … N more · /chief` row.
+
+## Installation
+
+The widget is installed only when the current session has a valid supported
+herdr/Pi identity and Pi is in TUI mode.
+
+A lead Pi session gets its exact owned subtree view.
+
+A valid managed leaf can receive an identity-only header.
+
+A delegation-enabled worker can receive its direct-worker counts and rows.
+
+Unmanaged or invalid worker environments do not receive the managed widget.
+
+## Refresh
+
+The widget refreshes managed herdr data plus mailbox state every two seconds.
+
+Refresh performs a bounded herdr pane-list lookup to validate the lead
+boundary. It does not add a socket transport or another worker-control protocol.
+
+A refresh failure never mutates mailbox/control eligibility.
+
+## Breadcrumb
+
+Example:
+
+```text
+● herd → implementer → scout
+```
+
+The breadcrumb uses validated definition/worker ancestry.
+
+Delegating-worker and leaf panes append their current Pi active tool names as
+muted bracketed metadata after the current identity, preserving Pi's exact
+order. Lead Pi sessions do not show this metadata. It is local to the current
+pane, is never copied to worker rows or authoritative worker state, and is
+truncated or omitted before breadcrumb identity is shortened when width is
+limited.
+
+If an ancestor cannot be proved, it is shown explicitly as `?` rather than
+guessed:
+
+```text
+● ? → scout
+```
+
+## Header counts
+
+Example:
+
+```text
+● herd  2 working · 1 blocked · 1 settling
+```
+
+The header reports exact non-zero lifecycle states in the order `working`,
+`blocked`, `settling`, `starting`, and `unknown`. `starting` is a
+presentation-only count for assignments whose final label and mailbox claim
+are known but whose authoritative worker startup has not completed. It is not
+mailbox state, control authority, or Running inventory.
+
+Before the first successful refresh, the header says `unavailable`.
+
+After a later refresh failure, the widget retains the last valid snapshot and
+marks the header `stale`.
+
+Header refresh staleness is not worker inactivity.
+
+## Worker rows
+
+Every visible worker is rendered in a stable tree. Siblings are sorted by
+logical label and use Pi's `├─`, `└─`, and `│` connectors.
+The row shows the agent definition and its exact logical worker label
+separately. Recovery-only ancestry evidence is retained by structured status
+paths but is not included in this human projection.
+
+Rows share globally aligned columns for state, elapsed time, compact model,
+thinking, context percentage, and optional inactivity. Context is shown as a
+percentage without a `ctx` prefix. Responsive layouts drop the task first,
+then elapsed time, then context percentage; the same column choice is used for
+every row. The task is the rightmost elastic field and is kept only when it has
+useful room before it is truncated.
+
+Working rows use `● working`, blocked rows use `◐ blocked`, settling rows use
+`◌ settling`, starting rows use `◌ starting`, and unknown rows use `? unknown`.
+Working, settling, and starting animate; blocked and unknown rows are static. A
+starting row is reconciled away
+when authoritative worker evidence replaces it, and is removed on startup
+failure, rollback, repeated session start, or shutdown.
+
+`Running` inspection shows every authoritative worker row and excludes
+presentation-only starting rows. A terminal result is followed by cleanup; the
+widget does not retain an idle completed worker.
+
+## Optional metadata
+
+Rows can include best-effort:
+
+- task;
+- elapsed time;
+- compact model;
+- thinking;
+- context percentage;
+- worker type/display metadata.
+
+These fields are not control authority.
+
+The renderer preserves identity/state information before truncating task text
+and bounds every output line by visible Unicode width.
+
+The current widget does **not** claim to display the full effective tool list.
+That remains separate from the definition overview.
+
+## Worker inactivity
+
+A `working` worker can expose an advisory inactivity marker based on durable
+Pi-observed activity.
+
+This is distinct from header `stale`, which means the widget failed to refresh
+its latest snapshot.
+
+Neither changes worker control state.
+
+## See also
+
+- [Worker states](worker-states.md)
+- [`/workers agents`](commands.md#workers-agents)
+- [Recovery](../guides/recovery.md)