@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,109 @@
|
|
|
1
|
+
# Phase 10 — Artifacts, cleanup, compatibility, and documentation (design notes)
|
|
2
|
+
|
|
3
|
+
Phase 10 closes the feature by (a) confirming the artifact lifecycle follows
|
|
4
|
+
task settlement, (b) confirming shutdown/cleanup behavior, (c) making the
|
|
5
|
+
explicit compatibility decisions for `shepherd_prompt` and `shepherd_wait`,
|
|
6
|
+
and (d) updating the active documentation.
|
|
7
|
+
|
|
8
|
+
## Artifacts
|
|
9
|
+
|
|
10
|
+
Delegate-time allocation was already in place from Phase 4: `delegateAgent`
|
|
11
|
+
reserves exactly one artifact per delegated task (mode `single`, task text
|
|
12
|
+
attached), marks it `running` with the taskId, and attaches a finalizer via
|
|
13
|
+
`attachTaskArtifact`. Ordinary messages never allocate artifacts — only
|
|
14
|
+
`delegateAgent` calls `reserveArtifacts`, so a `shepherd_message` cannot
|
|
15
|
+
create a note. "Open while waiting" is free because the note stays
|
|
16
|
+
`running` (only the frontmatter status changes; agents append freely) and
|
|
17
|
+
`settleTask` is the single authoritative finalization point:
|
|
18
|
+
|
|
19
|
+
- completed -> `completed`
|
|
20
|
+
- blocked (reply deadline, parent failure, ...) -> `failed`
|
|
21
|
+
- failed -> `failed`
|
|
22
|
+
- cancelled (close/cancel) -> `cancelled`
|
|
23
|
+
- timed_out -> `timed-out`
|
|
24
|
+
|
|
25
|
+
`settleTask` guards duplicate settlement (`if (record.settled) return
|
|
26
|
+
record.result!`), so repeated `shepherd_done`/reply/timeout/cancellation
|
|
27
|
+
events cannot double-finalize; `onSettled` runs exactly once and is wrapped
|
|
28
|
+
so an artifact failure never breaks task settlement. Final summaries
|
|
29
|
+
(`result.text`) and errors (`result.error`) are preserved in the note's
|
|
30
|
+
"## Shepherd orchestration" section, so "preserve final summaries and
|
|
31
|
+
errors" holds. Useful request/message references: the finalizer metadata
|
|
32
|
+
carries only the taskId (one note per task, not per chat — messages that
|
|
33
|
+
are correlated with a task use the task's artifact, not a new one).
|
|
34
|
+
|
|
35
|
+
Verified by `verify-delegate.mjs` (allocation + start + cancel finalization)
|
|
36
|
+
and `verify-artifact-sessions.mjs` (all four terminal artifact statuses +
|
|
37
|
+
final output/error sections + in-memory mirroring).
|
|
38
|
+
|
|
39
|
+
## Cleanup and shutdown
|
|
40
|
+
|
|
41
|
+
All of the following were already implemented in Phases 4–8:
|
|
42
|
+
|
|
43
|
+
- parent shutdown: `shutdownParentBroker` stops the parent mailbox poll and,
|
|
44
|
+
via `stopParentBrokerMonitor`, the stale-wait monitor;
|
|
45
|
+
- child shutdown: the child surface (`shepherd-done.ts`) closes its own
|
|
46
|
+
broker channel on session end;
|
|
47
|
+
- persisted task outcomes survive parent shutdown because they are on-disk
|
|
48
|
+
(session.json + note files);
|
|
49
|
+
- a closing agent cancels its active task (`registry.close()` ->
|
|
50
|
+
`cancelTask()`, rc 130) and the task settlement clears its pending
|
|
51
|
+
requests; duplicate events are idempotent (settleTask guard);
|
|
52
|
+
- created-pane ownership protects foreign panes (existing invariant,
|
|
53
|
+
verified by the launch suite); mailbox consumption is parent-only
|
|
54
|
+
(broker capability is parent-scoped; children get a child capability).
|
|
55
|
+
|
|
56
|
+
No new cleanup code was required in Phase 10; these behaviors are pinned by
|
|
57
|
+
existing tests plus the compat suite's "timeout never touches the task"
|
|
58
|
+
check.
|
|
59
|
+
|
|
60
|
+
## Compatibility decisions
|
|
61
|
+
|
|
62
|
+
`shepherd_prompt`
|
|
63
|
+
RETAINED, DEPRECATED. Fire-and-forget one-turn submission stays available so
|
|
64
|
+
existing transcripts/templates keep working, but every model-facing field
|
|
65
|
+
(label, description, promptSnippet, message parameter) now states it is a
|
|
66
|
+
deprecated compatibility path and names the migration target
|
|
67
|
+
(`shepherd_delegate` + `shepherd_watch`). Its one-turn completion semantics
|
|
68
|
+
are unchanged and documented, so they are not "silently active": the docs
|
|
69
|
+
say exactly what it does and what to use instead.
|
|
70
|
+
|
|
71
|
+
`shepherd_wait`
|
|
72
|
+
RETAINED, UPGRADED to be task-aware. It now accepts task ids (preferred) or
|
|
73
|
+
legacy prompt ids (unchanged path); mixing them in one call is rejected,
|
|
74
|
+
mirroring shepherd_watch. Task waits:
|
|
75
|
+
- resolve via the task-watcher registry hook (no polling), in input order
|
|
76
|
+
including for tasks that settle out of order;
|
|
77
|
+
- resolve instantly for already-settled tasks;
|
|
78
|
+
- a wait timeout is a wait-level timeout: it rejects with
|
|
79
|
+
LifecycleError('timeout', ...) and removes the watcher. The underlying
|
|
80
|
+
tasks keep running (their own deadlines remain authoritative) and the
|
|
81
|
+
error message points the model at shepherd_watch.
|
|
82
|
+
No task or message depends on the parent calling shepherd_wait; the tool
|
|
83
|
+
description says shepherd_watch is preferred for new orchestration.
|
|
84
|
+
|
|
85
|
+
Implementation: `LifecycleRegistry.waitForTasks(handles, timeoutMs)` plus a
|
|
86
|
+
public `removeWatcher(watcherId)`; `watchTasks` additionally delivers
|
|
87
|
+
already-settled tasks synchronously in input order (Set-callback form, used by
|
|
88
|
+
waitForTasks) while keeping the legacy single-callback contract intact.
|
|
89
|
+
|
|
90
|
+
Verification: `test/verify-compat.mjs` (descriptions/pointers, schema
|
|
91
|
+
accepts both id kinds with flat-object root, in-order resolution, instant
|
|
92
|
+
already-settled, timeout leaves the task untouched, unknown-id rejection,
|
|
93
|
+
doAction public task mapping with returnCode).
|
|
94
|
+
|
|
95
|
+
## Documentation
|
|
96
|
+
|
|
97
|
+
- README: new "Task delegation workflow" section (delegate ->
|
|
98
|
+
message/watch -> done, with a delegate+watch example and a child-to-child
|
|
99
|
+
message example), the task/message id explanation, idle-child-with-waiting-
|
|
100
|
+
task behavior, followUp vs steer, stale-wait reminders, and explicit
|
|
101
|
+
compatibility status for shepherd_prompt/shepherd_wait.
|
|
102
|
+
- docs/guides/tool-reference.md: delegate/message/done tools added;
|
|
103
|
+
prompt/wait/watch rows updated to reflect deprecation, task ids, and
|
|
104
|
+
mixing rules.
|
|
105
|
+
- docs/reference/dictionary: entries for task, task id, message, message id,
|
|
106
|
+
request/reply correlation, waiting tasks (idle child), and the deprecated
|
|
107
|
+
tools.
|
|
108
|
+
- docs/plans/architecture.md: task/message surface and broker added; the
|
|
109
|
+
"completed implementation" list now lists the tracked-task primitives.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Phase 6 — design notes (working decisions)
|
|
2
|
+
|
|
3
|
+
Canonical requirement: `worker asks planner while planner is busy → planner
|
|
4
|
+
receives the question as a queued follow-up → worker task stays waiting →
|
|
5
|
+
planner replies → worker returns to running.` The parent must own request and
|
|
6
|
+
task state because later phases (watchers, stale-wait, status) read the parent
|
|
7
|
+
`lifecycleRegistry`, which the child process cannot touch.
|
|
8
|
+
|
|
9
|
+
## How the pieces fit
|
|
10
|
+
|
|
11
|
+
1. **Transport.** `messaging.ts` already routes child↔child *through the
|
|
12
|
+
parent-owned broker* and child→parent into the parent inbox (Phase 2). No
|
|
13
|
+
routing change needed. One fix: acknowledgement/dedup is keyed by
|
|
14
|
+
`(participant, messageId)`, so the parent can consume an envelope and later
|
|
15
|
+
relay a **fresh**-`messageId` copy to a child without the old ack blocking.
|
|
16
|
+
|
|
17
|
+
2. **Request tracking (child-originated).** A child cannot put its task into
|
|
18
|
+
`waiting` by itself (the registry lives in the parent). So when the child
|
|
19
|
+
sends `shepherd_message` with `expectsReply` + a task, the child extension
|
|
20
|
+
also mirrors a `runtime` envelope (`requestOpen: true`) to the **parent**
|
|
21
|
+
inbox alongside the question. The parent opens a pending request on the
|
|
22
|
+
sender task and transitions it `running → waiting`.
|
|
23
|
+
|
|
24
|
+
3. **Reply (child-originated).** A child answers a question by sending
|
|
25
|
+
`shepherd_message` with `replyTo` to `shepherd`. The parent resolves the
|
|
26
|
+
matching pending request (clears it + `waiting → running`) and **relays**
|
|
27
|
+
the reply to the original sender's child inbox with a fresh `messageId`
|
|
28
|
+
(provenance preserved: `senderId` stays the replier's agent id). If no
|
|
29
|
+
matching request exists the reply is surfaced to the parent as a notification.
|
|
30
|
+
|
|
31
|
+
4. **Parent-originated.** `shepherd_message` tool → `publishFromParent` to the
|
|
32
|
+
target child inbox. If `expectsReply` + `taskId`, the parent also opens a
|
|
33
|
+
pending request on that task (parent can expect a reply from a delegated
|
|
34
|
+
agent the same way).
|
|
35
|
+
|
|
36
|
+
5. **Reply deadline.** Each pending request stores `deadlineAt` (settings
|
|
37
|
+
`timeout` minutes). The existing parent monitor settles expired request
|
|
38
|
+
owners as `blocked` (initial task policy).
|
|
39
|
+
|
|
40
|
+
6. **Parent notifications.** Child→parent `message`/`reply` are delivered to
|
|
41
|
+
the parent pi session as custom messages (`shepherd.message.incoming` /
|
|
42
|
+
`.reply`) with followUp delivery, reusing the prompt-completion
|
|
43
|
+
renderer/bridge pattern. No fieldnote is created.
|
|
44
|
+
|
|
45
|
+
7. **Delivered vs accepted.** `accepted` = the broker accepted the envelope
|
|
46
|
+
into the target inbox. It never means the recipient read it or replied.
|
|
47
|
+
|
|
48
|
+
## Envelope contract (Phase 6 usage)
|
|
49
|
+
|
|
50
|
+
- `message` → normal conversational content to a target.
|
|
51
|
+
- `reply` → `replyTo` set; answers a tracked question.
|
|
52
|
+
- `task` / `task_done` → existing (Phase 4/5).
|
|
53
|
+
- `runtime` with `taskId` + `expectsReply: true` + `requestOpen: true` →
|
|
54
|
+
child mirrors that it opened a tracked request (parent sets task to waiting).
|
|
55
|
+
`requestOpen` is a boolean field (envelope-validated).
|
|
56
|
+
|
|
57
|
+
## Explicit Phase-6 scope (initial)
|
|
58
|
+
|
|
59
|
+
- Parent `shepherd_message` tool + request/task integration.
|
|
60
|
+
- Parent inbox routing: message/reply → parent session; runtime request-open →
|
|
61
|
+
task waiting; reply → resolve + relay.
|
|
62
|
+
- Child mirrors request-open; child already delivers incoming to its inbox.
|
|
63
|
+
- Reply deadline + blocked settlement.
|
|
64
|
+
- `test/verify-message-routing.mjs` + schema/contract updates.
|
|
65
|
+
|
|
66
|
+
Deferred to later phases: child-side `replyTo` UX polish, thread id routing,
|
|
67
|
+
stale-wait (Phase 8), task-aware watchers (Phase 7), direct child-to-child
|
|
68
|
+
"question to a busy peer" as first-class (transport already supports the
|
|
69
|
+
relay; the request-tracking path targets the parent as the hub).
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# Phase 7 — Task-aware `shepherd_watch` (design notes)
|
|
2
|
+
|
|
3
|
+
Phase 7 makes `shepherd_watch` observe **tracked tasks** rather than individual
|
|
4
|
+
Pi turns. `shepherd_wait` and the legacy prompt watcher remain for
|
|
5
|
+
prompt-based flows, but new orchestration uses tasks.
|
|
6
|
+
|
|
7
|
+
## Core idea
|
|
8
|
+
|
|
9
|
+
Tasks settle only from explicit lifecycle events (a child calling
|
|
10
|
+
`shepherd_done`, or an explicit failure / cancellation / timeout). Because that
|
|
11
|
+
settlement always flows through `LifecycleRegistry.settleTask()`, the registry
|
|
12
|
+
already has a single, authoritative settlement point. The task watcher hooks
|
|
13
|
+
into *that* point instead of polling:
|
|
14
|
+
|
|
15
|
+
- `LifecycleRegistry.watchTasks(handles, callback)` registers a one-shot
|
|
16
|
+
observer for task ids. Synchronous, like `watchPrompts`: an already-settled
|
|
17
|
+
task is returned in `completed` immediately, pending tasks are tracked.
|
|
18
|
+
- `LifecycleRegistry.settleTask()` now, after writing the durable result,
|
|
19
|
+
notifies each registered task watcher **exactly once** for that task id
|
|
20
|
+
(mirroring how `settlePrompt` notifies prompt watchers). The callback is
|
|
21
|
+
wrapped in try/catch so a broken notifier can never affect settlement.
|
|
22
|
+
- A `TaskWatcherService` (in `lifecycle.ts`) wraps the registry: it coalesces
|
|
23
|
+
up to `coalesceMs` (25 ms) of completions per watcher and delivers one
|
|
24
|
+
`TaskWatcherNotification`, sorting coalesced completions into the caller's
|
|
25
|
+
input order. The flush timer is `unref()`'d, and `shutdown()` clears timers
|
|
26
|
+
+ registry registrations.
|
|
27
|
+
|
|
28
|
+
There is **no polling and no interval**: unlike `PromptWatcherService`
|
|
29
|
+
(which shells out to Herdr every 500 ms to infer prompt completion from
|
|
30
|
+
pane/agent state), a task watcher is driven purely by registry settlement.
|
|
31
|
+
Idle, `agent_end`, `agent_settled`, and `waiting` never call `settleTask`, so
|
|
32
|
+
they can never fire the watcher — the invariant holds by construction.
|
|
33
|
+
|
|
34
|
+
## Watcher identity / idempotency
|
|
35
|
+
|
|
36
|
+
The registry stores a `watchers` map keyed by `watcherId`, now generalized
|
|
37
|
+
with a `kind: 'prompt' | 'task'` tag, a `taskIds: string[]`, a `pending:
|
|
38
|
+
Set<string>`, and a `delivered: Set<string>`. `settleTask` removes the task's
|
|
39
|
+
entry from `taskWatchers` immediately after reading its watcher ids, so a task
|
|
40
|
+
can never notify the same watcher twice. Per-watcher `pending.size === 0`
|
|
41
|
+
removes the watcher from the map. `clearWatchers()` (called on parent
|
|
42
|
+
shutdown) drops both prompt and task registrations and indices.
|
|
43
|
+
|
|
44
|
+
## Dispatch and compatibility
|
|
45
|
+
|
|
46
|
+
`doAction('watch')` in `src/extension/shepherd.ts`:
|
|
47
|
+
|
|
48
|
+
1. Collects the id(s) (single or array).
|
|
49
|
+
2. Any id that `lifecycleRegistry.isTaskId(id)` accepts is a task; every other
|
|
50
|
+
id must resolve via `getPrompt(id)` or it is rejected with a
|
|
51
|
+
`LifecycleError('invalid_handle')` that names the bad id. Agent ids and
|
|
52
|
+
Herdr pane ids therefore fail with a clear error instead of being silently
|
|
53
|
+
mis-targeted.
|
|
54
|
+
3. A call cannot **mix** task ids and prompt ids (ambiguous scope) — it throws.
|
|
55
|
+
4. Task ids -> `taskWatcherService.watch(...)`; prompt ids -> the existing
|
|
56
|
+
`promptWatcherService.watch(...)`.
|
|
57
|
+
|
|
58
|
+
**Chosen compatibility behavior:** `shepherd_watch` **accepts** legacy prompt
|
|
59
|
+
ids (the pre-Phase-7 contract) and routes them to the prompt-watcher path.
|
|
60
|
+
Prompt ids are **not** re-interpreted as task ids; they continue to use the
|
|
61
|
+
prompt lifecycle and its pane/polling semantics. Task ids use the new
|
|
62
|
+
task path. This preserves `shepherd_wait`/prompt flows verbatim while adding
|
|
63
|
+
the task flow.
|
|
64
|
+
|
|
65
|
+
## Parent notification bridge
|
|
66
|
+
|
|
67
|
+
`configureTaskWatcherBridge(pi)` (extension) registers a
|
|
68
|
+
`shepherd.task.completion` message renderer and a
|
|
69
|
+
`configureTaskWatcherNotifications` handler that, when
|
|
70
|
+
`taskWatcherSessionActive` is true, formats the completion with the standard
|
|
71
|
+
`call:/return:/details:` layout (call name `shepherd_watch`, argument `id` =
|
|
72
|
+
task id or array) and sends a custom message with
|
|
73
|
+
`{ deliverAs: 'followUp', triggerTurn: true }`. A terminal task outcome always
|
|
74
|
+
triggers a parent turn (the child must then decide the next step), matching
|
|
75
|
+
the prompt bridge's policy.
|
|
76
|
+
|
|
77
|
+
`index.ts` toggles `setTaskWatcherSessionActive` on `session_start`/
|
|
78
|
+
`session_shutdown` and calls `shutdownTaskWatchers()` on shutdown so timers are
|
|
79
|
+
released and no notification is queued for a session that is gone.
|
|
80
|
+
|
|
81
|
+
## Test coverage
|
|
82
|
+
|
|
83
|
+
`test/verify-task-watchers.mjs` (added to the `npm test` chain after
|
|
84
|
+
`message-routing:test`):
|
|
85
|
+
|
|
86
|
+
- Non-blocking registration of a pending task.
|
|
87
|
+
- A task entering `waiting` does *not* complete the watcher (the canonical
|
|
88
|
+
"scout waits on a busy planner" property).
|
|
89
|
+
- No delivery while running/waiting.
|
|
90
|
+
- Completion -> exactly one notification carrying taskId, agentId, status,
|
|
91
|
+
returnCode, agent, label, and summary text.
|
|
92
|
+
- Already-settled task returns immediately and is not re-delivered.
|
|
93
|
+
- Array of task ids: independent settlement, coalesced in watch input order,
|
|
94
|
+
with correct terminal statuses and return codes (completed 0, blocked 2,
|
|
95
|
+
failed 1, cancelled 130, timed_out 124).
|
|
96
|
+
- Cancelled and timed-out tasks report their terminal status/return code.
|
|
97
|
+
- Two independent watchers on the same task each observe it exactly once.
|
|
98
|
+
- Unknown id and duplicate ids are rejected.
|
|
99
|
+
- Extension bridge: one turn-triggering custom follow-up keyed by task id
|
|
100
|
+
(no `promptId`), and delivery is suppressed once the session is deactivated.
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# Phase 8 — Stale-wait monitoring (design notes)
|
|
2
|
+
|
|
3
|
+
Phase 8 adds a *non-invasive* nudge for a tracked task that is sitting in the
|
|
4
|
+
`waiting` state — i.e. waiting on a required reply that has not yet arrived —
|
|
5
|
+
for longer than a configurable threshold. It never settles a task; it only
|
|
6
|
+
informs the parent that something has been waiting a long time.
|
|
7
|
+
|
|
8
|
+
## What counts as "stale"
|
|
9
|
+
|
|
10
|
+
A task is stale when **all** of these hold:
|
|
11
|
+
|
|
12
|
+
1. `task.state === 'waiting'` — the task has entered the `waiting` state.
|
|
13
|
+
2. `task.pendingReplyMessageId` is set — there is a specifically expected reply
|
|
14
|
+
(an `expectsReply` question, or a child mirror of one). A task that is
|
|
15
|
+
`waiting` for any other reason (a bare `agent_end`, a manual `setTaskWaiting`
|
|
16
|
+
with no outstanding reply) is *not* stale by definition, because there is no
|
|
17
|
+
reply to time out.
|
|
18
|
+
3. `now - task.waitingSince >= staleWaitThreshold` (minutes, from settings).
|
|
19
|
+
4. `task.staleNotifiedAt` is unset — the monitor has not yet nudged for this
|
|
20
|
+
waiting episode.
|
|
21
|
+
|
|
22
|
+
`waitingSince` is the timestamp the task entered `waiting` (set in
|
|
23
|
+
`setTaskWaiting` / `openPendingRequest`). The stale condition is evaluated on
|
|
24
|
+
the *task* record, not on the raw Herdr agent state, so an agent that is merely
|
|
25
|
+
idle but owns no waiting task never triggers a stale reminder. A completed,
|
|
26
|
+
failed, cancelled, or blocked task has already left the set of `waiting`
|
|
27
|
+
records and therefore never produces one.
|
|
28
|
+
|
|
29
|
+
## One notification per episode
|
|
30
|
+
|
|
31
|
+
Stale delivery is idempotent per *episode* (a single contiguous wait), not per
|
|
32
|
+
poll. `markStaleNotified(taskId)` stamps `task.staleNotifiedAt` the moment the
|
|
33
|
+
monitor emits a reminder; the monitor skips a task whenever the flag is present.
|
|
34
|
+
The flag is cleared at every state transition that ends or re-opens a wait:
|
|
35
|
+
|
|
36
|
+
- `setTaskRunning` (a resume) — clears `staleNotifiedAt`.
|
|
37
|
+
- `resolvePendingRequest` / `resolveReplyForTask` (a reply arrived) — clears it.
|
|
38
|
+
- `settleTask` (any terminal outcome) — the task leaves the `waiting` set.
|
|
39
|
+
|
|
40
|
+
Because a *reply* is normally the event that ends a stale wait, the practical
|
|
41
|
+
effect is: one reminder, then a reply (or a manual resume / settle) resets the
|
|
42
|
+
state. If the same task re-enters `waiting` with a new reply later, it is a new
|
|
43
|
+
episode and is entitled to its own reminder. This is exactly the exit-gate
|
|
44
|
+
property: "a reply clears the stale condition."
|
|
45
|
+
|
|
46
|
+
## Setting: `staleWaitThreshold`
|
|
47
|
+
|
|
48
|
+
`src/extension/config.ts`:
|
|
49
|
+
|
|
50
|
+
- Stored in **minutes**, like `timeout`.
|
|
51
|
+
- Default `5`. `0` (and negative) is a valid way to *disable* reminders
|
|
52
|
+
entirely; the UI exposes this as the `off (no reminders)` choice.
|
|
53
|
+
- `validField` treats `0` as a real value (unlike `timeout`, where `0`/invalid
|
|
54
|
+
means "fall back to the default"), so a user can deliberately turn the
|
|
55
|
+
feature off.
|
|
56
|
+
- In the monitor, a effective threshold `< 1` minute short-circuits the poll:
|
|
57
|
+
no reminder is ever emitted and the monitor stops itself.
|
|
58
|
+
|
|
59
|
+
It lives in both the user layer and the project delta (it is an
|
|
60
|
+
`OverridableField`), appears in the `/shepherd settings` menu, and is
|
|
61
|
+
documented in the README settings table with a dedicated "Stale-wait
|
|
62
|
+
reminders" section.
|
|
63
|
+
|
|
64
|
+
## The monitor (`StaleWaitMonitor` in `lifecycle.ts`)
|
|
65
|
+
|
|
66
|
+
A self-managing timer that:
|
|
67
|
+
|
|
68
|
+
- **Starts** (`kick()`) only when a task opens a pending reply — the two call
|
|
69
|
+
sites are `sendParentMessage` (`expectsReply` + task id) and the child
|
|
70
|
+
`runtime` mirror in `applyMessageEnvelope`. Both mean the task just entered
|
|
71
|
+
`waiting` on an expected reply.
|
|
72
|
+
- **Polls** at 1s (unref'd — it never keeps the process alive) and inspects
|
|
73
|
+
*task* state.
|
|
74
|
+
- **Stops** itself (`maybeStop()`) as soon as no `waiting` task remains; that
|
|
75
|
+
also covers shutdown via `stopParentBrokerMonitor` →
|
|
76
|
+
`shutdownStaleWaitMonitor()`.
|
|
77
|
+
- Emits **at most one** `StaleWaitInfo` per episode through
|
|
78
|
+
`configureStaleWaitNotifications`.
|
|
79
|
+
|
|
80
|
+
`StaleWaitInfo` carries the full context the parent needs to decide what to do:
|
|
81
|
+
`taskId`, `agentId`/display name, `description`, `waitingSince`, `elapsedMs`,
|
|
82
|
+
the `requestMessageId` being waited on, the `question`, the `recipientId` +
|
|
83
|
+
resolved `recipientName` and the recipient's own lifecycle `recipientState`, and
|
|
84
|
+
the applied `thresholdMinutes`.
|
|
85
|
+
|
|
86
|
+
## Parent delivery (`src/extension/shepherd.ts`)
|
|
87
|
+
|
|
88
|
+
A new `shepherd.stale.wait` custom message + renderer. It is delivered with
|
|
89
|
+
`deliverAs: 'followUp'` and **`triggerTurn: false`**.
|
|
90
|
+
|
|
91
|
+
That is the deliberate "no wake-up" policy: a stale wait is *information*, not a
|
|
92
|
+
decision point that needs an immediate parent turn. Forcing a turn here would
|
|
93
|
+
(i) wake the parent on every normal long wait and (ii) risk a notification
|
|
94
|
+
storm if several tasks went stale together or the parent were busy. The parent
|
|
95
|
+
sees the reminder in its next turn and can choose to nudge the recipient with
|
|
96
|
+
`shepherd_message`, or simply wait for the reply (or for the reply *deadline*
|
|
97
|
+
to settle the task as `blocked`). The body even lists those possible actions.
|
|
98
|
+
|
|
99
|
+
The reminder never mutates task state; the reply deadline (Phase 6) remains the
|
|
100
|
+
only authoritative mechanism that turns a stale wait into `blocked`.
|
|
101
|
+
|
|
102
|
+
## Compatibility / invariants preserved
|
|
103
|
+
|
|
104
|
+
- The Phase 5 invariant is untouched: only `shepherd_done` (or an explicit
|
|
105
|
+
failure/cancellation/timeout) settles a tracked task. A stale reminder is a
|
|
106
|
+
pure observation.
|
|
107
|
+
- Existing `setTaskRunning` / `resolve*` / `settleTask` behavior is unchanged
|
|
108
|
+
except for clearing the new `staleNotifiedAt` flag.
|
|
109
|
+
- The `timeout` reply-deadline path is unchanged; stale-wait is additive.
|
|
110
|
+
|
|
111
|
+
## Test coverage
|
|
112
|
+
|
|
113
|
+
`test/verify-stale-wait.mjs` uses the fake-clock helper to drive time
|
|
114
|
+
deterministically and asserts:
|
|
115
|
+
|
|
116
|
+
- No notification below the threshold; exactly one once crossed.
|
|
117
|
+
- No second notification while the episode remains open (no storm).
|
|
118
|
+
- Full notification content (task, owner, description, question, request id,
|
|
119
|
+
recipient id + state, elapsed time, threshold).
|
|
120
|
+
- A reply clears the episode; a *new* episode re-notifies.
|
|
121
|
+
- A completed task and an idle agent with no waiting task produce nothing.
|
|
122
|
+
- Stale-wait does **not** settle the task (it stays `waiting`); the reply
|
|
123
|
+
deadline is what settles it to `blocked`.
|
|
124
|
+
- The monitor starts only while a waiting task exists and stops when none remain.
|
|
125
|
+
- A disabled (`0`) threshold produces no notification.
|
|
126
|
+
- Bridge delivery is a follow-up with `triggerTurn: false`, and is suppressed
|
|
127
|
+
once the parent session goes inactive.
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Phase 9 — Status and TUI integration (design notes)
|
|
2
|
+
|
|
3
|
+
Phase 9 makes the *status surface* aware that a pi-shepherd agent now tracks
|
|
4
|
+
two independent dimensions: the **Herdr process state** (`working` /
|
|
5
|
+
`idle` / `done` / …) and the **tracked task state** (`created` / `running` /
|
|
6
|
+
`waiting` / terminal). The critical interaction: a child whose process is
|
|
7
|
+
`idle` may own a task that is `waiting` on a required reply — and vice versa.
|
|
8
|
+
Reporting only the process state (the pre-Phase 9 behavior) made in-flight
|
|
9
|
+
work invisible exactly when the child was parked.
|
|
10
|
+
|
|
11
|
+
## Status model
|
|
12
|
+
|
|
13
|
+
`AgentStatus` (`src/core/orchestration.ts`) gained an optional `task`
|
|
14
|
+
(`AgentTaskStatus`) alongside the process-level `state`. The view is produced
|
|
15
|
+
by a new `LifecycleRegistry.taskStatusForAgent(record)` which:
|
|
16
|
+
|
|
17
|
+
- returns `undefined` when the agent owns no open task (a settled task is not
|
|
18
|
+
"active" and is dropped — an intentional status semantics, not an error);
|
|
19
|
+
- surfaces `id`, `state`, `description`, and only the *applicable* optional
|
|
20
|
+
fields: `waitingSince` / `waitingMs` (age of the current `waiting` episode),
|
|
21
|
+
`pendingRequestMessageId` (the expected reply), `waitingRecipient` (the
|
|
22
|
+
display name of the agent the reply is expected from), and `stale` (true
|
|
23
|
+
once the Phase 8 monitor has reminded for this episode).
|
|
24
|
+
- never touches Herdr; everything is in-memory registry state, so
|
|
25
|
+
`shepherd_status` and the widget poll can both call it cheaply.
|
|
26
|
+
|
|
27
|
+
`registry.status()` now includes the task view; `statusAgent()` (lifecycle)
|
|
28
|
+
still resolves live process state from the pane when one exists, but the task
|
|
29
|
+
view comes from the registry in either path.
|
|
30
|
+
|
|
31
|
+
The `status` doAction case in `src/extension/shepherd.ts` maps that into a
|
|
32
|
+
compact **public** result:
|
|
33
|
+
|
|
34
|
+
```json
|
|
35
|
+
{
|
|
36
|
+
"id": "shepherd-agent-…",
|
|
37
|
+
"state": "idle",
|
|
38
|
+
"task": {
|
|
39
|
+
"id": "shepherd-task-…",
|
|
40
|
+
"state": "waiting",
|
|
41
|
+
"waitingMs": 423120,
|
|
42
|
+
"pendingRequest": "shepherd-message-…",
|
|
43
|
+
"waitingOn": "planner: rollout-planner",
|
|
44
|
+
"stale": true
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
and the summary text names both dimensions: `agent idle; task
|
|
50
|
+
shepherd-task-… waiting.` Opaque agent/task ids are passed through verbatim;
|
|
51
|
+
Herdr pane ids stay internal diagnostics (they are only present on the
|
|
52
|
+
`AgentStatus` shape, not on the public `status` result or the rendered
|
|
53
|
+
output).
|
|
54
|
+
|
|
55
|
+
## Status widget projection
|
|
56
|
+
|
|
57
|
+
`src/core/herdr.ts`:
|
|
58
|
+
|
|
59
|
+
- `activeTasksByPane()` maps paneId → active task (registry read only).
|
|
60
|
+
- `workingOrWaitingSubagents()` extends the old `workingSubagents()` filter:
|
|
61
|
+
an owned pane is listed when `state !== "idle"` **or** the pane's agent
|
|
62
|
+
owns an open task. This is the "do not filter waiting tasks out because the
|
|
63
|
+
process is idle" rule. `workingSubagents()` is retained as a working-only
|
|
64
|
+
projection; the widget uses the new query. Session-ownership filtering
|
|
65
|
+
(`paneOwner === sessionOwner`) is unchanged, so foreign sessions' panes are
|
|
66
|
+
still excluded.
|
|
67
|
+
|
|
68
|
+
`index.ts` (the widget):
|
|
69
|
+
|
|
70
|
+
- the per-second snapshot now attaches each row's `task` view;
|
|
71
|
+
- the header counts both dimensions: `N working · N waiting`;
|
|
72
|
+
- while a task is open the **task state** wins the right-hand label: a working
|
|
73
|
+
process with a `waiting` task renders `waiting`, not `working` (the process
|
|
74
|
+
is churning but the *work* is blocked);
|
|
75
|
+
- waiting rows append ` ⏳<minutes>m ←<recipient>` (elapsed wait + who still
|
|
76
|
+
has to answer). `stateIcon` renders them with the existing waiting glyph,
|
|
77
|
+
and a stale episode renders `waiting (stale)`.
|
|
78
|
+
- pane ids and opaque task ids are never painted into rows; only display
|
|
79
|
+
names, state labels, and the wait marker appear. Polling cadence is
|
|
80
|
+
unchanged (the 1s unref'd interval + sheep-animation interval); the task
|
|
81
|
+
overlay adds no new I/O.
|
|
82
|
+
|
|
83
|
+
## Tests
|
|
84
|
+
|
|
85
|
+
- `test/verify-status.mjs` (new): process/task independence (idle+waiting,
|
|
86
|
+
working+running, no-task), waiting fields (age, pending request,
|
|
87
|
+
recipient, stale flag and its clearing on reply), completed-task removal
|
|
88
|
+
from the view, and the public `doAction('status')` mapping (opaque ids
|
|
89
|
+
only, no pane leakage, dual-state summary text).
|
|
90
|
+
- `test/verify-status-widget.mjs` (extended): three snapshot phases over a
|
|
91
|
+
fake Herdr with one working pane (plain), one working pane with a running
|
|
92
|
+
task, one idle pane with a waiting+stale task, and a foreign working pane.
|
|
93
|
+
Phase 1/2 cover crash regression, cwd-driven emojiSheep (🐑 vs plain),
|
|
94
|
+
session-ownership filtering, pane-id opacity, and row-width fit. Phase 3
|
|
95
|
+
settles the waiting task and asserts the idle pane drops out of the widget.
|
|
96
|
+
|
|
97
|
+
## Invariants
|
|
98
|
+
|
|
99
|
+
- Phase 5 completion invariant untouched: status is a pure read; nothing here
|
|
100
|
+
settles or mutates tasks.
|
|
101
|
+
- Idle ≠ done: an idle process with a waiting task remains visible in every
|
|
102
|
+
status surface (exit gate: "an idle waiting scout remains visible").
|
|
103
|
+
- No new mailbox reads per render frame; the widget only ever reads the
|
|
104
|
+
in-memory registry plus the existing Herdr `agent list` snapshot.
|