pi-herdsman 0.1.0

package/docs/reference/supervision.md

@@ -0,0 +1,203 @@
+# Supervision reference
+
+[Documentation index](../README.md) · [Concept](../concepts/supervision.md)
+
+This is the current chief and staff contract for Pi Herdsman. Exact live
+identity and fresh authority checks are authoritative; presentation state and
+metadata are not.
+
+## Role, lease, and lead state
+
+`/chief` is available to an eligible lead. The session role is persisted as
+`customType: "pi-herdsman-role"` with `role: "lead"` or `"chief"`. A malformed
+role fails closed and records a durable error. There is at most one active
+chief for an exact `HERDR_SOCKET_PATH`; its descriptor is bound to the exact
+process-lock claim and Pi session identity.
+
+Every lead has one private atomic record in the supervision runtime's `leads/`
+directory, keyed by the SHA-256 hash of its exact Pi session ID:
+
+```json
+{
+  "version": 1,
+  "instanceId": "<lead generation>",
+  "piSessionId": "<exact Pi session ID>",
+  "pendingAsk": { "askId": "<id>", "question": "<text>" },
+  "updatedAt": 0
+}
+```
+
+`pendingAsk` is optional. The latest matching `pi-herdsman-lead-state` session
+entry is authoritative during lead startup. A fresh `instanceId` is created
+for every initialization. The lead record is checked against exact live
+Herdr/Pi identity; missing, malformed, stale, duplicate, or ambiguous evidence
+fails closed. The record is bounded to 2 KiB. Questions are limited to 1,024
+characters and 1,024 UTF-8 bytes.
+
+The record does not represent scheduling, capacity, permission, or message
+readiness. Herdr lifecycle observation is normalized to
+`idle|working|blocked|done|unknown`.
+
+Chief is a mode of a lead session. While active, its model has exactly the
+`staff` tool. Project/workspace context files and skills are excluded from
+chief model context; workspace-specific work remains the responsibility of
+supervised leads. `/chief leave` restores the session's ordinary tools.
+
+## Lead projection and actions
+
+An eligible lead requires one exact live recognized Pi agent, a matching lead
+record, and no chief or validated managed-worker identity. A lead's observed
+runtime state is informational. Every exact-identity-verified live lead has
+`inspect` and `message`, whether it is idle, working, blocked, done, or unknown.
+A pending ask is separate attention state: it projects as `needs_you`, exposes
+the bounded question and ask ID, and adds `reply`.
+
+The `staff list` representation contains `lead` (the exact full Pi session ID),
+`display_name` (a presentation-only label), identity fields, `runtime_state`,
+`needs_you`, optional pending-ask fields, `worker_counts`, optional
+`last_activity`, and `available_actions`. The automatic
+`<supervision_state>` context is hard-bounded to 16 KiB and uses
+`leads`, `worker_counts`, and `workers`. Oversized output is truncated only at
+complete lead records and identifies omitted state. Use `staff list` when a
+fresh complete roster is required.
+
+The `lead` value is the exact full Pi session ID shown in a fresh supervision
+snapshot or returned by `staff list`; the `display_name` label is never accepted
+as a target.
+
+## Metadata
+
+Pi Herdsman may publish best-effort Herdr metadata for display:
+
+```text
+source: pi-herdsman:lead
+pi_herdsman_role=lead
+pi_herdsman_ask=<ask-id>
+pi_herdsman_name=<session name>
+```
+
+Chief mode publishes the role token `chief`. Metadata never grants lead
+eligibility, chief authority, or message authority. Failed metadata
+publication does not change communication authority.
+
+## Chief transport
+
+Messages are bounded, versioned JSON files in the target session's hashed
+`inbox/` directory. Each record includes exact sender, target, `leadSessionId`,
+chief lease, kind, ID, text, and `createdAt`; asks and replies also include an
+ask ID. Extra fields are rejected. Transport kinds are:
+
+```text
+chief_message
+lead_message
+lead_ask
+chief_reply
+```
+
+Records are delivered in `createdAt`, then ID order and accepted through Pi
+follow-up delivery. Chief messages may queue while a lead works. Same-session
+restart preserves queued records, accepted IDs are deduplicated, and an
+individual quarantined record does not block a new record for that lead.
+Transient identity, authority, or delivery failures retain records. Exact
+identity and chief lease checks are never weakened.
+
+## `chief`
+
+This tool is available only to an ordinary lead. Its strict schemas reject
+extra fields. Both actions require a currently valid chief; descendants use
+`ask_owner`, never `chief`.
+
+### `message`
+
+```json
+{ "action": "message", "message": "Build completed." }
+```
+
+Use `message` for meaningful progress, reports, results, warnings, and
+completion. It queues one bounded `chief_message` and does not change lead
+coordination state.
+
+### `ask`
+
+```json
+{ "action": "ask", "question": "Should the release include the endpoint?" }
+```
+
+Use `ask` only when a chief decision is genuinely required. One pending ask is
+allowed per lead. The call durably records its ask ID and question, then queues
+the question. It is a terminating coordination call: make it the final tool
+call of the turn and wait rather than guessing.
+
+## `staff`
+
+This tool is available only to the active chief. Its target `lead` must be the
+exact full Pi session ID shown as `lead` in a fresh automatic supervision
+snapshot or returned by `staff list`; never use `display_name`.
+
+For general state questions and ordinary messages or replies, use the fresh
+automatic supervision snapshot directly; do not call `staff list`, `inspect`,
+or another read command first. The `message` and `reply` actions perform their
+own authoritative validation. Use `list` when the snapshot is stale or
+unavailable, an immediately refreshed roster is materially necessary, or
+diagnosis is required. Use `inspect` only when deeper lead evidence is needed.
+
+### `list`
+
+```json
+{ "action": "list" }
+```
+
+Returns a fresh supervision projection and fresh `available_actions`.
+
+### `inspect`
+
+```json
+{
+  "action": "inspect",
+  "lead": "<exact full Pi session ID shown as lead in a fresh snapshot>"
+}
+```
+
+Inspect is read-only and requires an active chief and eligible exact lead. It
+returns bounded identity-checked recent output and process evidence.
+
+### `message`
+
+```json
+{
+  "action": "message",
+  "lead": "<exact full Pi session ID shown as lead in a fresh snapshot>",
+  "message": "Run checks."
+}
+```
+
+The exact lead must currently expose `message`. Atomic creation of one bounded
+`chief_message` record queues a follow-up and does not wait for completion.
+
+### `reply`
+
+```json
+{
+  "action": "reply",
+  "lead": "<exact full Pi session ID shown as lead in a fresh snapshot>",
+  "askId": "<exact pending ask ID>",
+  "message": "Proceed."
+}
+```
+
+The exact lead, unchanged pending ask ID, current lead identity, and chief
+lease must validate. The pending ask is cleared only after accepted delivery.
+
+## UI and failure rules
+
+The `/chief` command is state-sensitive. From an ordinary lead, `/chief`
+activates chief mode and shows the ambient widget. While already active as
+chief, `/chief` opens the interactive overview. `/chief leave` leaves chief
+mode and removes the widget.
+
+The active chief gets a width-aware compact leads-only ambient widget and a
+native `/chief` overview with peek and focus. Leads are ordered by needs-you,
+working, blocked, idle/done, then unknown. The ambient widget uses
+presentation-only tree branches for visible lead rows, while the native
+overview stays flat. Missing, replaced, ambiguous, or conflicting identity
+fails closed. There is no descendant selector or force-takeover action.

package/docs/reference/worker-states.md

@@ -0,0 +1,57 @@
+# Worker states
+
+[Documentation index](../README.md)
+
+The public state is a safe-control projection built from live lifecycle and
+durable assignment/convergence evidence. It is not a raw herdr lifecycle string.
+
+| State      | Meaning                                                                                               |
+| ---------- | ----------------------------------------------------------------------------------------------------- |
+| `working`  | An assignment is active.                                                                              |
+| `blocked`  | Active assignment waits for owner attention or another condition.                                     |
+| `settling` | Assignment handoff, completion/result delivery, launch, direct-worker gate, or cleanup is converging. |
+| `unknown`  | Exact safe control state cannot be proved.                                                            |
+
+## `available_actions` is authoritative
+
+A live worker record in `worker list` includes an `available_actions` snapshot.
+Use only operations currently listed there; do not infer control eligibility
+from `state` alone. `steer` means active work accepts steering, `reply` means a
+correlated pending `ask_owner` is valid, and `close` means exact ownership or
+approved orphan recovery permits teardown. `available_actions` never includes
+`delegate`; a worker generation handles one assignment only. Every operation
+revalidates identity, ownership, mailbox state, and lifecycle immediately before
+mutation.
+
+A delegating worker may be blocked while direct worker work is pending and still accept
+steering when `steer` is listed. Descendant visibility does not imply authority;
+records outside the controller's direct ownership can have an empty action list.
+
+## `blocked` and owner questions
+
+A worker waiting on a valid `ask_owner` reply projects as `blocked` after its ask
+turn settles. Answer through the exact direct owner using `reply.worker`.
+
+## `settling`
+
+Examples include an uncompleted task handoff, pending final result delivery,
+direct-worker gating, terminal cleanup, result persistence recovery, and startup
+or integration handoff. Do not assign another task to a settling worker.
+
+## `unknown`
+
+Unknown is intentional fail-closed behavior. Unreadable, oversized, malformed,
+or validation-failing mailbox state is reported with a bounded diagnostic and an
+empty `available_actions` list. Do not substitute pane idleness, elapsed time,
+model metadata, missing activity, a guessed session, or an old worker identity.
+
+## Inactivity fields
+
+A qualifying `working` worker may also report `stale`, `inactive_ms`, and
+`last_activity_at`. This advisory does not change the state or prove a hang.
+
+## See also
+
+- [Lifecycle](../concepts/lifecycle.md)
+- [Recovery](../guides/recovery.md)
+- [`worker` API](worker.md)

package/docs/reference/worker.md

@@ -0,0 +1,201 @@
+# `worker` API
+
+[Documentation index](../README.md) · [supervision reference](supervision.md)
+
+`worker` is the structured model-facing API for managed workers. It has exactly six actions:
+
+```text
+list
+delegate
+steer
+reply
+close
+inspect
+```
+
+Unknown fields and unsupported selector combinations fail with `invalid_request`.
+The tool is registered only for the lead controller and authorized delegating worker
+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",
+  "definition": "implementer",
+  "task": "Implement the approved change"
+}
+```
+
+Allowed fields are `action`, `definition`, `task`, optional `label`, `cwd`,
+`files`, `fork`, and `timeoutMs`. The definition is resolved from
+the effective roster and delegating worker controllers may use only their allowlisted
+definitions. Project definitions still require trusted project approval.
+`fork`, when supplied, is an exact saved Pi session path or full UUID used as
+the source for a new derived context; otherwise a new Pi session is launched.
+Each accepted definition delegation creates one worker generation for one
+assignment. The terminal result is delivered once and the worker is cleaned up.
+
+### Session
+
+```json
+{
+  "action": "delegate",
+  "session": "<exact .jsonl path or full UUID>",
+  "task": "Continue the investigation"
+}
+```
+
+Allowed fields are `action`, `session`, `task`, optional `files`, and
+`timeoutMs`. The exact saved session supplies its cwd, definition identity, and
+historical Pi context. Session delegation always creates a new worker generation
+for one assignment; it never assigns work to an existing worker. The saved
+definition must currently resolve to an enabled, authorized effective
+definition, whose current 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.
+
+All successful delegation results use `action: "delegate"` and include
+`worker`, `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.
+
+## `list`
+
+Request:
+
+```json
+{ "action": "list" }
+```
+
+No selectors or other fields are accepted. A successful result includes the
+effective `agent_definitions` roster and visible worker records.
+
+Each actionable live worker record includes:
+
+| Field                                                           | Meaning                                                                                                                               |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `worker`                                                        | Exact live logical worker identity to copy into `steer.worker`, `reply.worker`, or `close.worker`. It is not a continuation identity. |
+| `state`                                                         | Safe lifecycle state for observability.                                                                                               |
+| `available_actions`                                             | Snapshot of operations currently eligible for this controller.                                                                        |
+| `workspace_id`, `pane_id`, `tab_id`, `tab_label`                | Herdr identity evidence.                                                                                                              |
+| `cwd`, `pi_session_id`, `pi_session_path`                       | Worker location and Pi session evidence.                                                                                              |
+| `owner_session_id`                                              | Exact direct owner Pi session.                                                                                                        |
+| `agent_definition`                                              | Effective definition name.                                                                                                            |
+| `active_request_id`, `last_activity_at`, `stale`, `inactive_ms` | Assignment and advisory activity evidence.                                                                                            |
+| `parent_label`, `orphan`                                        | Visible direct-owner ancestry and proven orphan recovery evidence.                                                                    |
+| `cleanup_error`, `result_error`, `diagnostic`, `tokens`         | Bounded recovery and presentation evidence when present.                                                                              |
+
+`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`: a worker 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.
+The public record does not expose `steerable`.
+
+Lead controllers see the complete effective definition roster and workers visible
+through their ownership boundary. Delegating workers see only allowed enabled
+leaf definitions and their visible workers. Unknown mailbox diagnostics remain
+non-actionable.
+
+## `inspect`
+
+```json
+{ "action": "inspect", "worker": "implementer-1" }
+```
+
+`inspect` accepts only `action` and the exact live worker label. It is available
+only to that worker's direct owner, and only when the worker is a current,
+unambiguous managed identity. The result is read-only and contains the exact
+session/pane identity, a bounded tail of the most recent 40 unwrapped terminal
+lines (at most 8 KiB), and advisory foreground process evidence when available.
+Its model-facing text includes the worker, session, pane, useful foreground
+commands, and recent activity; raw process and recent-output evidence remains
+in the structured result details.
+The identity is checked again after capture; if the pane or Pi session was
+replaced, inspection fails closed. Inspection does not change worker state,
+mailbox records, lifecycle, or available controls.
+
+## `files` and `timeoutMs`
+
+`files` is valid on all `delegate` variants 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
+from `5001` through `300000`. The startup budget reserves one bounded diagnostic
+window. Current message limits are governed by effective global/project/default
+settings and the fixed mailbox protocol ceiling. Managed mailbox records use
+protocol version 3, and control requests use the marker prefix
+`__PI_HERDSMAN_WORKER_V3__:`.
+
+## `steer`
+
+```json
+{
+  "action": "steer",
+  "worker": "implementer-1",
+  "message": "Also update the focused regression.",
+  "files": [".pi-herdsman/review.md"]
+}
+```
+
+Use only when `steer` is listed in `available_actions`. Steering changes the
+current assignment and does not create another final result.
+
+## `reply`
+
+```json
+{
+  "action": "reply",
+  "worker": "implementer-1",
+  "message": "Use option B."
+}
+```
+
+Use only when `reply` is listed in `available_actions` for a valid correlated
+pending `ask_owner` question. The reply continues the same assignment and
+contains its request, ask, assignment, and session correlation evidence.
+
+See [`ask_owner` API](ask-owner.md).
+
+## `close`
+
+```json
+{ "action": "close", "worker": "implementer-1" }
+```
+
+Only `action` and `worker` are accepted. Close requires exact direct ownership,
+or the lead-only evidence-backed orphan recovery condition. Closing abandons a
+pending owner question; closing a delegating worker cascades through directly
+owned workers first. Cleanup remains fail-closed when exact identity or ownership
+cannot be proved.
+
+## Result delivery and errors
+
+An accepted delegated task remains the internal mailbox `kind: "task"` request
+and has one correlated final result. Delivery goes to the exact owning Pi
+session and occurs exactly once. Model-visible completion wording uses
+`worker=<worker>`, `definition=<definition>`, `session=<id>`,
+`request=<id>`, and status. Details retain durable `workerLabel`,
+`agentDefinition`, `piSessionId`, `piSessionFile`, result paths, elapsed time,
+context usage, truncation, and persistence-error evidence. The worker is cleaned
+up after the terminal result is delivered; the Pi session remains available for
+continuation.
+
+Tool failures return structured details for normal public errors. See
+[Errors](errors.md), [worker states](worker-states.md), and
+[workers and identity](../concepts/workers.md).

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "pi-herdsman",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Asynchronous workers for Pi in herdr.",
+  "license": "SEE LICENSE IN LICENSE",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "workers",
+    "multi-agent",
+    "orchestration",
+    "delegation",
+    "supervision",
+    "herdr",
+    "pi-herdsman"
+  ],
+  "pi": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "skills": [
+      "."
+    ]
+  },
+  "scripts": {
+    "test": "node --experimental-test-module-mocks --experimental-strip-types --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",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.2",
+    "esbuild": "^0.28.2",
+    "typebox": "^1.3.7"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "README.md",
+    "SKILL.md",
+    "LICENSE",
+    "docs",
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  }
+}