@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,163 @@
|
|
|
1
|
+
# Historical Plan: Scoped Settings — user config + project config override
|
|
2
|
+
|
|
3
|
+
Status: superseded by [Per-workspace self-contained Shepherd settings](../../specs/005-per-workspace-settings/spec.md).
|
|
4
|
+
|
|
5
|
+
This document records the implemented delta-based design that preceded the
|
|
6
|
+
current per-workspace model. Do not use its `settingsScope` or project-delta
|
|
7
|
+
semantics for new work. The active design uses a project-owned boolean
|
|
8
|
+
`projectScope`, self-contained project files, and a user-owned
|
|
9
|
+
`confirmProjectAgents` security setting.
|
|
10
|
+
|
|
11
|
+
Implementation note: the user file lives in the pi agent dir as resolved by
|
|
12
|
+
`getAgentDir()` (`~/.pi/agent` by default, `PI_CODING_AGENT_DIR` overridable)
|
|
13
|
+
rather than a hard-coded home path.
|
|
14
|
+
|
|
15
|
+
## 1. Problem
|
|
16
|
+
|
|
17
|
+
All persisted settings live in a single user-level file
|
|
18
|
+
(`~/.pi/agent/pi-shepherd/settings.json`), so a project cannot carry its own
|
|
19
|
+
shepherd defaults (timeout, keepOpen, stayOpen, …). There is also no
|
|
20
|
+
project-level config surface at all, despite projects already carrying
|
|
21
|
+
`.pi/`/`.agents/` agent dirs and `.shepherd/sessions/` fieldnotes.
|
|
22
|
+
|
|
23
|
+
## 2. Decisions (agreed)
|
|
24
|
+
|
|
25
|
+
1. **Scope top-level item.** The settings menu (`/shepherd settings`) gains a
|
|
26
|
+
first, top-level entry: **Settings scope** — `user` (default) | `project`.
|
|
27
|
+
2. **Project file path.** `.shepherd/config.json` in the current working
|
|
28
|
+
directory (same `.shepherd` root fieldnotes already use; anchored at cwd,
|
|
29
|
+
no walk-up — consistent with `artifact-sessions.ts`).
|
|
30
|
+
3. **File creation.** Switching scope to `project` when
|
|
31
|
+
`.shepherd/config.json` does not exist creates it (as `{}` — empty delta,
|
|
32
|
+
no overrides) and sends a notification that the file was created.
|
|
33
|
+
4. **Override semantics.** The project file is a **delta**: fields override
|
|
34
|
+
the user layer one by one. Only fields that actually differ from the user
|
|
35
|
+
layer are written to the project file ("write only changed").
|
|
36
|
+
5. **Menu writes follow the current scope.** Scope is `user` → edits go to
|
|
37
|
+
the user file; scope is `project` → edits go to the project file.
|
|
38
|
+
6. **All fields are project-overridable** — except `settingsScope` itself,
|
|
39
|
+
which by definition lives only in the user file (it is the pointer to
|
|
40
|
+
where to look; a project file cannot select its own scope).
|
|
41
|
+
7. **Naming.** "Settings" is the interactive menu; the persisted artifacts are
|
|
42
|
+
*config*. Rename user file `settings.json` → `config.json` (one-shot
|
|
43
|
+
migration), module `settings.ts` → `config.ts`. Project file is
|
|
44
|
+
`.shepherd/config.json`.
|
|
45
|
+
|
|
46
|
+
## 3. Design
|
|
47
|
+
|
|
48
|
+
### 3.1 Storage core — `src/extension/settings.ts` → `src/extension/config.ts`
|
|
49
|
+
|
|
50
|
+
- New type `ConfigScope = "user" | "project"`. `ShepherdSettings` gains
|
|
51
|
+
`settingsScope: ConfigScope`, default `"user"` (user-file-only field).
|
|
52
|
+
- `userConfigFile()` → `~/.pi/agent/pi-shepherd/config.json` (same dir as
|
|
53
|
+
`created-panes.json`).
|
|
54
|
+
- `projectConfigFile(cwd)` → `path.resolve(cwd, ".shepherd", "config.json")`.
|
|
55
|
+
- One-time migration, same pattern as the existing timeout ms→min migration
|
|
56
|
+
in `loadSettings()`:
|
|
57
|
+
- `config.json` missing AND old `~/.pi/agent/pi-shepherd/settings.json`
|
|
58
|
+
exists → move the old file to `config.json`, silently.
|
|
59
|
+
- Both exist → `config.json` wins; old file left in place (no deletion).
|
|
60
|
+
- Only old file / neither / parse errors behave as today (defaults).
|
|
61
|
+
- `loadSettings(cwd?)`:
|
|
62
|
+
1. Load user layer: file (or defaults), validated/merged, **mtime-cached
|
|
63
|
+
per file path** (replaces the single global cache).
|
|
64
|
+
2. Resolve effective scope from the user layer's `settingsScope`.
|
|
65
|
+
3. If `project` and `cwd` given: read `.shepherd/config.json`, validate each
|
|
66
|
+
known field, overlay over the user layer. `{}` / missing / unreadable →
|
|
67
|
+
pure user layer. `settingsScope` in a project file is ignored (the merge
|
|
68
|
+
function simply never applies it).
|
|
69
|
+
4. Return merged `ShepherdSettings`.
|
|
70
|
+
- `saveSettings(next: ShepherdSettings, scope: ConfigScope = "user",
|
|
71
|
+
projectRoot?: string): { file: string, created: boolean }`:
|
|
72
|
+
- `user`: write the full object (today's behavior; `settingsScope`
|
|
73
|
+
always written).
|
|
74
|
+
- `project`: diff `next` against the current user layer; write only the
|
|
75
|
+
fields whose values differ (`{}` when all equal). Create the file (and
|
|
76
|
+
`.shepherd/` dir) if missing; `created` is true when a new file is born.
|
|
77
|
+
The `settingsScope` field is never written to the project file.
|
|
78
|
+
- Keep the mtime cache in sync after writes.
|
|
79
|
+
- `initializeSessionSettings(cwd?)` — the fieldnotes session snapshot reads
|
|
80
|
+
the merged, cwd-aware value (a session started inside a project sees
|
|
81
|
+
project-overridden fieldnotes state).
|
|
82
|
+
|
|
83
|
+
### 3.2 Settings menu — `src/extension/settings-ui.ts`
|
|
84
|
+
|
|
85
|
+
- New first `SettingItem`: **Settings scope** (`user`/`project`, ≤ 30-char
|
|
86
|
+
label), description notes that project values override user values.
|
|
87
|
+
- Menu opens with `ctx.cwd`; displayed values are the merged ones when scope
|
|
88
|
+
is `project`, so the menu shows exactly what the system is using.
|
|
89
|
+
- Change handling on the list `onChange`:
|
|
90
|
+
- **scope change** → always saved to the **user** file. If the new scope is
|
|
91
|
+
`project` and the project file didn't exist → create it (`{}` or the
|
|
92
|
+
current delta) and notify: `Config created at .shepherd/config.json`.
|
|
93
|
+
- **any other field** → saved to the **current scope's** file (user or
|
|
94
|
+
project delta). Project saves reuse the same created-notification when
|
|
95
|
+
the file is born.
|
|
96
|
+
- Existing notifications for `fieldnotes` (next-session effect) and
|
|
97
|
+
`agentScope` (repo-controlled notice) are preserved.
|
|
98
|
+
- Wrap saves in try/catch → error-level notification on failure (e.g.
|
|
99
|
+
read-only project directory) instead of an uncaught throw inside the TUI.
|
|
100
|
+
|
|
101
|
+
### 3.3 Thread `cwd` into every `loadSettings()` call
|
|
102
|
+
|
|
103
|
+
| Call site | cwd source |
|
|
104
|
+
|---|---|
|
|
105
|
+
| `src/core/lifecycle.ts` `startAgent` | `ctx.cwd` (already available) |
|
|
106
|
+
| `src/extension/shepherd.ts` `doAction` (spawn/prompt/wait/agents) | `ctx.cwd` |
|
|
107
|
+
| `src/extension/settings-ui.ts` `openSettings` | `ctx.cwd` |
|
|
108
|
+
| `src/extension/config.ts` `initializeSessionSettings` | `ctx.cwd` in `session_start` |
|
|
109
|
+
| `index.ts` widget render + command arg completions | `shepherdCommandCwd` |
|
|
110
|
+
|
|
111
|
+
No change to tool parameters: scope remains implicit from the config files,
|
|
112
|
+
exactly as `agentScope` resolution works today.
|
|
113
|
+
|
|
114
|
+
## 4. Behavior notes (accepted)
|
|
115
|
+
|
|
116
|
+
- Stale project deltas persist: if the project file overrides `keepOpen:
|
|
117
|
+
true` and you later change `keepOpen` to `false` in the user scope, the
|
|
118
|
+
project layer still wins while scope is `project`. Inherent to override
|
|
119
|
+
semantics.
|
|
120
|
+
- The merged result, not the raw files, is what tools/lifecycle consume; a
|
|
121
|
+
model-facing call that passes explicit args still wins over both layers
|
|
122
|
+
(no change).
|
|
123
|
+
- Editing `.shepherd/config.json` by hand takes effect immediately (mtime
|
|
124
|
+
cache), like the user file today.
|
|
125
|
+
|
|
126
|
+
## 5. Tests (`npm test`)
|
|
127
|
+
|
|
128
|
+
`test/verify-settings.mjs` (renamed expectations to the new file names):
|
|
129
|
+
- Project overlay: user `fieldnotes: true` + project `{ "fieldnotes": false }`
|
|
130
|
+
→ merged `false`; untouched fields stay user values.
|
|
131
|
+
- Delta-only writes: saving one changed field in project scope writes only
|
|
132
|
+
that field; unchanged fields are absent from the file; `{}` when nothing
|
|
133
|
+
differs.
|
|
134
|
+
- Scope switch: first change with scope `project` when no file exists →
|
|
135
|
+
created flag set, file exists, content is the delta (initially `{}`).
|
|
136
|
+
- `settingsScope` in a project file is ignored.
|
|
137
|
+
- Migration: old `~/.pi/agent/pi-shepherd/settings.json` without `config.json`
|
|
138
|
+
→ moved to `config.json`, values intact, old name gone. Both exist →
|
|
139
|
+
`config.json` wins, old name untouched.
|
|
140
|
+
- Fieldnotes session snapshot honors the merged (project-overridden) value.
|
|
141
|
+
|
|
142
|
+
`test/verify-command-ux.mjs`: existing `settings.json` fixture → `config.json`.
|
|
143
|
+
|
|
144
|
+
Live check (this repo): `/shepherd settings` → toggle scope `project` →
|
|
145
|
+
`.shepherd/config.json` appears (with the creation notification) → change a
|
|
146
|
+
field → file contains only the delta → toggle back + delete → user values
|
|
147
|
+
restore.
|
|
148
|
+
|
|
149
|
+
## 6. Docs
|
|
150
|
+
|
|
151
|
+
- README/docs mentions of `settings.json` → user `~/.pi/agent/pi-shepherd/
|
|
152
|
+
config.json` + project `.shepherd/config.json`, with the override model in
|
|
153
|
+
one short paragraph.
|
|
154
|
+
- `AGENTS.md`: short note on the two-file config model (user layer + project
|
|
155
|
+
delta; `settingsScope` user-only).
|
|
156
|
+
- Module rename `settings.ts` → `config.ts`; update the file-header comment
|
|
157
|
+
and all imports (9 call sites listed in §3.3 plus tests).
|
|
158
|
+
|
|
159
|
+
## 7. Out of scope
|
|
160
|
+
|
|
161
|
+
- Per-workspace (multi-root) config; config in `.pi/` instead of `.shepherd/`.
|
|
162
|
+
- A config "reload" command or file-watcher (mtime cache suffices).
|
|
163
|
+
- Restricting which fields the project layer may override (decided: all).
|
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
# Plan: Split the Shepherd Tool Surface
|
|
2
|
+
|
|
3
|
+
Status: in progress — Phases 0–5 complete (verified 2026-08-26). Next: Phase 6.
|
|
4
|
+
Related discussion: constrained-sampling backends drop arguments on bare-`anyOf` tool schemas
|
|
5
|
+
|
|
6
|
+
## 1. Problem
|
|
7
|
+
|
|
8
|
+
`shepherd.ts` defines the model-facing tool parameters as a TypeBox discriminated
|
|
9
|
+
union:
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
export const ShepherdParams = Type.Union([HerdParams, AgentsParams, StartParams, ...], {...});
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
The emitted JSON Schema has **no root `"type": "object"`** — only `{"anyOf": [...],
|
|
16
|
+
"description": "..."}`. Pi passes `tool.parameters` to providers essentially unchanged.
|
|
17
|
+
Backends that use grammar/schema-constrained decoding of tool-call arguments (observed
|
|
18
|
+
with `stealth/ox-alpha` via OpenRouter) have no allowed properties at the top level and
|
|
19
|
+
emit `{}` for every call, unrecoverably. Models served behind soft-guidance APIs
|
|
20
|
+
(Claude/GPT first-party) work fine, which masks the bug.
|
|
21
|
+
|
|
22
|
+
Secondary issues surfaced by the investigation:
|
|
23
|
+
|
|
24
|
+
- Cross-field rules (`wait` requires a prompt `id`) are enforced by JSON Schema today, but
|
|
25
|
+
any flattening loses that unless handled explicitly.
|
|
26
|
+
- The unified conceptual narrative (sheep, ids, lifecycle ordering) lives inside the
|
|
27
|
+
single tool description, coupling "what shepherd is" to "how one tool is shaped".
|
|
28
|
+
- The existing `/shepherd` command duplicates logic (`agents`/`herd`/`start` re-implement
|
|
29
|
+
what `doAction` already does) instead of delegating to the same core.
|
|
30
|
+
|
|
31
|
+
## 2. Goals
|
|
32
|
+
|
|
33
|
+
1. No bare-`anyOf` root anywhere on the wire → works on constrained backends.
|
|
34
|
+
2. Declarative requiredness (`id: required`) via separate flat-schema tools.
|
|
35
|
+
3. Preserve user ergonomics: `/shepherd spawn worker` (renamed from `start`) keeps working, gains coverage.
|
|
36
|
+
4. Single source of truth for behavior: both tools and command delegate to core.
|
|
37
|
+
5. Unified meta-description ("subagent framework for native Herdr orchestration") kept
|
|
38
|
+
in one obvious place.
|
|
39
|
+
|
|
40
|
+
## Non-goals
|
|
41
|
+
|
|
42
|
+
- No changes to Herdr integration, discovery precedence, or pane ownership invariants.
|
|
43
|
+
- No pi-core changes (schema normalization stays out of scope).
|
|
44
|
+
- No renaming of persisted settings or artifact-session behavior.
|
|
45
|
+
|
|
46
|
+
## 3. Target architecture
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
┌──────────── core: doAction() / lifecycle.ts ────────────┐
|
|
50
|
+
│ single source of truth for behavior │
|
|
51
|
+
▼ ▼ ▼
|
|
52
|
+
model surface (flat tools) user surface (/shepherd cmd) future RPC?
|
|
53
|
+
├─ shepherd (herd|agents|prune) ├─ agents, herd, spawn (existing, renamed)
|
|
54
|
+
├─ shepherd_spawn (agent, options…) ├─ status, read (new)
|
|
55
|
+
├─ shepherd_prompt (id, message, timeout) └─ prompt/wait/close (new, see §5)
|
|
56
|
+
├─ shepherd_watch (id[], timeout)
|
|
57
|
+
├─ shepherd_status (id)
|
|
58
|
+
├─ shepherd_close (id)
|
|
59
|
+
└─ shepherd_read (name, lines, source)
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Schema fragments shared across tools: opaque agent/prompt id schemas, timeout/lines/source optionals.
|
|
63
|
+
|
|
64
|
+
## 4. Phases
|
|
65
|
+
|
|
66
|
+
### Phase 0 — Baseline & guardrails
|
|
67
|
+
|
|
68
|
+
- [x] Capture current behavior: run `npm test`; record pass set. ✅ All 8 suites pass (schemas:test was added as the 8th).
|
|
69
|
+
- [x] Add a schema-shape regression test: assert every registered tool's root JSON Schema
|
|
70
|
+
has `"type": "object"` (fails today for `shepherd`; becomes the invariant).
|
|
71
|
+
✅ `test/verify-tool-schemas.mjs` added as `schemas:test`; wired into the default
|
|
72
|
+
`test` chain (runs first) and green now that the union is gone. Phase 3 adds the
|
|
73
|
+
six new tools to the checked list (placeholders already in the file).
|
|
74
|
+
- [ ] Optional: snapshot the current serialized `ShepherdParams` for diffing. (skipped — the flat schema is small enough to verify by eye)
|
|
75
|
+
|
|
76
|
+
Files: `test/verify-tool-schemas.mjs` (new), `package.json` (wire test if needed).
|
|
77
|
+
|
|
78
|
+
### Phase 1 — Unify the core path
|
|
79
|
+
|
|
80
|
+
Make `doAction()` the single entry so tools and command can never diverge.
|
|
81
|
+
|
|
82
|
+
- [x] Refactor `/shepherd` handler branches (`agents`, `herd`, `start`) to construct args
|
|
83
|
+
objects and call `doAction()`, rendering via a small result-to-notification helper,
|
|
84
|
+
instead of calling `discoverAgents`/`listHerdrAgents`/`startAgent` directly.
|
|
85
|
+
✅ Done via `runCommandAction()` in `index.ts`; results surface as notifications.
|
|
86
|
+
- [x] Keep `settings` branch command-only (no model-facing equivalent needed).
|
|
87
|
+
- [x] Extract `parentArtifactSessionForCommand` reuse so command and tool resolve
|
|
88
|
+
artifact sessions identically.
|
|
89
|
+
✅ Via the "explicit `artifactSession` wins" pattern: the command pre-resolves
|
|
90
|
+
tolerantly and passes the value, `doAction` honors an explicit value before
|
|
91
|
+
resolving/requiring the parent session itself.
|
|
92
|
+
|
|
93
|
+
Acceptance: `/shepherd agents|herd|start <agent>` behave identically before/after;
|
|
94
|
+
command tests still pass.
|
|
95
|
+
|
|
96
|
+
Files: `index.ts`, possibly new `cli.ts` for arg parsing/render helpers.
|
|
97
|
+
|
|
98
|
+
### Phase 2 — Flatten the retained `shepherd` tool
|
|
99
|
+
|
|
100
|
+
Reduce `shepherd` to the control plane + inspection actions.
|
|
101
|
+
|
|
102
|
+
- [ ] Replace `Type.Union([...])` with one `Type.Object`: ✅
|
|
103
|
+
- `action`: enum `['herd','agents','prune']`, plus optional `agentScope` (shared field for `agents`).
|
|
104
|
+
- description: meta-narrative + compact per-action table. ✅
|
|
105
|
+
- No per-action fields remain (`read` moved to `shepherd_read` in Phase 3). ✅
|
|
106
|
+
- The old union survives internally as `AnyShepherdUnion`; `ShepherdArgs`
|
|
107
|
+
(= its Static type) remains the core doAction signature so command and
|
|
108
|
+
future tools keep full-typed access to every verb.
|
|
109
|
+
- [ ] Runtime validation is trivial at this point (enum-only); keep the same
|
|
110
|
+
friendly text-result style used elsewhere. ✅ (doAction switch unchanged)
|
|
111
|
+
- [x] Update `prepareShepherdArguments`: kept as-is (string-coercion recovery for
|
|
112
|
+
handles, booleans, integers); reused by the Phase 3 tools. ✅
|
|
113
|
+
- [x] Update `renderCall`/`renderResult` — they key off `args.action` and kept working.
|
|
114
|
+
|
|
115
|
+
Acceptance: schema test from Phase 0 passes ✅; `npm test` green ✅; serialized
|
|
116
|
+
schema confirmed flat (`type: object`, enum action) ✅.
|
|
117
|
+
|
|
118
|
+
Files: `shepherd.ts`. ✅ Done
|
|
119
|
+
|
|
120
|
+
### Phase 3 — Extract lifecycle tools
|
|
121
|
+
|
|
122
|
+
One registration helper, six declarative tools. All roots are plain objects.
|
|
123
|
+
|
|
124
|
+
- [x] Generalize `registerShepherdTool` into `registerShepherdTools(pi)` registering:
|
|
125
|
+
- `shepherd_spawn`: `agent` (required), `label` (required), and optional
|
|
126
|
+
`placement` (`pane_right`, `pane_down`, `tab`, or `workspace`), `cwd`, and
|
|
127
|
+
`model`. Agent scope, project approval, and system-prompt behavior come
|
|
128
|
+
from settings and the discovered agent definition. ✅ (deliberately no
|
|
129
|
+
`timeout`: startup readiness uses fixed internal grace periods; timeout only
|
|
130
|
+
applies to prompts/waits — see the start-case comment in `doAction`)
|
|
131
|
+
- `shepherd_prompt`: `id` (required agent id), `message` (required), `timeout` ✅
|
|
132
|
+
- `shepherd_watch`: `id` (required prompt id or array of prompt ids), `timeout` ✅
|
|
133
|
+
- `shepherd_status`: `id` (required agent id) ✅
|
|
134
|
+
- `shepherd_close`: `id` (required agent id) ✅
|
|
135
|
+
- `shepherd_read`: `name` (required), `lines`?, `source`? ✅
|
|
136
|
+
- Note: the core action `start` was renamed to `spawn` (`SpawnParams`) to match the
|
|
137
|
+
tool naming scheme; the `/shepherd` command verb was renamed in Phase 4.
|
|
138
|
+
- [x] Share lifecycle id, timeout, and completion-state schemas across definitions.
|
|
139
|
+
✅ Originally derived with `Type.Omit(<LifecycleParams>, ['action'])`; superseded by the
|
|
140
|
+
AGENTS.md convention that every registration spells out its fields inline, so each
|
|
141
|
+
tool registration now declares its full `Type.Object` directly (identical fields and
|
|
142
|
+
descriptions; the shared `*Params` schemas in `types.ts` remain the internal
|
|
143
|
+
union/`doAction` contract only).
|
|
144
|
+
- [x] Each tool delegates to `doAction({action: '<verb>', ...params}, ...)`.
|
|
145
|
+
✅ Via a shared `executeShepherd(label, args, ctx, ...)` wrapper (Herdr gate +
|
|
146
|
+
try/catch to a friendly text result).
|
|
147
|
+
- [x] Per-tool `description`: short, operational; cross-references siblings
|
|
148
|
+
("Pass the agent id returned by shepherd_spawn" etc.). ✅
|
|
149
|
+
- [x] `renderCall`: per-tool CLI-style call preview reusing `shepherdCallPreview`
|
|
150
|
+
internals (e.g. `shepherd_spawn scout --cwd …`), plus a shared `renderToolResult`. ✅
|
|
151
|
+
- [x] Split `promptSnippet`/`promptGuidelines`: lifecycle tools share one snippet line;
|
|
152
|
+
the control tool keeps the narrative + guidelines; the old `Workflow:` guideline
|
|
153
|
+
line was dropped (superseded by per-tool descriptions). Full narrative relocation
|
|
154
|
+
remains Phase 5.
|
|
155
|
+
|
|
156
|
+
Acceptance: schema test passes for all seven tools ✅; `npm test` green ✅; live
|
|
157
|
+
end-to-end verified under a running Herdr session: idle spawn, non-blocking prompt,
|
|
158
|
+
wait (status `done`), status, close, read-after-close, and prune ✅. (Full multi-wait /
|
|
159
|
+
close-cancellation live matrix stays in Phase 7 alongside the constrained-backend check.)
|
|
160
|
+
|
|
161
|
+
Files: `shepherd.ts`, `types.ts` (`SpawnParams`), `index.ts`. ✅ Done
|
|
162
|
+
|
|
163
|
+
### Phase 4 — Extend the `/shepherd` command
|
|
164
|
+
|
|
165
|
+
Bring the human surface up to parity, scoped sensibly.
|
|
166
|
+
|
|
167
|
+
- [x] Decide blocking policy (recommended): allow quick actions only —
|
|
168
|
+
`status`, `read` join `agents|herd|spawn|settings`; keep `prompt`/`wait`/
|
|
169
|
+
`close` **model-only** initially (they can block minutes or mutate agent state
|
|
170
|
+
mid-conversation). Revisit after real-world use.
|
|
171
|
+
✅ `status` + `read` are command actions; prompt/wait/close remain model-only.
|
|
172
|
+
- [x] Rename the command verb `start` → `spawn` everywhere (handler branch,
|
|
173
|
+
completions, hints); no alias retained. ✅ (/shepherd list|sheep aliases for
|
|
174
|
+
*agents* remain, as before.)
|
|
175
|
+
- [x] Factor the CLI grammar into `parseShepherdCli(args)` shared with
|
|
176
|
+
`shepherdCallPreview` (parser = inverse of renderer); replace
|
|
177
|
+
`parseStartCommand` with it.
|
|
178
|
+
✅ Now `cli.ts`: one `OPTION_SPECS` table drives both `parseShepherdCli` (human)
|
|
179
|
+
and `formatShepherdCommand` (tool-call previews, moved out of `shepherd.ts`). A
|
|
180
|
+
quote-aware `tokenizeCli` makes the command split the exact inverse of the
|
|
181
|
+
renderer's JSON quoting, so a rendered line reparses to the same args.
|
|
182
|
+
Covered by the new `cli:test` suite (parses, rejections, round-trips).
|
|
183
|
+
- [x] Extend `getArgumentCompletions`: actions first; for `status`/`read`, complete
|
|
184
|
+
discovered agent names (reuse the pattern already used for `spawn`).
|
|
185
|
+
✅ Action list now includes `status`/`read`; both also complete live
|
|
186
|
+
agent ids from the session registry; 3-char-prefix candidates
|
|
187
|
+
(`/shepherd spo` → `spawn <agent>`) preserved for spawn/status/read.
|
|
188
|
+
- [x] `status` target resolution: `statusHandleTarget` maps agent name / lifecycle id /
|
|
189
|
+
pane id to the opaque lifecycle id (live-registry lookup, id fallback).
|
|
190
|
+
|
|
191
|
+
Acceptance: `/shepherd status <agent>` prints summary ✅ (live: state `idle` after
|
|
192
|
+
spawn); unknown input prints the updated hint line ✅ (`parseShepherdCli` error +
|
|
193
|
+
Usage); command paths live-verified (status, read w/ quoted args). The full TUI UX
|
|
194
|
+
pass (completions feel, long-running guardrails) stays in Phase 7.
|
|
195
|
+
|
|
196
|
+
Files: `cli.ts` (new), `index.ts`, `shepherd.ts` (preview moved to cli.ts),
|
|
197
|
+
`test/verify-cli.mjs` (new), `package.json` (wire `cli:test`), plan doc.
|
|
198
|
+
|
|
199
|
+
### Phase 5 — Consolidate the Shepherd narrative
|
|
200
|
+
|
|
201
|
+
Keep general Shepherd knowledge scoped to the umbrella `shepherd` tool rather than
|
|
202
|
+
injecting it into the global parent system prompt.
|
|
203
|
+
|
|
204
|
+
- [x] Make the umbrella `shepherd` tool the documentation and guidance hub for the
|
|
205
|
+
complete Shepherd tool family (`agents`, `herd`, `prune`, `spawn`, `prompt`,
|
|
206
|
+
`wait`, `status`, `close`, and `read`). ✅ Its description and prompt guidelines
|
|
207
|
+
now document the control-plane actions and the full lifecycle.
|
|
208
|
+
- [x] Put shared lifecycle guidance on the umbrella tool: wait for independent work
|
|
209
|
+
concurrently when possible, waiting does not close agents, pass lifecycle ids
|
|
210
|
+
unchanged, and follow the shared `shepherd.md` fieldnotes contract. ✅
|
|
211
|
+
- [x] Keep individual lifecycle tool descriptions short and operational; retain only
|
|
212
|
+
tool-specific usage hints and parameter expectations there. ✅ Removed duplicated
|
|
213
|
+
wait/close lifecycle guidance from the split tool descriptions.
|
|
214
|
+
- [x] Keep the meta-description ("subagent framework for native Herdr orchestration")
|
|
215
|
+
at the top of the umbrella `shepherd` tool description and the command description. ✅
|
|
216
|
+
- [x] Verify that the umbrella Shepherd tools and their guidance are exposed only in
|
|
217
|
+
the parent/orchestrator session, not in launched worker sessions. ✅ Added a
|
|
218
|
+
`PI_SHEPHERD_SESSION` guard around parent-only Shepherd tools, commands, settings,
|
|
219
|
+
and widget registration; the new `parent-surface:test` probes both environments.
|
|
220
|
+
- [x] Do not add a global `before_agent_start` lifecycle-guidance hook unless a later
|
|
221
|
+
use case shows that the umbrella tool's scoped guidance is insufficient. ✅
|
|
222
|
+
|
|
223
|
+
Acceptance: the umbrella `shepherd` tool explains the shared lifecycle and fieldnote
|
|
224
|
+
rules; each split tool explains only its own operation; worker sessions do not receive
|
|
225
|
+
parent orchestration tools or guidance. ✅ `npm test` green.
|
|
226
|
+
|
|
227
|
+
Files: `shepherd.ts`, `index.ts`, `test/verify-parent-surface.mjs`, `package.json`.
|
|
228
|
+
|
|
229
|
+
### Phase 6 — Docs & conventions
|
|
230
|
+
|
|
231
|
+
- [x] AGENTS.md: replace "the model-facing tool definition is the source of truth"
|
|
232
|
+
with "core semantics live in `doAction()`/`lifecycle.ts`; tools and `/shepherd`
|
|
233
|
+
are thin adapters." ✅
|
|
234
|
+
- [x] `docs/dictionary`: add entries for the split tool names and note the two surfaces. ✅
|
|
235
|
+
- [x] README: update invocation examples (both `shepherd_watch …` and `/shepherd …`),
|
|
236
|
+
add a compatibility note (old `shepherd action=prompt` form is gone). ✅
|
|
237
|
+
- [x] Grep sweep for stale references: `shepherd action=`, `action=start` etc. in
|
|
238
|
+
active docs, skills, prompts, and test fixtures. ✅ Current public docs and
|
|
239
|
+
implementation references are clean; the archived Phase 2 design records
|
|
240
|
+
retain historical `start` terminology, while current Phase 3 artifact examples
|
|
241
|
+
use `spawn`.
|
|
242
|
+
|
|
243
|
+
### Phase 7 — Verification
|
|
244
|
+
|
|
245
|
+
- [x] `npm test` fully green including the flat-object schema-invariant test. ✅
|
|
246
|
+
- [x] Live Herdr checklist (per AGENTS.md): idle spawn, non-blocking prompt,
|
|
247
|
+
single wait/result, concurrent multi-wait, iterative prompting, status,
|
|
248
|
+
close cancellation, focus preservation, ownership protection. ✅ Verified
|
|
249
|
+
against the running Herdr server; owned panes were closed and stale
|
|
250
|
+
registrations pruned.
|
|
251
|
+
- [x] Constrained-backend check: `stealth/ox-alpha` is no longer available
|
|
252
|
+
(OpenRouter returned 404), so `z-ai/glm-5.3` was used instead; it emitted
|
|
253
|
+
`{"action":"agents"}` and completed the call successfully. ✅
|
|
254
|
+
- [x] Soft-guidance sanity: GPT-style `openai/gpt-5.6-luna` selected the split
|
|
255
|
+
`shepherd_prompt` and `shepherd_read` tools with structured arguments. ✅
|
|
256
|
+
- [x] Command UX pass: added `test/verify-command-ux.mjs` covering partial and
|
|
257
|
+
argument completions, usage/error hints, and spawn status cleanup. ✅
|
|
258
|
+
|
|
259
|
+
## 5. Open decisions
|
|
260
|
+
|
|
261
|
+
| Question | Decision |
|
|
262
|
+
|---|---|
|
|
263
|
+
| Tool naming scheme | **Resolved:** `shepherd_<verb>`, lifecycle verbs are `spawn`, `prompt`, `wait`, `status`, `close`, `read` |
|
|
264
|
+
| `start` vs `spawn` in `/shepherd` command | **Resolved:** `/shepherd spawn worker` fully replaces `/shepherd start worker`; no alias |
|
|
265
|
+
| `read` placement | **Resolved:** own tool `shepherd_read(name, lines?, source?)` |
|
|
266
|
+
| Lifecycle reference representation | **Resolved:** public tools accept opaque string ids (an array of ids for wait); full handles remain internal, with legacy nested handles migrated in `prepareShepherdArguments` |
|
|
267
|
+
| Old single-tool form | **Resolved:** hard remove; grep sweep covers stragglers |
|
|
268
|
+
| `prompt`/`wait`/`close` via command | **Resolved:** model-only initially; revisit after real-world use |
|
|
269
|
+
| General lifecycle guidance location | **Resolved:** umbrella `shepherd` tool guidance; do not use the global system prompt initially |
|
|
270
|
+
|
|
271
|
+
## 6. Risk notes
|
|
272
|
+
|
|
273
|
+
- **Largest regression risk**: Phase 3 splitting — mitigated by keeping every tool a
|
|
274
|
+
pure `doAction` delegate and reusing verify scripts unchanged.
|
|
275
|
+
- **Prompt-quality risk**: models accustomed to one tool may mis-select between
|
|
276
|
+
`prompt`/`wait`; mitigated by cross-referencing descriptions + umbrella-tool guidance.
|
|
277
|
+
- **Doc drift**: two surfaces double the places to update; the grep sweep in Phase 6 is
|
|
278
|
+
the safety net.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Shepherd Concept Dictionary
|
|
2
|
+
|
|
3
|
+
- **Shepherd**: The main orchestrator agent. The main pi session running the pi-shepherd extension. The shepherd is responsible for managing the lifecycle of his herd of sheep.
|
|
4
|
+
- **Sheep**: Are agents created by the shepherd. Also called a subagent in other contexts. Sheep are the workers that perform tasks assigned by the shepherd. Each with a unique role defined by their markdown file.
|
|
5
|
+
- **Herd**: The collection of sheep managed by the shepherd. The herd can consist of multiple sheep, each with their own unique role and responsibilities. A herd is tied to the shepherd's pi session.
|
|
6
|
+
- **Fieldnotes**: A collection of notes tied to the session. in other frameworks this are sometimes called artifacts.
|
|
7
|
+
- **Note**: A single note in the fieldnotes. Each note belongs to a specific sheep or shepherd. Notes are used to by its owner to track and convey information about their work, progress, and observations. The Shepherd´s notes are used to track the overall progress of the herd and to provide guidance and feedback to future sheep. Notes can be created, updated, and deleted by their owner. Notes can be shared with other sheep or the shepherd for collaboration and feedback.
|
|
8
|
+
- **Sheep's note**: A note created by a sheep to track its work, observations, and progress, and to provide information for the shepherd and other sheep.
|
|
9
|
+
- **Shepherd's note**: A note created by the shepherd to track the overall progress of the herd and to provide guidance, feedback, and a map to all present and future sheep.
|
|
10
|
+
- **Session**: A session is tied to the shepherd's pi session and is used to track the state of the herd and its sheep.
|
|
11
|
+
- **Control-plane tool**: The model-facing `shepherd` tool. It handles cheap meta-actions: `agents`, `herd`, and `prune`, and serves as the guidance hub for the Shepherd tool family.
|
|
12
|
+
- **Lifecycle tools**: The separate model-facing tools `shepherd_spawn`, `shepherd_delegate`, `shepherd_message`, `shepherd_watch`, `shepherd_status`, `shepherd_close`, and `shepherd_read`, plus the deprecated `shepherd_prompt`. Each has a flat object schema and delegates to the shared `doAction()` core.
|
|
13
|
+
- **Model-facing surface**: The structured `shepherd` control tool plus the six `shepherd_<verb>` lifecycle tools. Lifecycle tools accept opaque scalar ids; the provider may wrap their argument object in its own transport envelope.
|
|
14
|
+
- **Command surface**: The human `/shepherd` command. It supports `agents`, `herd`, `spawn`, `status`, `read`, and `settings`; prompt/close remain model-only for now.
|
|
15
|
+
- **Agent id**: An opaque, session-scoped id returned by `shepherd_spawn` that identifies an owned agent. It is distinct from any Herdr pane id and is accepted by `shepherd_prompt`, `shepherd_status`, and `shepherd_close`.
|
|
16
|
+
- **Prompt id**: An opaque, session-scoped id returned by the deprecated `shepherd_prompt` that identifies one submitted child turn. It is accepted by `shepherd_watch` on the legacy path.
|
|
17
|
+
- **Task**: The tracked unit of delegated work. A task has a state (`created`, `running`, `waiting`, `completed`, `blocked`, `failed`, `cancelled`, `timed_out`) that is independent of the Herdr process state. Only `shepherd_done` or an explicit failure/cancel/timeout settles a task; an idle or ended child process never does.
|
|
18
|
+
- **Task id**: An opaque, session-scoped id returned by `shepherd_delegate`. It is the correlation key for task watchers, tracked replies, and `shepherd_done`.
|
|
19
|
+
- **Message**: An asynchronous, parent-mediated envelope between Shepherd and owned agents (or between agents in a shared project). A message is not a task and does not allocate a fieldnote on its own.
|
|
20
|
+
- **Message id**: An opaque, session-scoped id returned when a message is accepted. The agent answering a tracked request echoes it as `replyTo` so the reply correlates with the request.
|
|
21
|
+
- **Tracked reply request**: The state opened when a message with `expectsReply` is delivered to a task-owned agent. The sender's task enters `waiting` until a matching reply, a `shepherd_done`, close, or the reply deadline (which settles the task to `blocked`).
|
|
22
|
+
- **Waiting task (idle child)**: A task in `waiting` whose Herdr process is `idle` because its pi turn ended. Status and the TUI widget keep it visible, render the elapsed wait and the expected recipient, and flag it `stale` after a stale-wait reminder.
|
|
23
|
+
- **Stale-wait reminder**: An informational-only follow-up (no turn trigger) sent at most once per waiting episode after `staleWaitThreshold` minutes with no reply. It never settles the task; the reply deadline remains the only settlement path.
|
|
24
|
+
- **`followUp` / `steer` delivery**: `followUp` queues a message for the next child turn (default); `steer` injects it as urgent input into the agent's active turn.
|
|
25
|
+
- **Internal AgentHandle/PromptHandle/TaskHandle**: Full objects retained inside the lifecycle registry and TypeScript implementation. They are not part of the recommended model-facing protocol.
|
|
26
|
+
- **Parent broker**: The in-parent message channel that routes envelopes between the Shepherd and owned agents, delivers follow-ups, and enforces provenance. It is parent-scoped: children receive a child capability and can only talk through the broker.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Release checklist
|
|
2
|
+
|
|
3
|
+
Shepherd ships as one package with two independent host adapters. Every
|
|
4
|
+
release must say which host(s) it affects and must have run both verification
|
|
5
|
+
harnesses.
|
|
6
|
+
|
|
7
|
+
## Checklist
|
|
8
|
+
|
|
9
|
+
- [ ] Run `npm test` — this runs `pi-suite:test` **and** `opencode-suite:test`.
|
|
10
|
+
A release with either suite red does not ship.
|
|
11
|
+
- [ ] Determine host impact for the release range:
|
|
12
|
+
`npm run host-impact -- <previous-tag>..HEAD`
|
|
13
|
+
(or `npm run host-impact -- --files a,b,c` for an uncommitted set).
|
|
14
|
+
- [ ] Write release notes with an explicit **Pi impact** and **OpenCode impact**
|
|
15
|
+
line. Use `none` when a host is untouched — do not leave it implicit.
|
|
16
|
+
- [ ] If impact is Pi-only, verify the range has zero `src/opencode/` edits;
|
|
17
|
+
if OpenCode-only, verify zero `src/extension/`, `index.ts`, or Pi entry
|
|
18
|
+
edits. Shared `src/core/`, `src/runtimes/`, packaging, and docs changes
|
|
19
|
+
are cross-host and must be called out for both.
|
|
20
|
+
- [ ] For the farewell/rename pair, publish the **new package first** so the
|
|
21
|
+
migration pointer is never a 404:
|
|
22
|
+
1. Publish `@luminascale/shepherd@<new-version>` (`0.6.0` for the rename).
|
|
23
|
+
2. Publish the final old-name release from a short-lived release branch
|
|
24
|
+
or worktree that restores `"name": "@luminascale/pi-shepherd"` and
|
|
25
|
+
sets `0.5.2`. Its notice is gated by a per-host marker file and is
|
|
26
|
+
never emitted in a child sheep process.
|
|
27
|
+
3. Deprecate the old name with a pointer:
|
|
28
|
+
`npm deprecate @luminascale/pi-shepherd@0.5.2 "Moved to @luminascale/shepherd"`.
|
|
29
|
+
T018 still means the old name gets its final notice-bearing release and
|
|
30
|
+
is deprecated; T019 is the new package name. The user-facing ordering
|
|
31
|
+
requirement is that the pointer target exists before the pointer ships.
|
|
32
|
+
- [ ] Publish and confirm the install path from each host's own docs:
|
|
33
|
+
`pi install npm:<package>` and the OpenCode `plugins` entry.
|
|
34
|
+
|
|
35
|
+
## Host impact notes template
|
|
36
|
+
|
|
37
|
+
```markdown
|
|
38
|
+
## <version>
|
|
39
|
+
|
|
40
|
+
- Pi impact: <none | summary>
|
|
41
|
+
- OpenCode impact: <none | summary>
|
|
42
|
+
- Shared/engine impact: <none | summary>
|
|
43
|
+
- Verification: npm test (Pi + OpenCode suites) — pass
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
`npm run host-impact` classifies changed paths so the notes can be filled in
|
|
47
|
+
from evidence rather than memory.
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Phase 0 Baseline
|
|
2
|
+
|
|
3
|
+
This baseline was captured before implementing the tracked-task and messaging
|
|
4
|
+
runtime. It records the current behavior that Phase 1+ work must preserve or
|
|
5
|
+
replace explicitly.
|
|
6
|
+
|
|
7
|
+
## Repository and test baseline
|
|
8
|
+
|
|
9
|
+
- Branch: `feat/005-agent-messaging-and-task-lifecycle`
|
|
10
|
+
- Package version: `0.1.7`
|
|
11
|
+
- Runtime: TypeScript executed directly by Node; no build step.
|
|
12
|
+
- Full baseline command: `npm test`
|
|
13
|
+
- Baseline result: all existing test commands passed.
|
|
14
|
+
|
|
15
|
+
The baseline suite currently covers:
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
schemas
|
|
19
|
+
CLI behavior
|
|
20
|
+
parent surface
|
|
21
|
+
status widget
|
|
22
|
+
command UX
|
|
23
|
+
discovery
|
|
24
|
+
launch argument construction
|
|
25
|
+
effective prompts
|
|
26
|
+
registry behavior
|
|
27
|
+
multi-wait behavior
|
|
28
|
+
prompt watchers
|
|
29
|
+
artifact sessions
|
|
30
|
+
settings
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Phase 0 adds `phase0:test` to this suite for reusable fixtures and lifecycle
|
|
34
|
+
boundary assertions.
|
|
35
|
+
|
|
36
|
+
## Current parent tool surface
|
|
37
|
+
|
|
38
|
+
`registerShepherdTools()` currently registers eight parent tools, in this order:
|
|
39
|
+
|
|
40
|
+
```text
|
|
41
|
+
shepherd
|
|
42
|
+
shepherd_spawn
|
|
43
|
+
shepherd_prompt
|
|
44
|
+
shepherd_wait
|
|
45
|
+
shepherd_watch
|
|
46
|
+
shepherd_status
|
|
47
|
+
shepherd_close
|
|
48
|
+
shepherd_read
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The parent also registers the `/shepherd` command. Parent registration is
|
|
52
|
+
skipped when `PI_SHEPHERD_SESSION` is present, so launched children do not
|
|
53
|
+
inherit the parent Shepherd tools or command.
|
|
54
|
+
|
|
55
|
+
## Current child surface
|
|
56
|
+
|
|
57
|
+
Launched children receive `src/extension/shepherd-done.ts` as their Shepherd
|
|
58
|
+
extension. The current child extension:
|
|
59
|
+
|
|
60
|
+
- applies the delegated system-prompt replacement and Pi-documentation
|
|
61
|
+
filtering;
|
|
62
|
+
- observes `agent_end`;
|
|
63
|
+
- writes a `<session>.exit` completion sidecar for normal assistant turns;
|
|
64
|
+
- reports provider errors through that sidecar; and
|
|
65
|
+
- shuts down one-shot children after a normal turn unless stay-open behavior is
|
|
66
|
+
enabled.
|
|
67
|
+
|
|
68
|
+
It does not currently expose `shepherd_message` or `shepherd_done`.
|
|
69
|
+
|
|
70
|
+
## Current lifecycle behavior
|
|
71
|
+
|
|
72
|
+
The current registry contains opaque session-scoped agent and prompt IDs. It
|
|
73
|
+
supports one unresolved prompt per agent and prompt watchers.
|
|
74
|
+
|
|
75
|
+
The current prompt watcher polls Herdr and may settle a prompt from:
|
|
76
|
+
|
|
77
|
+
- a new completion sidecar;
|
|
78
|
+
- a detected provider error; or
|
|
79
|
+
- a post-submission Herdr state transition to `idle`, `done`, or `blocked`.
|
|
80
|
+
|
|
81
|
+
That behavior is retained as legacy prompt behavior during Phase 0. It must not
|
|
82
|
+
be copied into the future tracked-task path. In particular:
|
|
83
|
+
|
|
84
|
+
```text
|
|
85
|
+
agent process becomes idle != delegated task completed
|
|
86
|
+
agent_end != delegated task completed
|
|
87
|
+
agent_settled != delegated task completed
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The new task path will require `shepherd_done` or an explicit failure,
|
|
91
|
+
cancellation, or timeout event.
|
|
92
|
+
|
|
93
|
+
## Current artifact behavior
|
|
94
|
+
|
|
95
|
+
When fieldnotes are enabled, a prompt can reserve an artifact from the parent
|
|
96
|
+
Shepherd session. The artifact is started before prompt submission and
|
|
97
|
+
finalized when the prompt settles. The future implementation must move this
|
|
98
|
+
association to delegated task records and keep task artifacts open while a task
|
|
99
|
+
is waiting.
|
|
100
|
+
|
|
101
|
+
## Phase 0 guardrails added
|
|
102
|
+
|
|
103
|
+
- `test/helpers/test-utils.mjs` provides isolated temporary directories,
|
|
104
|
+
stable fake parent/child identities, and microtask flushing.
|
|
105
|
+
- `test/helpers/fake-clock.mjs` provides a manual clock and a scoped
|
|
106
|
+
`Date.now()` override for legacy code that cannot yet receive an injected
|
|
107
|
+
clock.
|
|
108
|
+
- `test/helpers/feature-contracts.mjs` centralizes planned tool, surface, and
|
|
109
|
+
task-state contracts for later phase tests without registering future tools.
|
|
110
|
+
- `test/verify-phase0.mjs` verifies fixture behavior and that changing an
|
|
111
|
+
agent's observed state to idle does not settle an open registry record.
|
|
112
|
+
- `src/core/orchestration.ts` documents that observed agent state and explicit
|
|
113
|
+
lifecycle settlement are separate concerns.
|
|
114
|
+
- `src/core/lifecycle.ts` documents that idle/done inference is legacy prompt
|
|
115
|
+
behavior and is not valid for tracked tasks.
|