@luminascale/shepherd 0.0.0-stage → 0.6.0
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 +424 -2
- package/docs/README.md +25 -0
- package/docs/guides/agent-definitions.md +42 -0
- package/docs/guides/diagnostics.md +199 -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 +599 -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 +259 -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 +35 -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 +69 -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,139 @@
|
|
|
1
|
+
# Implementation Plan: Non-blocking Shepherd Prompt Watchers
|
|
2
|
+
|
|
3
|
+
This plan implements `spec.md` by adding a background completion observer and a
|
|
4
|
+
parent notification bridge. The existing `shepherd_wait` implementation and
|
|
5
|
+
public behavior remain unchanged.
|
|
6
|
+
|
|
7
|
+
## Target architecture
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
shepherd_prompt
|
|
11
|
+
│
|
|
12
|
+
▼
|
|
13
|
+
existing PromptRecord
|
|
14
|
+
│
|
|
15
|
+
├── shepherd_wait (existing blocking consumer)
|
|
16
|
+
│
|
|
17
|
+
└── shepherd_watch
|
|
18
|
+
│
|
|
19
|
+
▼
|
|
20
|
+
watcher registry + background monitor
|
|
21
|
+
│
|
|
22
|
+
├── settle existing prompt result
|
|
23
|
+
├── buffer/deduplicate completion
|
|
24
|
+
└── notify parent via callback
|
|
25
|
+
│
|
|
26
|
+
▼
|
|
27
|
+
pi.sendMessage
|
|
28
|
+
followUp + triggerTurn
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Design decisions
|
|
32
|
+
|
|
33
|
+
1. **Prompt-level identity** — watchers accept prompt ids, not agent ids. A
|
|
34
|
+
persistent agent can receive multiple prompts, so an agent-level watcher
|
|
35
|
+
would be ambiguous.
|
|
36
|
+
2. **Immediate registration** — `shepherd_watch` returns an acknowledgment and
|
|
37
|
+
never awaits child completion. The eventual completion is a custom parent
|
|
38
|
+
message, not a delayed return from the original tool call.
|
|
39
|
+
3. **Result shape** — the registration response includes `watcherId`, the
|
|
40
|
+
normalized prompt ids, pending ids, and already-completed structured results.
|
|
41
|
+
Completion notifications include prompt id, agent id, status, return code,
|
|
42
|
+
error, and the last assistant message.
|
|
43
|
+
4. **One-shot watchers** — each watched prompt is delivered once per watcher.
|
|
44
|
+
A watcher automatically finishes when all its prompts settle; there is no
|
|
45
|
+
separate cancellation operation for watcher delivery.
|
|
46
|
+
5. **Existing wait remains authoritative for its callers** — do not modify the
|
|
47
|
+
`shepherd_wait` tool, its schemas, its public result format, or its current
|
|
48
|
+
timeout/cancellation semantics. Watcher observation may settle the shared
|
|
49
|
+
prompt record idempotently so a simultaneous wait sees the same result.
|
|
50
|
+
6. **Narrow notification boundary** — core code receives an injected callback
|
|
51
|
+
for parent notifications. It does not import or access a global `pi` object.
|
|
52
|
+
7. **Follow-up delivery** — use a custom Shepherd message with follow-up
|
|
53
|
+
delivery. Queue while the parent is active and trigger a new turn when the
|
|
54
|
+
parent is idle.
|
|
55
|
+
8. **Burst coalescing** — report individual completions as they arrive, but
|
|
56
|
+
coalesce completions observed in a short window into one parent message when
|
|
57
|
+
possible.
|
|
58
|
+
|
|
59
|
+
## Phase 1 — Define watcher state and protocol
|
|
60
|
+
|
|
61
|
+
Add internal watcher types and registry operations without changing existing
|
|
62
|
+
wait types:
|
|
63
|
+
|
|
64
|
+
- watcher handle and watcher result types;
|
|
65
|
+
- watcher records with prompt ids, delivery state, and lifecycle state;
|
|
66
|
+
- prompt-to-watcher indexes;
|
|
67
|
+
- registration, completion, and automatic cleanup operations;
|
|
68
|
+
- normalization and validation for one id or an array of ids.
|
|
69
|
+
|
|
70
|
+
The existing prompt result type should be reused for completed entries wherever
|
|
71
|
+
possible. No Herdr pane id should be part of the public watcher protocol.
|
|
72
|
+
|
|
73
|
+
## Phase 2 — Add background observation
|
|
74
|
+
|
|
75
|
+
Implement a monitor that starts only when a watcher is registered:
|
|
76
|
+
|
|
77
|
+
- inspect all active watched prompts from one parent session;
|
|
78
|
+
- use the existing completion sidecar, state sequence, result file, and
|
|
79
|
+
provider-error detection rules;
|
|
80
|
+
- handle prompts already settled before registration;
|
|
81
|
+
- settle the existing prompt record exactly once;
|
|
82
|
+
- notify watcher records after settlement;
|
|
83
|
+
- deduplicate polling and completion delivery;
|
|
84
|
+
- stop the monitor when no active watched prompts remain.
|
|
85
|
+
|
|
86
|
+
The monitor must not leave the `shepherd_watch` tool execution pending. It may
|
|
87
|
+
share low-level read helpers with wait, but must not change wait's code path or
|
|
88
|
+
external semantics.
|
|
89
|
+
|
|
90
|
+
## Phase 3 — Add parent notification bridge
|
|
91
|
+
|
|
92
|
+
At tool registration time, provide the watcher service with a narrow callback
|
|
93
|
+
that sends a custom message through the current parent `ExtensionAPI`:
|
|
94
|
+
|
|
95
|
+
- create a structured Shepherd completion message;
|
|
96
|
+
- include the watcher id, prompt id(s), agent id(s), labels, statuses, return
|
|
97
|
+
codes, errors, and final assistant text;
|
|
98
|
+
- use follow-up delivery so an active parent turn is not interrupted;
|
|
99
|
+
- trigger a parent turn when the parent is idle;
|
|
100
|
+
- coalesce close-together completions;
|
|
101
|
+
- suppress new turns during shutdown/reload.
|
|
102
|
+
|
|
103
|
+
The core service should continue buffering results even if message delivery is
|
|
104
|
+
unavailable or fails. Message delivery failure must not corrupt prompt
|
|
105
|
+
settlement or fieldnote finalization.
|
|
106
|
+
|
|
107
|
+
## Phase 4 — Register tools and integrate guidance
|
|
108
|
+
|
|
109
|
+
Add `shepherd_watch` to the extension surface:
|
|
110
|
+
|
|
111
|
+
- declare all tool metadata directly in each `pi.registerTool` call;
|
|
112
|
+
- use the existing public result formatting and opaque-id conventions;
|
|
113
|
+
- add watcher descriptions and guidance to the umbrella tool;
|
|
114
|
+
- keep the array input shape aligned with `shepherd_wait`;
|
|
115
|
+
- expose registration and completion details without exposing raw Herdr ids.
|
|
116
|
+
|
|
117
|
+
Update README/lifecycle examples to show both explicit blocking waits and
|
|
118
|
+
non-blocking watch-based workflows.
|
|
119
|
+
|
|
120
|
+
## Phase 5 — Resource and session boundaries
|
|
121
|
+
|
|
122
|
+
Ensure watcher state is bounded to the parent extension session:
|
|
123
|
+
|
|
124
|
+
- clean active monitors at `session_shutdown`;
|
|
125
|
+
- remove watcher registrations on reload/session replacement;
|
|
126
|
+
- do not close child panes as part of watcher completion;
|
|
127
|
+
- retain existing child result files and fieldnotes;
|
|
128
|
+
- avoid duplicate monitors after reload or repeated registration;
|
|
129
|
+
- ensure completion remains available to `shepherd_wait` after notification delivery.
|
|
130
|
+
|
|
131
|
+
## Phase 6 — Verification and rollout
|
|
132
|
+
|
|
133
|
+
Add focused registry, notification, and tool-schema tests, then run the full
|
|
134
|
+
suite. Perform live Herdr checks with one and multiple prompts, including
|
|
135
|
+
completion while the parent is active and completion while it is idle.
|
|
136
|
+
|
|
137
|
+
After all checks pass, update the implementation status in the specification
|
|
138
|
+
and add a completed-watcher entry to the repository's documentation index if
|
|
139
|
+
one exists.
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
# Non-blocking Shepherd Prompt Watchers
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Implemented. Focused registry, notification, schema, and lifecycle tests pass;
|
|
6
|
+
live Herdr verification remains an operational follow-up.
|
|
7
|
+
|
|
8
|
+
## Summary
|
|
9
|
+
|
|
10
|
+
Add an asynchronous watcher to pi-shepherd for prompt completions. A watcher
|
|
11
|
+
registers interest in one or more existing prompt ids and returns immediately.
|
|
12
|
+
When a watched prompt settles, Shepherd stores the result and sends a custom
|
|
13
|
+
follow-up message to the parent pi session so the parent model can process the
|
|
14
|
+
completion in a later turn.
|
|
15
|
+
|
|
16
|
+
The watcher is an additional synchronization mechanism. It does not replace,
|
|
17
|
+
modify, or change the public behavior of `shepherd_wait`.
|
|
18
|
+
|
|
19
|
+
The intended workflow is:
|
|
20
|
+
|
|
21
|
+
```text
|
|
22
|
+
spawn
|
|
23
|
+
→ prompt
|
|
24
|
+
→ watcher registration returns immediately
|
|
25
|
+
→ parent turn continues or ends
|
|
26
|
+
→ child completes
|
|
27
|
+
→ watcher records the result
|
|
28
|
+
→ watcher sends a custom follow-up message to the parent
|
|
29
|
+
→ parent model processes the completion
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Goals
|
|
33
|
+
|
|
34
|
+
- Allow the parent model to continue while child prompts run.
|
|
35
|
+
- Watch one prompt or an array of prompt ids.
|
|
36
|
+
- Report each completion with the exact prompt id and persistent agent id.
|
|
37
|
+
- Include the child agent's final assistant message in completion notifications.
|
|
38
|
+
- Handle prompts that finish before watcher registration without losing results.
|
|
39
|
+
- Preserve the existing `shepherd_wait` API and semantics.
|
|
40
|
+
- Make watcher completion idempotent and safe when `wait` is also polling.
|
|
41
|
+
- Keep watcher lifetime and notification delivery bounded to the parent session.
|
|
42
|
+
- Preserve existing fieldnote/artifact finalization through the prompt registry.
|
|
43
|
+
|
|
44
|
+
## Non-goals
|
|
45
|
+
|
|
46
|
+
- Do not replace or change `shepherd_wait`.
|
|
47
|
+
- Do not add workflow-specific `parallel`, `chain`, or fan-in modes.
|
|
48
|
+
- Do not watch by Herdr pane id or infer a prompt from an agent id.
|
|
49
|
+
- Do not make watcher registration block until a child completes.
|
|
50
|
+
- Do not use a synthetic user message for a Shepherd-generated notification.
|
|
51
|
+
- Do not automatically close agents when watched prompts complete.
|
|
52
|
+
- Do not make watcher notifications depend on the parent calling another
|
|
53
|
+
blocking tool.
|
|
54
|
+
|
|
55
|
+
## Terminology
|
|
56
|
+
|
|
57
|
+
### Prompt id
|
|
58
|
+
|
|
59
|
+
The opaque id returned by `shepherd_prompt`. A watcher observes a specific
|
|
60
|
+
prompt invocation, not all future work submitted to an agent.
|
|
61
|
+
|
|
62
|
+
### Watcher
|
|
63
|
+
|
|
64
|
+
A one-shot subscription associated with one or more prompt ids. It remains
|
|
65
|
+
active until all watched prompts settle or the parent session shuts down.
|
|
66
|
+
|
|
67
|
+
### Completion notification
|
|
68
|
+
|
|
69
|
+
A custom message injected into the parent pi session after one or more watched
|
|
70
|
+
prompts settle. It is not the return value of the original watcher tool call.
|
|
71
|
+
|
|
72
|
+
## Public API
|
|
73
|
+
|
|
74
|
+
### `shepherd_watch({ id })`
|
|
75
|
+
|
|
76
|
+
`id` accepts either one opaque prompt id or an array of opaque prompt ids. The
|
|
77
|
+
array behavior is completion-oriented rather than wait-oriented: prompts are
|
|
78
|
+
reported as they finish, not only after every prompt has completed.
|
|
79
|
+
|
|
80
|
+
Examples:
|
|
81
|
+
|
|
82
|
+
```text
|
|
83
|
+
shepherd_watch({ id: "shepherd-prompt-a" })
|
|
84
|
+
shepherd_watch({ id: ["shepherd-prompt-a", "shepherd-prompt-b"] })
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
The tool returns immediately with a registration acknowledgment. Its result
|
|
88
|
+
contains:
|
|
89
|
+
|
|
90
|
+
- `watcherId`: opaque watcher id;
|
|
91
|
+
- `promptIds`: normalized watched prompt ids;
|
|
92
|
+
- `pending`: prompt ids not yet settled;
|
|
93
|
+
- `completed`: results already available at registration time.
|
|
94
|
+
|
|
95
|
+
An already-completed prompt must appear in `completed` so a fast completion
|
|
96
|
+
cannot be lost between `prompt` and `watch`.
|
|
97
|
+
|
|
98
|
+
A representative result is:
|
|
99
|
+
|
|
100
|
+
```json
|
|
101
|
+
{
|
|
102
|
+
"watcherId": "shepherd-watch-...",
|
|
103
|
+
"promptIds": ["shepherd-prompt-a", "shepherd-prompt-b"],
|
|
104
|
+
"pending": ["shepherd-prompt-a"],
|
|
105
|
+
"completed": [
|
|
106
|
+
{
|
|
107
|
+
"promptId": "shepherd-prompt-b",
|
|
108
|
+
"agentId": "shepherd-agent-...",
|
|
109
|
+
"status": "done",
|
|
110
|
+
"ok": true,
|
|
111
|
+
"returnCode": 0,
|
|
112
|
+
"text": "The agent's last assistant message."
|
|
113
|
+
}
|
|
114
|
+
]
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
The public Shepherd tool result must continue to use the standard service
|
|
119
|
+
message, `call:`, `return:`, and `details:` structure.
|
|
120
|
+
|
|
121
|
+
## Completion notifications
|
|
122
|
+
|
|
123
|
+
When a watched prompt settles, Shepherd sends a custom message through the
|
|
124
|
+
parent extension using the equivalent of:
|
|
125
|
+
|
|
126
|
+
```text
|
|
127
|
+
pi.sendMessage(custom Shepherd completion message, {
|
|
128
|
+
deliverAs: "followUp",
|
|
129
|
+
triggerTurn: true
|
|
130
|
+
})
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
The notification must be queued as a follow-up rather than interrupting an
|
|
134
|
+
active parent tool chain. If the parent is idle, it should trigger a new model
|
|
135
|
+
turn. The message should be a custom Shepherd message, not a normal user
|
|
136
|
+
message.
|
|
137
|
+
|
|
138
|
+
Each notification includes:
|
|
139
|
+
|
|
140
|
+
- `watcherId`;
|
|
141
|
+
- `promptId`;
|
|
142
|
+
- `agentId`;
|
|
143
|
+
- agent name and label when available;
|
|
144
|
+
- terminal status;
|
|
145
|
+
- `ok` and process-style `returnCode`;
|
|
146
|
+
- error information for failed, blocked, timed-out, or cancelled prompts; and
|
|
147
|
+
- `text`, containing the last assistant message when available.
|
|
148
|
+
|
|
149
|
+
The prompt id is the primary correlation key because one persistent agent may
|
|
150
|
+
receive several prompts over its lifetime. Herdr pane ids must not be exposed
|
|
151
|
+
as watcher correlation ids.
|
|
152
|
+
|
|
153
|
+
For an array watcher, completions should be delivered independently as they
|
|
154
|
+
arrive. Completions occurring close together may be coalesced into one custom
|
|
155
|
+
message containing an array of completion results to avoid triggering one
|
|
156
|
+
parent turn per child. Coalesced completion arrays preserve the watcher's input
|
|
157
|
+
prompt order so their presentation is deterministic.
|
|
158
|
+
|
|
159
|
+
## Lifecycle and correctness
|
|
160
|
+
|
|
161
|
+
- A watcher is one-shot. Each watched prompt produces at most one notification
|
|
162
|
+
per watcher.
|
|
163
|
+
- Registering a watcher for an already-settled prompt returns that result in
|
|
164
|
+
the immediate `completed` collection and must not produce a duplicate event.
|
|
165
|
+
- Multiple watchers may observe the same prompt. Each watcher has independent
|
|
166
|
+
delivery state, while prompt settlement remains globally idempotent.
|
|
167
|
+
- A watcher may settle the existing prompt record using the existing lifecycle
|
|
168
|
+
settlement path. If `shepherd_wait` is also active, its promise resolves with
|
|
169
|
+
the same result and duplicate settlement is ignored.
|
|
170
|
+
- The final result remains stored in the prompt registry. Notifications are a
|
|
171
|
+
delivery mechanism, not the only copy of the result.
|
|
172
|
+
- Existing completion signals, state transitions, result files, and provider
|
|
173
|
+
error handling should be reused. The watcher must apply the same safeguards
|
|
174
|
+
against pre-submit idle state and stale completion signals.
|
|
175
|
+
- Successful, failed, blocked, timed-out, and close-cancelled prompts all
|
|
176
|
+
produce terminal watcher results.
|
|
177
|
+
- Watchers and monitor timers are released after completion or parent session
|
|
178
|
+
shutdown.
|
|
179
|
+
- The watcher must not delete child session files, fieldnotes, or other
|
|
180
|
+
existing retained lifecycle resources.
|
|
181
|
+
- When the parent is shutting down or reloading, no new parent turn should be
|
|
182
|
+
triggered. Active watcher resources must still be cleaned up safely.
|
|
183
|
+
|
|
184
|
+
## Integration boundaries
|
|
185
|
+
|
|
186
|
+
The watcher service may live in the core lifecycle/orchestration layer, but it
|
|
187
|
+
must not directly depend on a global pi singleton. The extension registration
|
|
188
|
+
layer should provide a narrow notification callback backed by `pi.sendMessage`.
|
|
189
|
+
|
|
190
|
+
The watcher may use the existing `LifecycleRegistry` prompt records and
|
|
191
|
+
settlement callbacks. It must not repurpose `LifecycleRegistry.sessionId` or
|
|
192
|
+
change public lifecycle id validation.
|
|
193
|
+
|
|
194
|
+
The parent extension owns message delivery policy. Core watcher state owns
|
|
195
|
+
prompt observation, result buffering, deduplication, and cleanup.
|
|
196
|
+
|
|
197
|
+
## Verification requirements
|
|
198
|
+
|
|
199
|
+
The implementation is complete only when focused unit tests and live Herdr
|
|
200
|
+
checks verify single and array watchers, fast completions, notification
|
|
201
|
+
queuing, completion ordering, failure states, duplicate observation, and parent
|
|
202
|
+
session cleanup. `npm test` must pass.
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
# Tasks: Non-blocking Shepherd Prompt Watchers
|
|
2
|
+
|
|
3
|
+
Implement in order. Mark a task complete only after its code and focused
|
|
4
|
+
verification pass. Do not modify `shepherd_wait` as part of this feature.
|
|
5
|
+
|
|
6
|
+
## Phase 1 — Protocol and registry
|
|
7
|
+
|
|
8
|
+
- [x] **1.1 Define watcher types**
|
|
9
|
+
- Add watcher handle, registration result, and notification types.
|
|
10
|
+
- Reuse existing prompt result fields for terminal outcomes.
|
|
11
|
+
- Keep watcher ids opaque and distinct from agent, prompt, and Herdr pane ids.
|
|
12
|
+
|
|
13
|
+
- [x] **1.2 Add watcher registry state**
|
|
14
|
+
- Track watcher records and prompt-to-watcher relationships.
|
|
15
|
+
- Track per-watcher delivered prompt ids.
|
|
16
|
+
- Enforce one notification per watched prompt per watcher.
|
|
17
|
+
- Support watcher lookup, completion, and removal.
|
|
18
|
+
|
|
19
|
+
- [x] **1.3 Validate watch input**
|
|
20
|
+
- Accept one prompt id or a non-empty array of prompt ids.
|
|
21
|
+
- Resolve every id through the existing prompt registry.
|
|
22
|
+
- Reject unknown, malformed, duplicate, or closed references according to the
|
|
23
|
+
existing lifecycle error conventions.
|
|
24
|
+
|
|
25
|
+
## Phase 2 — Background observation
|
|
26
|
+
|
|
27
|
+
- [x] **2.1 Start non-blocking monitoring**
|
|
28
|
+
- Start monitoring when `shepherd_watch` registers a prompt.
|
|
29
|
+
- Return from the tool without awaiting prompt completion.
|
|
30
|
+
- Deduplicate monitors for prompts watched by multiple watchers.
|
|
31
|
+
|
|
32
|
+
- [x] **2.2 Reuse completion detection**
|
|
33
|
+
- Apply completion sidecar and state-transition safeguards.
|
|
34
|
+
- Read the final assistant response from the existing result source.
|
|
35
|
+
- Detect provider errors, blocked states, timeout states, and cancellation.
|
|
36
|
+
- Handle completion before watcher registration.
|
|
37
|
+
|
|
38
|
+
- [x] **2.3 Settle and buffer results**
|
|
39
|
+
- Use the existing prompt settlement path exactly once.
|
|
40
|
+
- Preserve artifact/fieldnote callbacks.
|
|
41
|
+
- Keep results available after watcher delivery.
|
|
42
|
+
- Ensure a simultaneous existing `shepherd_wait` receives the same result.
|
|
43
|
+
|
|
44
|
+
- [x] **2.4 Clean monitoring resources**
|
|
45
|
+
- Stop monitors after all watched prompts settle.
|
|
46
|
+
- Stop monitors after completion and on parent session shutdown.
|
|
47
|
+
- Avoid timers or callbacks surviving session replacement/reload.
|
|
48
|
+
|
|
49
|
+
## Phase 3 — Parent notifications
|
|
50
|
+
|
|
51
|
+
- [x] **3.1 Add notification callback boundary**
|
|
52
|
+
- Inject a narrow parent notification callback into the watcher service.
|
|
53
|
+
- Keep core lifecycle code independent of a global `pi` object.
|
|
54
|
+
|
|
55
|
+
- [x] **3.2 Send custom follow-up messages**
|
|
56
|
+
- Use `pi.sendMessage`, not `pi.sendUserMessage`.
|
|
57
|
+
- Queue as `deliverAs: "followUp"`.
|
|
58
|
+
- Trigger a new parent turn when idle.
|
|
59
|
+
- Suppress new turns during shutdown/reload.
|
|
60
|
+
|
|
61
|
+
- [x] **3.3 Define completion payload**
|
|
62
|
+
- Include watcher id, prompt id, agent id, agent name/label, status, `ok`,
|
|
63
|
+
return code, error, and last assistant message.
|
|
64
|
+
- Preserve structured result information for array completions.
|
|
65
|
+
|
|
66
|
+
- [x] **3.4 Coalesce notification bursts**
|
|
67
|
+
- Report completions independently as they become available.
|
|
68
|
+
- Coalesce close-together completions into one notification where practical.
|
|
69
|
+
- Ensure coalescing does not lose ordering or individual prompt identity.
|
|
70
|
+
|
|
71
|
+
## Phase 4 — Tool surface
|
|
72
|
+
|
|
73
|
+
- [x] **4.1 Register `shepherd_watch`**
|
|
74
|
+
- Add the direct TypeBox schema for one id or an array of ids.
|
|
75
|
+
- Return watcher id, normalized prompt ids, pending ids, and completed results.
|
|
76
|
+
- Handle already-completed prompts without duplicate notifications.
|
|
77
|
+
- Preserve standard Shepherd call/return/details formatting.
|
|
78
|
+
|
|
79
|
+
- [x] **4.2 Update model guidance**
|
|
80
|
+
- Add watcher guidance to the umbrella tool and registered tool descriptions.
|
|
81
|
+
- Explain prompt-id arrays and asynchronous completion notifications.
|
|
82
|
+
- Explain that `wait` remains available for deterministic barriers.
|
|
83
|
+
|
|
84
|
+
## Phase 5 — Documentation and tests
|
|
85
|
+
|
|
86
|
+
- [x] **5.1 Add registry tests**
|
|
87
|
+
- Single watcher registration.
|
|
88
|
+
- Array watcher registration.
|
|
89
|
+
- Already-completed prompts.
|
|
90
|
+
- Multiple watchers for one prompt.
|
|
91
|
+
- Duplicate settlement and one-shot cleanup.
|
|
92
|
+
|
|
93
|
+
- [x] **5.2 Add result-state tests**
|
|
94
|
+
- Successful, failed, blocked, timed-out, and cancelled prompts.
|
|
95
|
+
- Final assistant text and all correlation ids.
|
|
96
|
+
- Concurrent watch and wait observing one shared result.
|
|
97
|
+
|
|
98
|
+
- [x] **5.3 Add notification tests**
|
|
99
|
+
- Follow-up delivery while the parent is active.
|
|
100
|
+
- Automatic triggering while the parent is idle.
|
|
101
|
+
- Burst coalescing.
|
|
102
|
+
- Notification delivery failure without lifecycle corruption.
|
|
103
|
+
- Shutdown/reload cleanup.
|
|
104
|
+
|
|
105
|
+
- [x] **5.4 Add tool and documentation coverage**
|
|
106
|
+
- Validate schemas and public result formatting.
|
|
107
|
+
- Update README and lifecycle examples.
|
|
108
|
+
- Document the watcher contract and distinction from `wait`.
|
|
109
|
+
|
|
110
|
+
- [x] **5.5 Run verification** (automated checks; live Herdr verification pending)
|
|
111
|
+
- Run `git diff --check`.
|
|
112
|
+
- Run focused watcher tests.
|
|
113
|
+
- Run `npm test`.
|
|
114
|
+
- Perform live Herdr verification with single and multi-prompt watchers.
|
|
115
|
+
|
|
116
|
+
## Phase 6 — Completion
|
|
117
|
+
|
|
118
|
+
- [x] **6.1 Review against specification**
|
|
119
|
+
- Confirm `shepherd_wait` was not replaced or behaviorally changed.
|
|
120
|
+
- Confirm no raw Herdr pane ids are exposed as watcher ids.
|
|
121
|
+
- Confirm watcher completion does not close agents.
|
|
122
|
+
- Confirm no retained child result or fieldnote resources are deleted.
|
|
123
|
+
|
|
124
|
+
- [x] **6.2 Mark the specification complete**
|
|
125
|
+
- Update `spec.md` status after implementation and verification pass.
|
|
126
|
+
- Record any intentional deviations from the specification.
|