@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,141 @@
|
|
|
1
|
+
# Spec — hc background poll
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Proposed. No behavior change yet. Direct continuation of 010: the settle
|
|
6
|
+
path is converged, but nothing *triggers* it promptly on hc. Spec-only:
|
|
7
|
+
no `src` changes in this spec; implementation follows one worker per
|
|
8
|
+
phase (see `plan.md`).
|
|
9
|
+
|
|
10
|
+
## Background: the gap
|
|
11
|
+
|
|
12
|
+
010 proved the ledger/observer/notice contract on both backends, and
|
|
13
|
+
Phase 3 made the deadline timer drain-first. The remaining hole is what
|
|
14
|
+
*pumps* the drain on hc:
|
|
15
|
+
|
|
16
|
+
- Herdr: `startParentBrokerMonitor()` (`src/runtimes/herdr/lifecycle.ts`
|
|
17
|
+
~line 84) runs `processParentBrokerMessages()` every 250 ms, unref'd,
|
|
18
|
+
from broker creation until shutdown. Tool calls never need to drain;
|
|
19
|
+
completions settle within ~250 ms of arrival, watchers fire, the
|
|
20
|
+
unseen bridge notices.
|
|
21
|
+
- hc: `drainBrokerInbox()` (`src/runtimes/hc/runtime.ts`) runs only
|
|
22
|
+
inside `message`, the `watch` blocking loop, and the delegate
|
|
23
|
+
deadline timer. The extension's `watch` action uses the non-blocking
|
|
24
|
+
`hcTaskWatcherService.watch` (no drain) and `status` uses
|
|
25
|
+
`describeHcStatusView` (no drain).
|
|
26
|
+
|
|
27
|
+
Live evidence (010 smoke-1): `task_done` + `reply` sat in
|
|
28
|
+
`parent/inbox` ~10 minutes across several `status`/`watch` calls; only
|
|
29
|
+
the deadline timer's drain settled them (`completed`, done beat
|
|
30
|
+
timeout — the Phase 3 guarantee working as a backstop). With the
|
|
31
|
+
default 60-minute delegate timeout, an idle hc parent could wait an
|
|
32
|
+
hour for a completion it already holds.
|
|
33
|
+
|
|
34
|
+
A second, smaller defect rides along: `applyMessageEnvelope` resolves
|
|
35
|
+
its own broker with a bare `ensureBroker()` (no session id), which —
|
|
36
|
+
when that helper runs outside a session-keyed drain — mints a
|
|
37
|
+
fallback-keyed junk broker (`hc-parent-<gen>`), replaces the module
|
|
38
|
+
broker, orphans the session mailbox for later drains, and addresses
|
|
39
|
+
reply relays to a store the child never polls (010 journal: junk dirs
|
|
40
|
+
`AyfED1`, `84O93R`). Any background poller must never do this: it must
|
|
41
|
+
drain through the session-keyed broker only.
|
|
42
|
+
|
|
43
|
+
## Contract
|
|
44
|
+
|
|
45
|
+
### 1. Background drain while work is open
|
|
46
|
+
|
|
47
|
+
The hc runtime runs one background poll while delegated work may still
|
|
48
|
+
settle:
|
|
49
|
+
|
|
50
|
+
- Interval 250 ms, matching Herdr. Single timer per process, idempotent
|
|
51
|
+
start, `unref`'d so it never keeps the host alive.
|
|
52
|
+
- Started on the first `delegate` (first open task — before that no
|
|
53
|
+
completion can arrive); stopped when zero unsettled tasks remain.
|
|
54
|
+
A later `delegate` restarts it. Stopped on module shutdown alongside
|
|
55
|
+
the existing `shutdownHcStaleWaitMonitor` /
|
|
56
|
+
`shutdownHcTaskWatchers` seams.
|
|
57
|
+
- Each tick calls exactly the existing `drainBrokerInbox()` (which
|
|
58
|
+
already ends with `settleDueReplyTimeouts()`). Synchronous poll;
|
|
59
|
+
a tick never overlaps the previous one in a way tool-call drains
|
|
60
|
+
don't already handle (all drains are idempotent; settlement is
|
|
61
|
+
first-wins per 010 §3).
|
|
62
|
+
- No session-identity drift, ever: the tick drains through the same
|
|
63
|
+
session-keyed broker the tool calls use. It must not call bare
|
|
64
|
+
`ensureBroker()` (see §3).
|
|
65
|
+
|
|
66
|
+
### 2. Observable behavior
|
|
67
|
+
|
|
68
|
+
- `delegate` with no `watch` and no `message` settles within ~1 s of
|
|
69
|
+
child `shepherd_done` while the poller runs (bounded by the 250 ms
|
|
70
|
+
tick, not by the delegate deadline).
|
|
71
|
+
- `watch` registration and `status` drain first, then report: an
|
|
72
|
+
already-settled task returns `completed` synchronously instead of
|
|
73
|
+
`pending`. Return shapes are unchanged, only the staleness is gone.
|
|
74
|
+
(Decision: drain-first AND the background poll. Drain-first covers
|
|
75
|
+
active parents at read time; the poll covers idle parents that make
|
|
76
|
+
no calls at all — without it an idle Shepherd would still wait for
|
|
77
|
+
the delegate deadline, up to the 60-minute default, before anything
|
|
78
|
+
settles and the unseen notice fires. Herdr has both; parity needs
|
|
79
|
+
both.)
|
|
80
|
+
- The unseen-notice contract (007/010) is unchanged; notices now fire
|
|
81
|
+
promptly instead of at the deadline. No new entry kinds, no new
|
|
82
|
+
timing guarantees beyond "tick-bounded".
|
|
83
|
+
- No new broker dirs, no new diagnostics, no retained timers after
|
|
84
|
+
quiescence/shutdown. The process exits exactly as before with no
|
|
85
|
+
open work.
|
|
86
|
+
|
|
87
|
+
### 3. Bare-`ensureBroker` hardening
|
|
88
|
+
|
|
89
|
+
`applyMessageEnvelope` already takes the drain's `active` broker (010
|
|
90
|
+
follow-up fix). The same rule becomes an invariant: **no settle-path
|
|
91
|
+
code may resolve a broker without the caller's session id.** The
|
|
92
|
+
background tick uses the session-keyed broker; if no session broker
|
|
93
|
+
can be resolved (no session context — e.g., after shutdown), the tick
|
|
94
|
+
skips instead of minting a fallback store.
|
|
95
|
+
|
|
96
|
+
Deliberate asymmetry (review resolution): `registerHcPollSession`
|
|
97
|
+
resolves through `ownerSessionKey` and never skips — the tick must poll
|
|
98
|
+
the same store the tool drains use (explicit id, env session, or the
|
|
99
|
+
process fallback). `drainHcInboxForSession` skips on blank ids instead:
|
|
100
|
+
a read path must never create state. Consequence: env-session runtimes
|
|
101
|
+
get background drains with no matching drain-first reads (the
|
|
102
|
+
registered key still matches the tool-call store, so settlement is
|
|
103
|
+
correct; only the read-side freshness guarantee rests on the tick
|
|
104
|
+
alone). Rejected-completion diagnostics are written beside the drain's
|
|
105
|
+
own `active` broker, never the module-cached one.
|
|
106
|
+
|
|
107
|
+
### 4. Verification: deterministic, no live spawn
|
|
108
|
+
|
|
109
|
+
- Unit-tick seam: the poller exposes start/stop plus a synchronous
|
|
110
|
+
single-tick entry (same precedent as 010 Phase 0 exporting the
|
|
111
|
+
observer call for testability), so suites drive it without
|
|
112
|
+
wall-clock waits and without live terminals.
|
|
113
|
+
- New suite file (e.g., `test/verify-hc-poll.mjs`), wired into
|
|
114
|
+
`package.json` scripts + the `test` chain: tick with queued
|
|
115
|
+
`task_done` settles it; tick with empty inbox is a no-op; timer
|
|
116
|
+
starts on delegate and stops at quiescence; no fallback broker is
|
|
117
|
+
ever minted by the tick; `unref` is set so the timer can't hold the
|
|
118
|
+
process open.
|
|
119
|
+
- Live smoke (throwaway, both runtimes for contrast): delegate with no
|
|
120
|
+
watch and no message; Herdr settles in ~250 ms as today, hc now too
|
|
121
|
+
(previously hc waited for a message or the deadline).
|
|
122
|
+
|
|
123
|
+
## Non-goals
|
|
124
|
+
|
|
125
|
+
- Changing `watch` (still non-blocking registration), `status` (still a
|
|
126
|
+
view), watcher batching, legacy prompt paths, or notice semantics.
|
|
127
|
+
- Persisting timers/ledgers across sessions; new settings (the 250 ms
|
|
128
|
+
interval is fixed, mirroring Herdr — not configurable).
|
|
129
|
+
- Touching the Herdr poller, the broker transport, envelopes, or
|
|
130
|
+
fieldnotes.
|
|
131
|
+
- Retrying failed drains, backoff, jitter, or adaptive intervals.
|
|
132
|
+
|
|
133
|
+
## Invariants (007/010 carried forward)
|
|
134
|
+
|
|
135
|
+
- Settlement is authoritative; the tick never settles directly and
|
|
136
|
+
never invents a completion.
|
|
137
|
+
- First-wins ordering unchanged (010 §3); `cancelled` still excluded;
|
|
138
|
+
`delegate-submission-failure` still excluded.
|
|
139
|
+
- Watched deliveries byte-for-byte unchanged; no new wake kinds.
|
|
140
|
+
- No tool-schema, prompt, settings, broker, or fieldnote changes.
|
|
141
|
+
- Existing suites pass untouched.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Tasks — 011 hc background poll
|
|
2
|
+
|
|
3
|
+
Work in order. One worker per phase — phases run strictly sequential (the
|
|
4
|
+
timer touches the drain/settle seam 010 just stabilized). A task is done
|
|
5
|
+
only when its implementation + verification are complete. This spec is
|
|
6
|
+
`011-hc-background-poll` (spec.md contract, plan.md design). Continues
|
|
7
|
+
010, converges hc onto the Herdr promptness contract.
|
|
8
|
+
|
|
9
|
+
**This task is spec-only: no `src` changes.** The checkboxes below bind
|
|
10
|
+
the later implementation.
|
|
11
|
+
|
|
12
|
+
## Overnight run + testing (no reload)
|
|
13
|
+
|
|
14
|
+
- The main Pi session cannot reload extensions, so never rely on in-place
|
|
15
|
+
reload for live verification (same rule as 009/010).
|
|
16
|
+
- For live tests needing new code: `hc run --bg` a fresh herdr-core agent
|
|
17
|
+
(full `pi` path), then have that child call `shepherd_*`
|
|
18
|
+
(`spawn`/`delegate`/`watch`/`done`) to spawn agents — a fresh Pi session
|
|
19
|
+
with updated code.
|
|
20
|
+
- Keep `npm test` green in the current session for unit checks; use the
|
|
21
|
+
fresh `hc` child only for live spawn/delegate/watch proof.
|
|
22
|
+
|
|
23
|
+
## Phase 0 — poller wiring + drain-first watch/status
|
|
24
|
+
|
|
25
|
+
- [x] **0.1 Background poller in the hc runtime**
|
|
26
|
+
- In `src/runtimes/hc/runtime.ts`: module timer (250 ms fixed,
|
|
27
|
+
`unref`'d, idempotent start), started on first `delegate`, stopped
|
|
28
|
+
when zero unsettled tasks remain, restarted by the next `delegate`,
|
|
29
|
+
stopped on module shutdown alongside `shutdownHcTaskWatchers` /
|
|
30
|
+
`shutdownHcStaleWaitMonitor`.
|
|
31
|
+
- Each tick calls exactly the existing `drainBrokerInbox()`; no new
|
|
32
|
+
settle logic, no reordering, no invented completions.
|
|
33
|
+
- Session-keyed broker only: the tick never calls bare
|
|
34
|
+
`ensureBroker()`; audit every settle-path call site so each passes
|
|
35
|
+
a session id (grep must show no bare settle-path calls left).
|
|
36
|
+
- Export start/stop + a synchronous tick entry for tests (name TBD;
|
|
37
|
+
precedent: 010 Phase 0 exporting the observer call).
|
|
38
|
+
|
|
39
|
+
- [x] **0.2 Drain-first hc watch registration + status view**
|
|
40
|
+
- `shepherd_watch` (hc path): drain first via the session-keyed
|
|
41
|
+
`drainBrokerInbox`, then the existing non-blocking
|
|
42
|
+
`hcTaskWatcherService.watch`. Already-settled tasks report
|
|
43
|
+
`completed` synchronously; return shapes unchanged.
|
|
44
|
+
- `describeHcStatusView`: drain first for the same reason (stale
|
|
45
|
+
`running` for settled tasks goes away).
|
|
46
|
+
- The background poll stays required: it covers idle parents that
|
|
47
|
+
make no calls (drain-first alone would still leave them
|
|
48
|
+
deadline-bound).
|
|
49
|
+
|
|
50
|
+
- [x] **0.3 Verify Phase 0**
|
|
51
|
+
- `npm test` green; no existing suite modified.
|
|
52
|
+
- No fallback broker is minted by any settle-path call (source audit
|
|
53
|
+
+ unit probe); timer is `unref`'d; start is idempotent; stop fires
|
|
54
|
+
at quiescence.
|
|
55
|
+
|
|
56
|
+
## Phase 1 — verification, docs, landing
|
|
57
|
+
|
|
58
|
+
- [x] **1.1 Deterministic suite** (`test/verify-hc-poll.mjs`, wired into
|
|
59
|
+
`package.json` scripts + the `test` chain)
|
|
60
|
+
- Tick with a queued `task_done` settles it through the 010 observer
|
|
61
|
+
path (single winner, transcript readable); tick with an empty inbox
|
|
62
|
+
is a no-op; tick with no session context skips without minting a
|
|
63
|
+
store.
|
|
64
|
+
- Timer starts on `delegate`, stops at zero unsettled tasks,
|
|
65
|
+
restarts on the next `delegate`; `unref` set (cannot hold the
|
|
66
|
+
process open).
|
|
67
|
+
- Deterministic: exported tick seam, isolated ledger/registry, fake
|
|
68
|
+
pi surface where needed, no live spawn, no wall-clock waits.
|
|
69
|
+
|
|
70
|
+
- [x] **1.2 Docs + live proof**
|
|
71
|
+
- One-row note where 007/010 documented the notice (README `###
|
|
72
|
+
Delegate, then watch` paragraph + `docs/guides/tool-reference.md`
|
|
73
|
+
`shepherd_watch` entry): hc completions now settle tick-promptly
|
|
74
|
+
even with no `watch` and no `message`.
|
|
75
|
+
- Live smoke (throwaway script, both backends): delegate with no
|
|
76
|
+
watch and no message; Herdr settles in ~250 ms as today, hc now in
|
|
77
|
+
~1 s (previously waited for a message or the deadline); no junk
|
|
78
|
+
broker dirs; close drops + reports as before.
|
|
79
|
+
|
|
80
|
+
- [x] **1.3 Full suite + landing**
|
|
81
|
+
- `npm test` green with all existing suites untouched.
|
|
82
|
+
- Record scope, evidence, and the landing note in a `journal.md`
|
|
83
|
+
before merging (follow the 007/010 journal precedent).
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Intent — 012 steer default
|
|
2
|
+
|
|
3
|
+
Parent→child and peer messages that omit `delivery` currently arrive
|
|
4
|
+
as `followUp` (queue passively). Observed live (011 Track C): a
|
|
5
|
+
followUp request to an idle hc child sat queued for minutes; the
|
|
6
|
+
steer retry completed promptly. Sheep are task-driven — a message to
|
|
7
|
+
one is almost always actionable — so the passive default is
|
|
8
|
+
backwards. Child→parent already upgrades wake-deserving messages to
|
|
9
|
+
steer (`parentMessageDeliveryOptions`); this aligns the other
|
|
10
|
+
direction. Every intentionally-passive internal sender (nudges,
|
|
11
|
+
stale bridges, herdr task publish) already passes explicit
|
|
12
|
+
`followUp`, so only agent-authored messages change behavior.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Journal — 012 steer default
|
|
2
|
+
|
|
3
|
+
## Scope
|
|
4
|
+
|
|
5
|
+
One user sentence ("default should be steer") → compact spec, six
|
|
6
|
+
ternary flips, one suite pin, live proof, land.
|
|
7
|
+
|
|
8
|
+
## What changed
|
|
9
|
+
|
|
10
|
+
- `deliveryMode()` inverted (child-side choke point).
|
|
11
|
+
- hc: three envelope stamps + the direct-terminal send (now
|
|
12
|
+
`--force` by default) inverted. The forcesend matches what the
|
|
13
|
+
explicit-steer C1b run already proved prompt.
|
|
14
|
+
- herdr: both `sendParentMessage` stamps inverted.
|
|
15
|
+
- Parent schema description + hc-path `returnValue` fallback report
|
|
16
|
+
the effective default.
|
|
17
|
+
- `test/verify-message-routing.mjs`: the plain-message default pin
|
|
18
|
+
`followUp` → `steer` (the one pin that contradicted the spec).
|
|
19
|
+
|
|
20
|
+
## Design notes
|
|
21
|
+
|
|
22
|
+
- The wake (`triggerTurn`) stays kind-driven and untouched; only
|
|
23
|
+
interruption urgency changed. Child→parent already steered
|
|
24
|
+
wake-deserving messages — this aligns the other direction.
|
|
25
|
+
- Choke-point correction: the first cut assumed `deliveryMode` was
|
|
26
|
+
the single default site; the runtimes stamp their own. All six
|
|
27
|
+
found by grep, all flipped.
|
|
28
|
+
- Deliberate trade recorded in spec §1: flagless FYI now interrupts.
|
|
29
|
+
Say `followUp` for passivity.
|
|
30
|
+
- Live proof limits: the C2-omitted run proves the child-side
|
|
31
|
+
default (fresh child processes build their own envelopes).
|
|
32
|
+
Post-reload C1-omitted (C4, `mango-69416`): the parent request
|
|
33
|
+
with no flag carried `steer` forensically and completed intact —
|
|
34
|
+
parent-side stamp proven too. All six sites now proven live.
|
|
35
|
+
|
|
36
|
+
## Verification
|
|
37
|
+
|
|
38
|
+
- `npm test` exit 0.
|
|
39
|
+
- Live C2-omitted: crossed `ping-69415`/`pong-69415`, envelopes
|
|
40
|
+
forensically `steer`, zero junk dirs, both sheep closed.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Plan — 012 steer default
|
|
2
|
+
|
|
3
|
+
1. Invert `deliveryMode()` + parent schema description.
|
|
4
|
+
2. `npm test` full; fix only pins that contradict the spec.
|
|
5
|
+
3. Live Track C1 with omitted `delivery` (fresh sheep, new nonce).
|
|
6
|
+
4. Skill one-liner (steer now default, may omit flag) + journal.
|
|
7
|
+
5. Land: branch → merge → push.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Spec — 012 steer default
|
|
2
|
+
|
|
3
|
+
## 1. Behavior
|
|
4
|
+
|
|
5
|
+
- The default `delivery` for `shepherd_message` (parent and child
|
|
6
|
+
surfaces, both runtimes) becomes `steer`. Explicit `followUp` still
|
|
7
|
+
queues passively; explicit `steer` is unchanged.
|
|
8
|
+
- Wake semantics are untouched: `triggerTurn` stays kind-driven
|
|
9
|
+
(`expectsReply` / `replyTo` / task delegation wake; plain chatter
|
|
10
|
+
does not). The change is interruption urgency for busy recipients
|
|
11
|
+
and prompt turn-start for idle ones, not who wakes.
|
|
12
|
+
- Deliberate trade: a plain FYI with no flag now interrupts a busy
|
|
13
|
+
recipient instead of queueing. Senders who want passivity say
|
|
14
|
+
`followUp` explicitly. Rationale: FYI-to-a-sheep is rare; actionable
|
|
15
|
+
traffic is the norm.
|
|
16
|
+
|
|
17
|
+
## 2. Implementation
|
|
18
|
+
|
|
19
|
+
- `deliveryMode()` (`src/extension/shepherd-done.ts`): invert —
|
|
20
|
+
`'followUp'` only when explicitly passed, else `'steer'`. Covers
|
|
21
|
+
child-side ingestion and child-built envelopes on both runtimes.
|
|
22
|
+
- hc stamps (`src/runtimes/hc/runtime.ts`, three envelope sites +
|
|
23
|
+
the direct-terminal `--force` send): invert each ternary. The
|
|
24
|
+
`--force` send now fires by default, matching the prompt-delivery
|
|
25
|
+
intent (proven live in Track C1b).
|
|
26
|
+
- herdr stamps (`src/runtimes/herdr/lifecycle.ts`, expectsReply +
|
|
27
|
+
plain branches): invert both.
|
|
28
|
+
- Parent `shepherd_message` schema description + the hc-path
|
|
29
|
+
`returnValue` fallback (`?? 'steer'`): report the effective default.
|
|
30
|
+
- No changes to explicit `delivery: 'followUp'` senders (nudges,
|
|
31
|
+
stale/task bridges, task-delegation envelopes — delegation wakes
|
|
32
|
+
by kind). No changes to `triggerTurn` logic anywhere.
|
|
33
|
+
|
|
34
|
+
## 3. Verification
|
|
35
|
+
|
|
36
|
+
- Full `npm test` green (no suite pins the default; any that does
|
|
37
|
+
gets updated only if the pin contradicts this spec).
|
|
38
|
+
- Live: skill Track C2 rerun with the `delivery` flag omitted on
|
|
39
|
+
both legs — crossed summaries exact (`ping-69415` / `pong-69415`),
|
|
40
|
+
and broker forensics show both envelopes carried `steer`. (C1 with
|
|
41
|
+
an omitted flag needs a reloaded parent, since the stale session
|
|
42
|
+
stamps the old default; deferred to the next reload.)
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# Tasks — 012 steer default
|
|
2
|
+
|
|
3
|
+
- [x] **0.1** Invert `deliveryMode()`, update parent schema description.
|
|
4
|
+
- [x] **0.2** Full `npm test` green.
|
|
5
|
+
- [x] **0.3** Live C1 with omitted `delivery` completes promptly, code word intact.
|
|
6
|
+
- [x] **0.4** Skill one-liner + journal, land (branch → merge → push).
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# Handoff: T011 live acceptance in OpenCode (human-driven)
|
|
2
|
+
|
|
3
|
+
**Spec:** `specs/013-opencode-shepherd` · **Task:** T011 remainder
|
|
4
|
+
**Date:** 2026-11-17 · **Status:** READY (verified 2026-11-18 morning: loader
|
|
5
|
+
present, fresh server, `shepherd agents` works, registries empty, quota back)
|
|
6
|
+
|
|
7
|
+
## Why human-driven
|
|
8
|
+
|
|
9
|
+
Pi-driven bench sessions (`hc send` into TUIs) proved unreliable for
|
|
10
|
+
acceptance: stale tool catalogs across restarts, 100K+ tokens of confused
|
|
11
|
+
context, and at least one session that faked tool results by re-running
|
|
12
|
+
adapter code via shell. A fresh human-opened session avoids all three and
|
|
13
|
+
matches real usage. The engine code is committed (`820f5da`) and the pi
|
|
14
|
+
suite is green (631 pass); only live OpenCode acceptance remains.
|
|
15
|
+
|
|
16
|
+
## Preconditions (assistant verifies before you start)
|
|
17
|
+
|
|
18
|
+
- [ ] `~/.config/opencode/plugins/shepherd-dev.ts` exists (the dev loader)
|
|
19
|
+
- [ ] Server log shows `loading plugin ... shepherd-dev.ts` with NO
|
|
20
|
+
`failed to load plugin ... shepherd` lines after it
|
|
21
|
+
- [ ] Registries empty: `~/.config/opencode/pi-shepherd/created-terminals.json`
|
|
22
|
+
and `created-panes.json` contain `[]`
|
|
23
|
+
- [ ] Assistant will NOT touch plugin/repo files, restart the server, or
|
|
24
|
+
send anything into your session while you test (coordinate first)
|
|
25
|
+
|
|
26
|
+
## Setup (you)
|
|
27
|
+
|
|
28
|
+
1. Open a **new** terminal, `cd` to the repo
|
|
29
|
+
(`/home/mikkelkp/.pi/agent/extensions/pi-shepherd`), run `opencode`.
|
|
30
|
+
2. Fresh session (new TUI = new session). Do not reuse an old session —
|
|
31
|
+
TUIs hold stale tool catalogs across server restarts.
|
|
32
|
+
3. Sanity check first — paste: `Call the shepherd tool with action agents.
|
|
33
|
+
Report the agent names.`
|
|
34
|
+
Expect 4 agents (reviewer, worker, planner, scout). If the model says
|
|
35
|
+
the tool is unavailable, STOP and tell the assistant (do not let it
|
|
36
|
+
improvise via shell — that invalidates the test).
|
|
37
|
+
|
|
38
|
+
## Test A — basic loop (must pass before B)
|
|
39
|
+
|
|
40
|
+
Paste, one step at a time, waiting for each result:
|
|
41
|
+
|
|
42
|
+
1. `Spawn scout label handA. Report the agent id, stop.`
|
|
43
|
+
2. `Delegate to <agent-id> with task: Reply with the word HAND then call
|
|
44
|
+
shepherd_done with completed. Then watch the task id and report, stop.`
|
|
45
|
+
|
|
46
|
+
**Pass criteria:** watcher completion arrives with status completed and the
|
|
47
|
+
summary mentions HAND. Report back: agent id, task id, watcher text.
|
|
48
|
+
|
|
49
|
+
## Test B — peer question loop (the actual T011 goal)
|
|
50
|
+
|
|
51
|
+
1. `Spawn scout label handB. Report the agent id, stop.`
|
|
52
|
+
2. `Delegate to <handA-id> with task: Ask <handB-id> (label handB) the
|
|
53
|
+
question "What is your label" using shepherd_message. When it replies,
|
|
54
|
+
call shepherd_done with completed and the answer. Then watch, stop.`
|
|
55
|
+
|
|
56
|
+
**Pass criteria:** handA's question reaches handB; handB replies via
|
|
57
|
+
shepherd_message (with replyTo set); handA calls shepherd_done; the watcher
|
|
58
|
+
fires completed with the answer ("handB" — note: the sheep may answer
|
|
59
|
+
"scout", its agent type; either is fine as long as the loop completes).
|
|
60
|
+
Report back: both agent ids, task id, and the full watcher completion text.
|
|
61
|
+
If handB instead claims the tool is missing or improvises via shell, STOP —
|
|
62
|
+
paste its exact words back (that is itself a finding).
|
|
63
|
+
|
|
64
|
+
## Test C — error paths (cheap, do if quota allows)
|
|
65
|
+
|
|
66
|
+
1. `Call shepherd_done with taskId shepherd-task-0000-0000 and status
|
|
67
|
+
completed. Report the exact error text, stop.`
|
|
68
|
+
2. `Call shepherd_message to shepherd-agent-0000-0000 with message hi.
|
|
69
|
+
Report the exact error text, stop.`
|
|
70
|
+
|
|
71
|
+
**Pass criteria:** both fail with "unknown" errors naming the bad id (not
|
|
72
|
+
a crash, not a hang). Report the exact error strings.
|
|
73
|
+
|
|
74
|
+
## Test D — done-nudge (optional, slow)
|
|
75
|
+
|
|
76
|
+
Only if quota is comfortable: delegate a trivial task to handA, then ask
|
|
77
|
+
handA nothing further and wait ~3 minutes without prompting it. The parent
|
|
78
|
+
should receive a nudge reminder about the open task. Report whether any
|
|
79
|
+
nudge arrived (check the session — it appears as a shepherd notice).
|
|
80
|
+
|
|
81
|
+
## Rules while testing
|
|
82
|
+
|
|
83
|
+
- Do NOT edit repo files, restart the server, or touch
|
|
84
|
+
`~/.config/opencode/plugins/` mid-test. If something looks broken,
|
|
85
|
+
report it instead of fixing it.
|
|
86
|
+
- Keep pastes sequential: one tool-using instruction per message, wait
|
|
87
|
+
for the result before the next.
|
|
88
|
+
- Report VERBATIM outputs (agent ids, task ids, watcher text, errors).
|
|
89
|
+
Do not summarize — the ids are needed for log forensics.
|
|
90
|
+
|
|
91
|
+
## Report back
|
|
92
|
+
|
|
93
|
+
Paste into chat: for each test, PASS/FAIL/STOP + the verbatim artifacts.
|
|
94
|
+
The assistant correlates with server logs, ticks T011, and moves to Phase 4.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Intent — Shepherd for OpenCode
|
|
2
|
+
|
|
3
|
+
`specs/013-opencode-shepherd` · Author: Mikkel (product owner) · 2026-11-17 · approved
|
|
4
|
+
|
|
5
|
+
## Problem
|
|
6
|
+
|
|
7
|
+
Shepherd (herding subagents in visible Herdr panes, with tracked tasks and
|
|
8
|
+
shared fieldnotes) only exists for Pi. I also work in OpenCode, and there I
|
|
9
|
+
have no equivalent: no persistent visible sheep, no delegate/watch flow, no
|
|
10
|
+
shared session notes across agents. Every OpenCode session starts from zero.
|
|
11
|
+
|
|
12
|
+
## Proposed outcome
|
|
13
|
+
|
|
14
|
+
Shepherd becomes available inside OpenCode too, working the same way it does
|
|
15
|
+
in Pi: I can ask for a planner/scout/worker, it spawns in a visible Herdr
|
|
16
|
+
pane, I can delegate tracked work to it, message it, watch for completion,
|
|
17
|
+
and the agents share fieldnotes. Herdr stays the execution substrate — how
|
|
18
|
+
sheep run today does not change. The same repo hosts both, and each host
|
|
19
|
+
(Pi, OpenCode) stays flexible and independent: using one must never require
|
|
20
|
+
or break the other.
|
|
21
|
+
|
|
22
|
+
## Affected users and systems
|
|
23
|
+
|
|
24
|
+
- Me and any other Shepherd users who work in both Pi and OpenCode.
|
|
25
|
+
- `pi-shepherd` extension as it exists today (must keep working untouched).
|
|
26
|
+
- Herdr / `hc` runtimes (reused, not replaced).
|
|
27
|
+
- The repo layout and npm packaging (must accommodate a second host).
|
|
28
|
+
|
|
29
|
+
## Constraints
|
|
30
|
+
|
|
31
|
+
- Herdr remains the main course: sheep still run in Herdr panes/terminals.
|
|
32
|
+
Path A only — no native OpenCode session runtime in this effort.
|
|
33
|
+
- Pi behavior must not regress; Pi users who never touch OpenCode should
|
|
34
|
+
notice nothing (apart from repo reorganization).
|
|
35
|
+
- One repo, one package — but host independence must hold in code layout:
|
|
36
|
+
the Pi and OpenCode adapters stay separate with no cross-imports, so a
|
|
37
|
+
change on one side never requires a change on the other. Both hosts'
|
|
38
|
+
verification suites run on every change, and releases call out per-host
|
|
39
|
+
impact.
|
|
40
|
+
- Agent definitions (Markdown) and project config (`.shepherd/config.json`)
|
|
41
|
+
should be shared, not forked per host.
|
|
42
|
+
|
|
43
|
+
## Decisions
|
|
44
|
+
|
|
45
|
+
- **Package name: `@luminascale/shepherd` (decided 2026-11-17).** Bare
|
|
46
|
+
`shepherd` is taken on npm; the scoped name is free. Only the package
|
|
47
|
+
name changes — tool names, env vars, and config/registry paths stay
|
|
48
|
+
frozen so existing users keep their settings and herd. A final
|
|
49
|
+
`@luminascale/pi-shepherd` release carries a one-time migration notice
|
|
50
|
+
and ships *before* the rename.
|
|
51
|
+
|
|
52
|
+
## Open questions
|
|
53
|
+
|
|
54
|
+
- Does the OpenCode side need its own settings surface from day one, or is
|
|
55
|
+
file-based config enough for the first slice?
|
|
56
|
+
|
|
57
|
+
## Approval
|
|
58
|
+
|
|
59
|
+
- [x] Product owner reviewed and approved — Mikkel, 2026-11-17
|