@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,204 @@
|
|
|
1
|
+
# Plan — Shepherd for OpenCode
|
|
2
|
+
|
|
3
|
+
`specs/013-opencode-shepherd` · draft · 2026-11-17 · spec: `spec.md`
|
|
4
|
+
|
|
5
|
+
## Summary
|
|
6
|
+
|
|
7
|
+
Satisfy FR-001–FR-012 with Path A: keep the Herdr/hc pane runtimes, the
|
|
8
|
+
file broker, and the orchestration registries untouched, and add an OpenCode
|
|
9
|
+
server-plugin adapter beside the existing Pi adapter in one package. The Pi
|
|
10
|
+
import surface in today's `src/core` is decoupled behind injected
|
|
11
|
+
directories/parsers so both adapters share one engine; OpenCode children boot
|
|
12
|
+
as interactive sessions in panes (the `opencode run` subcommand is one-shot
|
|
13
|
+
and unsuitable for persistent sheep) and get their `shepherd_message` /
|
|
14
|
+
`shepherd_done` tools from the same installed plugin.
|
|
15
|
+
|
|
16
|
+
## Requirement coverage
|
|
17
|
+
|
|
18
|
+
- **FR-001** (OpenCode parity: spawn/delegate/message/watch/status/read/close)
|
|
19
|
+
→ new OpenCode server-plugin adapter exposing one tool per operation with
|
|
20
|
+
the same lifecycle semantics as the Pi tools; all calls route through the
|
|
21
|
+
shared runtime resolver.
|
|
22
|
+
- **FR-002** (sheep run in visible Herdr panes/terminals) → reuse of the two
|
|
23
|
+
existing pane runtimes unchanged; only the child boot command is
|
|
24
|
+
parameterized (boot `opencode` instead of `pi`).
|
|
25
|
+
- **FR-003** (explicit-completion settlement) → reuse of the broker's
|
|
26
|
+
`task_done` envelope + `shepherd_done` as the single settlement signal;
|
|
27
|
+
new OpenCode child tool publishes the same envelope shape.
|
|
28
|
+
- **FR-004** (results retrievable, delivered once) → reuse of the task
|
|
29
|
+
registries, watcher services, and unseen-completion ledger unchanged.
|
|
30
|
+
- **FR-005** (shared definitions/config) → discovery and config move to
|
|
31
|
+
directory-injected helpers shared by both adapters; project
|
|
32
|
+
`.shepherd/config.json` stays the single project source.
|
|
33
|
+
- **FR-006** (cross-host fieldnotes) → artifact sessions are host-neutral
|
|
34
|
+
files; the OpenCode adapter resolves/creates the same parent session
|
|
35
|
+
layout the Pi adapter uses. The OpenCode session id is the opaque parent
|
|
36
|
+
identity and the session cwd is the project root — the same
|
|
37
|
+
`(parent identity, effective project root)` binding key Pi uses — passed
|
|
38
|
+
to the shared resolver. Spawn stores the session on the agent record and
|
|
39
|
+
delegate re-resolves it, so both runtimes reserve notes in that collection.
|
|
40
|
+
- **FR-007** (no Pi regression) → zero behavior change in the Pi adapter;
|
|
41
|
+
the full existing `verify-*` suites stay green and run on every change.
|
|
42
|
+
- **FR-008** (no cross-host code paths) → layout rule: shared engine
|
|
43
|
+
imports nothing host-specific; each adapter imports the engine, never the
|
|
44
|
+
other adapter. New modules, no edits to Pi-owned behavior.
|
|
45
|
+
- **FR-009** (both suites green, per-host release notes) → a mirrored
|
|
46
|
+
OpenCode verification harness plus a release checklist entry.
|
|
47
|
+
- **FR-010** (one package, clear docs) → single manifest carrying both a Pi
|
|
48
|
+
extension entry and an OpenCode plugin entry; README splits into
|
|
49
|
+
per-host tracks on the first screen.
|
|
50
|
+
- **FR-011** (clean failure when Herdr is unreachable) → the existing
|
|
51
|
+
backend resolver and setup-hint errors are reused verbatim by the
|
|
52
|
+
OpenCode adapter.
|
|
53
|
+
- **FR-012** (deadlines, bounded waits, nudges) → reuse of the timeout,
|
|
54
|
+
stale-wait, and done-nudge machinery; OpenCode child turn-end maps onto
|
|
55
|
+
the same nudge boundary the Pi child uses.
|
|
56
|
+
|
|
57
|
+
## Technical context
|
|
58
|
+
|
|
59
|
+
- **Language / runtime**: TypeScript run directly by both hosts, no build
|
|
60
|
+
step (matches the current repo: no bundler, no compiled output).
|
|
61
|
+
- **Dependencies**: host SDKs stay peer/optional and adapter-local — the Pi
|
|
62
|
+
SDK inside the Pi adapter only, `@opencode/plugin` inside the OpenCode
|
|
63
|
+
adapter only. The shared engine depends on neither.
|
|
64
|
+
- **Storage**: today's file layout is kept — created-pane/terminal
|
|
65
|
+
registries, parent-owned mailbox broker directories, artifact session
|
|
66
|
+
files, per-host user config plus shared project `.shepherd/config.json`.
|
|
67
|
+
- **Platform**: any machine with Herdr (or `hc`) plus the host CLI
|
|
68
|
+
installed; Node 22+.
|
|
69
|
+
- **Constraints**: opaque lifecycle ids stay opaque on both hosts (native
|
|
70
|
+
pane/terminal/session ids never cross tool boundaries); backend choice
|
|
71
|
+
stays app-side (the model never selects it).
|
|
72
|
+
|
|
73
|
+
## Architecture
|
|
74
|
+
|
|
75
|
+
One engine, two thin adapters:
|
|
76
|
+
|
|
77
|
+
```text
|
|
78
|
+
+------------------ shared engine ------------------+
|
|
79
|
+
| discovery · config · ids · broker/messaging |
|
|
80
|
+
| orchestration registries · artifacts · runtimes |
|
|
81
|
+
| (herdr panes · hc terminals · backend resolver) |
|
|
82
|
+
+-----------+------------------+--------------------+
|
|
83
|
+
| |
|
|
84
|
+
Pi adapter (today) OpenCode adapter (new)
|
|
85
|
+
tools · /shepherd server tools · commands
|
|
86
|
+
settings UI · widget (settings UI deferred, see Q2)
|
|
87
|
+
child extension child plugin tools
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
- The engine gains no host concepts: today's Pi imports in discovery/config
|
|
91
|
+
(agent directory, frontmatter parser, config-dir name) become injected
|
|
92
|
+
parameters with each adapter supplying its host's values.
|
|
93
|
+
- The launch-file builder is parameterized by child binary, child entry,
|
|
94
|
+
env prefix, and — because the opencode CLI has no equivalent of pi's
|
|
95
|
+
session/extension flags — a full-command override (`command: 'opencode'`),
|
|
96
|
+
which skips Pi arg construction and runs verbatim. Pi callers omit all
|
|
97
|
+
four and get byte-identical scripts. `opencode run`
|
|
98
|
+
is deliberately *not* used for sheep: it executes one message and exits,
|
|
99
|
+
while sheep must stay alive across turns.
|
|
100
|
+
- Children obtain Shepherd tools from the normally installed plugin (global
|
|
101
|
+
install recommended, mirroring `pi install`, so any child cwd inherits
|
|
102
|
+
it); no per-spawn plugin injection.
|
|
103
|
+
- Parent→sheep delivery uses terminal input (Herdr `agent prompt` with a
|
|
104
|
+
`pane send-text` fallback; `hc send`), because the opencode TUI ignores
|
|
105
|
+
`--session` attach and creates its server session lazily on first input.
|
|
106
|
+
`session.prompt` is used only for parent-session notices, where the
|
|
107
|
+
session id is exactly known; human `/shepherd` command output instead uses
|
|
108
|
+
`session.prompt(..., resume: false)` so it renders in full without waking
|
|
109
|
+
the model.
|
|
110
|
+
- Operational limits (see tasks.md Later): one active parent session per
|
|
111
|
+
OpenCode server process is a deliberate, engine-wide boundary (broker
|
|
112
|
+
singletons, session-keyed registry rotation, one drain timer/poll key),
|
|
113
|
+
not a broker-only limitation; sheep of one parent never collide. Phase 3
|
|
114
|
+
verifies single-parent flows only. A plugin reload/server restart resets
|
|
115
|
+
in-memory orchestration state while panes/terminals survive; the adapter
|
|
116
|
+
detects those orphans from the ownership registries, notifies once, and
|
|
117
|
+
offers an ownership-checked `reap` action. Tracked tasks and watchers do
|
|
118
|
+
not survive a restart.
|
|
119
|
+
Completion notices are delivered only to sessions that were recorded as
|
|
120
|
+
task parents (never to sheep sessions), with bounded retry when the parent
|
|
121
|
+
session is busy. Sheep session binding wins over a stale parent mark so a
|
|
122
|
+
child that called a parent tool before binding can still reply to peers.
|
|
123
|
+
- The capability handoff (broker directory, session/broker/agent ids,
|
|
124
|
+
token, inbox path) keeps its file+environment-variable shape so the
|
|
125
|
+
shared builder stays single-sourced; each host's surface reads it under
|
|
126
|
+
its own variable prefix (today's prefix keeps working for Pi).
|
|
127
|
+
|
|
128
|
+
## Data model
|
|
129
|
+
|
|
130
|
+
- Unchanged: opaque agent/task/message/watcher ids with per-process
|
|
131
|
+
namespaces; broker envelopes (`task`, `message`, `reply`, `runtime`,
|
|
132
|
+
`task_done`) with the same required fields; artifact reservations with
|
|
133
|
+
terminal statuses (completed/blocked/failed/cancelled/timed-out).
|
|
134
|
+
- Config: per-host user files (Pi's agent dir; OpenCode's config dir) plus
|
|
135
|
+
the one shared project file. `backend` and the project-agent trust gate
|
|
136
|
+
stay user-owned on both hosts: a repository config can never force them.
|
|
137
|
+
- Ownership: created panes/terminals remain tagged by parent session, so
|
|
138
|
+
the herd views on both hosts show only their own sheep while sharing the
|
|
139
|
+
underlying registry files.
|
|
140
|
+
|
|
141
|
+
## Interfaces
|
|
142
|
+
|
|
143
|
+
| interface | behavior |
|
|
144
|
+
|---|---|
|
|
145
|
+
| OpenCode `shepherd_spawn` (+ `delegate`, `message`, `watch`, `status`, `read`, `close`, umbrella) | Same lifecycle semantics as the Pi tools; same opaque-id discipline; same setup-hint failures. |
|
|
146
|
+
| OpenCode command (e.g. `/shepherd`) | Same human surface as Pi's: list agents/herd, spawn, status, read; settings entry point when decided (see Q2). |
|
|
147
|
+
| Child `shepherd_message` / `shepherd_done` (OpenCode) | Same validation as the Pi child: task inference, reply→task match, broker-unavailable error when no capability was handed down. |
|
|
148
|
+
| Env capability contract | Same fields as today (root dir, session/broker/agent ids, token, inbox); per-host variable prefix. |
|
|
149
|
+
| Package manifest | One manifest named `@luminascale/shepherd` with two entries: Pi extension entry + OpenCode plugin entry (server part; TUI/GUI parts only if needed). |
|
|
150
|
+
|
|
151
|
+
## Invariants
|
|
152
|
+
|
|
153
|
+
- No adapter imports the other adapter; the engine imports neither.
|
|
154
|
+
- Native ids (pane, terminal, OpenCode session) never appear in tool
|
|
155
|
+
inputs, outputs, or results — diagnostics only.
|
|
156
|
+
- One outstanding tracked reply per task; completion only via the
|
|
157
|
+
explicit done signal, cancellation/close, or deadline.
|
|
158
|
+
- Watcher delivery exactly-once per settlement; late watchers still get
|
|
159
|
+
already-settled results synchronously.
|
|
160
|
+
- A pinned backend that is unreachable fails with its setup hint; never a
|
|
161
|
+
silent cross-spawn to the other runtime.
|
|
162
|
+
- Functional identifiers stay frozen across the rename: `shepherd_*` tool
|
|
163
|
+
names, the env-capability prefix and fields, and the user config/registry
|
|
164
|
+
paths. Only the npm package name changes.
|
|
165
|
+
- Release ordering around the rename: the old name still gets one final
|
|
166
|
+
notice-bearing release (`@luminascale/pi-shepherd@0.5.2`) and is then
|
|
167
|
+
deprecated with a pointer. The renamed package
|
|
168
|
+
(`@luminascale/shepherd@0.6.0`) is published **first**, so the pointer in
|
|
169
|
+
the notice and the deprecation warning resolves to a real install target.
|
|
170
|
+
The one-time notice is marker-gated, human-sessions-only, and never emitted
|
|
171
|
+
in a child sheep pane.
|
|
172
|
+
|
|
173
|
+
## Failure behavior
|
|
174
|
+
|
|
175
|
+
- Herdr/hc unreachable ⇒ setup-hint error naming the missing runtime; no
|
|
176
|
+
fallback spawn (FR-011).
|
|
177
|
+
- Child never becomes ready ⇒ spawn fails with the child's output tail and
|
|
178
|
+
temporary resources are removed; no orphan registration.
|
|
179
|
+
- Broker capability missing in a child ⇒ child tools return a structured
|
|
180
|
+
unavailable error; the parent task still settles by deadline (FR-012).
|
|
181
|
+
- Turn ends with an open tracked task ⇒ one bounded reminder turn, then a
|
|
182
|
+
visible stall escalation; the task itself stays open until done,
|
|
183
|
+
cancelled, or timed out.
|
|
184
|
+
- Rejected/duplicate completions ⇒ written to the broker's rejected store
|
|
185
|
+
and surfaced, never silently applied or lost.
|
|
186
|
+
|
|
187
|
+
## Recovery
|
|
188
|
+
|
|
189
|
+
- Stale pane/terminal registrations are pruned; only owned panes/terminals
|
|
190
|
+
may be closed.
|
|
191
|
+
- Orphaned launch directories are removed once their pane/terminal is
|
|
192
|
+
confirmed gone.
|
|
193
|
+
- Background inbox drains are idempotent: re-polling never double-settles,
|
|
194
|
+
and one bad envelope never stops the drain.
|
|
195
|
+
|
|
196
|
+
## Open questions
|
|
197
|
+
|
|
198
|
+
1. Package name — decided: `@luminascale/shepherd` (bare `shepherd` is
|
|
199
|
+
taken on npm; the scoped name is free). Functional identifiers stay
|
|
200
|
+
frozen per the invariant above.
|
|
201
|
+
2. OpenCode settings surface on day one vs file-based config first?
|
|
202
|
+
Proposed default stands (files first) unless the spec review overturns it.
|
|
203
|
+
3. OpenCode plugin `id` and whether the child tool names need namespacing
|
|
204
|
+
to avoid collisions in sessions that install other plugins.
|
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
# Spec — Shepherd for OpenCode
|
|
2
|
+
|
|
3
|
+
`specs/013-opencode-shepherd` · agreed · 2026-11-17 · From: `intent.md` (Mikkel)
|
|
4
|
+
|
|
5
|
+
## Summary
|
|
6
|
+
|
|
7
|
+
Shepherd becomes usable from OpenCode as well as Pi: the same herding of
|
|
8
|
+
visible Herdr sheep, tracked task delegation, agent messaging, and shared
|
|
9
|
+
fieldnotes — shipped as one package with a Pi entry and an OpenCode entry,
|
|
10
|
+
with Herdr remaining the execution substrate.
|
|
11
|
+
|
|
12
|
+
## User Scenarios & Testing
|
|
13
|
+
|
|
14
|
+
### User Story 1 — Spawn a sheep from OpenCode (Priority: P1)
|
|
15
|
+
|
|
16
|
+
An OpenCode user asks for a specialist (e.g. a planner). A sheep starts in a
|
|
17
|
+
visible Herdr pane, owned by that OpenCode session, and the user can see and
|
|
18
|
+
inspect it the same way a Pi user can today.
|
|
19
|
+
|
|
20
|
+
**Why this priority**: without spawning there is no product; this is the
|
|
21
|
+
entry point everything else builds on.
|
|
22
|
+
|
|
23
|
+
**Independent test**: from OpenCode, request a named agent; confirm a live,
|
|
24
|
+
visible sheep exists and is owned by the session, then close it.
|
|
25
|
+
|
|
26
|
+
**Acceptance scenarios**:
|
|
27
|
+
|
|
28
|
+
1. **Given** Herdr is reachable and an agent named `planner` exists, **when**
|
|
29
|
+
the user asks OpenCode for a planner, **then** a visible sheep running
|
|
30
|
+
that agent appears and reports back as ready.
|
|
31
|
+
2. **Given** Herdr is not reachable, **when** the user asks for a sheep,
|
|
32
|
+
**then** they get a clear setup hint instead of a hang or a cryptic
|
|
33
|
+
error.
|
|
34
|
+
3. **Given** an unknown agent name, **when** the user asks for it, **then**
|
|
35
|
+
they are told the name is unknown and how to list exact names.
|
|
36
|
+
|
|
37
|
+
### User Story 2 — Delegate tracked work and get the result (Priority: P1)
|
|
38
|
+
|
|
39
|
+
An OpenCode user delegates a task to a sheep and continues working; when the
|
|
40
|
+
sheep finishes, the result is delivered and nothing is lost even if nobody
|
|
41
|
+
was watching at the moment of completion.
|
|
42
|
+
|
|
43
|
+
**Why this priority**: this is Shepherd's core loop; spawning without
|
|
44
|
+
delegation has no value.
|
|
45
|
+
|
|
46
|
+
**Independent test**: delegate a small task, do other work, receive the
|
|
47
|
+
completion and verify its content matches what the sheep did.
|
|
48
|
+
|
|
49
|
+
**Acceptance scenarios**:
|
|
50
|
+
|
|
51
|
+
1. **Given** a spawned sheep, **when** the user delegates a task, **then**
|
|
52
|
+
delegation returns immediately with a task reference and the sheep starts
|
|
53
|
+
working.
|
|
54
|
+
2. **Given** a delegated task finishes while no watcher is attached, **when**
|
|
55
|
+
the user next checks, **then** the result is still retrievable exactly
|
|
56
|
+
once — never lost, never delivered twice.
|
|
57
|
+
3. **Given** a sheep that never finishes, **when** its deadline passes,
|
|
58
|
+
**then** the task settles as timed-out/blocked with an explanation
|
|
59
|
+
instead of hanging forever.
|
|
60
|
+
|
|
61
|
+
### User Story 3 — Agents talk to each other (Priority: P2)
|
|
62
|
+
|
|
63
|
+
A sheep working a task can ask the user-side session or a peer sheep a
|
|
64
|
+
question and wait for the answer; replies resume the waiting work.
|
|
65
|
+
|
|
66
|
+
**Why this priority**: real tasks need clarification; without messaging,
|
|
67
|
+
delegated work stalls or guesses.
|
|
68
|
+
|
|
69
|
+
**Independent test**: have a sheep ask a question mid-task, answer it, and
|
|
70
|
+
confirm the sheep resumes and completes.
|
|
71
|
+
|
|
72
|
+
**Acceptance scenarios**:
|
|
73
|
+
|
|
74
|
+
1. **Given** a sheep needs input, **when** it asks a question expecting a
|
|
75
|
+
reply, **then** its task is visibly marked as waiting and the question
|
|
76
|
+
reaches the right recipient.
|
|
77
|
+
2. **Given** a waiting task, **when** the reply arrives, **then** the task
|
|
78
|
+
resumes and the reply is correlated to the original question.
|
|
79
|
+
|
|
80
|
+
### User Story 4 — Sheep share fieldnotes (Priority: P2)
|
|
81
|
+
|
|
82
|
+
Delegated work in OpenCode leaves durable notes in the same shared place Pi
|
|
83
|
+
sheep use, so a later agent (from either host) can pick up the context.
|
|
84
|
+
|
|
85
|
+
**Why this priority**: continuity across agents and across hosts is the
|
|
86
|
+
multiplier; without it every delegation starts from zero.
|
|
87
|
+
|
|
88
|
+
**Independent test**: delegate two sequential tasks and confirm the second
|
|
89
|
+
sheep can see what the first one left behind.
|
|
90
|
+
|
|
91
|
+
**Acceptance scenarios**:
|
|
92
|
+
|
|
93
|
+
1. **Given** a completed delegation with notes enabled, **when** a new
|
|
94
|
+
sheep is delegated follow-up work, **then** it can read the earlier
|
|
95
|
+
sheep's notes.
|
|
96
|
+
2. **Given** notes from a Pi delegation, **when** an OpenCode sheep does
|
|
97
|
+
follow-up work, **then** the Pi notes are visible to it (and vice
|
|
98
|
+
versa).
|
|
99
|
+
|
|
100
|
+
### User Story 5 — Pi users notice nothing (Priority: P1)
|
|
101
|
+
|
|
102
|
+
A Pi user who never touches OpenCode experiences zero regression: same
|
|
103
|
+
commands, same tools, same behavior, same install.
|
|
104
|
+
|
|
105
|
+
**Why this priority**: the installed base must not pay for a host they
|
|
106
|
+
don't use; this constraint gates the whole effort.
|
|
107
|
+
|
|
108
|
+
**Independent test**: run the existing Pi verification suites unchanged and
|
|
109
|
+
green, and walk the core Pi flows manually.
|
|
110
|
+
|
|
111
|
+
**Acceptance scenarios**:
|
|
112
|
+
|
|
113
|
+
1. **Given** the combined package installed in Pi, **when** the user herds
|
|
114
|
+
sheep as before, **then** every flow behaves exactly as it did before
|
|
115
|
+
the OpenCode work.
|
|
116
|
+
2. **Given** a Pi-only change, **when** it ships, **then** it requires no
|
|
117
|
+
OpenCode-side change (and vice versa).
|
|
118
|
+
3. **Given** an existing `@luminascale/pi-shepherd` install, **when** the
|
|
119
|
+
farewell release runs, **then** the user sees a one-time migration
|
|
120
|
+
notice pointing at the new name; **and when** they remove-then-install
|
|
121
|
+
the new package, **then** settings and herd registrations are intact.
|
|
122
|
+
|
|
123
|
+
### User Story 6 — One package, two homes (Priority: P2)
|
|
124
|
+
|
|
125
|
+
A new user finds one Shepherd package, installs it in their host (Pi or
|
|
126
|
+
OpenCode), and gets host-appropriate guidance without confusion about which
|
|
127
|
+
host the docs describe.
|
|
128
|
+
|
|
129
|
+
**Why this priority**: the packaging decision only pays off if discovery
|
|
130
|
+
and install are genuinely unified.
|
|
131
|
+
|
|
132
|
+
**Independent test**: fresh install in each host following only the docs;
|
|
133
|
+
confirm working sheep in both.
|
|
134
|
+
|
|
135
|
+
**Acceptance scenarios**:
|
|
136
|
+
|
|
137
|
+
1. **Given** a Pi user, **when** they install the package, **then** no
|
|
138
|
+
OpenCode-specific setup is required of them (and vice versa).
|
|
139
|
+
2. **Given** the documentation, **when** a user of either host reads it,
|
|
140
|
+
**then** they can tell within seconds which instructions apply to them.
|
|
141
|
+
|
|
142
|
+
### Edge cases
|
|
143
|
+
|
|
144
|
+
- Herdr reachable but the child agent never becomes ready: the user gets
|
|
145
|
+
the failure plus whatever the child produced, not a silent timeout.
|
|
146
|
+
- Two sheep given the same display label: the second spawn is rejected
|
|
147
|
+
clearly instead of creating an ambiguous herd.
|
|
148
|
+
- A sheep's turn ends without reporting its task done: it gets a bounded
|
|
149
|
+
reminder, then the stall is escalated visibly instead of looping forever.
|
|
150
|
+
- A project-local agent definition the user hasn't approved: OpenCode asks
|
|
151
|
+
first, same trust gate as Pi.
|
|
152
|
+
- Human `/shepherd …` command results are display-only: listing agents (or
|
|
153
|
+
herd/status/read) via the command shows the result and returns control to
|
|
154
|
+
the user, without starting an assistant turn. Command output is delivered
|
|
155
|
+
as a normal session message with `resume: false` (full TUI rendering, but no
|
|
156
|
+
model wake); parent-session notices omit `resume: false` because those are
|
|
157
|
+
meant to wake the model.
|
|
158
|
+
- Fieldnotes are keyed by `(host parent session identity, effective project
|
|
159
|
+
root)` on both hosts. The OpenCode session id is that opaque identity;
|
|
160
|
+
neither a pane/terminal id nor an agent/task id is used. The fieldnotes
|
|
161
|
+
setting is snapshotted per parent session, so disabling it never changes
|
|
162
|
+
the contract of agents already running in that session.
|
|
163
|
+
|
|
164
|
+
## Requirements
|
|
165
|
+
|
|
166
|
+
- **FR-001**: OpenCode users MUST be able to spawn, delegate to, message,
|
|
167
|
+
check on, read output from, watch, and close sheep with the same semantics
|
|
168
|
+
Pi users have.
|
|
169
|
+
- **FR-002**: Sheep delegated from OpenCode MUST run in visible Herdr
|
|
170
|
+
panes/terminals (Path A); no hidden or host-native-only execution in this
|
|
171
|
+
effort.
|
|
172
|
+
- **FR-003**: A tracked task MUST settle only through an explicit completion
|
|
173
|
+
signal from the working sheep, a cancellation/close, or its deadline —
|
|
174
|
+
never through a turn ending, idleness, or silence.
|
|
175
|
+
- **FR-004**: Settled task results MUST remain retrievable after settlement
|
|
176
|
+
and MUST be delivered exactly once to watchers. Automatic completion notices
|
|
177
|
+
MUST go only to human parent sessions, never to a sheep pane, and MUST be
|
|
178
|
+
retried when the parent session is temporarily busy.
|
|
179
|
+
- **FR-015**: A delegated sheep session MUST remain recognised as a sheep even
|
|
180
|
+
if it called a parent-only tool before its session was lazily bound. Such an
|
|
181
|
+
early call MUST NOT permanently classify it as a parent, which would block
|
|
182
|
+
the sheep form of `shepherd_message` for peer replies.
|
|
183
|
+
- **FR-005**: Agent definitions and project configuration MUST be shared
|
|
184
|
+
between hosts, not forked; a definition written for Pi MUST work from
|
|
185
|
+
OpenCode unchanged.
|
|
186
|
+
- **FR-006**: Fieldnotes written from one host MUST be readable from the
|
|
187
|
+
other.
|
|
188
|
+
- **FR-007**: The Pi experience MUST NOT regress: existing Pi verification
|
|
189
|
+
suites stay green and Pi-only flows behave identically.
|
|
190
|
+
- **FR-008**: A change to one host's adapter MUST NOT require a change to
|
|
191
|
+
the other; the two adapters MUST share no code paths that can couple
|
|
192
|
+
their releases.
|
|
193
|
+
- **FR-009**: Every change MUST be verified against both hosts' suites
|
|
194
|
+
before shipping, and releases MUST call out per-host impact.
|
|
195
|
+
- **FR-010**: One installable package MUST serve both hosts, with
|
|
196
|
+
documentation that lets each host's users identify their instructions
|
|
197
|
+
immediately.
|
|
198
|
+
- **FR-011**: When the Herdr runtime is unreachable, the system MUST fail
|
|
199
|
+
with a setup hint and MUST NOT silently fall back to a different
|
|
200
|
+
execution substrate.
|
|
201
|
+
- **FR-012**: Stuck tracked work MUST settle by deadline with an explanation,
|
|
202
|
+
and messages awaiting replies MUST have a bounded wait after which the
|
|
203
|
+
waiter is reminded or the task settles as blocked.
|
|
204
|
+
- **FR-013**: The package MUST ship as `@luminascale/shepherd` with both
|
|
205
|
+
host entries, while tool names, env vars, and config/registry paths MUST
|
|
206
|
+
stay unchanged so existing installs migrate without loss.
|
|
207
|
+
- **FR-014**: The final `@luminascale/pi-shepherd` release MUST show
|
|
208
|
+
existing users a one-time migration notice (human sessions only, never
|
|
209
|
+
repeated, never in child sheep panes) and MUST ship before the rename.
|
|
210
|
+
|
|
211
|
+
## Key entities
|
|
212
|
+
|
|
213
|
+
- **Sheep**: a persistent specialist agent running in a visible Herdr
|
|
214
|
+
pane/terminal, owned by exactly one parent session; has a definition name
|
|
215
|
+
and an optional label.
|
|
216
|
+
- **Tracked task**: one unit of delegated work on a sheep; has a lifecycle
|
|
217
|
+
(running → waiting → settled) and exactly one terminal outcome.
|
|
218
|
+
- **Message / reply**: asynchronous communication between sheep, or between
|
|
219
|
+
sheep and the parent session; a reply is correlated to the question it
|
|
220
|
+
answers.
|
|
221
|
+
- **Fieldnote session**: durable shared notes for one parent session's
|
|
222
|
+
delegations, readable by later sheep from either host.
|
|
223
|
+
- **Package**: the single installable unit exposing a Pi entry and an
|
|
224
|
+
OpenCode entry.
|
|
225
|
+
|
|
226
|
+
## Success criteria
|
|
227
|
+
|
|
228
|
+
- **SC-001**: An OpenCode user completes spawn → delegate → watch → close
|
|
229
|
+
end-to-end with a visible sheep, following only the docs.
|
|
230
|
+
- **SC-002**: All pre-existing Pi verification suites pass unchanged, and a
|
|
231
|
+
mirrored OpenCode verification suite covering FR-001–FR-004 passes.
|
|
232
|
+
- **SC-003**: Fresh installs in Pi and in OpenCode (each following only
|
|
233
|
+
their host's instructions) both yield working sheep, with no steps from
|
|
234
|
+
the other host required.
|
|
235
|
+
- **SC-004**: A Pi-only change ships with zero OpenCode-side edits, and the
|
|
236
|
+
release notes state per-host impact.
|
|
237
|
+
- **SC-005**: An existing `@luminascale/pi-shepherd` user sees the
|
|
238
|
+
migration notice exactly once and completes remove-then-install with
|
|
239
|
+
settings and herd intact.
|
|
240
|
+
|
|
241
|
+
## Assumptions
|
|
242
|
+
|
|
243
|
+
- Herdr (or `hc`) is installed and reachable wherever sheep are herded;
|
|
244
|
+
Shepherd does not install or manage Herdr itself.
|
|
245
|
+
- The OpenCode plugin interface used is the current (v2) one; tracking its
|
|
246
|
+
future breaking changes is maintenance, not part of this effort.
|
|
247
|
+
- One maintainer ships both sides, so release gating across both suites is
|
|
248
|
+
acceptable overhead.
|
|
249
|
+
- Agent frontmatter conventions (Markdown + YAML) stay host-agnostic.
|
|
250
|
+
|
|
251
|
+
## Open questions from intent
|
|
252
|
+
|
|
253
|
+
- What is the package called, and does `pi-shepherd` get renamed? —
|
|
254
|
+
answered: `@luminascale/shepherd`; only the package name changes,
|
|
255
|
+
functional identifiers stay frozen (see FR-013).
|
|
256
|
+
- Does the OpenCode side need its own settings surface from day one, or is
|
|
257
|
+
file-based config enough for the first slice? — carried forward (owner:
|
|
258
|
+
Mikkel; proposed default: file-based config first, settings UI later).
|