@luminascale/shepherd 0.0.0-stage → 0.6.0
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 +424 -2
- package/docs/README.md +25 -0
- package/docs/guides/agent-definitions.md +42 -0
- package/docs/guides/diagnostics.md +199 -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 +599 -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 +259 -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 +35 -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 +69 -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,147 @@
|
|
|
1
|
+
# Tasks: Unwatched completion notice
|
|
2
|
+
|
|
3
|
+
Work in order. A task is done only when its implementation + verification
|
|
4
|
+
are complete. This spec is `007-unwatched-completion-notice`
|
|
5
|
+
(`spec.md` contract, `plan.md` design). Related: issue #15.
|
|
6
|
+
|
|
7
|
+
## Phase 1 — Detection + ledger (core)
|
|
8
|
+
|
|
9
|
+
- [x] **1.1 Add `src/core/unseen-completions.ts`**
|
|
10
|
+
- `UnseenCompletionLedger` keyed by `taskId`, entries are the structural
|
|
11
|
+
`UnseenSettlement` (result fields + optional `agent`/`label`),
|
|
12
|
+
insertion order; a queue of un-noticed settlements.
|
|
13
|
+
- `record(result, { hadWatchers, agent?, label?, source? })` adds only
|
|
14
|
+
when `hadWatchers === false`, `result.status !== "cancelled"`,
|
|
15
|
+
`source !== "delegate-submission-failure"`, and no entry exists;
|
|
16
|
+
returns whether a new entry was added.
|
|
17
|
+
- `pending()`, `drain(ids)`, `clear(ids): string[]`,
|
|
18
|
+
`clearForAgent(agentId): string[]`, `clearAll()`.
|
|
19
|
+
- Pure module: no `@earendil-works/*`, `src/runtimes/`, or
|
|
20
|
+
`src/extension/` imports; export the class and a
|
|
21
|
+
`unseenCompletionLedger` singleton (mirroring `taskWatcherService`).
|
|
22
|
+
|
|
23
|
+
- [x] **1.2 Add the settlement observer to the task registry**
|
|
24
|
+
- `onTaskSettled(listener): () => void` in
|
|
25
|
+
`src/runtimes/herdr/orchestration.ts`; listener receives
|
|
26
|
+
`(result, { hadWatchers, agent?, label?, source? })`, with `result`
|
|
27
|
+
passed as a shallow copy.
|
|
28
|
+
- `hadWatchers` is true only when at least one watcher callback actually
|
|
29
|
+
ran for the settlement (set inside the existing fan-out); capture the
|
|
30
|
+
agent handle for `agent`/`label` in the same place.
|
|
31
|
+
- `settleTask` takes an optional internal options argument carrying
|
|
32
|
+
`source`; `src/runtimes/herdr/lifecycle.ts` `delegateAgent` failure path
|
|
33
|
+
passes `source: "delegate-submission-failure"`.
|
|
34
|
+
- Listeners run after the fan-out, inside `try/catch`; observer failure
|
|
35
|
+
cannot affect settlement; no listener = identical behavior.
|
|
36
|
+
- Fires only on an actual transition into a terminal state; legacy
|
|
37
|
+
prompt settlements are not observed.
|
|
38
|
+
- Document the hook in the code as part of the runtime contract so the
|
|
39
|
+
durable runtime (spec 006 Phase 1+) implements it identically.
|
|
40
|
+
|
|
41
|
+
- [x] **1.3 Core cases in `test/verify-unseen-completions.mjs`**
|
|
42
|
+
- Create the suite file with ledger + observer cases first (run it
|
|
43
|
+
directly; chain wiring happens in 3.1).
|
|
44
|
+
- Ledger: cancelled exclusion, had-watchers exclusion,
|
|
45
|
+
delegate-submission-failure exclusion, dedupe, insertion order, drain,
|
|
46
|
+
`clear`/`clearForAgent` returning ids, `clearAll`.
|
|
47
|
+
- Observer: settle with watcher → `hadWatchers: true`; without → `false`
|
|
48
|
+
plus `agent`/`label`; `source` passthrough; listener throw does not
|
|
49
|
+
break `settleTask`; unsubscribe stops delivery.
|
|
50
|
+
|
|
51
|
+
## Phase 2 — Notice delivery (extension)
|
|
52
|
+
|
|
53
|
+
- [x] **2.1 Session-scoped bridge + activity tracking + idle wake**
|
|
54
|
+
- New `src/extension/unseen-completions.ts`,
|
|
55
|
+
`configureUnseenCompletionBridge(pi, { coalesceMs?, ledger? })`.
|
|
56
|
+
- Subscribe `lifecycleRegistry.onTaskSettled` on `session_start`
|
|
57
|
+
(idempotent), release on `session_shutdown`; no subscription without a
|
|
58
|
+
parent session.
|
|
59
|
+
- `session_start`/`agent_settled` → idle; `agent_start` → busy; transition
|
|
60
|
+
to idle re-checks pending entries (aborted/errored runs still get one
|
|
61
|
+
later wake); prefer `ctx.isIdle()` when the captured lifecycle context
|
|
62
|
+
exposes it.
|
|
63
|
+
- `record()` while idle schedules one debounced flush
|
|
64
|
+
(`UNSEEN_NOTICE_COALESCE_MS = 250`); a burst sends exactly one
|
|
65
|
+
`pi.sendMessage(notice, { triggerTurn: true })` and drains after the
|
|
66
|
+
call returns.
|
|
67
|
+
- Timer firing while busy is a no-op; flush no-ops without a
|
|
68
|
+
`pi.sendMessage` function; synchronous send failure leaves entries
|
|
69
|
+
pending (no unbounded retry).
|
|
70
|
+
|
|
71
|
+
- [x] **2.2 Boundary continuation**
|
|
72
|
+
- `pi.on("agent_before_settle", event)`: only when
|
|
73
|
+
`event.outcome === "completed"` and pending entries exist — build one
|
|
74
|
+
`custom_message` entry, drain those ids, return
|
|
75
|
+
`{ entries: [entry], continue: true }`. No pre-entry
|
|
76
|
+
`event.context.canContinue` check: pi commits the drafts first and then
|
|
77
|
+
decides, so the pre-entry snapshot is not authoritative (#16).
|
|
78
|
+
- Aborted/errored outcomes return nothing; entries stay pending.
|
|
79
|
+
- Loop guard: drained entries never re-notify; a second boundary with no
|
|
80
|
+
new entries returns `undefined`.
|
|
81
|
+
|
|
82
|
+
- [x] **2.3 Notice content + renderer**
|
|
83
|
+
- One formatter (exported for tests) producing the spec's text: header,
|
|
84
|
+
`- <taskId> (<agent>[, "label"]): <status> — <summary|error>` lines,
|
|
85
|
+
and `Full results: shepherd_watch({ id: [ "id", ... ] })`.
|
|
86
|
+
- `details: { taskIds, settlements }` (not `completions`, which collides
|
|
87
|
+
with the generic collapsed formatter); export
|
|
88
|
+
`renderShepherdNotification` from `src/extension/shepherd.ts` and
|
|
89
|
+
register `shepherd.task.unseen` with it plus the notice formatter.
|
|
90
|
+
|
|
91
|
+
- [x] **2.4 Clearing wiring**
|
|
92
|
+
- `src/extension/shepherd.ts` `watch` action:
|
|
93
|
+
`unseenCompletionLedger.clear(registration.taskIds)` after
|
|
94
|
+
`taskWatcherService.watch(taskIds)` — the authoritative retrieval
|
|
95
|
+
clear. Do not add clearing to the watcher notifier (late watch
|
|
96
|
+
deliveries never reach it).
|
|
97
|
+
- `close` action: `clearForAgent(handle.id)` after a successful
|
|
98
|
+
`runtime.close`; report dropped task ids in the tool result when any.
|
|
99
|
+
- `session_shutdown` clears timers, observer subscription, and the
|
|
100
|
+
ledger; `session_start` clears stale entries before going idle.
|
|
101
|
+
|
|
102
|
+
- [x] **2.5 Wire the bridge in `index.ts`**
|
|
103
|
+
- Call `configureUnseenCompletionBridge(pi)` after the
|
|
104
|
+
`PI_SHEPHERD_SESSION` guard and `registerShepherdTools(pi)`
|
|
105
|
+
(`index.ts` ~447). Not inside `registerShepherdTools`: six suites pass
|
|
106
|
+
fake pi objects without `on` and with renderer allow-lists there.
|
|
107
|
+
- No tool schema, prompt, settings, or message-delivery changes for
|
|
108
|
+
watchers.
|
|
109
|
+
|
|
110
|
+
## Phase 3 — Verification, docs, landing
|
|
111
|
+
|
|
112
|
+
- [x] **3.1 Finish `test/verify-unseen-completions.mjs` + wiring**
|
|
113
|
+
- Add bridge cases with a fake pi surface (capture `on`,
|
|
114
|
+
`registerMessageRenderer`, `sendMessage` like
|
|
115
|
+
`test/verify-parent-surface.mjs`): idle burst → exactly one
|
|
116
|
+
`triggerTurn` notice and no duplicates; busy settle → one boundary
|
|
117
|
+
result with `continue: true`; second boundary → `undefined`; `aborted`
|
|
118
|
+
outcome → none; completed boundary with `canContinue: false` →
|
|
119
|
+
continues; late `watch` clears; close clears and reports; renderer
|
|
120
|
+
registered; missing `sendMessage` never throws; `session_shutdown`
|
|
121
|
+
unsubscribes.
|
|
122
|
+
- Inject small `coalesceMs` and an isolated ledger for determinism.
|
|
123
|
+
- Register `unseen-completions:test` in `package.json` and append it to
|
|
124
|
+
the `test` chain.
|
|
125
|
+
|
|
126
|
+
- [x] **3.2 Full suite untouched and green**
|
|
127
|
+
- `npm test` with `PI_*`/`HERDR_*` unset: all existing suites + the new
|
|
128
|
+
script pass; no existing test file modified.
|
|
129
|
+
|
|
130
|
+
- [x] **3.3 Docs**
|
|
131
|
+
- README `### Delegate, then watch`: unwatched settlements surface at the
|
|
132
|
+
next settle boundary, or as one wake when the Shepherd is idle; the
|
|
133
|
+
notice names `shepherd_watch` for retrieval.
|
|
134
|
+
- `docs/guides/tool-reference.md`: same note on the `shepherd_watch`
|
|
135
|
+
entry; reiterate that `shepherd_watch` retrieves already-settled tasks
|
|
136
|
+
synchronously.
|
|
137
|
+
- Fix the pre-existing "delivered as follow-ups" wording for
|
|
138
|
+
`shepherd_watch` (`docs/guides/tool-reference.md` and the tool
|
|
139
|
+
description in `src/extension/shepherd.ts` ~1570) to match the actual
|
|
140
|
+
`steer` delivery.
|
|
141
|
+
|
|
142
|
+
- [x] **3.4 Live smoke + journal**
|
|
143
|
+
- Throwaway script (not committed): delegate to a real agent with **no**
|
|
144
|
+
watch; the boundary notice appears with the retrieval command; the
|
|
145
|
+
result is retrievable; no duplicate notice follows.
|
|
146
|
+
- Record scope, evidence, and the landing note in `journal.md` before
|
|
147
|
+
merging; note the branch name (`feat/007-unwatched-completion-notice`).
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# Intent — Sheep on another machine (remote Herdr)
|
|
2
|
+
|
|
3
|
+
## Why this exists
|
|
4
|
+
|
|
5
|
+
Herdr stopped being a single-machine tool before pi-shepherd noticed. The
|
|
6
|
+
CLI now exposes saved SSH profiles (`herdr machine add|list|status`) and a
|
|
7
|
+
machine-scoped command form (`herdr --machine <label-or-id> <command>`), so
|
|
8
|
+
a pane, a tab, a workspace, and an agent can all live on a machine other
|
|
9
|
+
than the one the Shepherd runs on. This box already has two profiles
|
|
10
|
+
configured.
|
|
11
|
+
|
|
12
|
+
pi-shepherd is now the only part of the stack that assumes one computer:
|
|
13
|
+
`pane split --cwd "$PWD"`, a local broker directory, local absolute launch
|
|
14
|
+
files, a local pane registry. Everything a user actually wants from two
|
|
15
|
+
machines — "put the heavy build on the desktop", "run the overnight suite
|
|
16
|
+
where the repo is", "keep my laptop cool while the GPU box works" — is
|
|
17
|
+
already possible by hand, and is abandoned the moment you want a shepherd
|
|
18
|
+
watching.
|
|
19
|
+
|
|
20
|
+
This spec exists to make machine placement an attribute of a sheep instead
|
|
21
|
+
of a fork in the mental model.
|
|
22
|
+
|
|
23
|
+
## What already holds — do not rebuild it
|
|
24
|
+
|
|
25
|
+
- **Herdr owns the wire.** Machine profiles, SSH credentials, session
|
|
26
|
+
names, and reconnect behavior are Herdr's job. We address a machine by
|
|
27
|
+
its Herdr profile label or id, never by a raw `ssh` target of our own.
|
|
28
|
+
- **The runtime contract is already backend-neutral.** `src/runtimes/runtime.ts`
|
|
29
|
+
exists precisely so a second substrate can sit under the same opaque,
|
|
30
|
+
session-scoped ids (`specs/006-dual-runtime-herdr-durable`).
|
|
31
|
+
- **Four operations are cross-machine for free** once the `--machine` prefix
|
|
32
|
+
exists: spawn placement, `status`, `read`, and `close`. So is the status
|
|
33
|
+
widget's notion of agent state (`herdr --machine m agent list`).
|
|
34
|
+
- **The envelope layer is transport-shaped, not filesystem-shaped.**
|
|
35
|
+
`src/runtimes/herdr/messaging.ts` keeps envelopes self-describing
|
|
36
|
+
(schema version, session, broker, message, sender, target), authenticates
|
|
37
|
+
children with a token, publishes atomically, records acknowledgements,
|
|
38
|
+
dead-letters malformed mail, and requires idempotent handlers. At-least-once
|
|
39
|
+
delivery over an unreliable link is therefore an existing property, not a
|
|
40
|
+
new problem.
|
|
41
|
+
|
|
42
|
+
## The one thing that is not free
|
|
43
|
+
|
|
44
|
+
The broker is a **local filesystem** with a 250 ms child-side inbox poll,
|
|
45
|
+
and the launch path writes **local absolute paths** into the child (task
|
|
46
|
+
file, system prompt file, session file, and the `-e` path of the
|
|
47
|
+
`shepherd-done` sidecar). A remote pane can read none of them.
|
|
48
|
+
|
|
49
|
+
That single fact decides the whole shape of this work: pane control goes
|
|
50
|
+
over Herdr's existing SSH channel, but **coordination needs its own
|
|
51
|
+
transport**, and the transport is the only genuinely new subsystem here.
|
|
52
|
+
|
|
53
|
+
## Direction we intend (not a design lock)
|
|
54
|
+
|
|
55
|
+
An **SSH relay in the direction we already have** — parent → remote —
|
|
56
|
+
layered beneath the existing envelope code. The contract, and every check
|
|
57
|
+
that proves it, is in [prerequisites.md](prerequisites.md).
|
|
58
|
+
|
|
59
|
+
- Each side keeps a normal, local broker. Envelopes are the wire format;
|
|
60
|
+
the relay only moves them, so envelope semantics are implemented once.
|
|
61
|
+
- The parent drives the loop per machine: push unsent mail into the remote
|
|
62
|
+
inbox, pull new mail from the remote outbox, acknowledge what was
|
|
63
|
+
delivered. The child's existing 250 ms inbox poll stays local and never
|
|
64
|
+
touches the network.
|
|
65
|
+
- **The sheep machine never needs SSH to the shepherd.** No reverse
|
|
66
|
+
credential, no listener on the parent, no tunnel to supervise. A
|
|
67
|
+
parent-opened `ssh -N -R` tunnel or a `restrict`ed key is an opt-in
|
|
68
|
+
latency optimisation, not a prerequisite.
|
|
69
|
+
- **Launch assets travel as content**, written to a remote path the parent
|
|
70
|
+
chooses. Choosing that path is what makes the remote mailbox addressable
|
|
71
|
+
at all.
|
|
72
|
+
- **Install method is not part of the identity.** The remote instance
|
|
73
|
+
self-reports through a manifest (package version, protocol version,
|
|
74
|
+
capabilities, sidecar path, agent dir), so npm, git, a dev clone, `-e`,
|
|
75
|
+
and Nix-store paths all resolve the same way.
|
|
76
|
+
- **Prerequisite, not optional:** the remote machine has `pi` plus the
|
|
77
|
+
`shepherd-done` sidecar. "A tracked task settles only through an explicit
|
|
78
|
+
child `shepherd_done`" is load-bearing; without the sidecar a remote
|
|
79
|
+
sheep's task can only ever time out.
|
|
80
|
+
- **Herdr as a nudge, never as the channel.** `herdr --machine m pane
|
|
81
|
+
send-keys` can tell a remote child "mail is waiting, poll now". It types
|
|
82
|
+
into a TUI, so it must never carry the message itself.
|
|
83
|
+
|
|
84
|
+
## Phasing
|
|
85
|
+
|
|
86
|
+
1. **Placement without coordination.** Machine inventory surfaced next to
|
|
87
|
+
`herd`; `machine add` runs the preflight and records a verified machine;
|
|
88
|
+
`machine` accepted as a spawn attribute; `status`/`read`/`close` working
|
|
89
|
+
cross-machine; `delegate` and `message` refused with a clear, specific
|
|
90
|
+
error. The registry key becomes `(machine, agentDir, paneId)` first.
|
|
91
|
+
2. **Coordination.** Parent-driven SSH relay under the existing envelope
|
|
92
|
+
layer, gated by the wire handshake in
|
|
93
|
+
[prerequisites.md](prerequisites.md); `delegate`/`message`/`watch` reach
|
|
94
|
+
parity for remote sheep.
|
|
95
|
+
3. **Comfort.** Optional reverse tunnel or wake nudge, multi-machine widget
|
|
96
|
+
polling, and an explicit decision about fieldnotes for remote sheep.
|
|
97
|
+
|
|
98
|
+
## Who it serves
|
|
99
|
+
|
|
100
|
+
1. **Laptop orchestrator, desktop worker.** The Shepherd stays where the
|
|
101
|
+
human is; the heavy sheep live where the CPU is.
|
|
102
|
+
2. **Long-running remote work.** The suite runs where the repo and its
|
|
103
|
+
secrets already are, and the answer comes back to the same result blocks.
|
|
104
|
+
3. **Maintainer (us).** One tool surface. `machine` is a spawn attribute,
|
|
105
|
+
not a second universe of `remote_*` tools, and machine support costs
|
|
106
|
+
nothing when it is unused.
|
|
107
|
+
|
|
108
|
+
## What success looks like
|
|
109
|
+
|
|
110
|
+
- Adding a machine is one line the user already has in Herdr, then
|
|
111
|
+
`/shepherd spawn worker --machine eos-ext` behaves like any other spawn:
|
|
112
|
+
same opaque id, same `call:`/`return:`/`details:` result, same lifecycle.
|
|
113
|
+
- `shepherd herd` shows which machine each sheep is on, and `status`,
|
|
114
|
+
`read`, and `close` behave identically for local and remote sheep.
|
|
115
|
+
- A remote sheep asks the Shepherd a question mid-task and receives a
|
|
116
|
+
correlated reply; `shepherd_done` remains the only terminal outcome.
|
|
117
|
+
- Losing the SSH link turns into a visible terminal failure — never a
|
|
118
|
+
silent hang, and never a fabricated completion.
|
|
119
|
+
- A local-only user notices nothing: no new dependency, no new config, no
|
|
120
|
+
SSH key required to run pi-shepherd as it runs today.
|
|
121
|
+
|
|
122
|
+
## Guiding values
|
|
123
|
+
|
|
124
|
+
1. **Herdr owns machines.** Profiles, credentials, and session naming stay
|
|
125
|
+
in Herdr. We consume its inventory; we do not grow a parallel SSH config.
|
|
126
|
+
2. **One surface, one id space.** Machine is an attribute of spawn. Opaque
|
|
127
|
+
ids stay opaque. A pane id from another machine is never more valid as a
|
|
128
|
+
handle than a local one.
|
|
129
|
+
3. **Fail loud, fail closed.** An unreachable machine is a terminal
|
|
130
|
+
outcome, not a pending one.
|
|
131
|
+
4. **Local by default.** No behavior change, no new dependency, no new
|
|
132
|
+
credential for the single-machine install.
|
|
133
|
+
|
|
134
|
+
## Deliberate temptations to resist
|
|
135
|
+
|
|
136
|
+
- **Shared mount (sshfs/NFS) as "the cheap way."** It preserves the 250 ms
|
|
137
|
+
poll unchanged, and in exchange the remote host can read and rewrite the
|
|
138
|
+
broker directory and its tokens, and a stalled mount blocks the parent
|
|
139
|
+
poll instead of failing it.
|
|
140
|
+
- **The child's TUI as the message channel.** Lossy, unaddressable, no
|
|
141
|
+
metadata, and it collides with approval prompts.
|
|
142
|
+
- **Adding the reverse SSH direction by default.** It buys latency the
|
|
143
|
+
parent-driven pull loop already provides, and costs a credential on the
|
|
144
|
+
orchestrating machine.
|
|
145
|
+
- **Guessing remote install paths**, or letting an npm-shaped layout become
|
|
146
|
+
part of the identity.
|
|
147
|
+
- **Trusting the SSH key alone** to authorize an agent id.
|
|
148
|
+
- **Silently syncing agent definitions or fieldnotes** to remote machines.
|
|
149
|
+
Each is a trust decision about which repo content may define what a sheep
|
|
150
|
+
does, and remote repo content feeding a locally user-owned gate is a real
|
|
151
|
+
regression, not a convenience.
|
|
152
|
+
- **250 ms polling over SSH** fanned out across every remote sheep.
|
|
153
|
+
- **Reading agent state as completion.** `idle`/`done` from a remote list is
|
|
154
|
+
visibility, not a result.
|
|
155
|
+
|
|
156
|
+
## Open questions
|
|
157
|
+
|
|
158
|
+
Transport direction, version skew, and install resolution are specified in
|
|
159
|
+
[prerequisites.md](prerequisites.md). What remains genuinely open:
|
|
160
|
+
|
|
161
|
+
- Per-machine default working directory. Herdr profiles deliberately carry
|
|
162
|
+
no cwd, so this must be ours, and validated on the far side (preflight
|
|
163
|
+
P8).
|
|
164
|
+
- Model inheritance when the remote machine lacks the parent's provider.
|
|
165
|
+
- Clock skew against envelope `deadlineAt` and `completedAt`.
|
|
166
|
+
- Fieldnotes for remote sheep: shared, mirrored, or explicitly unavailable.
|
|
167
|
+
- What a repo-controlled remote `.shepherd/config.json` is allowed to
|
|
168
|
+
influence given the project-agent gate is user-owned and local.
|
|
169
|
+
- Ownership and pruning when a machine is powered off at prune time.
|
|
170
|
+
|
|
171
|
+
## When we are done
|
|
172
|
+
|
|
173
|
+
We can delete this file's doubts: placement stopped being a decision about
|
|
174
|
+
which tool the user reaches for, and became one flag on the same sheep.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# Journal — 008 sheep on another machine (remote Herdr)
|
|
2
|
+
|
|
3
|
+
## Status — 2026-10-22
|
|
4
|
+
|
|
5
|
+
- **Scope: specification only.** No code, no settings, no tool-surface
|
|
6
|
+
change. `specs/008-remote-machine-sheep/` holds `intent.md` and
|
|
7
|
+
`prerequisites.md`; there is no `spec.md`, `plan.md`, or `tasks.md` yet.
|
|
8
|
+
- Nothing is implemented: no `machine` spawn attribute, no relay, no
|
|
9
|
+
preflight, no instance manifest, no registry key change.
|
|
10
|
+
- Landed on `main` as documentation, not on a feature branch.
|
|
11
|
+
- **Exit condition for this stage:** intent (why, who, success, values,
|
|
12
|
+
temptations) and the remote contract (transport direction, version skew,
|
|
13
|
+
install resolution, preflight, rejected alternatives) are written down and
|
|
14
|
+
mutually consistent.
|
|
15
|
+
|
|
16
|
+
## Decisions
|
|
17
|
+
|
|
18
|
+
- Transport is **parent → remote push/pull**, not child → parent. Herdr's
|
|
19
|
+
`machine add` already establishes that direction, so the sheep machine
|
|
20
|
+
never needs SSH to the shepherd: no reverse credential, no listener on the
|
|
21
|
+
orchestrator, no tunnel to supervise. A parent-opened `ssh -N -R` tunnel or
|
|
22
|
+
a `restrict`ed key is an opt-in latency optimisation, never a prerequisite.
|
|
23
|
+
- Launch assets (script, task, system prompt, session) travel as **content**
|
|
24
|
+
to a **parent-chosen** remote path. Choosing that path is what makes the
|
|
25
|
+
remote mailbox addressable at all.
|
|
26
|
+
- The child is launched with the **remote's own** sidecar path
|
|
27
|
+
(`-e <remoteSidecarPath>`) — not the parent's absolute path, and not the
|
|
28
|
+
remote's auto-loaded package. This keeps the child surface identical to
|
|
29
|
+
local: sidecar only, so `shepherd_message` + `shepherd_done`, rather than
|
|
30
|
+
silently granting remote sheep the full `spawn`/`delegate`/`close` surface.
|
|
31
|
+
- **Package version is informational; the wire protocol gates.** Envelopes
|
|
32
|
+
already carry `schemaVersion: 1` and reject anything else, and today a
|
|
33
|
+
mismatch dead-letters the envelope so the task hangs to its timeout.
|
|
34
|
+
Mismatch must be refused at `delegate`, with a capability list alongside the
|
|
35
|
+
protocol version.
|
|
36
|
+
- **Install method is not part of the identity.** The extension self-reports
|
|
37
|
+
through `$PI_CODING_AGENT_DIR/pi-shepherd/instance.json`, so npm, git, a dev
|
|
38
|
+
clone, `-e`, and Nix-store paths resolve the same way. Addressing becomes
|
|
39
|
+
`(machine, agentDir)`; the ownership key becomes
|
|
40
|
+
`(machine, agentDir, paneId)`.
|
|
41
|
+
- Provisioning mirrors `herdr machine add`: probe, print the exact install
|
|
42
|
+
line, require interactive approval, round-trip the mailbox, record
|
|
43
|
+
`verifiedAt`. No silent remote install, no silent agent or fieldnotes sync.
|
|
44
|
+
|
|
45
|
+
## Deliberately not decided
|
|
46
|
+
|
|
47
|
+
Per-machine default cwd policy, remote model inheritance when the machine
|
|
48
|
+
lacks the parent's provider, clock skew against envelope `deadlineAt` /
|
|
49
|
+
`completedAt`, fieldnotes for remote sheep, what a repo-controlled remote
|
|
50
|
+
`.shepherd/config.json` may influence, and pruning while a machine is powered
|
|
51
|
+
off. These stay in `intent.md` until there is code to argue with.
|
|
52
|
+
|
|
53
|
+
## Next
|
|
54
|
+
|
|
55
|
+
`spec.md` for the public surface (`machine` spawn attribute, `herd` and
|
|
56
|
+
`machine status` output, refusal errors), then `plan.md`/`tasks.md` for phase 1
|
|
57
|
+
— inventory, preflight, and the registry key — before any relay work starts.
|
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
# Prerequisites — what a sheep machine must provide
|
|
2
|
+
|
|
3
|
+
Companion to [intent.md](intent.md). The intent says a sheep may live on
|
|
4
|
+
another machine; this file fixes the **contract** that makes that safe: what
|
|
5
|
+
the remote side must offer, what pi-shepherd refuses to require, and how each
|
|
6
|
+
claim is *verified* rather than assumed.
|
|
7
|
+
|
|
8
|
+
Four questions drove this file, and each has a settled answer:
|
|
9
|
+
|
|
10
|
+
1. What if the sheep machine cannot reach the shepherd over SSH?
|
|
11
|
+
2. What if the pi-shepherd versions differ?
|
|
12
|
+
3. What if it is installed differently (npm, git, clone, `-e`, Nix)?
|
|
13
|
+
4. How do we prove any of the above before a task is delegated?
|
|
14
|
+
|
|
15
|
+
The governing rule: **a claim that cannot be round-tripped is not a
|
|
16
|
+
precondition, it is a hope.** Every item below ends in an observable check
|
|
17
|
+
with a specific failure message.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## 1. Transport direction — the sheep never needs SSH to the shepherd
|
|
22
|
+
|
|
23
|
+
Herdr's `machine add` already establishes exactly one direction: **parent →
|
|
24
|
+
remote** (that is how pane, agent, and workspace commands reach the remote
|
|
25
|
+
server). So do not add the opposite direction. Invert the relay.
|
|
26
|
+
|
|
27
|
+
- Both brokers stay local to their own machine. Nothing is shared, nothing is
|
|
28
|
+
mounted.
|
|
29
|
+
- The parent drives one loop per machine that owns live sheep:
|
|
30
|
+
- **push** unsent envelopes into the remote inbox,
|
|
31
|
+
- **pull** new envelopes from the remote outbox,
|
|
32
|
+
- **ack** by moving/removing the delivered file.
|
|
33
|
+
- The child's 250 ms inbox poll (`src/extension/shepherd-done.ts`) stays local
|
|
34
|
+
and unchanged. The child never touches the network. This is the property
|
|
35
|
+
that makes the design cheap: one implementation of envelope semantics, two
|
|
36
|
+
transports.
|
|
37
|
+
- **No reverse credential**, no listener on the parent, no
|
|
38
|
+
`authorized_keys` edit on the parent, no tunnel lifecycle to supervise.
|
|
39
|
+
|
|
40
|
+
Latency budget: a child's question reaches the shepherd within one parent
|
|
41
|
+
poll interval (~1 s per machine); the child receives mail within ~250 ms of a
|
|
42
|
+
push. That is adequate for ask-and-wait work and unacceptable for
|
|
43
|
+
real-time steering, which is why the reverse direction is a **latency
|
|
44
|
+
optimisation, not a requirement**: a parent-opened `ssh -N -R` tunnel, or an
|
|
45
|
+
opt-in `restrict`ed key with a forced command pinned to one agent id. Both
|
|
46
|
+
stay off by default and are visible in `machine status` when enabled.
|
|
47
|
+
|
|
48
|
+
Scaling note: N machines × 1 poll each needs `ControlMaster`/`ControlPersist`
|
|
49
|
+
and a poll that only runs for machines with live sheep. Unreachable machines
|
|
50
|
+
must **stop** being polled (and surface as unreachable), never retry silently
|
|
51
|
+
forever.
|
|
52
|
+
|
|
53
|
+
## 2. Launch assets travel as content, not as paths
|
|
54
|
+
|
|
55
|
+
Today `writePiLaunchFiles` writes `launch-*.sh`, `task-*.md`, `sysprompt-*.md`
|
|
56
|
+
and a session file into a local `mkdtemp`, then passes absolute local paths,
|
|
57
|
+
including `-e <parent>/src/extension/shepherd-done.ts`. A remote pane can read
|
|
58
|
+
none of that. Two consequences:
|
|
59
|
+
|
|
60
|
+
- Script, task, and system prompt must be **uploaded as bytes** over the same
|
|
61
|
+
ssh channel and written to a remote path the **parent chooses**. Choosing
|
|
62
|
+
the path is what makes the mailbox addressable at all: the parent knows the
|
|
63
|
+
remote `PI_SHEPHERD_BROKER_DIR` because it invented it.
|
|
64
|
+
- The `-e` argument must be the **remote's own** sidecar path, never the
|
|
65
|
+
parent's (see §4). This is the single change that keeps a remote child's
|
|
66
|
+
capability surface identical to a local child's: sidecar only, so
|
|
67
|
+
`shepherd_message` + `shepherd_done` and nothing else. Relying instead on
|
|
68
|
+
the remote's auto-loaded package would silently give every remote sheep the
|
|
69
|
+
full shepherd surface (`spawn`/`delegate`/`close`) — a capability
|
|
70
|
+
asymmetry nobody asked for.
|
|
71
|
+
|
|
72
|
+
Transport mechanics wanted: pure POSIX shell over `ssh` to the profile's
|
|
73
|
+
`target`, no remote helper binary and no build step —
|
|
74
|
+
`cat > …/.tmp.$$ && mv` for atomic publish, length-prefixed or NUL-framed
|
|
75
|
+
batches for pull. Envelope sizes already bounded by `maxMessageBytes`, and
|
|
76
|
+
handlers are already idempotent, so a duplicated batch is safe.
|
|
77
|
+
|
|
78
|
+
## 3. Version skew — protocol gates, package version does not
|
|
79
|
+
|
|
80
|
+
Two versions exist and only one may gate:
|
|
81
|
+
|
|
82
|
+
- **Package version** (`@luminascale/pi-shepherd` 0.5.0) — informational.
|
|
83
|
+
- **Wire protocol** — already implicit: envelopes carry `schemaVersion: 1`,
|
|
84
|
+
and `src/runtimes/herdr/messaging.ts` rejects anything else.
|
|
85
|
+
|
|
86
|
+
Today's mismatch failure mode is the worst one available: an invalid envelope
|
|
87
|
+
is moved to `rejected/`, the child never learns, and the task hangs until
|
|
88
|
+
timeout. Therefore:
|
|
89
|
+
|
|
90
|
+
- Handshake before work: `protocolVersion` plus a **capability list**
|
|
91
|
+
(`mailPull`, `ackByMarker`, `steer`, …). A scalar breaks on the first
|
|
92
|
+
optional feature; a list does not.
|
|
93
|
+
- Accept N/N-1 and refuse the rest, at `delegate` time, with an actionable
|
|
94
|
+
remedy — never at completion.
|
|
95
|
+
- **Treat the child as the weak side.** An ancient remote sidecar must be able
|
|
96
|
+
to answer "I am protocol 0"; silence is a failed preflight, not a pending
|
|
97
|
+
task.
|
|
98
|
+
- What actually has to move together, and therefore belongs under the protocol
|
|
99
|
+
number: envelope shape, ack semantics, the child tool names
|
|
100
|
+
(`shepherd_message`, `shepherd_done`), the `PI_SHEPHERD_*` environment
|
|
101
|
+
contract, and the sidecar load path. Cosmetic releases must not bump it.
|
|
102
|
+
- Locally, version lockstep is free (`-e <parent's own path>`). Cross-machine
|
|
103
|
+
drift is a **new class of bug**, so `verify-compat.mjs` (which checks the
|
|
104
|
+
*surface*) needs a sibling that checks the *wire*: parent-v1 ↔ child-v2
|
|
105
|
+
fixtures, both directions.
|
|
106
|
+
|
|
107
|
+
## 4. Install resolution — ask the machine, never compute a path
|
|
108
|
+
|
|
109
|
+
No path guessable from the parent works: npm lands "under the Pi npm
|
|
110
|
+
directory", git clones reconcile to a ref, a dev clone lives in
|
|
111
|
+
`~/.pi/agent/extensions/pi-shepherd`, `-e` is a one-off, and `PI_PACKAGE_DIR`
|
|
112
|
+
exists precisely because Nix/Guix store paths are arbitrary. The package has
|
|
113
|
+
no `bin`, so `which pi-shepherd` is not an option either.
|
|
114
|
+
|
|
115
|
+
Instead, the extension knows its own root (`import.meta.url`) and its agent
|
|
116
|
+
dir (`PI_CODING_AGENT_DIR`), so it writes an **instance manifest** at load:
|
|
117
|
+
|
|
118
|
+
```json
|
|
119
|
+
{
|
|
120
|
+
"packageVersion": "0.5.0",
|
|
121
|
+
"protocolVersion": 1,
|
|
122
|
+
"capabilities": ["mailPull", "ackByMarker"],
|
|
123
|
+
"piVersion": "1.4.0",
|
|
124
|
+
"extensionRoot": "/…/pi-shepherd",
|
|
125
|
+
"sidecarPath": "/…/pi-shepherd/src/extension/shepherd-done.ts",
|
|
126
|
+
"agentDir": "/home/u/.pi/agent",
|
|
127
|
+
"pid": 1234,
|
|
128
|
+
"startedAt": 0
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Stored at `$PI_CODING_AGENT_DIR/pi-shepherd/instance.json`. One read-only
|
|
133
|
+
`ssh target cat …` then answers *installed? which version? where?* identically
|
|
134
|
+
for npm, git, clone, `-e`, and Nix. **Install method stops being part of the
|
|
135
|
+
identity.**
|
|
136
|
+
|
|
137
|
+
Two consequences:
|
|
138
|
+
|
|
139
|
+
- **Addressing is `(machine, agentDir)`**, not `machine`. One host can carry
|
|
140
|
+
two installs (npm copy plus a dev clone) or two agent dirs, and those are
|
|
141
|
+
distinct shepherds. The ownership registry key must become
|
|
142
|
+
`(machine, agentDir, paneId)` before any of this lands; today `CreatedPane`
|
|
143
|
+
is keyed by a bare `paneId`, which collides across machines because pane ids
|
|
144
|
+
(`w1:p1`) are per-session-per-machine.
|
|
145
|
+
- A **stale manifest** is normal (last shutdown leaves it behind), so treat it
|
|
146
|
+
as a hint plus a liveness check, not as truth: `pid` + `startedAt` let the
|
|
147
|
+
probe distinguish "installed, idle" from "installed, running".
|
|
148
|
+
|
|
149
|
+
## 5. Provisioning — approved once, verified every time
|
|
150
|
+
|
|
151
|
+
Mirror the model Herdr already uses for itself: `herdr machine add` prepares
|
|
152
|
+
the remote installation and *missing or incompatible installations require
|
|
153
|
+
approval in an interactive terminal.*
|
|
154
|
+
|
|
155
|
+
`shepherd machine add <herdr-profile>` should:
|
|
156
|
+
|
|
157
|
+
1. Probe (§6). Print exactly what is missing and the exact fix, e.g.
|
|
158
|
+
`pi install npm:@luminascale/pi-shepherd@0.5.0`.
|
|
159
|
+
2. Offer to run it; never run it silently. A remote pi package is code
|
|
160
|
+
execution in the user's remote shell, and remote sheep already execute
|
|
161
|
+
remote repo content.
|
|
162
|
+
3. Round-trip the mailbox and only then record
|
|
163
|
+
`{machine, agentDir, protocolVersion, sidecarPath, cwd, verifiedAt}`.
|
|
164
|
+
4. Re-verify on `machine status`, and re-probe at `spawn` when `verifiedAt` is
|
|
165
|
+
stale.
|
|
166
|
+
|
|
167
|
+
Never auto-sync agent definitions or fieldnotes. Each is a trust decision
|
|
168
|
+
about which repo content may define what a sheep does.
|
|
169
|
+
|
|
170
|
+
## 6. Preflight checklist
|
|
171
|
+
|
|
172
|
+
Cheap, ordered, each step with a specific remedy. Blocking steps must block
|
|
173
|
+
`delegate`; advisory steps only warn.
|
|
174
|
+
|
|
175
|
+
| # | Check | How | Failure means |
|
|
176
|
+
|---|---|---|---|
|
|
177
|
+
| P1 | Machine known and enabled | `herdr machine list --json` → `enabled: true` | "run `herdr machine add <target>`" |
|
|
178
|
+
| P2 | SSH reachable parent → remote | one `ssh <target> true` | "machine unreachable; nothing was spawned" |
|
|
179
|
+
| P3 | Remote `pi` present and new enough | `pi --version` vs minimum | "remote pi too old for `-e` TypeScript sidecar" |
|
|
180
|
+
| P4 | pi-shepherd installed remotely | read `instance.json` | "install `@luminascale/pi-shepherd@<v>` on `<machine>`" |
|
|
181
|
+
| P5 | Protocol compatible | manifest `protocolVersion` ∈ window | "machine speaks protocol 2, this shepherd 1" |
|
|
182
|
+
| P6 | Sidecar readable | `ssh <target> test -r <sidecarPath>` | "install incomplete; reinstall the package" |
|
|
183
|
+
| P7 | Mailbox round trip | push envelope, pull it back, ack | "no working mail route; using tunnel or refusing `delegate`" |
|
|
184
|
+
| P8 | cwd exists remotely | `ssh <target> test -d <cwd>` | "per-machine cwd `<dir>` does not exist" |
|
|
185
|
+
| P9 | Model/provider available | advisory | warning only; herd records the substitution |
|
|
186
|
+
|
|
187
|
+
P4/P5/P6 replace what would otherwise be a **30 s `herdr agent start` detect
|
|
188
|
+
timeout**: without them a missing remote surface shows up as an opaque agent
|
|
189
|
+
start failure, which is exactly the diagnosis-free outcome this list exists to
|
|
190
|
+
prevent.
|
|
191
|
+
|
|
192
|
+
## 7. Rejected alternatives
|
|
193
|
+
|
|
194
|
+
- **Shared mount (sshfs/NFS) at identical paths.** Preserves the 250 ms poll
|
|
195
|
+
with zero new transport code, but lets the remote host read and rewrite the
|
|
196
|
+
broker directory and its tokens, and a stalled mount blocks the parent poll
|
|
197
|
+
instead of failing it.
|
|
198
|
+
- **Reverse SSH as the default.** Requires a credential on the *orchestrator*
|
|
199
|
+
that a remote compromise can use, to buy latency the pull loop already
|
|
200
|
+
delivers.
|
|
201
|
+
- **Bundling/copying the sidecar as a standalone file.** It imports
|
|
202
|
+
`../runtimes/herdr/messaging.ts` and `./system-prompt.ts`, and the repo has
|
|
203
|
+
no build step (AGENTS.md). Requiring the package is cheaper than inventing a
|
|
204
|
+
bundler.
|
|
205
|
+
- **Path discovery by guessing** (`node_modules`, `which`, `~/.pi/agent/extensions`).
|
|
206
|
+
Wrong for at least two supported install methods, silently wrong when two
|
|
207
|
+
installs coexist.
|
|
208
|
+
- **`herdr pane run` / `send-keys` as the message channel.** Types into a TUI:
|
|
209
|
+
lossy, unaddressable, collides with approval prompts. Wake signal only.
|
|
210
|
+
- **Silent remote install or silent agent/fieldnotes sync.**
|
|
211
|
+
|
|
212
|
+
## 8. Still owned by intent.md
|
|
213
|
+
|
|
214
|
+
These are not settled here and must not be smuggled in by an implementation
|
|
215
|
+
detail: per-machine default cwd policy, model inheritance when the remote
|
|
216
|
+
lacks the parent's provider, clock skew against envelope `deadlineAt` /
|
|
217
|
+
`completedAt`, the fieldnotes decision for remote sheep, what a repo-controlled
|
|
218
|
+
remote `.shepherd/config.json` may influence, and pruning while a machine is
|
|
219
|
+
powered off.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Intent — hc-app Runtime (Herdr TUI + hc core)
|
|
2
|
+
|
|
3
|
+
## Why this exists
|
|
4
|
+
|
|
5
|
+
pi-shepherd is Herdr-TUI-native today (`herdr` CLI, panes/tabs/workspaces).
|
|
6
|
+
The Herdr app (`hc` / herdr-core terminals) is now available in the same
|
|
7
|
+
sessions. Users run Shepherd from either place and expect sheep to run
|
|
8
|
+
where they are, not cross-spawned into the other UI.
|
|
9
|
+
|
|
10
|
+
This spec adds a second runtime (`hc`) beside `herdr` behind one Shepherd
|
|
11
|
+
surface, with per-command auto-detect and `auto` as default.
|
|
12
|
+
|
|
13
|
+
This spec is independent from `006-dual-runtime-herdr-durable` (paused).
|
|
14
|
+
Same 2-runtimes-1-core pattern, different second runtime.
|
|
15
|
+
|
|
16
|
+
## Who it serves
|
|
17
|
+
|
|
18
|
+
1. **TUI user** — runs in `herdr` terminal, sheep appear as panes/tabs.
|
|
19
|
+
Must notice zero change by default.
|
|
20
|
+
2. **App user** — runs in `hc` terminal (`HC_TERMINAL_ID`, `hc ls`), sheep
|
|
21
|
+
appear as `hc` terminals. Must get same `spawn -> delegate -> watch ->
|
|
22
|
+
done` flow.
|
|
23
|
+
3. **Maintainer** — one tool surface, one agent format, two executors.
|
|
24
|
+
No `herdr_*` vs `hc_*` tool fork.
|
|
25
|
+
|
|
26
|
+
## What success looks like
|
|
27
|
+
|
|
28
|
+
- Same orchestrator prompt runs unchanged in TUI and in app.
|
|
29
|
+
- Default setting `backend: auto` means: every command runs where it was
|
|
30
|
+
called from, unless the settings UI explicitly pins `herdr` or `hc`.
|
|
31
|
+
- Explicit pin is respected but fails cleanly with a hint when that
|
|
32
|
+
runtime is unreachable (no silent cross-spawn).
|
|
33
|
+
- The model never chooses a runtime. No `backend` param on any
|
|
34
|
+
`shepherd_*` tool. Backend lives only in settings (app side).
|
|
35
|
+
- `shepherd.md` + per-agent fieldnotes stay the shared memory on both.
|
|
36
|
+
|
|
37
|
+
## Guiding values
|
|
38
|
+
|
|
39
|
+
1. **Same shepherd, different field.** Tool names, opaque IDs, agent
|
|
40
|
+
Markdown, handoff habits do not fork.
|
|
41
|
+
2. **Auto by default.** Detect per command, run local.
|
|
42
|
+
3. **No magic / no cross-spawn.** Never spawn a TUI pane from the app
|
|
43
|
+
(or vice versa) unless explicitly pinned *and* reachable.
|
|
44
|
+
4. **Boring.** No new deps, no migration, default stays working.
|