@luminascale/shepherd 0.0.0-stage → 0.6.1
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/.agents/agents/README.md +12 -0
- package/.agents/agents/planner.md +38 -0
- package/.agents/agents/reviewer.md +38 -0
- package/.agents/agents/scout.md +43 -0
- package/.agents/agents/worker.md +33 -0
- package/.agents/skills/smoke-test/SKILL.md +155 -0
- package/.agents/skills/smoke-test/references/forensics.md +46 -0
- package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
- package/.github/workflows/publish.yml +77 -0
- package/.pi/prompts/release.md +21 -0
- package/.prettierrc +10 -0
- package/AGENTS.md +88 -0
- package/CONTRIBUTING.md +177 -0
- package/LICENSE +201 -0
- package/README.md +397 -2
- package/docs/README.md +26 -0
- package/docs/guides/agent-definitions.md +42 -0
- package/docs/guides/diagnostics.md +199 -0
- package/docs/guides/installation.md +61 -0
- package/docs/guides/tool-reference.md +55 -0
- package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
- package/docs/plans/agent-labels.md +257 -0
- package/docs/plans/architecture.md +110 -0
- package/docs/plans/settings-scope.md +163 -0
- package/docs/plans/tool-surface-split.md +278 -0
- package/docs/reference/dictionary +26 -0
- package/docs/releasing.md +47 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
- package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
- package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
- package/index.ts +602 -0
- package/package.json +112 -4
- package/scripts/capture-system-prompt.mjs +45 -0
- package/scripts/extract-pi-system-prompt.mjs +277 -0
- package/scripts/host-impact.mjs +74 -0
- package/scripts/resolve-agent.mjs +43 -0
- package/scripts/show-shepherd-orchestrator.mjs +58 -0
- package/scripts/show-shepherd-prompt.mjs +96 -0
- package/scripts/verify-suites.mjs +67 -0
- package/specs/001-artifacts/spec.md +436 -0
- package/specs/002-simplify-agent-orchestration/plan.md +287 -0
- package/specs/002-simplify-agent-orchestration/spec.md +323 -0
- package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
- package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
- package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
- package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
- package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
- package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
- package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
- package/specs/005-per-workspace-settings/plan.md +230 -0
- package/specs/005-per-workspace-settings/spec.md +368 -0
- package/specs/005-per-workspace-settings/tasks.md +178 -0
- package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
- package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
- package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
- package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
- package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
- package/specs/007-unwatched-completion-notice/journal.md +145 -0
- package/specs/007-unwatched-completion-notice/plan.md +186 -0
- package/specs/007-unwatched-completion-notice/spec.md +284 -0
- package/specs/007-unwatched-completion-notice/tasks.md +147 -0
- package/specs/008-remote-machine-sheep/intent.md +174 -0
- package/specs/008-remote-machine-sheep/journal.md +57 -0
- package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
- package/specs/009-hc-runtime/intent.md +44 -0
- package/specs/009-hc-runtime/plan.md +49 -0
- package/specs/009-hc-runtime/spec.md +118 -0
- package/specs/009-hc-runtime/tasks.md +62 -0
- package/specs/010-unseen-watch-parity/intent.md +57 -0
- package/specs/010-unseen-watch-parity/journal.md +172 -0
- package/specs/010-unseen-watch-parity/plan.md +74 -0
- package/specs/010-unseen-watch-parity/spec.md +191 -0
- package/specs/010-unseen-watch-parity/tasks.md +119 -0
- package/specs/011-hc-background-poll/intent.md +57 -0
- package/specs/011-hc-background-poll/journal.md +95 -0
- package/specs/011-hc-background-poll/plan.md +87 -0
- package/specs/011-hc-background-poll/spec.md +141 -0
- package/specs/011-hc-background-poll/tasks.md +83 -0
- package/specs/012-steer-default/intent.md +12 -0
- package/specs/012-steer-default/journal.md +40 -0
- package/specs/012-steer-default/plan.md +7 -0
- package/specs/012-steer-default/spec.md +42 -0
- package/specs/012-steer-default/tasks.md +6 -0
- package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
- package/specs/013-opencode-shepherd/intent.md +59 -0
- package/specs/013-opencode-shepherd/plan.md +204 -0
- package/specs/013-opencode-shepherd/spec.md +258 -0
- package/specs/013-opencode-shepherd/tasks.md +263 -0
- package/src/core/artifact-sessions.ts +835 -0
- package/src/core/config.ts +329 -0
- package/src/core/discovery.ts +342 -0
- package/src/core/herdr.ts +1 -0
- package/src/core/host.ts +77 -0
- package/src/core/ids.ts +78 -0
- package/src/core/lifecycle.ts +1 -0
- package/src/core/messaging.ts +1 -0
- package/src/core/migration.ts +55 -0
- package/src/core/orchestration.ts +1 -0
- package/src/core/types.ts +143 -0
- package/src/core/unseen-completions.ts +114 -0
- package/src/extension/cli.ts +417 -0
- package/src/extension/config.ts +1 -0
- package/src/extension/settings-ui.ts +296 -0
- package/src/extension/shepherd-done.ts +768 -0
- package/src/extension/shepherd.ts +2548 -0
- package/src/extension/system-prompt.ts +38 -0
- package/src/extension/unseen-completions.ts +237 -0
- package/src/opencode/actions.ts +794 -0
- package/src/opencode/bridge.ts +777 -0
- package/src/opencode/display.ts +36 -0
- package/src/opencode/fieldnotes.ts +60 -0
- package/src/opencode/host.ts +62 -0
- package/src/opencode/orphans.ts +162 -0
- package/src/opencode/server.ts +458 -0
- package/src/runtimes/backend.ts +119 -0
- package/src/runtimes/detect.ts +102 -0
- package/src/runtimes/hc/hc.ts +527 -0
- package/src/runtimes/hc/runtime.ts +1898 -0
- package/src/runtimes/herdr/herdr.ts +912 -0
- package/src/runtimes/herdr/lifecycle.ts +1712 -0
- package/src/runtimes/herdr/messaging.ts +703 -0
- package/src/runtimes/herdr/orchestration.ts +1583 -0
- package/src/runtimes/herdr/runtime.ts +224 -0
- package/src/runtimes/runtime.ts +133 -0
- package/src/runtimes/settle-observations.ts +114 -0
- package/test/fixtures/context-project/AGENTS.md +2 -0
- package/test/fixtures/home/.agents/agents/same.md +6 -0
- package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
- package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
- package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
- package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
- package/test/fixtures/proj/.pi/agents/same.md +6 -0
- package/test/helpers/fake-clock.mjs +39 -0
- package/test/helpers/feature-contracts.mjs +44 -0
- package/test/helpers/test-utils.mjs +44 -0
- package/test/verify-artifact-sessions.mjs +258 -0
- package/test/verify-backend.mjs +297 -0
- package/test/verify-child-mislabel.mjs +135 -0
- package/test/verify-child-surface.mjs +321 -0
- package/test/verify-cli.mjs +197 -0
- package/test/verify-command-ux.mjs +100 -0
- package/test/verify-compat.mjs +32 -0
- package/test/verify-cross-host-notes.mjs +128 -0
- package/test/verify-delegate.mjs +161 -0
- package/test/verify-detect.mjs +151 -0
- package/test/verify-discovery.mjs +239 -0
- package/test/verify-done-nudge.mjs +238 -0
- package/test/verify-effective-prompt.mjs +98 -0
- package/test/verify-hc-matrix.mjs +246 -0
- package/test/verify-hc-poll.mjs +260 -0
- package/test/verify-host-docs.mjs +66 -0
- package/test/verify-host-impact.mjs +49 -0
- package/test/verify-ids.mjs +141 -0
- package/test/verify-launch.mjs +183 -0
- package/test/verify-message-routing.mjs +560 -0
- package/test/verify-messaging.mjs +303 -0
- package/test/verify-migration-notice.mjs +74 -0
- package/test/verify-multi-wait.mjs +42 -0
- package/test/verify-opencode-display.mjs +47 -0
- package/test/verify-opencode-fieldnotes.mjs +121 -0
- package/test/verify-opencode-notice.mjs +77 -0
- package/test/verify-opencode-nudge.mjs +116 -0
- package/test/verify-opencode-orphans.mjs +160 -0
- package/test/verify-opencode-surface.mjs +107 -0
- package/test/verify-packaging.mjs +82 -0
- package/test/verify-parent-surface.mjs +118 -0
- package/test/verify-phase0.mjs +95 -0
- package/test/verify-registry.mjs +124 -0
- package/test/verify-rename-migration.mjs +111 -0
- package/test/verify-rendering.mjs +379 -0
- package/test/verify-session-boundary.mjs +146 -0
- package/test/verify-settings.mjs +260 -0
- package/test/verify-stale-wait.mjs +339 -0
- package/test/verify-status-widget.mjs +377 -0
- package/test/verify-status.mjs +172 -0
- package/test/verify-task-completion.mjs +156 -0
- package/test/verify-task-failures.mjs +201 -0
- package/test/verify-task-mislabel.mjs +143 -0
- package/test/verify-task-registry.mjs +194 -0
- package/test/verify-task-watchers.mjs +217 -0
- package/test/verify-tool-schemas.mjs +120 -0
- package/test/verify-unseen-completions.mjs +1211 -0
- package/test/verify-watchers.mjs +181 -0
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Installation
|
|
2
|
+
|
|
3
|
+
Shepherd is one npm package — `@luminascale/shepherd` — with two host entry
|
|
4
|
+
points. Install the one that matches your host; neither host needs anything
|
|
5
|
+
from the other. You need [Herdr](https://github.com/herdrdev/herdr) and Node.js
|
|
6
|
+
22 or newer in either case.
|
|
7
|
+
|
|
8
|
+
- [Pi](#pi)
|
|
9
|
+
- [OpenCode](#opencode)
|
|
10
|
+
|
|
11
|
+
## Pi
|
|
12
|
+
|
|
13
|
+
Install with pi's package installer:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
pi install npm:@luminascale/shepherd
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Reload pi, then verify the extension is available with `/shepherd agents`. You
|
|
20
|
+
should see the bundled agent definitions, including `scout`, `planner`,
|
|
21
|
+
`worker`, and `reviewer`.
|
|
22
|
+
|
|
23
|
+
Pi uses the `/shepherd settings` menu for configuration (see
|
|
24
|
+
[Settings](../README.md#settings)), and pi's steer mode for completion notices.
|
|
25
|
+
No OpenCode setup is required.
|
|
26
|
+
|
|
27
|
+
## OpenCode
|
|
28
|
+
|
|
29
|
+
Add the package to your OpenCode plugin list:
|
|
30
|
+
|
|
31
|
+
```jsonc
|
|
32
|
+
// ~/.config/opencode/opencode.json (or the project-level .opencode/opencode.json)
|
|
33
|
+
{
|
|
34
|
+
"$schema": "https://opencode.ai/config.json",
|
|
35
|
+
"plugins": ["@luminascale/shepherd"]
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Restart OpenCode, then verify with `/shepherd agents`. The `shepherd_*` tools
|
|
40
|
+
and `/shepherd` command have the same names and semantics as in Pi. You do not
|
|
41
|
+
need to install pi to use Shepherd from OpenCode.
|
|
42
|
+
|
|
43
|
+
OpenCode differences:
|
|
44
|
+
|
|
45
|
+
- Settings are file-based: `~/.config/opencode/pi-shepherd/config.json` (user)
|
|
46
|
+
and `.shepherd/config.json` (project, with `"projectScope": true`). There is
|
|
47
|
+
no settings menu yet.
|
|
48
|
+
- Human `/shepherd …` command output is display-only — it renders in full and
|
|
49
|
+
returns control without starting an assistant turn.
|
|
50
|
+
- Completion notices arrive as normal parent-session messages that wake the
|
|
51
|
+
model.
|
|
52
|
+
- Fieldnotes are bound to the OpenCode session id and the session's working
|
|
53
|
+
directory, on the same `.shepherd/sessions/` layout Pi uses.
|
|
54
|
+
- After an OpenCode server restart, sheep keep running but their opaque ids are
|
|
55
|
+
lost. You get one display-only notice listing the orphaned sheep; use
|
|
56
|
+
`shepherd({ action: "reap" })` to close them safely (or respawn and close the
|
|
57
|
+
old panes). Fieldnotes and queued envelopes remain on disk until reaped.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
[Back to README](../README.md)
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Tool reference
|
|
2
|
+
|
|
3
|
+
pi-shepherd exposes these structured tools to the Shepherd. Lifecycle IDs are opaque, session-scoped handles; do not substitute Herdr pane IDs.
|
|
4
|
+
|
|
5
|
+
## Discovery and inspection
|
|
6
|
+
|
|
7
|
+
| Tool | Arguments | Purpose |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| `shepherd` | `action`: `agents`, `herd`, or `prune`; optional `agentScope`: `user`, `project`, or `both` | Discover definitions, list active agents, or remove stale registrations. |
|
|
10
|
+
| `shepherd_status` | `id`: agent ID | Inspect an agent without focusing its pane. For an open task the result carries the task ID, state, waiting age, pending request, recipient, and stale flag. |
|
|
11
|
+
| `shepherd_read` | `name`: agent name, agent ID, or pane ID; optional `lines`, `source` | Read recent terminal output for diagnostics. |
|
|
12
|
+
|
|
13
|
+
## Lifecycle
|
|
14
|
+
|
|
15
|
+
| Tool | Arguments | Purpose |
|
|
16
|
+
| --- | --- | --- |
|
|
17
|
+
| `shepherd_spawn` | `agent`, `label`; optional `placement`, `cwd` | Create an idle persistent agent. Placement is `pane_right`, `pane_down`, `tab`, or `workspace`; the default is a background tab. The model and requested thinking level come from the agent definition Markdown frontmatter. |
|
|
18
|
+
| `shepherd_delegate` | `target`: agent ID, `task`: description; optional `timeout` | Start a tracked task and return a task ID without waiting. One active task per agent. |
|
|
19
|
+
| `shepherd_message` | `target`: agent ID, `message`; optional `taskId`, `threadId`, `replyTo`, `expectsReply`, `delivery` | Send an asynchronous message (parent or peer). `expectsReply` opens a tracked reply request; the sender's task enters `waiting` until the reply. |
|
|
20
|
+
| `shepherd_prompt` | `id`: agent ID, `message`: one-turn message | **Deprecated** compatibility path. Ties completion to one child turn; prefer `shepherd_delegate` for tracked work. |
|
|
21
|
+
| `shepherd_watch` | `id`: task ID(s) (preferred) or legacy prompt ID(s) | Register a non-blocking completion watcher; completions arrive as steered notifications. An unwatched settlement surfaces at the next settle boundary or as one coalesced idle wake (identical wording on Herdr and hc; only opaque ids differ). |
|
|
22
|
+
| `shepherd_close` | `id`: agent ID | Close an owned agent, cancel its active task (and unresolved prompt), and clear pending requests. |
|
|
23
|
+
|
|
24
|
+
`shepherd_watch` is the explicit observation point: watching an already-settled task returns its result synchronously, and a pending watch delivers steered notifications as tasks settle. An unwatched settlement is still surfaced at the next settle boundary (one extra model request) while the Shepherd is busy, or as one coalesced idle wake; the notice names the `shepherd_watch` call that retrieves the full results. This holds on both backends: Herdr pane settles and hc terminal settles use identical notice wording. On hc, `shepherd_watch` registration and the status view drain first, and a 250 ms background poll keeps the registry fresh while work is open.
|
|
25
|
+
|
|
26
|
+
Example:
|
|
27
|
+
|
|
28
|
+
```text
|
|
29
|
+
shepherd_spawn({
|
|
30
|
+
agent: "worker",
|
|
31
|
+
label: "implementation",
|
|
32
|
+
placement: "pane_right",
|
|
33
|
+
cwd: "/path/to/project"
|
|
34
|
+
})
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`cwd` defaults to the Shepherd session. The model and requested thinking level come from the discovered agent definition; omission, `null`, or `default` inherit the Shepherd session's corresponding settings. Agent scope, project approval, and prompt-shaping options come from settings and the discovered definition rather than spawn arguments. Only panes created and recorded by pi-shepherd can be closed by the extension.
|
|
38
|
+
|
|
39
|
+
## Child-side tools
|
|
40
|
+
|
|
41
|
+
| Tool | Arguments | Purpose |
|
|
42
|
+
| --- | --- | --- |
|
|
43
|
+
| `shepherd_message` | `target`: `parent` or an owned agent ID, `message`; optional `taskId`, `threadId`, `replyTo`, `expectsReply`, `delivery` | A child sends an asynchronous message to the parent or a peer. `expectsReply` (to a parent task) opens the tracked reply request. |
|
|
44
|
+
| `shepherd_done` | `taskId`, `summary`; optional `ok`, `returnCode`, `error` | The only normal successful completion for a tracked task. Repeated calls are idempotent. |
|
|
45
|
+
|
|
46
|
+
A child that ends a turn with its tracked task still open feeds itself one reminder turn asking for `shepherd_done` (budget: one per task, `PI_SHEPHERD_DONE_NUDGES` overrides, `0` disables). Aborted or errored turns and turns waiting on an `expectsReply` request are never nudged; a task that survives every reminder is reported to the parent as a stalled completion.
|
|
47
|
+
|
|
48
|
+
## IDs at a glance
|
|
49
|
+
|
|
50
|
+
- **Agent id** – from `shepherd_spawn`; accepted by `delegate`, `message`, `status`, `close`.
|
|
51
|
+
- **Task id** – from `shepherd_delegate`; the tracked unit of work; accepted by `wait`, `watch`, `message` (`taskId`), and `shepherd_done`.
|
|
52
|
+
- **Prompt id** – from the deprecated `shepherd_prompt`; accepted by `wait` and `watch` (legacy path).
|
|
53
|
+
- **Message id** – returned by `shepherd_message`; used as `replyTo` by the agent answering the request.
|
|
54
|
+
|
|
55
|
+
None of these can be substituted with a Herdr pane ID; pane IDs are diagnostic targets for `shepherd_read` only.
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
# Manual test: ping-pong peer messaging
|
|
2
|
+
|
|
3
|
+
Use this smoke test to verify that two live Shepherd children can exchange a
|
|
4
|
+
correlated request and reply, resume the requester, and complete through
|
|
5
|
+
`shepherd_done`.
|
|
6
|
+
|
|
7
|
+
## Preconditions
|
|
8
|
+
|
|
9
|
+
- Run inside a live Herdr-managed Shepherd session.
|
|
10
|
+
- Reload the extension after changing the implementation.
|
|
11
|
+
- Use visible child panes (`pane_right` and `pane_down`) when possible.
|
|
12
|
+
- Use generous task deadlines; provider startup can take more than a minute.
|
|
13
|
+
- Do **not** use the removed blocking `shepherd_wait` operation.
|
|
14
|
+
|
|
15
|
+
## Procedure
|
|
16
|
+
|
|
17
|
+
### 1. Spawn the children
|
|
18
|
+
|
|
19
|
+
Spawn a planner and a worker, recording the opaque agent IDs returned by each
|
|
20
|
+
call:
|
|
21
|
+
|
|
22
|
+
```json
|
|
23
|
+
{"agent":"planner","label":"manual planner","placement":"pane_right"}
|
|
24
|
+
{"agent":"worker","label":"manual worker","placement":"pane_down"}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Do not substitute display names, Herdr pane IDs, or agent-kind names for the
|
|
28
|
+
returned lifecycle IDs.
|
|
29
|
+
|
|
30
|
+
### 2. Delegate the planner task
|
|
31
|
+
|
|
32
|
+
Use the planner's returned agent ID and a deadline of at least 10 minutes:
|
|
33
|
+
|
|
34
|
+
> Watch for one incoming peer request. When you receive it, reply to the exact
|
|
35
|
+
> `replyTo` using `shepherd_message`, omit `taskId` so it is inferred, then call
|
|
36
|
+
> `shepherd_done` with text `planner replied`. Do not use `shepherd_wait`.
|
|
37
|
+
|
|
38
|
+
Record the returned planner task ID.
|
|
39
|
+
|
|
40
|
+
### 3. Delegate the worker task
|
|
41
|
+
|
|
42
|
+
Use the worker's returned agent ID and put the planner's **actual opaque ID**
|
|
43
|
+
from Step 1 into the task text. Do not pass the planner's definition name,
|
|
44
|
+
display label, Herdr pane ID, or angle-bracket placeholder.
|
|
45
|
+
|
|
46
|
+
> Send planner a peer request using `shepherd_message`: set `target` to the
|
|
47
|
+
> planner spawn result's `id` field (the full opaque `shepherd-agent-...` string),
|
|
48
|
+
> message `Reply with exactly pong`, `expectsReply: true`. Wait for the reply
|
|
49
|
+
> using normal turns (never `shepherd_wait`), then call `shepherd_done` with text
|
|
50
|
+
> containing the reply. Do not call `shepherd_wait`.
|
|
51
|
+
|
|
52
|
+
Do not copy a documentation placeholder into the worker task. Before calling
|
|
53
|
+
`shepherd_delegate`, interpolate the exact ID copied from the planner's spawn
|
|
54
|
+
result into the task text. `planner`, `manual planner`, Herdr pane IDs, and
|
|
55
|
+
angle-bracket placeholders are invalid targets; the child tool rejects them.
|
|
56
|
+
|
|
57
|
+
Record the returned worker task ID.
|
|
58
|
+
|
|
59
|
+
### 4. Register non-blocking watchers
|
|
60
|
+
|
|
61
|
+
Register a watcher for both task IDs:
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{"id":["<planner task ID>","<worker task ID>"]}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The call must return immediately with both tasks in `pending`. Use
|
|
68
|
+
`shepherd_status` periodically to inspect intermediate state; do not block the
|
|
69
|
+
Shepherd turn waiting for completion.
|
|
70
|
+
|
|
71
|
+
Expected intermediate behavior:
|
|
72
|
+
|
|
73
|
+
- Planner may become idle while its task remains active until it receives the
|
|
74
|
+
request.
|
|
75
|
+
- Worker enters `waiting` after sending the request.
|
|
76
|
+
- Planner replies with `pong` using the request's exact `replyTo`; omitting
|
|
77
|
+
`taskId` exercises child-side task-ID inference.
|
|
78
|
+
- Worker resumes and calls `shepherd_done`.
|
|
79
|
+
|
|
80
|
+
If a watcher was already consumed or completed, register a fresh watcher using
|
|
81
|
+
the task ID. A watcher ID itself is not a valid `shepherd_watch` target.
|
|
82
|
+
|
|
83
|
+
### 5. Verify terminal results
|
|
84
|
+
|
|
85
|
+
Watch each task ID again, or use the follow-up completion notification. Both
|
|
86
|
+
results must contain:
|
|
87
|
+
|
|
88
|
+
```text
|
|
89
|
+
status: completed
|
|
90
|
+
ok: true
|
|
91
|
+
returnCode: 0
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
The worker result text should contain:
|
|
95
|
+
|
|
96
|
+
```text
|
|
97
|
+
Planner reply: pong
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The planner result should contain:
|
|
101
|
+
|
|
102
|
+
```text
|
|
103
|
+
planner replied
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### 6. Clean up
|
|
107
|
+
|
|
108
|
+
Only after both tasks are terminal, close both agents using their opaque agent
|
|
109
|
+
IDs. Do not close an agent while its watcher is still pending.
|
|
110
|
+
|
|
111
|
+
## Pass criteria
|
|
112
|
+
|
|
113
|
+
The test passes when:
|
|
114
|
+
|
|
115
|
+
1. Both children launch in visible panes.
|
|
116
|
+
2. The worker request reaches the planner.
|
|
117
|
+
3. The planner's correlated reply reaches the worker.
|
|
118
|
+
4. The worker resumes without a redundant acknowledgment step.
|
|
119
|
+
5. Both tasks settle as `completed` with return code `0`.
|
|
120
|
+
6. `shepherd_watch` reports both terminal results.
|
|
121
|
+
7. Both agents close cleanly afterward.
|
|
122
|
+
|
|
123
|
+
## Failure notes
|
|
124
|
+
|
|
125
|
+
- `Agent pane disappeared before the task completed` means the live lifecycle
|
|
126
|
+
test failed; do not count it as a pass even if a response later appears.
|
|
127
|
+
- A short deadline may expire during provider startup. Retry with 10 minutes or
|
|
128
|
+
more before diagnosing messaging behavior.
|
|
129
|
+
- If the child appears idle, inspect `shepherd_status`: idle process state does
|
|
130
|
+
not necessarily mean the tracked task is complete.
|
|
131
|
+
- If a reply is rejected, verify that `replyTo` is the exact incoming request
|
|
132
|
+
message ID and that any explicit `taskId` is the requester's task ID, not the
|
|
133
|
+
responder's task ID.
|
|
134
|
+
- The large `artifactSession` object in a watcher result includes historical
|
|
135
|
+
session artifacts. Use the top-level task result for current status.
|
|
136
|
+
|
|
137
|
+
## Recorded successful run
|
|
138
|
+
|
|
139
|
+
The reloaded-extension run on 2026-09-01 (steered watcher delivery, issue #10
|
|
140
|
+
fix) succeeded with:
|
|
141
|
+
|
|
142
|
+
- Planner result: `completed`, `ok: true`, `returnCode: 0`, `planner replied`
|
|
143
|
+
- Worker result: `completed`, `ok: true`, `returnCode: 0`, `received reply: pong`
|
|
144
|
+
- Completion observation: both watcher completions were delivered as steered
|
|
145
|
+
follow-ups **mid-turn**, before any cleanup; the combined watcher settled
|
|
146
|
+
both tasks before the agents were closed
|
|
147
|
+
- Cleanup: both agents closed after terminal completion
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
# pi-shepherd — Task-Specific Agent Labels Plan
|
|
2
|
+
|
|
3
|
+
## Goal
|
|
4
|
+
|
|
5
|
+
Give each spawned agent an optional, human-facing task label while retaining the
|
|
6
|
+
opaque lifecycle ID as the authoritative identifier used by code and lifecycle
|
|
7
|
+
calls.
|
|
8
|
+
|
|
9
|
+
Example:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
shepherd_spawn({ agent: "reviewer", label: "code review" })
|
|
13
|
+
→ reviewer: code review
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Proposed semantics
|
|
17
|
+
|
|
18
|
+
- `agent` remains the discovered agent definition name, such as `reviewer`.
|
|
19
|
+
- `label` is a short, task-specific instance label selected by the calling
|
|
20
|
+
agent.
|
|
21
|
+
- `id` remains the unique lifecycle handle used by `prompt`, `wait`, `status`,
|
|
22
|
+
and `close`.
|
|
23
|
+
- No automatic numbering scheme is introduced.
|
|
24
|
+
- An unlabeled spawn has an empty label and is displayed using its agent type
|
|
25
|
+
alone everywhere, including the Herdr tab, pane, or workspace name:
|
|
26
|
+
|
|
27
|
+
```text
|
|
28
|
+
/shepherd spawn reviewer
|
|
29
|
+
→ reviewer
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The display-name rule is intentionally simple: use `<agent>: <label>` when a
|
|
33
|
+
non-empty label is present; otherwise use `<agent>` unchanged. In other words,
|
|
34
|
+
an unlabeled user-created reviewer should produce a Herdr name of `reviewer`,
|
|
35
|
+
not `reviewer:`, `reviewer-`, or an automatically numbered variant.
|
|
36
|
+
|
|
37
|
+
- A labeled spawn combines the agent name and label for human-facing output:
|
|
38
|
+
|
|
39
|
+
```text
|
|
40
|
+
reviewer + code review → reviewer: code review
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The model-facing `shepherd_spawn` input requires a label so every spawned
|
|
44
|
+
instance has a short, task-specific human identifier. Tool guidance should make
|
|
45
|
+
providing that label explicit. The label is separate from the discovered agent
|
|
46
|
+
name and is validated for safe display. The human `/shepherd spawn reviewer`
|
|
47
|
+
command remains valid without a label and passes an empty label through
|
|
48
|
+
unchanged. A human can provide one explicitly with:
|
|
49
|
+
|
|
50
|
+
```text
|
|
51
|
+
/shepherd spawn reviewer --label "code review"
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Handle shape
|
|
55
|
+
|
|
56
|
+
The resolved handle may represent an empty label explicitly:
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
{
|
|
60
|
+
id: "shepherd-agent-...",
|
|
61
|
+
agent: "reviewer",
|
|
62
|
+
label: ""
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The friendly display name is derived rather than stored separately:
|
|
67
|
+
|
|
68
|
+
```text
|
|
69
|
+
label present → reviewer: code review
|
|
70
|
+
label empty → reviewer
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
This can be implemented conceptually as a presence check: if `label` is null,
|
|
74
|
+
undefined, or empty after trimming, return the agent type; otherwise return the
|
|
75
|
+
agent type, separator, and label.
|
|
76
|
+
|
|
77
|
+
Use the same representation for the user-visible tool call/result, the herd
|
|
78
|
+
widget, and the Herdr pane, tab, or workspace label. The recommended format is
|
|
79
|
+
`<agent>: <label>` because the colon clearly separates the role from the
|
|
80
|
+
human-readable task description. A hyphenated form such as
|
|
81
|
+
`reviewer-code-review` is more compact but looks like a machine slug and makes
|
|
82
|
+
the boundary less obvious.
|
|
83
|
+
|
|
84
|
+
This avoids storing redundant `displayName` state and keeps the definition name,
|
|
85
|
+
instance label, and lifecycle identity distinct.
|
|
86
|
+
|
|
87
|
+
## Identity and lookup
|
|
88
|
+
|
|
89
|
+
The label is for recognition and presentation in the user-facing tool call and
|
|
90
|
+
result, the herd widget, Herdr labels, status, and diagnostics. The TUI should
|
|
91
|
+
show the derived representation instead of exposing the long opaque ID in those
|
|
92
|
+
places.
|
|
93
|
+
|
|
94
|
+
This is a presentation change, not a protocol change. The underlying tool
|
|
95
|
+
arguments and lifecycle registry continue to use the opaque ID so `prompt`,
|
|
96
|
+
`wait`, `status`, and `close` remain unambiguous. Tool results may retain the ID
|
|
97
|
+
for the parent model while `renderCall`/`renderResult` hide it from the user.
|
|
98
|
+
Changing the actual tool protocol to accept only labels is out of scope.
|
|
99
|
+
|
|
100
|
+
Duplicate labels do not change lifecycle identity. Empty labels may be
|
|
101
|
+
repeated, so multiple unlabeled agents can exist as `reviewer`. Non-empty labels
|
|
102
|
+
must be unique for the complete display name within the parent session; reject a
|
|
103
|
+
duplicate rather than silently suffixing it. A label shared by different agent
|
|
104
|
+
types is valid because the complete display names differ:
|
|
105
|
+
|
|
106
|
+
```text
|
|
107
|
+
reviewer: code review ✅
|
|
108
|
+
reviewer: api review ✅
|
|
109
|
+
reviewer: code review ❌ duplicate
|
|
110
|
+
scout: code review ✅
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Labels are not accepted as lifecycle IDs. Lifecycle operations continue to
|
|
114
|
+
resolve agents exclusively by opaque ID.
|
|
115
|
+
|
|
116
|
+
## Validation
|
|
117
|
+
|
|
118
|
+
Because `label` is a human-facing label rather than a machine slug, preserve
|
|
119
|
+
readable spaces instead of forcing a hyphenated form. Apply these rules:
|
|
120
|
+
|
|
121
|
+
- trim leading and trailing whitespace;
|
|
122
|
+
- treat an empty-after-trimming value as no label;
|
|
123
|
+
- reject control characters and newlines;
|
|
124
|
+
- allow letters, numbers, spaces, `_`, `-`, and `.`;
|
|
125
|
+
- reject `:` because it is the role/label separator;
|
|
126
|
+
- preserve the user's casing; and
|
|
127
|
+
- limit the label to 64 characters.
|
|
128
|
+
|
|
129
|
+
The label must not be confused with the discovered agent name or a Herdr pane
|
|
130
|
+
ID. Any machine-safe value needed for temporary files or launch arguments should
|
|
131
|
+
be derived separately and should not become the user-facing label.
|
|
132
|
+
|
|
133
|
+
## Implementation areas
|
|
134
|
+
|
|
135
|
+
- Extend spawn arguments and `AgentHandle` with `label`, keeping it separate
|
|
136
|
+
from the discovered agent name.
|
|
137
|
+
- Resolve the optional input to an empty label when omitted; do not maintain a
|
|
138
|
+
per-agent counter or generate labels such as `reviewer-01`.
|
|
139
|
+
- Propagate the label to the user-facing tool call/result, herd widget, and
|
|
140
|
+
Herdr tab/pane/workspace presentation without changing agent discovery or
|
|
141
|
+
launch semantics.
|
|
142
|
+
- Derive the friendly display name at presentation boundaries instead of adding
|
|
143
|
+
a stored `displayName` field.
|
|
144
|
+
- Keep the opaque ID in the underlying model-facing lifecycle protocol even when
|
|
145
|
+
the TUI renders the label instead.
|
|
146
|
+
- Update tool descriptions and prompt guidance so calling agents normally
|
|
147
|
+
provide a short task-specific label.
|
|
148
|
+
- Update `/shepherd` parsing and help text while preserving unlabeled human
|
|
149
|
+
commands.
|
|
150
|
+
- Update README examples and documentation.
|
|
151
|
+
|
|
152
|
+
## Phased implementation plan
|
|
153
|
+
|
|
154
|
+
### Phase 1 — Lock down the contract
|
|
155
|
+
|
|
156
|
+
- Use `label` as the public field name; it is optional at the spawn boundary.
|
|
157
|
+
- Use the resolved representation where `agent` is the agent definition name,
|
|
158
|
+
`label` is an empty or non-empty task label, and `id` remains the opaque
|
|
159
|
+
lifecycle identifier.
|
|
160
|
+
- Define the display formatter once:
|
|
161
|
+
|
|
162
|
+
```text
|
|
163
|
+
non-empty label → <agent>: <label>
|
|
164
|
+
empty label → <agent>
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
- Apply the decided validation rules: trim whitespace, reject control
|
|
168
|
+
characters/newlines and `:`, allow letters, numbers, spaces, `_`, `-`, and `.`,
|
|
169
|
+
preserve case, and limit labels to 64 characters.
|
|
170
|
+
- Permit repeated empty labels, but reject duplicate non-empty complete display
|
|
171
|
+
names within the parent session. Do not add automatic numbering.
|
|
172
|
+
- Use `/shepherd spawn reviewer --label "code review"` as the documented human
|
|
173
|
+
command syntax; the label remains optional.
|
|
174
|
+
|
|
175
|
+
### Phase 2 — Extend the lifecycle data model
|
|
176
|
+
|
|
177
|
+
- Add `label` to the spawn input and resolved `AgentHandle`.
|
|
178
|
+
- Resolve omitted, null, or whitespace-only input to an empty label.
|
|
179
|
+
- Preserve the existing opaque-ID registry and lookup behavior.
|
|
180
|
+
- Ensure labels are assigned consistently before the handle is returned and are
|
|
181
|
+
available to status, prompt results, and close-related output.
|
|
182
|
+
- Add registry-level tests for labeled and unlabeled handles.
|
|
183
|
+
|
|
184
|
+
### Phase 3 — Add shared presentation formatting
|
|
185
|
+
|
|
186
|
+
- Add one shared formatter for the friendly agent name rather than duplicating
|
|
187
|
+
string concatenation across adapters.
|
|
188
|
+
- Verify that an empty label returns exactly the agent type, with no separator,
|
|
189
|
+
suffix, or generated number.
|
|
190
|
+
- Verify that a labeled instance returns the chosen `<agent>: <label>` form.
|
|
191
|
+
- Keep the formatter presentation-only; it must not become a lifecycle lookup
|
|
192
|
+
key or replace the opaque ID.
|
|
193
|
+
|
|
194
|
+
### Phase 4 — Update spawn surfaces and Herdr presentation
|
|
195
|
+
|
|
196
|
+
- Extend model-facing `shepherd_spawn` schema, descriptions, and guidance so
|
|
197
|
+
calling agents normally provide a short task-specific label.
|
|
198
|
+
- Keep `/shepherd spawn reviewer` valid without a label and pass the empty label
|
|
199
|
+
through unchanged.
|
|
200
|
+
- Use the derived friendly name for Herdr tab, pane, and workspace labels.
|
|
201
|
+
- Use the agent type alone for an unlabeled user-created instance, such as a tab
|
|
202
|
+
named `reviewer`.
|
|
203
|
+
- Preserve the discovered agent name for discovery and launch semantics; do not
|
|
204
|
+
use the composite display name to resolve agent definitions.
|
|
205
|
+
- Ensure background placement and pane ownership behavior remain unchanged.
|
|
206
|
+
|
|
207
|
+
### Phase 5 — Update user-facing tool and widget rendering
|
|
208
|
+
|
|
209
|
+
- Render the friendly name instead of the long opaque ID in user-facing tool
|
|
210
|
+
calls and results.
|
|
211
|
+
- Update the herd/status widget to show the same friendly name consistently.
|
|
212
|
+
- Retain the opaque ID in the underlying tool result data or model-facing text
|
|
213
|
+
wherever it is needed for follow-up lifecycle calls.
|
|
214
|
+
- Verify that user-facing rendering does not make labels usable accidentally as
|
|
215
|
+
lifecycle IDs.
|
|
216
|
+
|
|
217
|
+
### Phase 6 — Documentation and compatibility
|
|
218
|
+
|
|
219
|
+
- Update the README, lifecycle examples, command help, and tool guidance.
|
|
220
|
+
- Document labeled and unlabeled spawn behavior, including the exact Herdr name
|
|
221
|
+
for an unlabeled spawn.
|
|
222
|
+
- Document that labels are for human recognition while IDs remain authoritative.
|
|
223
|
+
- Review diagnostics, fieldnotes, and persisted metadata for places where the
|
|
224
|
+
friendly name should be shown without changing stored identity semantics.
|
|
225
|
+
|
|
226
|
+
### Phase 7 — Verification and live smoke testing
|
|
227
|
+
|
|
228
|
+
- Run all automated schema, CLI, registry, launch, widget, and lifecycle tests.
|
|
229
|
+
- Run a live Herdr check for a labeled spawn and verify the tab/pane/workspace
|
|
230
|
+
name.
|
|
231
|
+
- Run a live Herdr check for `/shepherd spawn reviewer` and verify the name is
|
|
232
|
+
exactly `reviewer`.
|
|
233
|
+
- Verify prompt, wait, status, and close still work using the opaque ID.
|
|
234
|
+
- Verify multiple labels, repeated empty labels, and rejection of duplicate
|
|
235
|
+
non-empty complete display names.
|
|
236
|
+
- Verify no numbering state or generated labels exist.
|
|
237
|
+
|
|
238
|
+
## Verification
|
|
239
|
+
|
|
240
|
+
Add coverage for:
|
|
241
|
+
|
|
242
|
+
- schema acceptance of labeled and unlabeled spawns;
|
|
243
|
+
- `/shepherd spawn reviewer` producing an empty label;
|
|
244
|
+
- a supplied label producing the expected friendly name (`reviewer: code review`);
|
|
245
|
+
- no automatic numbering or counter state;
|
|
246
|
+
- label normalization and validation;
|
|
247
|
+
- repeated empty labels and duplicate non-empty display-name rejection;
|
|
248
|
+
- propagation to tool-call rendering, the herd widget, and Herdr presentation;
|
|
249
|
+
- user-facing rendering hiding the opaque ID while model-facing results retain
|
|
250
|
+
whatever ID data is required for follow-up calls; and
|
|
251
|
+
- lifecycle calls continuing to use the opaque ID.
|
|
252
|
+
|
|
253
|
+
Run the existing test suite with:
|
|
254
|
+
|
|
255
|
+
```bash
|
|
256
|
+
npm test
|
|
257
|
+
```
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# pi-shepherd — Implementation Plan
|
|
2
|
+
|
|
3
|
+
pi-shepherd is a Herdr-native pi extension for explicit agent lifecycle
|
|
4
|
+
orchestration **and asynchronous tracked-task delegation**. There is no
|
|
5
|
+
subprocess fallback; coordination between agents happens over a parent-
|
|
6
|
+
mediated message broker.
|
|
7
|
+
|
|
8
|
+
## Architecture
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
index.ts extension entry and /shepherd command
|
|
12
|
+
src/core/discovery.ts fresh agent discovery and frontmatter parsing
|
|
13
|
+
src/core/orchestration.ts opaque serializable handles and in-memory registries
|
|
14
|
+
src/core/lifecycle.ts spawn, prompt, wait, status, and close primitives
|
|
15
|
+
src/core/herdr.ts Herdr CLI, launch, pane, and ownership helpers
|
|
16
|
+
src/core/artifact-sessions.ts durable parent-bound session, note, and fieldnotes persistence
|
|
17
|
+
src/extension/shepherd.ts umbrella control tool plus separate lifecycle tools
|
|
18
|
+
src/extension/shepherd-done.ts in-tab completion extension
|
|
19
|
+
.agents/agents/ bundled pi-format and shared-format agents
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Public lifecycle API
|
|
23
|
+
|
|
24
|
+
- `shepherd_spawn({ agent, ...options })` creates an idle persistent agent and
|
|
25
|
+
submits no task.
|
|
26
|
+
- `shepherd_delegate({ target, task, timeout? })` starts a **tracked task** on
|
|
27
|
+
an agent and returns a task id without waiting. Delegation is the preferred
|
|
28
|
+
way to assign work that may need to survive peer replies.
|
|
29
|
+
- `shepherd_message({ target, message, ... })` sends an asynchronous,
|
|
30
|
+
parent-mediated message to the parent or to an owned agent. With
|
|
31
|
+
`expectsReply` it opens a tracked reply request: the sender's task enters
|
|
32
|
+
`waiting` (its pi process may go idle) until a matching reply, a
|
|
33
|
+
`shepherd_done`, or the reply deadline.
|
|
34
|
+
- `shepherd_done` (child-side) is the only normal successful completion
|
|
35
|
+
signal for a tracked task; idle/`agent_end`/`agent_settled` never settle a
|
|
36
|
+
task.
|
|
37
|
+
- `shepherd_watch({ id })` compatibility wait: task ids (preferred) or legacy
|
|
38
|
+
prompt ids; a wait timeout bounds the wait only.
|
|
39
|
+
- `shepherd_watch({ id })` non-blocking task-watcher; completions arrive as
|
|
40
|
+
follow-ups.
|
|
41
|
+
- `shepherd_status({ id })` performs non-mutating inspection; reports
|
|
42
|
+
process state and task state independently.
|
|
43
|
+
- `shepherd_close({ id })` explicitly terminates an owned agent, cancels its
|
|
44
|
+
active tracked task (and unresolved prompt), and clears pending requests.
|
|
45
|
+
- `shepherd_read({ name, lines?, source? })` reads recent terminal output.
|
|
46
|
+
- `shepherd_prompt({ id, message })` is a **deprecated** one-turn
|
|
47
|
+
compatibility path (see docs/guides/tool-reference.md).
|
|
48
|
+
|
|
49
|
+
The umbrella `shepherd` control tool handles `agents`, `herd`, and `prune` and
|
|
50
|
+
contains the shared lifecycle and fieldnotes guidance. The `/shepherd` command
|
|
51
|
+
supports the human-facing `agents`, `herd`, `spawn`, `status`, `read`, and
|
|
52
|
+
`settings` actions.
|
|
53
|
+
|
|
54
|
+
Parallel work and chains are caller composition, not first-class workflow
|
|
55
|
+
modes. A one-shot tracked operation is
|
|
56
|
+
`shepherd_spawn + shepherd_delegate + shepherd_watch + shepherd_close`.
|
|
57
|
+
|
|
58
|
+
## Completed implementation
|
|
59
|
+
|
|
60
|
+
- Agent, task, prompt, and message references are opaque session-scoped ids exposed in tool arguments and result text. Full handle objects remain internal registry state.
|
|
61
|
+
- Tracked tasks are independent of Herdr process state: `running`,
|
|
62
|
+
`waiting`, and the terminal states (`completed`, `blocked`, `failed`,
|
|
63
|
+
`cancelled`, `timed_out`) live in the lifecycle registry. Only
|
|
64
|
+
`shepherd_done` (or explicit failure/cancellation/timeout) settles a task;
|
|
65
|
+
a child's idle or `agent_end` never does.
|
|
66
|
+
- Cross-agent communication is parent-mediated: the parent broker routes
|
|
67
|
+
envelopes between owned agents with provenance (sender, thread, replyTo)
|
|
68
|
+
and delivers them as queued follow-ups (`followUp`) or urgent input
|
|
69
|
+
(`steer`). Request/reply correlation uses `replyTo` == pending reply
|
|
70
|
+
`messageId`; one outstanding request per task is the initial policy.
|
|
71
|
+
- Stale-wait reminders are informational only: at most one per waiting
|
|
72
|
+
episode, `triggerTurn: false`, and the reply deadline remains the only
|
|
73
|
+
mechanism that settles a stale wait to `blocked`.
|
|
74
|
+
- Registries enforce one unresolved prompt per agent, idempotent settlement, and
|
|
75
|
+
deterministic cancellation.
|
|
76
|
+
- Persistent Herdr tabs launch pi with discovered system prompt, tools, model,
|
|
77
|
+
cwd, and no initial user message.
|
|
78
|
+
- Prompt submission is non-blocking and requires Herdr detection.
|
|
79
|
+
- Wait ignores pre-submit idle state, tracks post-submit transitions, returns
|
|
80
|
+
structured per-prompt results, and supports concurrent multi-wait.
|
|
81
|
+
- Status and close use lifecycle ids and retain the created-pane ownership invariant.
|
|
82
|
+
- Project agent scope remains opt-in and trust-gated.
|
|
83
|
+
- Legacy `delegate`, workflow modes, and `subagent.ts` have been removed.
|
|
84
|
+
- When enabled, durable notes are allocated once per parent pi session/project
|
|
85
|
+
binding, with one fieldnotes collection and distinct per-prompt note files.
|
|
86
|
+
- Fieldnotes can be disabled in settings; the setting is snapshotted when a
|
|
87
|
+
parent pi session starts.
|
|
88
|
+
- README and focused registry/multi-wait tests document and verify the API.
|
|
89
|
+
|
|
90
|
+
## Verification
|
|
91
|
+
|
|
92
|
+
Run:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
npm test
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Live Herdr checks cover idle spawn, non-blocking prompt, wait/result recovery,
|
|
99
|
+
parallel multi-wait, iterative prompting, cancellation on close, focus
|
|
100
|
+
preservation, and ownership protection.
|
|
101
|
+
|
|
102
|
+
## Security invariants
|
|
103
|
+
|
|
104
|
+
- User agent discovery is the default.
|
|
105
|
+
- Project-controlled agent definitions require explicit scope and confirmation.
|
|
106
|
+
- Agents have the host user's normal pi tool permissions.
|
|
107
|
+
- Background placement uses `--no-focus`.
|
|
108
|
+
- Only panes recorded in the pi-shepherd created-pane registry may be closed.
|
|
109
|
+
- Launch/session resources are removed only after the child pane is gone.
|
|
110
|
+
- Note sessions are retained and never automatically cleaned up.
|