@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,145 @@
|
|
|
1
|
+
# Journal — 007 unwatched completion notice
|
|
2
|
+
|
|
3
|
+
## Status — 2026-10-18
|
|
4
|
+
|
|
5
|
+
- **Scope: implement all of spec 007** (unseen-settlement ledger + settle
|
|
6
|
+
boundary / idle-wake notice). The design is the approved direction in
|
|
7
|
+
GitHub issue #15.
|
|
8
|
+
- Branch: `feat/007-unwatched-completion-notice`, created off `main`.
|
|
9
|
+
- No auto-watch on `delegate`; no child-side `task_done_ack` (deferred); no
|
|
10
|
+
broker protocol, tool schema, prompt, or settings changes; no new
|
|
11
|
+
dependencies; existing `verify-*.mjs` suites must stay untouched.
|
|
12
|
+
- **Merge condition:** reviewer pass + `npm test` green (existing suites
|
|
13
|
+
untouched, new `verify-unseen-completions` in the chain) + live smoke
|
|
14
|
+
(an unwatched settlement produces the boundary notice with the retrieval
|
|
15
|
+
command; `shepherd_watch` retrieves the result; no duplicate notice).
|
|
16
|
+
Then merge `feat/007-unwatched-completion-notice` back into `main`.
|
|
17
|
+
- **Status: implemented, reviewed, and verified.** Full `npm test`
|
|
18
|
+
EXIT=0 with 487 PASS assertions (new suite in the chain; no existing
|
|
19
|
+
test file modified); live Herdr smoke ALL PASS twice, including once
|
|
20
|
+
after the review fixes.
|
|
21
|
+
|
|
22
|
+
## Decisions
|
|
23
|
+
|
|
24
|
+
- The runtime-neutral seam is a registry observer:
|
|
25
|
+
`onTaskSettled(result, { hadWatchers, agent?, label?, source? })`, fired
|
|
26
|
+
after the watcher fan-out on the transition into a terminal task state.
|
|
27
|
+
- The ledger is pure core (`src/core/unseen-completions.ts`, singleton like
|
|
28
|
+
`taskWatcherService`, structural `UnseenSettlement`, no runtime imports);
|
|
29
|
+
delivery policy lives in `src/extension/unseen-completions.ts`.
|
|
30
|
+
- The ledger is a queue of **un-noticed** settlements: notify drains the
|
|
31
|
+
entry, so notify-once and loop-safety hold by construction. Entries clear
|
|
32
|
+
on retrieval (watch action) / close (`clearForAgent`, reported) / session
|
|
33
|
+
end.
|
|
34
|
+
- Clearing for a late `shepherd_watch` lives in the **watch action**, not
|
|
35
|
+
the watcher notifier: settled tasks are delivered inline inside
|
|
36
|
+
`TaskWatcherService.watch` before the watcher id exists, so the notifier
|
|
37
|
+
never sees them.
|
|
38
|
+
- Parent-initiated cancellations (`shepherd_close` → `cancelled`) never
|
|
39
|
+
enter the ledger; neither do `delegateAgent` submission failures (tagged
|
|
40
|
+
`source: "delegate-submission-failure"` — the Shepherd already sees the
|
|
41
|
+
error in the tool result).
|
|
42
|
+
- No persistence: the ledger is session-scoped like the task registry.
|
|
43
|
+
- The bridge is wired in `index.ts` (parent surface), not in
|
|
44
|
+
`registerShepherdTools`, and subscribes only while a parent session is
|
|
45
|
+
active.
|
|
46
|
+
|
|
47
|
+
## Log
|
|
48
|
+
|
|
49
|
+
- 2026-10-18: spec/plan/tasks drafted
|
|
50
|
+
(`specs/007-unwatched-completion-notice/`), branch
|
|
51
|
+
`feat/007-unwatched-completion-notice` created off `main`.
|
|
52
|
+
- 2026-10-18: static spec review delegated to the `reviewer` sheep
|
|
53
|
+
(`shepherd-task-3a2282a0-d0e0c413-…`), watcher registered.
|
|
54
|
+
- 2026-10-18: review returned 3 Critical + 6 Warning + suggestions; verified
|
|
55
|
+
against source and folded in before the implementation commit:
|
|
56
|
+
1. clear-on-watch was impossible as specified (late delivery bypasses the
|
|
57
|
+
notifier) → clear in the watch action;
|
|
58
|
+
2. wiring inside `registerShepherdTools` would break six fake-pi suites →
|
|
59
|
+
wire in `index.ts` after the worker guard, session-scoped subscription,
|
|
60
|
+
`sendMessage` surface guard;
|
|
61
|
+
3. the core ledger could not import `TaskResult` from the Herdr runtime →
|
|
62
|
+
structural `UnseenSettlement` in core;
|
|
63
|
+
4. observer context now carries `agent`/`label`/`source`;
|
|
64
|
+
5. delegate submission failures no longer produce a false notice;
|
|
65
|
+
6. `details` uses `settlements` (the generic collapsed formatter owns
|
|
66
|
+
`completions`); close reports dropped entries; drop-on-notify replaces
|
|
67
|
+
the `unseen|notified` two-state design; debounce/ledger injectable for
|
|
68
|
+
deterministic tests; docs fix for the stale "follow-ups" wording.
|
|
69
|
+
- 2026-10-18: implementation delegated to worker-05
|
|
70
|
+
(`shepherd-task-3a2282a0-93277d49-…`, watched). It delivered the ledger,
|
|
71
|
+
observer + `source` tag, bridge, wiring, tests, and docs without
|
|
72
|
+
committing. I inspected the diff, ran the full suite, and ran the live
|
|
73
|
+
smoke, which caught one harness bug (counting every `sendMessage` instead
|
|
74
|
+
of the unseen-notice custom type) and then passed.
|
|
75
|
+
- 2026-10-18: independent code review delegated to reviewer-05
|
|
76
|
+
(`shepherd-task-3a2282a0-713bd813-…`, watched). Verdict: **no
|
|
77
|
+
Critical**; all 3 spec-review Criticals and all 8 warnings confirmed
|
|
78
|
+
fixed, boundary semantics cross-checked against pi's runner internals.
|
|
79
|
+
Two warnings fixed after review: (a) `hadWatchers` no longer counts a
|
|
80
|
+
callback-less watcher registration as observed, and (b) the test suite
|
|
81
|
+
now guards the delegate-failure source tag end-to-end and watched
|
|
82
|
+
settlement suppression at the bridge level.
|
|
83
|
+
- 2026-10-18: post-review polish adopted from the suggestions: summary
|
|
84
|
+
detail falls back to error text on an empty summary and is clipped at
|
|
85
|
+
200 chars (full result stays one `shepherd_watch` away); the renderer
|
|
86
|
+
falls back to message content when `details.settlements` is absent;
|
|
87
|
+
`agent_settled` no longer schedules an empty-ledger timer; the boundary
|
|
88
|
+
comment names the cross-extension projection trigger. Not adopted:
|
|
89
|
+
clearing on `waitForTasks` retrieval (not reachable from the tool
|
|
90
|
+
surface; the spec defines clearing on the watch action and the notice is
|
|
91
|
+
accurate) and close-details duplication (consistent with existing
|
|
92
|
+
actions).
|
|
93
|
+
- 2026-10-18: final verification after the fixes: `npm test` EXIT=0,
|
|
94
|
+
487 PASS, no failures; live smoke ALL PASS; then merge to `main`.
|
|
95
|
+
|
|
96
|
+
## Landing — 2026-10-18
|
|
97
|
+
|
|
98
|
+
- Landed on `main` as `93fafe8` (fast-forward from
|
|
99
|
+
`feat/007-unwatched-completion-notice`).
|
|
100
|
+
- Evidence at landing: `npm test` EXIT=0, 487 PASS assertions (new
|
|
101
|
+
`unseen-completions:test` in the chain; every pre-existing suite
|
|
102
|
+
untouched); live Herdr smoke ALL PASS — a real spawned worker with no
|
|
103
|
+
watcher produced exactly one boundary notice (`continue: true`) while
|
|
104
|
+
busy, exactly one coalesced `triggerTurn` notice while idle, and
|
|
105
|
+
`shepherd_watch` retrieval of the settled task cleared the ledger with
|
|
106
|
+
no duplicate notice.
|
|
107
|
+
- Review: reviewer-05 found no Critical; all three spec-review Criticals
|
|
108
|
+
and all eight warnings were verified fixed before merge.
|
|
109
|
+
- Deferred non-goals (kept in issue #15): auto-watch on delegate;
|
|
110
|
+
child-side `task_done_ack`; ledger persistence across sessions; a
|
|
111
|
+
fallback when a watcher exists but its notification delivery is
|
|
112
|
+
swallowed; clearing on `waitForTasks` retrieval.
|
|
113
|
+
|
|
114
|
+
## Correction — 2026-10-19
|
|
115
|
+
|
|
116
|
+
- **Defect (#16):** the `agent_before_settle` handler bailed out when
|
|
117
|
+
`event.context.canContinue` was false. pi builds that snapshot from the
|
|
118
|
+
entries that existed *before* the handler runs (`emitBoundary` in
|
|
119
|
+
`dist/core/extensions/runner.js`), so at a completed boundary it is
|
|
120
|
+
`finalRole === 'assistant'` and therefore always false: the primary
|
|
121
|
+
boundary route was dead code and only the 250ms idle wake ever delivered
|
|
122
|
+
a notice. `pi -p` lost notices entirely — the unref'd timer never fires
|
|
123
|
+
and `session_shutdown` clears the ledger.
|
|
124
|
+
- **Fix:** `ccf339c` drops the pre-entry guard. The handler always returns
|
|
125
|
+
`{ entries: [entry], continue: true }` for a completed run with pending
|
|
126
|
+
entries; `_runBeforeSettleBoundary` in `dist/core/agent-session.js`
|
|
127
|
+
commits the drafts via `_commitBoundaryDrafts` and only then recomputes
|
|
128
|
+
`finalContext.canContinue` via `_buildBoundaryContext`, where a committed
|
|
129
|
+
`custom_message` projects through `convertToLlm` as a user-role message.
|
|
130
|
+
- **Live evidence (real pi):** the `pi -p` probe logs
|
|
131
|
+
`canContinue=true pending=0` followed by exactly one continuation
|
|
132
|
+
(previously `canContinue=false pending=1` and the notice was discarded);
|
|
133
|
+
an unwatched child settling mid-turn is announced 61ms after the
|
|
134
|
+
turn-end marker. That is faster than the 250ms idle-wake debounce, so the
|
|
135
|
+
idle path cannot have produced it and the boundary route is demonstrably
|
|
136
|
+
the delivering path.
|
|
137
|
+
- **This entry (#17)** corrects the test and spec contract that still
|
|
138
|
+
pinned the old behavior: the suite's busy-boundary fixture used a
|
|
139
|
+
synthetic `canContinue: true` (a pre-entry shape pi only emits when
|
|
140
|
+
queued or pending messages already exist) and asserted that
|
|
141
|
+
`canContinue: false` returns `undefined`; `spec.md` plus the plan/tasks
|
|
142
|
+
notes described the same pre-entry assumption. Fixtures now use pi's
|
|
143
|
+
real clean-boundary shape and assert the continuation, with a drift-guard
|
|
144
|
+
comment naming the pi internals; the post-commit gate stays covered by
|
|
145
|
+
the real-pi probe, not the hermetic suite.
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
# Implementation Plan: Unwatched completion notice
|
|
2
|
+
|
|
3
|
+
This plan implements `spec.md` (reviewer fixes folded in). Three stages:
|
|
4
|
+
core detection + ledger, extension notice delivery, verification + docs. No
|
|
5
|
+
behavior change for watched tasks, no broker or tool-surface change.
|
|
6
|
+
|
|
7
|
+
## Files
|
|
8
|
+
|
|
9
|
+
| File | Change |
|
|
10
|
+
|---|---|
|
|
11
|
+
| `src/core/unseen-completions.ts` | new: `UnseenCompletionLedger` + singleton, structural `UnseenSettlement` |
|
|
12
|
+
| `src/runtimes/herdr/orchestration.ts` | `onTaskSettled(listener)` observer + `source` tag on the delegate failure settle |
|
|
13
|
+
| `src/runtimes/herdr/lifecycle.ts` | tag the `delegateAgent` failure settle with `source: "delegate-submission-failure"` |
|
|
14
|
+
| `src/extension/unseen-completions.ts` | new: session-scoped subscription, activity tracking, idle wake, boundary continuation, renderer |
|
|
15
|
+
| `src/extension/shepherd.ts` | export `renderShepherdNotification`; clear-on-watch in the `watch` action; clear-on-close with report in the `close` action |
|
|
16
|
+
| `index.ts` | call `configureUnseenCompletionBridge(pi)` after the worker guard (parent surface only) |
|
|
17
|
+
| `test/verify-unseen-completions.mjs` | new suite (core cases first, bridge cases added in Stage 3) |
|
|
18
|
+
| `package.json` | register `unseen-completions:test` in the `test` chain |
|
|
19
|
+
| `README.md`, `docs/guides/tool-reference.md` | watch/notification behavior note; fix the stale "follow-ups" wording |
|
|
20
|
+
|
|
21
|
+
## Stage 1 — Detection + ledger (core)
|
|
22
|
+
|
|
23
|
+
1. `UnseenCompletionLedger` (`src/core/unseen-completions.ts`):
|
|
24
|
+
- `tasks: Map<taskId, UnseenSettlement>` insertion-ordered.
|
|
25
|
+
- `record` flattens a `TaskResult` + observer context into
|
|
26
|
+
`UnseenSettlement`; returns false for `hadWatchers === true`,
|
|
27
|
+
`status === "cancelled"`, `source === "delegate-submission-failure"`,
|
|
28
|
+
or an existing entry.
|
|
29
|
+
- `pending()`; `drain(ids)`; `clear(ids): string[]`;
|
|
30
|
+
`clearForAgent(agentId): string[]`; `clearAll()`.
|
|
31
|
+
- Pure module: only builtins; no `@earendil-works/*`, `src/runtimes/`,
|
|
32
|
+
or `src/extension/` imports. Export the class and the
|
|
33
|
+
`unseenCompletionLedger` singleton.
|
|
34
|
+
2. Registry observer in `orchestration.ts`:
|
|
35
|
+
- `private readonly settlementListeners = new Set<...>()`.
|
|
36
|
+
- `onTaskSettled(listener)` adds and returns an unsubscribe function.
|
|
37
|
+
- Compute `hadWatchers` in the fan-out by marking when
|
|
38
|
+
`notifyTaskWatcher(...)` actually runs (the watcher `delivered` check
|
|
39
|
+
already gates duplicates), capture the agent handle for
|
|
40
|
+
`agent`/`label`, then invoke listeners inside a `try/catch` after the
|
|
41
|
+
fan-out. Pass `{ ...result }` and a fresh context object; carry the
|
|
42
|
+
internal `source` tag through from `settleTask`.
|
|
43
|
+
- Fire only on the transition to terminal (the existing early-return for
|
|
44
|
+
already-settled tasks stays untouched); prompt settlement paths are not
|
|
45
|
+
touched.
|
|
46
|
+
- `settleTask` gains an optional internal options argument for `source`;
|
|
47
|
+
only `delegateAgent`'s failure path in `lifecycle.ts` passes it.
|
|
48
|
+
|
|
49
|
+
Rationale: the observer gives one runtime-neutral seam. The extension
|
|
50
|
+
subscribes; tests can subscribe directly. The durable runtime (spec 006,
|
|
51
|
+
Phase 1) implements the same hook instead of duplicating the ledger.
|
|
52
|
+
|
|
53
|
+
## Stage 2 — Notice delivery (extension)
|
|
54
|
+
|
|
55
|
+
`src/extension/unseen-completions.ts`, module state:
|
|
56
|
+
|
|
57
|
+
- `active` subscription flag, `unsubscribe`, `idle` boolean (default true),
|
|
58
|
+
`flushTimer`, captured lifecycle `ctx`.
|
|
59
|
+
- `configureUnseenCompletionBridge(pi, options?: { coalesceMs?, ledger? })`:
|
|
60
|
+
- `pi.on("session_start")` → `clearAll()`, idle, subscribe to
|
|
61
|
+
`ledger`'s registry observer (`lifecycleRegistry.onTaskSettled`) if not
|
|
62
|
+
already subscribed. Idempotent across repeated session starts.
|
|
63
|
+
- `pi.on("agent_start")` → busy; `pi.on("agent_settled")` → idle +
|
|
64
|
+
`scheduleIdleWake()` (no-op without pending entries; catches settlements
|
|
65
|
+
whose boundary did not run).
|
|
66
|
+
- `pi.on("session_shutdown")` → clear timer, `clearAll()`, unsubscribe,
|
|
67
|
+
reset to idle.
|
|
68
|
+
- `pi.on("agent_before_settle", event => ...)`:
|
|
69
|
+
- return `undefined` unless `event.outcome === "completed"`,
|
|
70
|
+
- **and** the ledger has pending entries (no pre-entry
|
|
71
|
+
`event.context.canContinue` check: that snapshot predates our draft,
|
|
72
|
+
and pi recomputes `canContinue` after committing the drafts; #16),
|
|
73
|
+
- build the `custom_message` entry, drain its task ids, and return
|
|
74
|
+
`{ entries: [entry], continue: true }`.
|
|
75
|
+
- `pi.registerMessageRenderer("shepherd.task.unseen", ...)` using
|
|
76
|
+
`renderShepherdNotification` (exported from `shepherd.ts`) with the
|
|
77
|
+
notice formatter reading `details.settlements`.
|
|
78
|
+
- Observer callback:
|
|
79
|
+
`lifecycleRegistry.onTaskSettled((result, context) => {
|
|
80
|
+
if (ledger.record(result, context)) scheduleIdleWake(); })`.
|
|
81
|
+
- `scheduleIdleWake()`: return if a timer is pending or not idle;
|
|
82
|
+
`setTimeout(flush, coalesceMs)` (unref) → `flush()`:
|
|
83
|
+
- return unless `typeof pi.sendMessage === "function"`, idle, and
|
|
84
|
+
`ledger.pending().length > 0`;
|
|
85
|
+
- build the notice, `pi.sendMessage(notice, { triggerTurn: true })`,
|
|
86
|
+
drain only after the synchronous call returns without throwing;
|
|
87
|
+
wrap in try/catch so a throw leaves entries pending.
|
|
88
|
+
- Notice formatter (exported for tests) produces the exact spec text:
|
|
89
|
+
header `Shepherd notice — N task(s) settled with no watcher attached:`,
|
|
90
|
+
per-entry `- <taskId> (<agent>[, "label"]): <status> — <summary|error>`,
|
|
91
|
+
and `Full results: shepherd_watch({ id: [ "id", ... ] })`.
|
|
92
|
+
|
|
93
|
+
Wiring in `src/extension/shepherd.ts`:
|
|
94
|
+
|
|
95
|
+
- Export `renderShepherdNotification` (its internals stay private; new
|
|
96
|
+
module imports it — no cycle because `shepherd.ts` imports only the core
|
|
97
|
+
ledger).
|
|
98
|
+
- In the `watch` action, after `taskWatcherService.watch(taskIds)` returns:
|
|
99
|
+
`unseenCompletionLedger.clear(registration.taskIds)`. Do **not** add
|
|
100
|
+
clearing to the watcher notifier: late `shepherd_watch` deliveries never
|
|
101
|
+
reach it (verified against `TaskWatcherService.watch` and
|
|
102
|
+
`verify-task-watchers.mjs`).
|
|
103
|
+
- In the `close` action, after `runtime.close(id)` succeeds:
|
|
104
|
+
`const cleared = unseenCompletionLedger.clearForAgent(handle.id)` and
|
|
105
|
+
append a report line/details when `cleared.length > 0`.
|
|
106
|
+
|
|
107
|
+
Wiring in `index.ts` (after `if (process.env.PI_SHEPHERD_SESSION) return;`
|
|
108
|
+
and `registerShepherdTools(pi)`, line ~447):
|
|
109
|
+
|
|
110
|
+
- `configureUnseenCompletionBridge(pi);`
|
|
111
|
+
- Not inside `registerShepherdTools` (six suites pass fakes without `on`
|
|
112
|
+
and with renderer allow-lists).
|
|
113
|
+
|
|
114
|
+
## Stage 3 — Tests, docs, verification
|
|
115
|
+
|
|
116
|
+
- `test/verify-unseen-completions.mjs` (created in Stage 1 for core cases,
|
|
117
|
+
extended here):
|
|
118
|
+
- ledger: cancelled excluded; had-watchers excluded;
|
|
119
|
+
delegate-submission-failure excluded; dedupe; drain; `clear` /
|
|
120
|
+
`clearForAgent` return ids; `clearAll`.
|
|
121
|
+
- observer: settle with watcher → `hadWatchers: true`; without → `false`
|
|
122
|
+
+ agent/label; `source` passthrough; listener throw does not break
|
|
123
|
+
`settleTask`; unsubscribe works.
|
|
124
|
+
- bridge with a fake pi surface (capture `on`,
|
|
125
|
+
`registerMessageRenderer`, `sendMessage` like
|
|
126
|
+
`test/verify-parent-surface.mjs`): idle burst → exactly one
|
|
127
|
+
`triggerTurn` send and no duplicates; busy settle → single
|
|
128
|
+
`agent_before_settle` result with `continue: true`; second boundary →
|
|
129
|
+
`undefined`; `aborted` outcome → no continuation; a completed boundary
|
|
130
|
+
with `canContinue: false` (pi's real pre-entry shape) → still
|
|
131
|
+
continues; late `shepherd_watch` clears (assert through the real watch
|
|
132
|
+
action or a direct `clear`); close clears and reports; renderer
|
|
133
|
+
registered; fake pi without `sendMessage` never throws; unsubscribe on
|
|
134
|
+
`session_shutdown`.
|
|
135
|
+
- Use injected `coalesceMs` and an isolated ledger instance to keep the
|
|
136
|
+
suite deterministic.
|
|
137
|
+
- Register `unseen-completions:test` in `package.json` and append it to
|
|
138
|
+
the `test` chain.
|
|
139
|
+
- Full `npm test` green with all existing suites untouched.
|
|
140
|
+
- Docs: README `### Delegate, then watch` gains the no-watcher notice
|
|
141
|
+
paragraph; `docs/guides/tool-reference.md` `shepherd_watch` entry notes
|
|
142
|
+
that unwatched settlements surface at the next settle boundary or as one
|
|
143
|
+
idle wake, and that `shepherd_watch` still retrieves settled tasks
|
|
144
|
+
synchronously. While there, fix the pre-existing "delivered as
|
|
145
|
+
follow-ups" wording in the `shepherd_watch` description
|
|
146
|
+
(`docs/guides/tool-reference.md`, `src/extension/shepherd.ts` ~1570) to
|
|
147
|
+
match the actual `steer` delivery.
|
|
148
|
+
- Live smoke (throwaway script): delegate to a real agent without a watch,
|
|
149
|
+
confirm the boundary notice + retrieval command; confirm `shepherd_watch`
|
|
150
|
+
returns the result and no duplicate notice follows.
|
|
151
|
+
|
|
152
|
+
## Risks and decisions
|
|
153
|
+
|
|
154
|
+
- **pi boundary continuation safety** — guarded by the pending → drained
|
|
155
|
+
transition; a second boundary with no new entries returns `undefined`.
|
|
156
|
+
- **Boundary `valid: false` drop window** — entries are drained when handed
|
|
157
|
+
to pi; a pi-side rejection is not retried (documented residual). The
|
|
158
|
+
entry is a well-formed `CustomMessageEntryDraft`, so rejection is
|
|
159
|
+
unlikely.
|
|
160
|
+
- **Busy/idle desync** — `agent_settled` always transitions to idle and
|
|
161
|
+
re-checks pending entries, so a missed boundary (abort/error) still
|
|
162
|
+
yields one idle wake; `ctx.isIdle()` is preferred when available.
|
|
163
|
+
- **Delegate failure false positive** — eliminated by the
|
|
164
|
+
`delegate-submission-failure` source tag.
|
|
165
|
+
- **Send failure** — synchronous throw keeps entries pending; no unbounded
|
|
166
|
+
retry. `sendMessage` has no return value, so an async failure inside pi is
|
|
167
|
+
invisible (same as existing bridges).
|
|
168
|
+
- **Race: watcher registers between drain and flush** — `clear` in the
|
|
169
|
+
watch action removes the entry; a notice already sent can list a just
|
|
170
|
+
retrieved entry, which is harmless (the model still has the result). No
|
|
171
|
+
locking added.
|
|
172
|
+
- **Close drops pending entries** — reported in the close tool result so
|
|
173
|
+
nothing vanishes silently.
|
|
174
|
+
- **No persistence** — a parent restart drops the ledger with the
|
|
175
|
+
session-scoped registry; recovery for orphaned children is unchanged and
|
|
176
|
+
outside this spec.
|
|
177
|
+
- **Existing suites** — subscription is session-scoped and the busy-pi
|
|
178
|
+
flush checks the `sendMessage` surface, so suites that settle tasks with
|
|
179
|
+
fake pi objects never break.
|
|
180
|
+
|
|
181
|
+
## Verification gates
|
|
182
|
+
|
|
183
|
+
1. Stage 1 + 2 unit suites green.
|
|
184
|
+
2. Full `npm test` green, existing suites untouched.
|
|
185
|
+
3. Live smoke passes (notice delivered, retrieval works, no duplicate).
|
|
186
|
+
4. No new dependencies; no tool schema, prompt, or settings diff.
|
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
# Unwatched completion notice
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Reviewed specification (reviewer pass 2026-10-18 folded in, see journal).
|
|
6
|
+
No behavior change yet. Implements the approved direction in issue #15
|
|
7
|
+
(`bug: unwatched task completions are silently missed`).
|
|
8
|
+
|
|
9
|
+
## Summary
|
|
10
|
+
|
|
11
|
+
A tracked task that settles while the Shepherd has zero watchers is
|
|
12
|
+
currently silent: `settleTask` fans out only to registered watchers
|
|
13
|
+
(`src/runtimes/herdr/orchestration.ts`), so the durable result is never
|
|
14
|
+
surfaced and an idle Shepherd can sleep through it.
|
|
15
|
+
|
|
16
|
+
Add an **unseen-settlement ledger** and a parent-side notice:
|
|
17
|
+
|
|
18
|
+
- **Shepherd busy** → the notice is appended at pi's `agent_before_settle`
|
|
19
|
+
boundary and the handler returns `continue: true` for one extra model
|
|
20
|
+
request. No mid-turn interruption; the batch is read at the point where
|
|
21
|
+
the run would otherwise end.
|
|
22
|
+
- **Shepherd idle** → one coalesced notice sent with
|
|
23
|
+
`pi.sendMessage(..., { triggerTurn: true })`. This is the overnight
|
|
24
|
+
guarantee.
|
|
25
|
+
- **Aborted/errored run** → no boundary continuation; entries stay pending
|
|
26
|
+
and the idle path still delivers them once.
|
|
27
|
+
|
|
28
|
+
`shepherd_watch` stays the explicit, opt-in batching primitive (choose when
|
|
29
|
+
to become observable, choose which set of agents is one wake-up batch).
|
|
30
|
+
`shepherd_delegate` stays subscription-free. Nothing auto-subscribes.
|
|
31
|
+
|
|
32
|
+
## Problem
|
|
33
|
+
|
|
34
|
+
- `src/runtimes/herdr/orchestration.ts` — the task settlement fan-out
|
|
35
|
+
delivers only to `taskWatchers`; with zero watchers the result is durable
|
|
36
|
+
but unobserved.
|
|
37
|
+
- `src/extension/shepherd.ts` — `taskWatcherService.watch(...)` is the only
|
|
38
|
+
subscription point (the `watch` action). `delegate` never subscribes.
|
|
39
|
+
- Incident (issue #15): task `shepherd-task-3a2282a0-1dcb4518-…` settled
|
|
40
|
+
`completed` at 11:50:50 with no watcher; no notification was ever
|
|
41
|
+
delivered; a later explicit `shepherd_watch` recovered it at 11:53.
|
|
42
|
+
- Delivery machinery itself works mid-turn when a watcher exists
|
|
43
|
+
(`TaskWatcherService.flush` → `configureTaskWatcherBridge` →
|
|
44
|
+
`pi.sendMessage` with `steer`), so the gap is purely "no subscriber".
|
|
45
|
+
|
|
46
|
+
## Goals
|
|
47
|
+
|
|
48
|
+
- Every non-cancelled tracked-task settlement that had no watcher at settle
|
|
49
|
+
time is surfaced: delivered at the next boundary, or via one wake when the
|
|
50
|
+
Shepherd is idle.
|
|
51
|
+
- Preserve `watch` flexibility: explicit timing and multi-task batching
|
|
52
|
+
remain the Shepherd's choice; no auto-watch.
|
|
53
|
+
- Overnight safety: an idle Shepherd cannot sleep through a completion
|
|
54
|
+
batch; a busy Shepherd is never interrupted mid-run.
|
|
55
|
+
- Notify once per settlement; no continuation loops; results stay
|
|
56
|
+
retrievable until retrieved or closed.
|
|
57
|
+
- Zero change for watched tasks, legacy prompt watchers, lifecycle timing,
|
|
58
|
+
broker protocol, tool schemas, and settings.
|
|
59
|
+
|
|
60
|
+
## Non-goals
|
|
61
|
+
|
|
62
|
+
- Auto-watch on `delegate` (rejected in issue #15).
|
|
63
|
+
- Child-side `shepherd_done` return changes and a `task_done_ack` envelope
|
|
64
|
+
(deferred in issue #15).
|
|
65
|
+
- Broker envelope/schema changes of any kind.
|
|
66
|
+
- Persisting the ledger across sessions; it is in-memory and session-scoped
|
|
67
|
+
like the task registry.
|
|
68
|
+
- Changes to legacy prompt watchers, watcher delivery mode (`steer`), or
|
|
69
|
+
watcher batching semantics.
|
|
70
|
+
- New model-facing tools; a `shepherd_status` unseen-count is a possible
|
|
71
|
+
follow-up, not part of this spec.
|
|
72
|
+
|
|
73
|
+
## Design
|
|
74
|
+
|
|
75
|
+
### 1. Detection: registry settlement observer
|
|
76
|
+
|
|
77
|
+
Add `onTaskSettled(listener): () => void` to the task registry
|
|
78
|
+
(`src/runtimes/herdr/orchestration.ts`). It fires once per actual
|
|
79
|
+
transition into a terminal task state, after the watcher fan-out, with:
|
|
80
|
+
|
|
81
|
+
- `result`: a shallow copy of the settled `TaskResult`, and
|
|
82
|
+
- `context: { hadWatchers: boolean; agent?: string; label?: string;
|
|
83
|
+
source?: "delegate-submission-failure" }`
|
|
84
|
+
- `hadWatchers` means "at least one watcher callback was invoked for
|
|
85
|
+
this settlement";
|
|
86
|
+
- `agent`/`label` come from the settled agent's handle so the notice can
|
|
87
|
+
name the sheep without a registry lookup;
|
|
88
|
+
- `source` lets callers mark settlements that are not unseen-at-source
|
|
89
|
+
(see below).
|
|
90
|
+
|
|
91
|
+
- The observer is inert until subscribed; no existing call site changes
|
|
92
|
+
behavior.
|
|
93
|
+
- Listener errors must never affect settlement (same discipline as the
|
|
94
|
+
existing watcher callbacks).
|
|
95
|
+
- Prompt (legacy) settlements are not observed.
|
|
96
|
+
- **Delegate submission failure is not an unseen completion.** When
|
|
97
|
+
`delegateAgent` fails before the child ever receives the task, it settles
|
|
98
|
+
the task `failed` and throws; the Shepherd already sees the error in the
|
|
99
|
+
`shepherd_delegate` tool result. That settle path passes
|
|
100
|
+
`source: "delegate-submission-failure"` and the ledger ignores it.
|
|
101
|
+
- The hook is a registry capability, not one of the seven
|
|
102
|
+
`ShepherdRuntime` methods. When the durable runtime lands (spec 006,
|
|
103
|
+
Phase 1+), its registry equivalent must expose `onTaskSettled` with the
|
|
104
|
+
same semantics; the extension subscribes through the active runtime's
|
|
105
|
+
registry instead of importing the Herdr module directly.
|
|
106
|
+
|
|
107
|
+
### 2. Ledger: `src/core/unseen-completions.ts`
|
|
108
|
+
|
|
109
|
+
A small pure module exporting `UnseenCompletionLedger` plus a module-level
|
|
110
|
+
singleton `unseenCompletionLedger`, matching the `taskWatcherService`
|
|
111
|
+
precedent. It must import nothing from `@earendil-works/*`,
|
|
112
|
+
`src/runtimes/`, or `src/extension/`; it defines its own structural result
|
|
113
|
+
shape so it never depends on the Herdr runtime:
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
export interface UnseenSettlement {
|
|
117
|
+
taskId: string;
|
|
118
|
+
agentId: string;
|
|
119
|
+
agent?: string;
|
|
120
|
+
label?: string;
|
|
121
|
+
status: "completed" | "blocked" | "failed" | "timed_out";
|
|
122
|
+
ok: boolean;
|
|
123
|
+
returnCode: number;
|
|
124
|
+
text?: string;
|
|
125
|
+
error?: string;
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
The ledger is a **queue of settlements that have not yet been noticed**,
|
|
130
|
+
keyed by `taskId`, in insertion order. Entries exist only while un-noticed;
|
|
131
|
+
notifying (boundary or idle) drains them. API:
|
|
132
|
+
|
|
133
|
+
- `record(result, { hadWatchers, agent?, label?, source? }): boolean` — adds
|
|
134
|
+
only when `hadWatchers === false`, `source !== "delegate-submission-failure"`,
|
|
135
|
+
`result.status !== "cancelled"`, and no entry exists. Returns whether a
|
|
136
|
+
new entry was added.
|
|
137
|
+
- `pending(): ReadonlyArray<UnseenSettlement>` — un-noticed entries in
|
|
138
|
+
insertion order.
|
|
139
|
+
- `drain(taskIds: string[]): void` — called after a notice was successfully
|
|
140
|
+
handed to pi (boundary entry appended / idle send returned).
|
|
141
|
+
- `clear(taskIds: string[]): string[]` — retrieval; returns removed ids.
|
|
142
|
+
- `clearForAgent(agentId: string): string[]` — close; returns removed ids
|
|
143
|
+
so the close tool result can report what was dropped.
|
|
144
|
+
- `clearAll(): void` — session lifecycle.
|
|
145
|
+
|
|
146
|
+
Excluded: parent-initiated cancellations (`shepherd_close` → `cancelled`)
|
|
147
|
+
and delegate submission failures. Included: `completed`, `blocked`,
|
|
148
|
+
`failed`, `timed_out`.
|
|
149
|
+
|
|
150
|
+
### 3. Notice content
|
|
151
|
+
|
|
152
|
+
Custom message `customType: "shepherd.task.unseen"`, `display: true`,
|
|
153
|
+
`details: { taskIds, settlements }`:
|
|
154
|
+
|
|
155
|
+
```text
|
|
156
|
+
Shepherd notice — N task(s) settled with no watcher attached:
|
|
157
|
+
- shepherd-task-… (worker "label"): completed — summary
|
|
158
|
+
- shepherd-task-… (reviewer): failed — error
|
|
159
|
+
Full results: shepherd_watch({ id: [ "id", ... ] })
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
- `details` uses `settlements`, not `completions`: the generic collapsed
|
|
163
|
+
formatter (`formatCollapsedNotification` in `src/extension/shepherd.ts`)
|
|
164
|
+
special-cases `details.completions` with watcher wording, which would
|
|
165
|
+
replace the notice text in collapsed view.
|
|
166
|
+
- The custom type gets its own renderer (via the existing
|
|
167
|
+
`renderShepherdNotification` helper, which must be exported from
|
|
168
|
+
`shepherd.ts` for that purpose); the renderer formats from `settlements`
|
|
169
|
+
and never falls through to the watcher formatter.
|
|
170
|
+
- The wording must say "no watcher attached", never "never retrievable": a
|
|
171
|
+
watcher registered after settlement still receives the result
|
|
172
|
+
synchronously. The notice never claims the result is lost.
|
|
173
|
+
|
|
174
|
+
### 4. Delivery policy
|
|
175
|
+
|
|
176
|
+
New extension bridge `src/extension/unseen-completions.ts`,
|
|
177
|
+
`configureUnseenCompletionBridge(pi, options?)`.
|
|
178
|
+
|
|
179
|
+
- **Wiring point:** called from `index.ts` after the
|
|
180
|
+
`PI_SHEPHERD_SESSION` worker guard, next to `registerShepherdTools(pi)`
|
|
181
|
+
— *not* inside `registerShepherdTools`. Six existing suites call
|
|
182
|
+
`registerShepherdTools` with fake pi objects that have no `on` and an
|
|
183
|
+
allow-list of renderer custom types (`verify-tool-schemas.mjs`,
|
|
184
|
+
`verify-compat.mjs`, `verify-delegate.mjs`, `verify-stale-wait.mjs`,
|
|
185
|
+
`verify-task-watchers.mjs`, `verify-watchers.mjs`); wiring there would
|
|
186
|
+
break them. The index factory is exercised by suites that already pass
|
|
187
|
+
`on` + `registerMessageRenderer` and is the real parent surface.
|
|
188
|
+
- **Session-scoped activation:** the bridge registers the `onTaskSettled`
|
|
189
|
+
subscription on `session_start` and releases it on `session_shutdown`; a
|
|
190
|
+
process that only imports the factory and settles tasks without a
|
|
191
|
+
session never records anything. Re-subscription is idempotent
|
|
192
|
+
(repeated `session_start` keeps one subscription).
|
|
193
|
+
- **Options:** `{ coalesceMs?, ledger? }`, defaulting to
|
|
194
|
+
`UNSEEN_NOTICE_COALESCE_MS = 250` and the `unseenCompletionLedger`
|
|
195
|
+
singleton, so tests can inject small timings and an isolated ledger.
|
|
196
|
+
- **Idle detection:** the bridge tracks busy/idle from `agent_start` →
|
|
197
|
+
busy, `agent_settled` → idle, `session_start` → idle, and prefers
|
|
198
|
+
`ctx.isIdle()` from the captured lifecycle context when available
|
|
199
|
+
(`ExtensionContext.isIdle()`, pi types line 236). `pi.sendMessage` during
|
|
200
|
+
the run-start window joins the starting run, so the fallback is safe.
|
|
201
|
+
- **Surface guard:** `flush` no-ops unless `pi.sendMessage` is a function;
|
|
202
|
+
the fake-pi suites stay safe even if a timer fires.
|
|
203
|
+
|
|
204
|
+
Idle wake:
|
|
205
|
+
|
|
206
|
+
- `record()` returning true while idle schedules one debounced flush. A
|
|
207
|
+
burst produces exactly one `pi.sendMessage(notice, { triggerTurn: true })`
|
|
208
|
+
covering all pending entries; entries are drained after the call returns
|
|
209
|
+
without throwing.
|
|
210
|
+
- If the timer fires while busy, it does nothing; the boundary path owns
|
|
211
|
+
delivery.
|
|
212
|
+
- Delivery is best-effort: `pi.sendMessage` returns `void`, so only a
|
|
213
|
+
synchronous throw is observable; that throw leaves entries pending so a
|
|
214
|
+
later boundary/wake retries. Rejections and async failures inside pi are
|
|
215
|
+
invisible and are not retried (consistent with the existing bridges).
|
|
216
|
+
- `session_shutdown` clears the timer; pending entries are dropped with the
|
|
217
|
+
session-scoped ledger.
|
|
218
|
+
|
|
219
|
+
Boundary continuation:
|
|
220
|
+
|
|
221
|
+
- `pi.on("agent_before_settle", event)` — when `event.outcome ===
|
|
222
|
+
"completed"` and pending entries exist, build one
|
|
223
|
+
`custom_message` entry, drain those task ids, and return
|
|
224
|
+
`{ entries: [entry], continue: true }`.
|
|
225
|
+
- Aborted/errored runs return no continuation. In real pi an aborted run
|
|
226
|
+
generally never reaches the boundary; this guard is defense-in-depth and
|
|
227
|
+
the idle path is the actual catch-all.
|
|
228
|
+
- The pre-entry `event.context` is not authoritative, so the handler always
|
|
229
|
+
offers the continuation for a completed run with pending entries. pi
|
|
230
|
+
builds that snapshot from the entries that existed before the handler
|
|
231
|
+
ran, so it is non-continuable at a completed boundary; pi then commits
|
|
232
|
+
the returned drafts and decides. A committed `custom_message` projects
|
|
233
|
+
through `convertToLlm` as a user-role message, so the run continues. If
|
|
234
|
+
pi still declines, the entry is already committed (rendered, not lost).
|
|
235
|
+
See #16.
|
|
236
|
+
- pi may discard a boundary result it considers invalid (the runner's
|
|
237
|
+
`valid: false` window). Our entry is a well-formed
|
|
238
|
+
`CustomMessageEntryDraft`, so this is a rare residual: entries are
|
|
239
|
+
drained when handed to pi and are not re-notified if pi rejects the
|
|
240
|
+
result. This is documented, not retried.
|
|
241
|
+
- Loop safety: only the pending → drained transition produces a
|
|
242
|
+
continuation; a second boundary with no pending entries returns
|
|
243
|
+
`undefined`.
|
|
244
|
+
|
|
245
|
+
### 5. Clearing
|
|
246
|
+
|
|
247
|
+
- **Watch action** (`src/extension/shepherd.ts`, `watch` case):
|
|
248
|
+
`unseenCompletionLedger.clear(registration.taskIds)` after
|
|
249
|
+
`taskWatcherService.watch(...)` returns. This is the authoritative
|
|
250
|
+
retrieval clear. It must not rely on the watcher notifier: for an
|
|
251
|
+
already-settled task `watchTasks` delivers inline inside
|
|
252
|
+
`TaskWatcherService.watch` *before* `watcherId` is assigned, so the
|
|
253
|
+
queued delivery is dropped (`lifecycle.ts` `queue()` early-returns on an
|
|
254
|
+
empty watcher id) and the notifier never sees it
|
|
255
|
+
(`test/verify-task-watchers.mjs` already asserts that).
|
|
256
|
+
- **Close action:** after a successful `runtime.close(id)`, call
|
|
257
|
+
`clearForAgent(handle.id)`; if it removed entries, the close tool result
|
|
258
|
+
reports the dropped task ids (the Shepherd can `shepherd_watch` them
|
|
259
|
+
before closing instead).
|
|
260
|
+
- `session_start` and `session_shutdown`: `clearAll()`.
|
|
261
|
+
- Pending entries are removed by retrieval, close, or session end. There is
|
|
262
|
+
no second chance after a notice: a noticed entry is gone from the ledger.
|
|
263
|
+
|
|
264
|
+
### 6. Invariants
|
|
265
|
+
|
|
266
|
+
- Settlement is authoritative; the ledger and notice never change task
|
|
267
|
+
state and never invent a completion.
|
|
268
|
+
- The settlement observer cannot slow or break settlement.
|
|
269
|
+
- Watched deliveries are byte-for-byte unchanged (mid-turn `steer`).
|
|
270
|
+
- No `continue: true` after an aborted or errored run.
|
|
271
|
+
- Notify-once per entry: no duplicate notices, no continuation loops.
|
|
272
|
+
- No tool-schema, prompt, settings, broker, or fieldnote changes.
|
|
273
|
+
- `registerShepherdTools` behavior is unchanged; all existing suites pass
|
|
274
|
+
untouched.
|
|
275
|
+
- The ledger does not record while no parent pi session is active; session
|
|
276
|
+
teardown clears it.
|
|
277
|
+
|
|
278
|
+
## Compatibility
|
|
279
|
+
|
|
280
|
+
- Existing `verify-*.mjs` suites pass untouched.
|
|
281
|
+
- Herdr-only installs keep working with no new dependencies and no
|
|
282
|
+
settings.
|
|
283
|
+
- The observer hook is additive; `settleTask` behavior without a subscriber
|
|
284
|
+
is identical.
|