@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,287 @@
|
|
|
1
|
+
# Implementation Plan: Low-Level Agent Orchestration
|
|
2
|
+
|
|
3
|
+
This plan implements the contract in `spec.md` by making agent lifecycle and
|
|
4
|
+
prompt synchronization the primary pi-shepherd model. It deliberately avoids
|
|
5
|
+
adding workflow-specific behavior to the core API.
|
|
6
|
+
|
|
7
|
+
## Target surface
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
start(agent, options) -> AgentHandle
|
|
11
|
+
prompt(agentHandle, message, options) -> PromptHandle
|
|
12
|
+
wait(promptHandle | promptHandles, options) -> Result | Result[]
|
|
13
|
+
status(agentHandle) -> Status
|
|
14
|
+
close(agentHandle) -> void
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
The model-facing `shepherd` tool remains action-discriminated. Existing
|
|
18
|
+
operational actions such as `sheep`, `herd`, `read`, and `prune` remain available.
|
|
19
|
+
Legacy `delegate` may be retained temporarily as a compatibility wrapper, but
|
|
20
|
+
new orchestration guidance should use the primitives.
|
|
21
|
+
|
|
22
|
+
## Design decisions
|
|
23
|
+
|
|
24
|
+
- `start` never accepts a task and always starts a persistent agent.
|
|
25
|
+
- `prompt` submits work and returns without waiting for completion.
|
|
26
|
+
- `wait` waits for one or many prompts; arrays wait concurrently and preserve
|
|
27
|
+
input order.
|
|
28
|
+
- A single agent may have only one unresolved prompt initially.
|
|
29
|
+
- `wait` returns per-prompt failure results rather than discarding successful
|
|
30
|
+
results when another prompt fails.
|
|
31
|
+
- Agents remain alive after `wait`; only `close` terminates them.
|
|
32
|
+
- One-shot behavior is `start + prompt + wait + close`.
|
|
33
|
+
- Public handles are stable serialized IDs, not raw Herdr pane IDs.
|
|
34
|
+
- Prompt and agent registries are session-scoped initially, with clear invalid
|
|
35
|
+
handle errors after reload or process loss.
|
|
36
|
+
- Existing project-agent trust gating, Herdr focus rules, and close ownership
|
|
37
|
+
checks remain unchanged.
|
|
38
|
+
|
|
39
|
+
## Phase 1 — Extract lifecycle primitives
|
|
40
|
+
|
|
41
|
+
### 1.1 Define internal types and registries
|
|
42
|
+
|
|
43
|
+
Add a small lifecycle module (for example `orchestration.ts`) containing:
|
|
44
|
+
|
|
45
|
+
- `AgentHandleRecord`: public ID, discovered agent name/config, pane/tab/
|
|
46
|
+
workspace IDs, cwd, launch directory/session metadata, lifecycle state, and
|
|
47
|
+
active prompt ID if any.
|
|
48
|
+
- `PromptHandleRecord`: public prompt ID, owning agent ID, submission time,
|
|
49
|
+
timeout, state, and result metadata.
|
|
50
|
+
- `AgentHandle`, `PromptHandle`, `Status`, and `Result` serialized shapes.
|
|
51
|
+
- In-memory maps for live handles and unresolved prompts.
|
|
52
|
+
- ID generation that is opaque and collision-resistant within the session.
|
|
53
|
+
|
|
54
|
+
Keep the existing created-pane registry as the ownership source of truth. The
|
|
55
|
+
new agent registry may reference it but must not weaken its close checks.
|
|
56
|
+
|
|
57
|
+
Define helpers for:
|
|
58
|
+
|
|
59
|
+
- resolving a public handle;
|
|
60
|
+
- resolving legacy name/pane targets during migration;
|
|
61
|
+
- rejecting unknown, closed, or foreign handles;
|
|
62
|
+
- marking prompts settled/failed/cancelled exactly once;
|
|
63
|
+
- clearing active prompt state;
|
|
64
|
+
- returning safe, serializable tool details.
|
|
65
|
+
|
|
66
|
+
### 1.2 Refactor launch configuration
|
|
67
|
+
|
|
68
|
+
Split launch configuration from task submission in `herdr.ts`:
|
|
69
|
+
|
|
70
|
+
- Preserve agent discovery-derived system prompt, model, tools, cwd, and
|
|
71
|
+
`omitSystemPrompt` behavior.
|
|
72
|
+
- Remove `stayOpen` from the new start path.
|
|
73
|
+
- Launch pi in a persistent interactive mode with no initial user task.
|
|
74
|
+
- Keep launch/session temp files for the lifetime of the child process.
|
|
75
|
+
- Ensure `start` waits for shell readiness and Herdr agent detection before
|
|
76
|
+
returning.
|
|
77
|
+
- Ensure background starts use `--no-focus` by default.
|
|
78
|
+
|
|
79
|
+
The existing `writePiLaunchFiles`/`launchPiInPane` path should be reused where
|
|
80
|
+
possible, but its bare launch behavior must become the normal `start` behavior,
|
|
81
|
+
not a special workflow mode.
|
|
82
|
+
|
|
83
|
+
### 1.3 Implement `start`
|
|
84
|
+
|
|
85
|
+
Add an internal function such as:
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
startAgent(ctx, agentName, options, signal) -> Promise<AgentHandle>
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
It should:
|
|
92
|
+
|
|
93
|
+
1. Resolve the agent fresh from disk using the requested scope.
|
|
94
|
+
2. Apply project-agent confirmation/trust checks.
|
|
95
|
+
3. Ensure Herdr runtime availability.
|
|
96
|
+
4. Create the requested tab or sibling pane according to placement options.
|
|
97
|
+
5. Record ownership immediately after creation.
|
|
98
|
+
6. Launch persistent pi with the selected agent configuration and no task.
|
|
99
|
+
7. Wait until Herdr detects the agent.
|
|
100
|
+
8. Register and return the serialized `AgentHandle`.
|
|
101
|
+
|
|
102
|
+
On failure after pane creation, perform best-effort cleanup only for the pane
|
|
103
|
+
created by this operation and remove its temporary resources when safe.
|
|
104
|
+
|
|
105
|
+
## Phase 2 — Implement prompt and wait
|
|
106
|
+
|
|
107
|
+
### 2.1 Implement `prompt`
|
|
108
|
+
|
|
109
|
+
Add:
|
|
110
|
+
|
|
111
|
+
```ts
|
|
112
|
+
promptAgent(handle, message, options) -> Promise<PromptHandle>
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Behavior:
|
|
116
|
+
|
|
117
|
+
1. Resolve the handle and verify the agent is live.
|
|
118
|
+
2. Reject if the agent has an unresolved prompt.
|
|
119
|
+
3. Confirm Herdr detects the agent before sending anything.
|
|
120
|
+
4. Submit the message using the Herdr agent surface without `--wait`.
|
|
121
|
+
5. Detect submission/stall errors and do not create a handle on failure.
|
|
122
|
+
6. Register and return a `PromptHandle` immediately.
|
|
123
|
+
|
|
124
|
+
The implementation must not use the current synchronous `herdr agent prompt
|
|
125
|
+
--wait` behavior for this path. If Herdr's CLI requires a separate command
|
|
126
|
+
for non-blocking submission, use that command; otherwise send through the
|
|
127
|
+
lowest-level supported agent input operation and then track lifecycle state.
|
|
128
|
+
|
|
129
|
+
Prompt options should initially include timeout and may include future
|
|
130
|
+
cancellation/settling options. Do not add workflow options.
|
|
131
|
+
|
|
132
|
+
### 2.2 Implement single `wait`
|
|
133
|
+
|
|
134
|
+
Add:
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
waitPrompt(promptHandle, options) -> Promise<Result>
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
It should poll/await the specific prompt's owning agent until it reaches a
|
|
141
|
+
settled state (`idle`, `done`, `blocked`, failure, timeout, or cancellation).
|
|
142
|
+
It must associate the result with the prompt handle rather than merely
|
|
143
|
+
reporting whatever state the agent happens to have.
|
|
144
|
+
|
|
145
|
+
Recover response text through the existing safe mechanisms:
|
|
146
|
+
|
|
147
|
+
- completion sidecar/session data where available;
|
|
148
|
+
- Herdr output as a diagnostic fallback;
|
|
149
|
+
- never read or delete a still-running child session file.
|
|
150
|
+
|
|
151
|
+
When settled, mark the prompt complete and clear the owning agent's active
|
|
152
|
+
prompt. A subsequent prompt on that agent is then allowed.
|
|
153
|
+
|
|
154
|
+
### 2.3 Implement multi-wait
|
|
155
|
+
|
|
156
|
+
Add:
|
|
157
|
+
|
|
158
|
+
```ts
|
|
159
|
+
waitPrompts(promptHandles, options) -> Promise<Result[]>
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Use concurrent waits (`Promise.all` over individual wait operations), not a
|
|
163
|
+
sequential loop. Preserve the caller's input order. Convert individual
|
|
164
|
+
exceptions into structured failed results so all handles are represented.
|
|
165
|
+
|
|
166
|
+
Initially support wait-for-all only. Do not add `until: "any"` until the basic
|
|
167
|
+
contract is proven.
|
|
168
|
+
|
|
169
|
+
## Phase 3 — Implement status and close
|
|
170
|
+
|
|
171
|
+
### 3.1 `status`
|
|
172
|
+
|
|
173
|
+
Add `statusAgent(handle)` backed by `herdr agent get`. Return the stable handle
|
|
174
|
+
identity plus Herdr state (`idle`, `working`, `blocked`, `done`, `unknown`) and
|
|
175
|
+
map missing/dead panes to `failed` or `closed` consistently.
|
|
176
|
+
|
|
177
|
+
Status must not focus panes or mutate Herdr state. It should tolerate stale
|
|
178
|
+
registry entries and return actionable invalid-handle errors.
|
|
179
|
+
|
|
180
|
+
### 3.2 `close`
|
|
181
|
+
|
|
182
|
+
Add `closeAgent(handle)` using the existing ownership-guarded close path.
|
|
183
|
+
|
|
184
|
+
Before/while closing:
|
|
185
|
+
|
|
186
|
+
- reject foreign handles and unregistered raw panes;
|
|
187
|
+
- mark unresolved prompts as cancelled/failed so future waits terminate;
|
|
188
|
+
- remove the live agent registration;
|
|
189
|
+
- clean temporary launch resources only after the child process is gone;
|
|
190
|
+
- preserve created-pane registry semantics and idempotency.
|
|
191
|
+
|
|
192
|
+
Do not close agents automatically after `wait`.
|
|
193
|
+
|
|
194
|
+
## Phase 4 — Wire the shepherd tool
|
|
195
|
+
|
|
196
|
+
Update `types.ts` and `shepherd.ts`:
|
|
197
|
+
|
|
198
|
+
- Add schemas/actions for `start`, `prompt`, `wait`, `status`, and `close`.
|
|
199
|
+
- `start` requires agent plus options but no task.
|
|
200
|
+
- `prompt` accepts a serialized agent handle and message.
|
|
201
|
+
- `wait` accepts one serialized prompt handle or an array.
|
|
202
|
+
- `status` and `close` accept serialized agent handles.
|
|
203
|
+
- Keep legacy name/pane target resolution only for existing management flows
|
|
204
|
+
during migration.
|
|
205
|
+
- Return structured details containing handles, statuses, and results.
|
|
206
|
+
- Make tool descriptions explain the two-step `prompt` then `wait` protocol.
|
|
207
|
+
- Update the tool prompt/guidelines so parallel work is shown as multiple
|
|
208
|
+
starts/prompts followed by one `wait([...])` call.
|
|
209
|
+
|
|
210
|
+
Retain `read`, because it is needed for diagnosing blocked agents and result
|
|
211
|
+
recovery. Retain `sheep`, `herd`, and `prune`.
|
|
212
|
+
|
|
213
|
+
## Phase 5 — Compatibility and sheep migration
|
|
214
|
+
|
|
215
|
+
### 5.1 Compatibility wrapper
|
|
216
|
+
|
|
217
|
+
Refactor `subagent.ts` so the old delegation modes call the primitives where
|
|
218
|
+
practical:
|
|
219
|
+
|
|
220
|
+
```text
|
|
221
|
+
delegate(single) = start + prompt + wait
|
|
222
|
+
(+ close when one-shot cleanup is requested)
|
|
223
|
+
delegate(parallel) = multiple start/prompt + wait(all)
|
|
224
|
+
delegate(chain) = repeated start + prompt + wait
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
The wrapper may preserve existing note/session behavior while migration is
|
|
228
|
+
underway. It must not add `stayOpen` to `start`; persistence is controlled by
|
|
229
|
+
whether/when the wrapper calls `close`.
|
|
230
|
+
|
|
231
|
+
### 5.2 Slash command and docs
|
|
232
|
+
|
|
233
|
+
Update `/shepherd` behavior and README examples to show primitive usage. Make
|
|
234
|
+
clear that:
|
|
235
|
+
|
|
236
|
+
- `start` launches an idle persistent agent;
|
|
237
|
+
- `prompt` returns a prompt handle immediately;
|
|
238
|
+
- `wait` synchronizes one or many prompts;
|
|
239
|
+
- `close` is explicit.
|
|
240
|
+
|
|
241
|
+
Mark workflow modes as compatibility conveniences if they remain exposed.
|
|
242
|
+
Update root `PLAN.md` only after this spec implementation is complete, so the
|
|
243
|
+
existing roadmap accurately reflects the migration.
|
|
244
|
+
|
|
245
|
+
## Phase 6 — Tests and live verification
|
|
246
|
+
|
|
247
|
+
Add focused tests for pure registry/result behavior where possible:
|
|
248
|
+
|
|
249
|
+
- stable handle serialization and lookup;
|
|
250
|
+
- unknown/closed/foreign handle rejection;
|
|
251
|
+
- one active prompt per agent;
|
|
252
|
+
- prompt settlement clears active state exactly once;
|
|
253
|
+
- multi-wait preserves input order;
|
|
254
|
+
- multi-wait returns partial failures;
|
|
255
|
+
- close cancels unresolved prompts;
|
|
256
|
+
- no automatic close after wait.
|
|
257
|
+
|
|
258
|
+
Add a fake Herdr/CLI seam or injectable runner for non-live tests if the current
|
|
259
|
+
module structure makes this practical. Keep `discovery.ts` pure.
|
|
260
|
+
|
|
261
|
+
Run live verification in Herdr:
|
|
262
|
+
|
|
263
|
+
1. `start("scout", options)` creates an idle visible agent and sends no task.
|
|
264
|
+
2. `prompt(handle, task)` returns before completion.
|
|
265
|
+
3. `wait(promptHandle)` returns the task result.
|
|
266
|
+
4. Start two agents, prompt both, then `wait([pA, pB])`; verify concurrent
|
|
267
|
+
execution and ordered results.
|
|
268
|
+
5. Prompt the same agent twice before waiting; verify the second prompt is
|
|
269
|
+
rejected.
|
|
270
|
+
6. Wait, prompt again, and verify iterative use works.
|
|
271
|
+
7. Close the agent and verify future status/wait behavior is deterministic.
|
|
272
|
+
8. Attempt to close an unowned pane and verify refusal.
|
|
273
|
+
9. Verify project-agent trust confirmation and plain-terminal Herdr startup
|
|
274
|
+
remain intact.
|
|
275
|
+
|
|
276
|
+
## Completion checklist
|
|
277
|
+
|
|
278
|
+
- [ ] Primitive types/registries implemented.
|
|
279
|
+
- [ ] Persistent no-task `start` implemented.
|
|
280
|
+
- [ ] Immediate non-blocking `prompt` implemented.
|
|
281
|
+
- [ ] Single and concurrent multi-prompt `wait` implemented.
|
|
282
|
+
- [ ] Structured partial-failure results implemented.
|
|
283
|
+
- [ ] Handle-based `status` and ownership-safe `close` implemented.
|
|
284
|
+
- [ ] Tool schemas and model-facing guidance updated.
|
|
285
|
+
- [ ] Legacy delegation migrated or clearly isolated as compatibility code.
|
|
286
|
+
- [ ] README, root `PLAN.md`, and relevant comments updated.
|
|
287
|
+
- [ ] Registry, lifecycle, safety, and live Herdr checks pass.
|
|
@@ -0,0 +1,323 @@
|
|
|
1
|
+
# Low-Level Agent Orchestration Primitives
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Proposed specification.
|
|
6
|
+
|
|
7
|
+
## Summary
|
|
8
|
+
|
|
9
|
+
Replace workflow-oriented delegation as the primary orchestration model with a
|
|
10
|
+
small set of low-level agent lifecycle primitives:
|
|
11
|
+
|
|
12
|
+
```text
|
|
13
|
+
start(agent, options) -> agent id
|
|
14
|
+
prompt(agent id, message, options) -> prompt id
|
|
15
|
+
wait(prompt id | prompt ids) -> Result | Result[]
|
|
16
|
+
status(agent id) -> Status
|
|
17
|
+
close(agent id) -> void
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Starting an agent must not submit work. Work is submitted explicitly with
|
|
21
|
+
`prompt`, and synchronization is explicit with `wait`. Parallel, sequential,
|
|
22
|
+
chain, fan-out/fan-in, retry, and review-loop workflows are composed by the
|
|
23
|
+
caller rather than being special delegation modes in pi-shepherd.
|
|
24
|
+
|
|
25
|
+
## Goals
|
|
26
|
+
|
|
27
|
+
- Make agent orchestration small, explicit, and composable.
|
|
28
|
+
- Separate agent lifecycle from work submission and result synchronization.
|
|
29
|
+
- Allow an agent to be started without an initial task.
|
|
30
|
+
- Support parallel work by waiting on multiple prompt ids.
|
|
31
|
+
- Preserve Herdr-native execution and visibility.
|
|
32
|
+
- Keep agent placement and launch configuration in `start` options.
|
|
33
|
+
- Return stable, serializable opaque ids suitable for later tool calls.
|
|
34
|
+
- Preserve pi-shepherd's safety invariant: only panes created by pi-shepherd
|
|
35
|
+
may be closed through pi-shepherd.
|
|
36
|
+
- Make failures and partial results observable rather than hiding them inside
|
|
37
|
+
workflow-specific orchestration.
|
|
38
|
+
- Retain diagnostic operations such as listing agents and reading pane output.
|
|
39
|
+
|
|
40
|
+
## Non-goals
|
|
41
|
+
|
|
42
|
+
- No first-class `single`, `parallel`, or `chain` workflow modes in the core
|
|
43
|
+
orchestration API.
|
|
44
|
+
- No task, message, or initial prompt argument to `start`.
|
|
45
|
+
- No implicit `{previous}` substitution or chain-specific result plumbing.
|
|
46
|
+
- No requirement that pi-shepherd implement arbitrary workflow composition.
|
|
47
|
+
- No simultaneous unresolved prompts for one agent in the initial version.
|
|
48
|
+
- No requirement to expose Herdr pane IDs as the public lifecycle-id format.
|
|
49
|
+
- No automatic closing of agents after a prompt completes.
|
|
50
|
+
- No `stayOpen` option on `start`; started agents remain alive until `close`.
|
|
51
|
+
|
|
52
|
+
## Core API
|
|
53
|
+
|
|
54
|
+
### `start(agent, options) -> AgentHandle`
|
|
55
|
+
|
|
56
|
+
`start` resolves the requested discovered agent definition, creates and places
|
|
57
|
+
its Herdr pane/tab, launches pi, and waits until Herdr detects the agent as
|
|
58
|
+
ready. It returns only after the agent is addressable.
|
|
59
|
+
|
|
60
|
+
`start` does **not** send a task or user message.
|
|
61
|
+
|
|
62
|
+
The selected agent definition supplies its system prompt and agent-specific
|
|
63
|
+
launch configuration. Start callers may optionally provide only a working
|
|
64
|
+
directory, model, label, or placement. Agent scope, project approval, and
|
|
65
|
+
system-prompt behavior are controlled by Shepherd settings and the discovered
|
|
66
|
+
agent definition; callers cannot override them per spawn.
|
|
67
|
+
|
|
68
|
+
Illustrative options:
|
|
69
|
+
|
|
70
|
+
```ts
|
|
71
|
+
start("reviewer", {
|
|
72
|
+
cwd: "/project",
|
|
73
|
+
placement: "pane_right", // or "pane_down", "tab", or "workspace"
|
|
74
|
+
model: "provider/model",
|
|
75
|
+
label: "authentication review",
|
|
76
|
+
})
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
A started agent is persistent until explicitly closed. `start` must not expose a
|
|
80
|
+
`stayOpen` option: because it accepts no task, `stayOpen: false` would create an
|
|
81
|
+
agent only to immediately terminate it, which is not meaningful for this API.
|
|
82
|
+
One-shot behavior belongs in a compatibility/convenience wrapper that performs
|
|
83
|
+
`start + prompt + wait + close`.
|
|
84
|
+
|
|
85
|
+
The exact placement schema is implementation-defined, but it must support the
|
|
86
|
+
Herdr primitives appropriate to the requested topology. By default, background
|
|
87
|
+
agents should not steal focus, and the caller's working directory should be
|
|
88
|
+
preserved unless explicitly overridden.
|
|
89
|
+
|
|
90
|
+
#### Start errors
|
|
91
|
+
|
|
92
|
+
`start` fails if the agent definition cannot be resolved, project-agent trust
|
|
93
|
+
requirements are not satisfied, Herdr cannot be reached or started, the pane
|
|
94
|
+
cannot be created, or pi cannot become ready. A failed start must not return a
|
|
95
|
+
usable handle.
|
|
96
|
+
|
|
97
|
+
### `prompt(agent id, message, options) -> prompt id`
|
|
98
|
+
|
|
99
|
+
`prompt` sends exactly one user message to an already-started agent identified by
|
|
100
|
+
its opaque id and returns
|
|
101
|
+
immediately after the message has been accepted for processing. It does not
|
|
102
|
+
wait for the agent's turn to settle.
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
const operation = prompt(agent, "Review the current diff", {
|
|
106
|
+
timeout: 120_000,
|
|
107
|
+
})
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
The returned prompt id identifies this particular submitted operation and can
|
|
111
|
+
be passed to `wait`. At the model-facing tool boundary, pass it as the top-level
|
|
112
|
+
`id` string; a raw Herdr pane ID is invalid.
|
|
113
|
+
|
|
114
|
+
The initial implementation must reject a prompt when the agent already has an
|
|
115
|
+
unresolved prompt. This prevents ambiguous result association. Parallel work
|
|
116
|
+
is achieved by prompting multiple agents, not by concurrently prompting one
|
|
117
|
+
agent.
|
|
118
|
+
|
|
119
|
+
`prompt` must not silently discard messages. If Herdr does not detect the
|
|
120
|
+
agent, the agent is unavailable, or submission stalls, it returns an error and
|
|
121
|
+
no usable `PromptHandle` is produced.
|
|
122
|
+
|
|
123
|
+
### `wait(promptHandle | promptHandles, options) -> Result | Result[]`
|
|
124
|
+
|
|
125
|
+
`wait` waits for one or more submitted prompts to settle and returns their
|
|
126
|
+
results. Waiting is a synchronization operation, not an agent-lifecycle
|
|
127
|
+
operation: it must not close or terminate the agent. The caller uses `close`
|
|
128
|
+
when the agent is no longer needed.
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
const result = await wait(operation)
|
|
132
|
+
const results = await wait([researchA, researchB])
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
For the model-facing `shepherd` tools, `operation`, `researchA`, and `researchB`
|
|
136
|
+
are prompt id strings returned by `prompt`. A multi-wait uses one array of prompt
|
|
137
|
+
ids. The provider may wrap the argument object in its own transport envelope,
|
|
138
|
+
but the lifecycle argument itself is always an opaque id.
|
|
139
|
+
|
|
140
|
+
For an array, the default behavior is **wait for all**. Results preserve the
|
|
141
|
+
same order as the input handles, regardless of completion order. Waiting for
|
|
142
|
+
multiple prompts must wait concurrently, not sequentially.
|
|
143
|
+
|
|
144
|
+
Multi-wait should return a result for every input, including failures, so one
|
|
145
|
+
failed or timed-out agent does not hide successful results from other agents.
|
|
146
|
+
It therefore has `Promise.allSettled`-like failure behavior at the result level.
|
|
147
|
+
|
|
148
|
+
A future version may support options such as `until: "any"`, but first version
|
|
149
|
+
behavior is only wait-for-all.
|
|
150
|
+
|
|
151
|
+
### `status(agent id) -> Status`
|
|
152
|
+
|
|
153
|
+
`status` performs a non-blocking inspection of the agent's current state.
|
|
154
|
+
Possible lifecycle states should reflect Herdr's recognized states:
|
|
155
|
+
|
|
156
|
+
```text
|
|
157
|
+
idle | working | blocked | done | unknown | failed | closed
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
The returned status should include stable identity and placement metadata where
|
|
161
|
+
available, such as agent name, lifecycle id, pane ID, tab ID, and workspace ID.
|
|
162
|
+
`status` must not focus the agent or otherwise alter user-visible Herdr state.
|
|
163
|
+
|
|
164
|
+
### `close(agent id) -> void`
|
|
165
|
+
|
|
166
|
+
`close` resolves the agent id to its owned Herdr pane/tab and releases its
|
|
167
|
+
pi-shepherd resources. It must refuse to close a pane that pi-shepherd did not
|
|
168
|
+
create, even if a caller supplies a matching raw pane ID.
|
|
169
|
+
|
|
170
|
+
Closing an agent with unresolved prompts should be explicit and deterministic.
|
|
171
|
+
The initial implementation should mark those prompts as failed/cancelled and
|
|
172
|
+
ensure subsequent `wait` calls return those results rather than hanging.
|
|
173
|
+
|
|
174
|
+
Close should be idempotent for an agent that has already been closed, while an
|
|
175
|
+
id from another session or an unknown id should produce a clear error.
|
|
176
|
+
|
|
177
|
+
## Data model
|
|
178
|
+
|
|
179
|
+
Lifecycle ids are stable opaque strings returned in tool result text and are
|
|
180
|
+
intended to be passed back across model/tool calls. Full handle objects may be
|
|
181
|
+
used internally and may contain Herdr identifiers, but they are not part of the
|
|
182
|
+
recommended model-facing protocol. Callers must not derive lifecycle ids from
|
|
183
|
+
pane ids.
|
|
184
|
+
|
|
185
|
+
Illustrative shapes:
|
|
186
|
+
|
|
187
|
+
```ts
|
|
188
|
+
type AgentHandle = {
|
|
189
|
+
id: string
|
|
190
|
+
agent: string
|
|
191
|
+
paneId?: string
|
|
192
|
+
tabId?: string
|
|
193
|
+
workspaceId?: string
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
type PromptHandle = {
|
|
197
|
+
id: string
|
|
198
|
+
agentId: string
|
|
199
|
+
createdAt: number
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
type Result = {
|
|
203
|
+
promptId: string
|
|
204
|
+
agentId: string
|
|
205
|
+
status: "idle" | "done" | "blocked" | "failed" | "timeout" | "cancelled"
|
|
206
|
+
ok: boolean
|
|
207
|
+
text?: string
|
|
208
|
+
error?: string
|
|
209
|
+
}
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
The exact TypeScript representation may differ. The public contract must retain
|
|
213
|
+
stable IDs, prompt-to-agent association, terminal status, and either returned
|
|
214
|
+
text or an actionable error.
|
|
215
|
+
|
|
216
|
+
## Composition examples
|
|
217
|
+
|
|
218
|
+
### Parallel work
|
|
219
|
+
|
|
220
|
+
```ts
|
|
221
|
+
const researcherA = await start("scout", { cwd: project })
|
|
222
|
+
const researcherB = await start("scout", { cwd: project })
|
|
223
|
+
|
|
224
|
+
const promptA = await prompt(researcherA, "Research authentication")
|
|
225
|
+
const promptB = await prompt(researcherB, "Research authorization")
|
|
226
|
+
|
|
227
|
+
const [resultA, resultB] = await wait([promptA, promptB])
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
When composing this through `shepherd`, pass the returned ids directly:
|
|
231
|
+
`wait({ id: promptA.id })` for one prompt, or
|
|
232
|
+
`wait({ id: [promptA.id, promptB.id] })` for two. Do not substitute Herdr pane
|
|
233
|
+
ids or quote an entire argument object as a string.
|
|
234
|
+
|
|
235
|
+
### Sequential chain
|
|
236
|
+
|
|
237
|
+
```ts
|
|
238
|
+
const scout = await start("scout", options)
|
|
239
|
+
const scoutPrompt = await prompt(scout, "Inspect the repository")
|
|
240
|
+
const scoutResult = await wait(scoutPrompt)
|
|
241
|
+
|
|
242
|
+
const planner = await start("planner", options)
|
|
243
|
+
const plannerPrompt = await prompt(
|
|
244
|
+
planner,
|
|
245
|
+
`Create a plan from this report:\n\n${scoutResult.text}`,
|
|
246
|
+
)
|
|
247
|
+
const plannerResult = await wait(plannerPrompt)
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
### Iterative work on one agent
|
|
251
|
+
|
|
252
|
+
```ts
|
|
253
|
+
const worker = await start("worker", options)
|
|
254
|
+
const first = await wait(await prompt(worker, "Implement the feature"))
|
|
255
|
+
const second = await wait(await prompt(worker, "Run tests and fix failures"))
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
## Existing functionality and migration
|
|
259
|
+
|
|
260
|
+
The existing Herdr management actions for `sheep`, `herd`, `read`, and `gc`
|
|
261
|
+
remain useful and may remain separate operational actions. `status` and
|
|
262
|
+
`close` should be updated to accept `AgentHandle`s while retaining safe
|
|
263
|
+
resolution of existing created-pane records during migration.
|
|
264
|
+
|
|
265
|
+
The current `delegate` modes (`single`, `parallel`, `chain`, and `bare`) should
|
|
266
|
+
not remain the fundamental implementation. The implementation should first
|
|
267
|
+
extract reusable start/prompt/wait lifecycle operations from the existing Herdr
|
|
268
|
+
runner and persistent-agent path. The low-level `start` operation always
|
|
269
|
+
creates a persistent agent; the old `bare` mode is therefore replaced by
|
|
270
|
+
`start` with no initial prompt.
|
|
271
|
+
|
|
272
|
+
A temporary compatibility wrapper may implement legacy delegation as:
|
|
273
|
+
|
|
274
|
+
```text
|
|
275
|
+
delegate(single) = start + prompt + wait + close (if one-shot behavior is requested)
|
|
276
|
+
delegate(parallel) = multiple start/prompt + wait(all) + close (if requested)
|
|
277
|
+
delegate(chain) = repeated start + prompt + wait + close (if requested)
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
If retained, this wrapper must be documented as convenience syntax and must not
|
|
281
|
+
reintroduce workflow behavior into the low-level primitives. It may be removed
|
|
282
|
+
in a later breaking change.
|
|
283
|
+
|
|
284
|
+
## Lifecycle and persistence
|
|
285
|
+
|
|
286
|
+
- Agent handles must be backed by a registry while their agents are alive.
|
|
287
|
+
- Prompt handles must remain resolvable until they settle, fail, are cancelled,
|
|
288
|
+
or are explicitly garbage-collected.
|
|
289
|
+
- Extension reload and parent-session boundaries must either preserve these
|
|
290
|
+
registries or return clear invalid-handle errors; they must never wait
|
|
291
|
+
indefinitely on lost state.
|
|
292
|
+
- Temporary launch/session files must not be deleted while a child pi process
|
|
293
|
+
can still access them.
|
|
294
|
+
- Completion results should be recovered from the existing completion sidecar
|
|
295
|
+
and/or child session data only after the child has reached a safe settled
|
|
296
|
+
state, preserving the existing sentinel/session-file invariant.
|
|
297
|
+
|
|
298
|
+
## Security and safety
|
|
299
|
+
|
|
300
|
+
- User-level agent discovery remains the default.
|
|
301
|
+
- Project-controlled agent definitions remain trust-gated and require explicit
|
|
302
|
+
opt-in/confirmation.
|
|
303
|
+
- Agents retain host-user tool permissions; this must remain documented.
|
|
304
|
+
- Herdr commands must use explicit pane/workspace context and preserve focus by
|
|
305
|
+
default.
|
|
306
|
+
- `close` must never close panes pi-shepherd did not create.
|
|
307
|
+
- Raw caller-supplied pane IDs must not bypass ownership checks.
|
|
308
|
+
|
|
309
|
+
## Acceptance criteria
|
|
310
|
+
|
|
311
|
+
- An agent can be started with no task and becomes visible/ready in Herdr.
|
|
312
|
+
- `start` returns a stable handle and sends no user message.
|
|
313
|
+
- `prompt` returns before the agent finishes processing the message.
|
|
314
|
+
- `wait` returns the corresponding result for one prompt.
|
|
315
|
+
- `wait` on multiple prompts runs waits concurrently and returns ordered,
|
|
316
|
+
per-prompt results including partial failures.
|
|
317
|
+
- A second unresolved prompt to the same agent is rejected.
|
|
318
|
+
- `status` reports lifecycle state without focusing or mutating the agent.
|
|
319
|
+
- `close` enforces pi-shepherd pane ownership and resolves outstanding prompts.
|
|
320
|
+
- Parallel and chain behavior can be implemented entirely by composing the
|
|
321
|
+
primitives.
|
|
322
|
+
- Existing project-agent trust and temporary-file safety invariants remain
|
|
323
|
+
intact.
|