@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.
Files changed (203) hide show
  1. package/.agents/agents/README.md +12 -0
  2. package/.agents/agents/planner.md +38 -0
  3. package/.agents/agents/reviewer.md +38 -0
  4. package/.agents/agents/scout.md +43 -0
  5. package/.agents/agents/worker.md +33 -0
  6. package/.agents/skills/smoke-test/SKILL.md +155 -0
  7. package/.agents/skills/smoke-test/references/forensics.md +46 -0
  8. package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
  9. package/.github/workflows/publish.yml +77 -0
  10. package/.pi/prompts/release.md +21 -0
  11. package/.prettierrc +10 -0
  12. package/AGENTS.md +88 -0
  13. package/CONTRIBUTING.md +177 -0
  14. package/LICENSE +201 -0
  15. package/README.md +424 -2
  16. package/docs/README.md +25 -0
  17. package/docs/guides/agent-definitions.md +42 -0
  18. package/docs/guides/diagnostics.md +199 -0
  19. package/docs/guides/tool-reference.md +55 -0
  20. package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
  21. package/docs/plans/agent-labels.md +257 -0
  22. package/docs/plans/architecture.md +110 -0
  23. package/docs/plans/settings-scope.md +163 -0
  24. package/docs/plans/tool-surface-split.md +278 -0
  25. package/docs/reference/dictionary +26 -0
  26. package/docs/releasing.md +47 -0
  27. package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
  28. package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
  29. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
  30. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
  31. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
  32. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
  33. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
  34. package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
  35. package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
  36. package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
  37. package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
  38. package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
  39. package/index.ts +599 -0
  40. package/package.json +112 -4
  41. package/scripts/capture-system-prompt.mjs +45 -0
  42. package/scripts/extract-pi-system-prompt.mjs +277 -0
  43. package/scripts/host-impact.mjs +74 -0
  44. package/scripts/resolve-agent.mjs +43 -0
  45. package/scripts/show-shepherd-orchestrator.mjs +58 -0
  46. package/scripts/show-shepherd-prompt.mjs +96 -0
  47. package/scripts/verify-suites.mjs +67 -0
  48. package/specs/001-artifacts/spec.md +436 -0
  49. package/specs/002-simplify-agent-orchestration/plan.md +287 -0
  50. package/specs/002-simplify-agent-orchestration/spec.md +323 -0
  51. package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
  52. package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
  53. package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
  54. package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
  55. package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
  56. package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
  57. package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
  58. package/specs/005-per-workspace-settings/plan.md +230 -0
  59. package/specs/005-per-workspace-settings/spec.md +368 -0
  60. package/specs/005-per-workspace-settings/tasks.md +178 -0
  61. package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
  62. package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
  63. package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
  64. package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
  65. package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
  66. package/specs/007-unwatched-completion-notice/journal.md +145 -0
  67. package/specs/007-unwatched-completion-notice/plan.md +186 -0
  68. package/specs/007-unwatched-completion-notice/spec.md +284 -0
  69. package/specs/007-unwatched-completion-notice/tasks.md +147 -0
  70. package/specs/008-remote-machine-sheep/intent.md +174 -0
  71. package/specs/008-remote-machine-sheep/journal.md +57 -0
  72. package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
  73. package/specs/009-hc-runtime/intent.md +44 -0
  74. package/specs/009-hc-runtime/plan.md +49 -0
  75. package/specs/009-hc-runtime/spec.md +118 -0
  76. package/specs/009-hc-runtime/tasks.md +62 -0
  77. package/specs/010-unseen-watch-parity/intent.md +57 -0
  78. package/specs/010-unseen-watch-parity/journal.md +172 -0
  79. package/specs/010-unseen-watch-parity/plan.md +74 -0
  80. package/specs/010-unseen-watch-parity/spec.md +191 -0
  81. package/specs/010-unseen-watch-parity/tasks.md +119 -0
  82. package/specs/011-hc-background-poll/intent.md +57 -0
  83. package/specs/011-hc-background-poll/journal.md +95 -0
  84. package/specs/011-hc-background-poll/plan.md +87 -0
  85. package/specs/011-hc-background-poll/spec.md +141 -0
  86. package/specs/011-hc-background-poll/tasks.md +83 -0
  87. package/specs/012-steer-default/intent.md +12 -0
  88. package/specs/012-steer-default/journal.md +40 -0
  89. package/specs/012-steer-default/plan.md +7 -0
  90. package/specs/012-steer-default/spec.md +42 -0
  91. package/specs/012-steer-default/tasks.md +6 -0
  92. package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
  93. package/specs/013-opencode-shepherd/intent.md +59 -0
  94. package/specs/013-opencode-shepherd/plan.md +204 -0
  95. package/specs/013-opencode-shepherd/spec.md +258 -0
  96. package/specs/013-opencode-shepherd/tasks.md +259 -0
  97. package/src/core/artifact-sessions.ts +835 -0
  98. package/src/core/config.ts +329 -0
  99. package/src/core/discovery.ts +342 -0
  100. package/src/core/herdr.ts +1 -0
  101. package/src/core/host.ts +77 -0
  102. package/src/core/ids.ts +78 -0
  103. package/src/core/lifecycle.ts +1 -0
  104. package/src/core/messaging.ts +1 -0
  105. package/src/core/migration.ts +55 -0
  106. package/src/core/orchestration.ts +1 -0
  107. package/src/core/types.ts +143 -0
  108. package/src/core/unseen-completions.ts +114 -0
  109. package/src/extension/cli.ts +417 -0
  110. package/src/extension/config.ts +1 -0
  111. package/src/extension/settings-ui.ts +296 -0
  112. package/src/extension/shepherd-done.ts +768 -0
  113. package/src/extension/shepherd.ts +2548 -0
  114. package/src/extension/system-prompt.ts +38 -0
  115. package/src/extension/unseen-completions.ts +237 -0
  116. package/src/opencode/actions.ts +794 -0
  117. package/src/opencode/bridge.ts +777 -0
  118. package/src/opencode/display.ts +36 -0
  119. package/src/opencode/fieldnotes.ts +60 -0
  120. package/src/opencode/host.ts +62 -0
  121. package/src/opencode/orphans.ts +162 -0
  122. package/src/opencode/server.ts +458 -0
  123. package/src/runtimes/backend.ts +119 -0
  124. package/src/runtimes/detect.ts +102 -0
  125. package/src/runtimes/hc/hc.ts +527 -0
  126. package/src/runtimes/hc/runtime.ts +1898 -0
  127. package/src/runtimes/herdr/herdr.ts +912 -0
  128. package/src/runtimes/herdr/lifecycle.ts +1712 -0
  129. package/src/runtimes/herdr/messaging.ts +703 -0
  130. package/src/runtimes/herdr/orchestration.ts +1583 -0
  131. package/src/runtimes/herdr/runtime.ts +224 -0
  132. package/src/runtimes/runtime.ts +133 -0
  133. package/src/runtimes/settle-observations.ts +114 -0
  134. package/test/fixtures/context-project/AGENTS.md +2 -0
  135. package/test/fixtures/home/.agents/agents/same.md +6 -0
  136. package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
  137. package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
  138. package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
  139. package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
  140. package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
  141. package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
  142. package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
  143. package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
  144. package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
  145. package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
  146. package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
  147. package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
  148. package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
  149. package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
  150. package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
  151. package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
  152. package/test/fixtures/proj/.pi/agents/same.md +6 -0
  153. package/test/helpers/fake-clock.mjs +39 -0
  154. package/test/helpers/feature-contracts.mjs +44 -0
  155. package/test/helpers/test-utils.mjs +44 -0
  156. package/test/verify-artifact-sessions.mjs +258 -0
  157. package/test/verify-backend.mjs +297 -0
  158. package/test/verify-child-mislabel.mjs +135 -0
  159. package/test/verify-child-surface.mjs +321 -0
  160. package/test/verify-cli.mjs +197 -0
  161. package/test/verify-command-ux.mjs +100 -0
  162. package/test/verify-compat.mjs +32 -0
  163. package/test/verify-cross-host-notes.mjs +128 -0
  164. package/test/verify-delegate.mjs +161 -0
  165. package/test/verify-detect.mjs +151 -0
  166. package/test/verify-discovery.mjs +239 -0
  167. package/test/verify-done-nudge.mjs +238 -0
  168. package/test/verify-effective-prompt.mjs +98 -0
  169. package/test/verify-hc-matrix.mjs +246 -0
  170. package/test/verify-hc-poll.mjs +260 -0
  171. package/test/verify-host-docs.mjs +35 -0
  172. package/test/verify-host-impact.mjs +49 -0
  173. package/test/verify-ids.mjs +141 -0
  174. package/test/verify-launch.mjs +183 -0
  175. package/test/verify-message-routing.mjs +560 -0
  176. package/test/verify-messaging.mjs +303 -0
  177. package/test/verify-migration-notice.mjs +69 -0
  178. package/test/verify-multi-wait.mjs +42 -0
  179. package/test/verify-opencode-display.mjs +47 -0
  180. package/test/verify-opencode-fieldnotes.mjs +121 -0
  181. package/test/verify-opencode-notice.mjs +77 -0
  182. package/test/verify-opencode-nudge.mjs +116 -0
  183. package/test/verify-opencode-orphans.mjs +160 -0
  184. package/test/verify-opencode-surface.mjs +107 -0
  185. package/test/verify-packaging.mjs +82 -0
  186. package/test/verify-parent-surface.mjs +118 -0
  187. package/test/verify-phase0.mjs +95 -0
  188. package/test/verify-registry.mjs +124 -0
  189. package/test/verify-rename-migration.mjs +111 -0
  190. package/test/verify-rendering.mjs +379 -0
  191. package/test/verify-session-boundary.mjs +146 -0
  192. package/test/verify-settings.mjs +260 -0
  193. package/test/verify-stale-wait.mjs +339 -0
  194. package/test/verify-status-widget.mjs +377 -0
  195. package/test/verify-status.mjs +172 -0
  196. package/test/verify-task-completion.mjs +156 -0
  197. package/test/verify-task-failures.mjs +201 -0
  198. package/test/verify-task-mislabel.mjs +143 -0
  199. package/test/verify-task-registry.mjs +194 -0
  200. package/test/verify-task-watchers.mjs +217 -0
  201. package/test/verify-tool-schemas.mjs +120 -0
  202. package/test/verify-unseen-completions.mjs +1211 -0
  203. package/test/verify-watchers.mjs +181 -0
package/package.json CHANGED
@@ -1,6 +1,114 @@
1
1
  {
2
2
  "name": "@luminascale/shepherd",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.6.0",
4
+ "type": "module",
5
+ "description": "🐑 No-fuss herdr native subagent orchestration 🐑 (Pi + OpenCode)",
6
+ "exports": {
7
+ ".": "./src/opencode/server.ts",
8
+ "./pi": "./index.ts",
9
+ "./package.json": "./package.json"
10
+ },
11
+ "license": "Apache-2.0",
12
+ "homepage": "https://github.com/MikkelKappelPersson/shepherd#readme",
13
+ "repository": {
14
+ "type": "git",
15
+ "url": "git+https://github.com/MikkelKappelPersson/shepherd.git"
16
+ },
17
+ "bugs": {
18
+ "url": "https://github.com/MikkelKappelPersson/shepherd/issues"
19
+ },
20
+ "keywords": [
21
+ "pi-package",
22
+ "pi",
23
+ "pi-agent",
24
+ "extension",
25
+ "subagent",
26
+ "subagents",
27
+ "agent",
28
+ "agents",
29
+ "herdr",
30
+ "shepherd",
31
+ "sheep",
32
+ "artifacts",
33
+ "fieldnotes"
34
+ ],
35
+ "pi": {
36
+ "extensions": [
37
+ "./index.ts"
38
+ ]
39
+ },
40
+ "scripts": {
41
+ "host-impact": "node scripts/host-impact.mjs",
42
+ "clean": "echo 'nothing to clean'",
43
+ "build": "echo 'nothing to build'",
44
+ "check": "echo 'nothing to check'",
45
+ "discovery:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-discovery.mjs",
46
+ "schemas:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-tool-schemas.mjs",
47
+ "cli:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-cli.mjs",
48
+ "parent-surface:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-parent-surface.mjs",
49
+ "status-widget:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-status-widget.mjs",
50
+ "rendering:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-rendering.mjs",
51
+ "command-ux:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-command-ux.mjs",
52
+ "opencode-display:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-opencode-display.mjs",
53
+ "opencode-notice:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-opencode-notice.mjs",
54
+ "opencode-nudge:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-opencode-nudge.mjs",
55
+ "opencode-fieldnotes:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-opencode-fieldnotes.mjs",
56
+ "opencode-surface:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-opencode-surface.mjs",
57
+ "cross-host-notes:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-cross-host-notes.mjs",
58
+ "packaging:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-packaging.mjs",
59
+ "host-docs:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-host-docs.mjs",
60
+ "host-impact:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-host-impact.mjs",
61
+ "migration-notice:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-migration-notice.mjs",
62
+ "rename-migration:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-rename-migration.mjs",
63
+ "opencode-orphans:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-opencode-orphans.mjs",
64
+ "launch:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-launch.mjs",
65
+ "effective-prompt:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-effective-prompt.mjs",
66
+ "registry:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-registry.mjs",
67
+ "ids:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-ids.mjs",
68
+ "session-boundary:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-session-boundary.mjs",
69
+ "task-registry:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-task-registry.mjs",
70
+ "messaging:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-messaging.mjs",
71
+ "child-surface:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-child-surface.mjs",
72
+ "done-nudge:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-done-nudge.mjs",
73
+ "child-mislabel:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-child-mislabel.mjs",
74
+ "delegate:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-delegate.mjs",
75
+ "task-completion:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-task-completion.mjs",
76
+ "task-mislabel:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-task-mislabel.mjs",
77
+ "task-failures:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-task-failures.mjs",
78
+ "message-routing:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-message-routing.mjs",
79
+ "multi-wait:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-multi-wait.mjs",
80
+ "watchers:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-watchers.mjs",
81
+ "artifact-sessions:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-artifact-sessions.mjs",
82
+ "settings:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-settings.mjs",
83
+ "phase0:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-phase0.mjs",
84
+ "detect:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-detect.mjs",
85
+ "backend:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-backend.mjs",
86
+ "hc-matrix:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-hc-matrix.mjs",
87
+ "hc-poll:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-hc-poll.mjs",
88
+ "smoke:poll": "node --experimental-strip-types --disable-warning=ExperimentalWarning .agents/skills/smoke-test/scripts/live-smoke-poll.mjs",
89
+ "show:shepherd-prompt": "node --experimental-strip-types --disable-warning=ExperimentalWarning scripts/show-shepherd-prompt.mjs",
90
+ "show:shepherd-orchestrator": "node --experimental-strip-types --disable-warning=ExperimentalWarning scripts/show-shepherd-orchestrator.mjs",
91
+ "extract:system-prompt": "node --experimental-strip-types --disable-warning=ExperimentalWarning scripts/extract-pi-system-prompt.mjs",
92
+ "pi-suite:test": "node scripts/verify-suites.mjs pi",
93
+ "opencode-suite:test": "node scripts/verify-suites.mjs opencode",
94
+ "test": "npm run pi-suite:test && npm run opencode-suite:test",
95
+ "task-watchers:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-task-watchers.mjs",
96
+ "unseen-completions:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-unseen-completions.mjs",
97
+ "stale-wait:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-stale-wait.mjs",
98
+ "status:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-status.mjs",
99
+ "compat:test": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/verify-compat.mjs"
100
+ },
101
+ "dependencies": {
102
+ "yaml": "^2.9.0"
103
+ },
104
+ "peerDependencies": {
105
+ "@earendil-works/pi-agent-core": "*",
106
+ "@earendil-works/pi-ai": "*",
107
+ "@earendil-works/pi-coding-agent": "*",
108
+ "@earendil-works/pi-tui": "*",
109
+ "typebox": "*"
110
+ },
111
+ "devDependencies": {
112
+ "@opencode/plugin": "^2.3.2"
113
+ }
114
+ }
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Tiny pi extension used by extract-pi-system-prompt.mjs.
3
+ *
4
+ * Pi exposes the fully assembled prompt at before_agent_start, immediately
5
+ * before it would make the first provider request. Keeping this as a separate
6
+ * extension also makes the extractor usable without changing pi-shepherd's
7
+ * normal runtime behavior.
8
+ */
9
+
10
+ import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
11
+ import { dirname } from 'node:path';
12
+ import { randomUUID } from 'node:crypto';
13
+
14
+ export default function captureSystemPrompt(pi) {
15
+ const target = process.env.PI_SYSTEM_PROMPT_CAPTURE_FILE;
16
+ if (!target) return;
17
+
18
+ let captured = false;
19
+ pi.on('before_agent_start', (event, ctx) => {
20
+ if (captured) return;
21
+ captured = true;
22
+
23
+ const prompt =
24
+ typeof event?.systemPrompt === 'string'
25
+ ? event.systemPrompt
26
+ : typeof ctx?.getSystemPrompt === 'function'
27
+ ? ctx.getSystemPrompt()
28
+ : '';
29
+
30
+ try {
31
+ mkdirSync(dirname(target), { recursive: true });
32
+ const temporary = `${target}.${randomUUID()}.tmp`;
33
+ writeFileSync(temporary, prompt, { encoding: 'utf8', mode: 0o600 });
34
+ renameSync(temporary, target);
35
+ } catch {
36
+ // The parent reports a useful timeout/error. Do not change the agent's
37
+ // prompt or make prompt extraction affect the actual pi run.
38
+ }
39
+
40
+ // Abort before the first provider request. shutdown is a second safety
41
+ // net for JSON-mode implementations that do not honor abort here.
42
+ ctx?.abort?.();
43
+ ctx?.shutdown?.();
44
+ });
45
+ }
@@ -0,0 +1,277 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Boot a diagnostic pi session and extract the fully assembled system prompt.
4
+ *
5
+ * The public pi extension API exposes the final prompt in before_agent_start.
6
+ * This script starts pi with a harmless diagnostic message, captures that
7
+ * prompt before the provider request, and terminates the diagnostic process.
8
+ * No model response (or API request) is needed.
9
+ *
10
+ * Usage:
11
+ * node --experimental-strip-types scripts/extract-pi-system-prompt.mjs shepherd
12
+ * node --experimental-strip-types scripts/extract-pi-system-prompt.mjs agent scout
13
+ * node --experimental-strip-types scripts/extract-pi-system-prompt.mjs agent scout --scope both --cwd /path/to/project
14
+ *
15
+ * By default only the requested pi-shepherd extension is loaded explicitly,
16
+ * which makes the result deterministic and avoids loading this extension a
17
+ * second time when the script is run from an installed pi environment.
18
+ */
19
+
20
+ import { spawn } from 'node:child_process';
21
+ import { mkdtempSync, readFileSync, rmSync, existsSync, mkdirSync } from 'node:fs';
22
+ import { tmpdir } from 'node:os';
23
+ import { dirname, resolve } from 'node:path';
24
+ import { fileURLToPath } from 'node:url';
25
+ import process from 'node:process';
26
+
27
+ // Piping a large prompt through `head` should be a normal successful use.
28
+ process.stdout.on('error', error => {
29
+ if (error.code === 'EPIPE') process.exit(0);
30
+ throw error;
31
+ });
32
+
33
+ const scriptDir = dirname(fileURLToPath(import.meta.url));
34
+ const packageDir = resolve(scriptDir, '..');
35
+ const captureExtension = resolve(scriptDir, 'capture-system-prompt.mjs');
36
+ const resolverExtension = resolve(scriptDir, 'resolve-agent.mjs');
37
+ const shepherdExtension = resolve(packageDir, 'index.ts');
38
+ const agentExtension = resolve(packageDir, 'src/extension/shepherd-done.ts');
39
+
40
+ function usage(exitCode = 2) {
41
+ console.error(`Usage:
42
+ extract-pi-system-prompt shepherd [options]
43
+ extract-pi-system-prompt agent <agent> [options]
44
+
45
+ Options:
46
+ --cwd <path> Cwd used for discovery (default: current directory)
47
+ --scope <scope> user, project, or both (agent mode; default: user)
48
+ --output <path> Write the raw prompt to this path as well as stdout
49
+ --json Print metadata and the prompt as JSON
50
+ --model <model> Override the model used by the diagnostic session
51
+ --prompt <text> Diagnostic user message (default: an internal marker)
52
+ --timeout <sec> Startup timeout (default: 20)
53
+ --pi <command> Pi executable (default: pi)
54
+ --help Show this help
55
+
56
+ The agent mode uses the discovered agent's system prompt, model, and tools.
57
+ The shepherd mode loads pi-shepherd's parent extension and captures the
58
+ parent/shepherd prompt contribution. The process is stopped immediately after
59
+ before_agent_start, before a provider request is made.
60
+ `);
61
+ process.exit(exitCode);
62
+ }
63
+
64
+ const argv = process.argv.slice(2);
65
+ if (argv.includes('--help') || argv.includes('-h')) usage(0);
66
+
67
+ const role = argv.shift();
68
+ if (role !== 'shepherd' && role !== 'agent') usage();
69
+ const agentName = role === 'agent' ? argv.shift() : undefined;
70
+ if (role === 'agent' && !agentName) usage();
71
+
72
+ let cwd = process.cwd();
73
+ let scope = 'user';
74
+ let output;
75
+ let json = false;
76
+ let model;
77
+ let diagnosticPrompt = '[pi-shepherd system-prompt diagnostic]';
78
+ let timeoutSeconds = 20;
79
+ let piCommand = 'pi';
80
+
81
+ for (let i = 0; i < argv.length; i++) {
82
+ const arg = argv[i];
83
+ if (arg === '--json') {
84
+ json = true;
85
+ continue;
86
+ }
87
+ if (['--cwd', '--scope', '--output', '--model', '--prompt', '--timeout', '--pi'].includes(arg)) {
88
+ const value = argv[++i];
89
+ if (!value) usage();
90
+ if (arg === '--cwd') cwd = value;
91
+ else if (arg === '--scope') scope = value;
92
+ else if (arg === '--output') output = value;
93
+ else if (arg === '--model') model = value;
94
+ else if (arg === '--prompt') diagnosticPrompt = value;
95
+ else if (arg === '--timeout') timeoutSeconds = Number(value);
96
+ else if (arg === '--pi') piCommand = value;
97
+ continue;
98
+ }
99
+ console.error(`Unknown option: ${arg}`);
100
+ usage();
101
+ }
102
+
103
+ if (!['user', 'project', 'both'].includes(scope)) {
104
+ console.error(`Invalid scope: ${scope}`);
105
+ usage();
106
+ }
107
+ if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
108
+ console.error('--timeout must be a positive number of seconds.');
109
+ process.exit(2);
110
+ }
111
+ cwd = resolve(cwd);
112
+ if (output) output = resolve(output);
113
+
114
+ const temporaryDir = mkdtempSync(resolve(tmpdir(), 'pi-system-prompt-'));
115
+
116
+ async function resolveAgent() {
117
+ const discoveryFile = resolve(temporaryDir, 'agent.json');
118
+ const child = spawn(
119
+ piCommand,
120
+ ['--mode', 'json', '--no-session', '--no-extensions', '--approve', '-e', resolverExtension],
121
+ {
122
+ cwd,
123
+ stdio: ['ignore', 'ignore', 'pipe'],
124
+ env: {
125
+ ...process.env,
126
+ PI_AGENT_DISCOVERY_FILE: discoveryFile,
127
+ PI_AGENT_DISCOVERY_CWD: cwd,
128
+ PI_AGENT_DISCOVERY_SCOPE: scope,
129
+ PI_AGENT_DISCOVERY_NAME: agentName,
130
+ },
131
+ }
132
+ );
133
+ let stderr = '';
134
+ child.stderr.setEncoding('utf8');
135
+ child.stderr.on('data', chunk => {
136
+ stderr += chunk;
137
+ if (stderr.length > 8_000) stderr = stderr.slice(-8_000);
138
+ });
139
+ let spawnError;
140
+ child.on('error', error => {
141
+ spawnError = error;
142
+ });
143
+ const deadline = Date.now() + timeoutSeconds * 1000;
144
+ while (!existsSync(discoveryFile) && !spawnError && Date.now() < deadline) {
145
+ await new Promise(resolvePromise => setTimeout(resolvePromise, 50));
146
+ }
147
+ if (spawnError) throw new Error(`Could not start pi for agent discovery: ${spawnError.message}`);
148
+ if (!existsSync(discoveryFile)) {
149
+ if (!child.killed && child.exitCode === null) child.kill('SIGTERM');
150
+ await new Promise(resolvePromise => {
151
+ if (child.exitCode !== null || child.signalCode !== null) resolvePromise();
152
+ else child.once('close', resolvePromise);
153
+ });
154
+ throw new Error(
155
+ `Timed out discovering agent "${agentName}" (${timeoutSeconds}s).${stderr.trim() ? `\n${stderr.trim()}` : ''}`
156
+ );
157
+ }
158
+ const result = JSON.parse(readFileSync(discoveryFile, 'utf8'));
159
+ if (!result.ok) throw new Error(result.error ?? `Agent not found: ${agentName}`);
160
+ if (!child.killed && child.exitCode === null) child.kill('SIGTERM');
161
+ return result.agent;
162
+ }
163
+
164
+ let agent;
165
+ try {
166
+ if (role === 'agent') agent = await resolveAgent();
167
+ } catch (error) {
168
+ rmSync(temporaryDir, { recursive: true, force: true });
169
+ console.error(error?.message ?? String(error));
170
+ process.exit(1);
171
+ }
172
+ const captureFile = resolve(temporaryDir, 'system-prompt.md');
173
+ const agentSystemPromptFile = agent ? resolve(temporaryDir, 'agent-system-prompt.md') : undefined;
174
+ if (agentSystemPromptFile) {
175
+ const { writeFileSync } = await import('node:fs');
176
+ writeFileSync(agentSystemPromptFile, agent.systemPrompt, { encoding: 'utf8', mode: 0o600 });
177
+ }
178
+ const extension = role === 'shepherd' ? shepherdExtension : agentExtension;
179
+ const args = [
180
+ '--mode',
181
+ 'json',
182
+ '--no-session',
183
+ '--no-extensions',
184
+ '--approve',
185
+ '-e',
186
+ extension,
187
+ '-e',
188
+ captureExtension,
189
+ ];
190
+
191
+ if (agent?.model || model) args.push('--model', model ?? agent.model);
192
+ if (agent?.omitContextFiles === true) args.push('--no-context-files');
193
+ if (agent?.tools?.length)
194
+ args.push('--tools', [...agent.tools, ...(role === 'agent' ? ['shepherd_done'] : [])].join(','));
195
+ if (agent?.omitSystemPrompt) args.push('--system-prompt', agentSystemPromptFile);
196
+ args.push(diagnosticPrompt);
197
+
198
+ const child = spawn(piCommand, args, {
199
+ cwd,
200
+ stdio: ['ignore', 'pipe', 'pipe'],
201
+ env: {
202
+ ...process.env,
203
+ PI_SYSTEM_PROMPT_CAPTURE_FILE: captureFile,
204
+ ...(agentSystemPromptFile
205
+ ? { PI_SHEPHERD_AGENT_SYSTEM_PROMPT_FILE: agentSystemPromptFile }
206
+ : {}),
207
+ ...(agent?.omitPiDocumentation ? { PI_SHEPHERD_OMIT_PI_DOCUMENTATION: '1' } : {}),
208
+ },
209
+ });
210
+ let stderr = '';
211
+ child.stderr.setEncoding('utf8');
212
+ child.stderr.on('data', chunk => {
213
+ stderr += chunk;
214
+ if (stderr.length > 8_000) stderr = stderr.slice(-8_000);
215
+ });
216
+ let spawnError;
217
+ child.on('error', error => {
218
+ spawnError = error;
219
+ });
220
+
221
+ function stopChild() {
222
+ if (!child.killed && child.exitCode === null) child.kill('SIGTERM');
223
+ }
224
+
225
+ function waitForChildClose() {
226
+ if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve();
227
+ return new Promise(resolvePromise => child.once('close', resolvePromise));
228
+ }
229
+
230
+ const deadline = Date.now() + timeoutSeconds * 1000;
231
+ while (!existsSync(captureFile) && !spawnError && Date.now() < deadline) {
232
+ await new Promise(resolvePromise => setTimeout(resolvePromise, 50));
233
+ }
234
+ if (spawnError) {
235
+ rmSync(temporaryDir, { recursive: true, force: true });
236
+ console.error(`Could not start pi: ${spawnError.message}`);
237
+ process.exit(1);
238
+ }
239
+ if (!existsSync(captureFile)) {
240
+ stopChild();
241
+ await waitForChildClose();
242
+ rmSync(temporaryDir, { recursive: true, force: true });
243
+ console.error(`Timed out waiting for pi's before_agent_start (${timeoutSeconds}s).`);
244
+ if (stderr.trim()) console.error(stderr.trim());
245
+ process.exit(1);
246
+ }
247
+
248
+ const prompt = readFileSync(captureFile, 'utf8');
249
+ if (output) {
250
+ mkdirSync(dirname(output), { recursive: true });
251
+ // The capture is already written atomically. This copy is intentionally raw
252
+ // so --output can be passed directly to pi's --system-prompt flag.
253
+ const { chmodSync, writeFileSync } = await import('node:fs');
254
+ writeFileSync(output, prompt, { encoding: 'utf8', mode: 0o600 });
255
+ chmodSync(output, 0o600);
256
+ }
257
+
258
+ stopChild();
259
+ // Do not let a slow provider request hold the diagnostic command open.
260
+ await Promise.race([
261
+ new Promise(resolvePromise => child.once('close', resolvePromise)),
262
+ new Promise(resolvePromise => setTimeout(resolvePromise, 1_000)),
263
+ ]);
264
+ if (!child.killed && child.exitCode === null) child.kill('SIGKILL');
265
+ rmSync(temporaryDir, { recursive: true, force: true });
266
+
267
+ const metadata = {
268
+ role,
269
+ agent: agent?.name,
270
+ source: agent?.source,
271
+ definition: agent?.filePath,
272
+ cwd,
273
+ scope: role === 'agent' ? scope : undefined,
274
+ promptLength: prompt.length,
275
+ };
276
+ if (json) console.log(JSON.stringify({ ...metadata, systemPrompt: prompt }, null, 2));
277
+ else process.stdout.write(prompt.endsWith('\n') ? prompt : `${prompt}\n`);
@@ -0,0 +1,74 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Classify a change set by host for release notes (T017).
4
+ *
5
+ * Usage:
6
+ * node scripts/host-impact.mjs <git-range> e.g. v0.5.1..HEAD
7
+ * node scripts/host-impact.mjs --files a,b,c synthetic/uncommitted set
8
+ *
9
+ * Print-only: the verdict informs the release notes; it never blocks a build.
10
+ */
11
+ import { execFileSync } from 'node:child_process';
12
+
13
+ const args = process.argv.slice(2);
14
+ if (args.length === 0) {
15
+ console.error('usage: node scripts/host-impact.mjs <git-range> | --files a,b,c');
16
+ process.exit(2);
17
+ }
18
+
19
+ let files;
20
+ if (args[0] === '--files') {
21
+ files = (args[1] ?? '').split(',').map(s => s.trim()).filter(Boolean);
22
+ } else {
23
+ files = execFileSync('git', ['diff', '--name-only', args.join(' ')], {
24
+ encoding: 'utf8',
25
+ })
26
+ .split('\n')
27
+ .map(s => s.trim())
28
+ .filter(Boolean);
29
+ }
30
+
31
+ const groups = { pi: [], opencode: [], shared: [], docs: [] };
32
+ for (const file of files) {
33
+ const normalized = file.replace(/\\/g, '/');
34
+ if (normalized.startsWith('src/opencode/') || normalized.includes('/src/opencode/'))
35
+ groups.opencode.push(file);
36
+ else if (
37
+ normalized === 'index.ts' ||
38
+ normalized.startsWith('src/extension/') ||
39
+ normalized.includes('/src/extension/')
40
+ )
41
+ groups.pi.push(file);
42
+ else if (
43
+ normalized.startsWith('src/') ||
44
+ normalized.includes('/src/') ||
45
+ normalized === 'package.json' ||
46
+ normalized.endsWith('/package.json')
47
+ )
48
+ groups.shared.push(file);
49
+ else groups.docs.push(file);
50
+ }
51
+
52
+ const label = {
53
+ pi: 'Pi-only files',
54
+ opencode: 'OpenCode-only files',
55
+ shared: 'Shared engine/runtime/packaging files (cross-host)',
56
+ docs: 'Docs/tests/spec files (no runtime impact)',
57
+ };
58
+ for (const key of ['pi', 'opencode', 'shared', 'docs']) {
59
+ console.log(`${label[key]}: ${groups[key].length}`);
60
+ for (const file of groups[key]) console.log(` ${file}`);
61
+ }
62
+
63
+ const codeHosts = [groups.pi.length > 0, groups.opencode.length > 0].filter(Boolean).length;
64
+ const verdict =
65
+ codeHosts === 0 && groups.shared.length === 0
66
+ ? 'docs-and-tests-only release'
67
+ : codeHosts === 0
68
+ ? 'shared-engine release — call out impact for BOTH hosts'
69
+ : codeHosts === 2 || groups.shared.length > 0
70
+ ? 'cross-host release — call out impact for BOTH hosts'
71
+ : groups.pi.length > 0
72
+ ? 'Pi-only code release — OpenCode impact must be none'
73
+ : 'OpenCode-only code release — Pi impact must be none';
74
+ console.log(`\nVerdict: ${verdict}`);
@@ -0,0 +1,43 @@
1
+ /**
2
+ * Helper extension for the standalone system-prompt diagnostic.
3
+ *
4
+ * It runs inside pi so pi's normal module resolver can load discovery.ts and
5
+ * its pi dependencies. The outer Node script intentionally does not import
6
+ * discovery.ts directly: extension packages are available to pi, but are not
7
+ * necessarily on Node's ordinary ESM resolution path when this repository is
8
+ * run from a checkout.
9
+ */
10
+
11
+ import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
12
+ import { dirname } from 'node:path';
13
+ import { randomUUID } from 'node:crypto';
14
+ import { discoverAgents } from '../src/core/discovery.ts';
15
+
16
+ export default function resolveAgent(pi) {
17
+ const target = process.env.PI_AGENT_DISCOVERY_FILE;
18
+ if (!target) return;
19
+
20
+ pi.on('session_start', (_event, ctx) => {
21
+ let result;
22
+ try {
23
+ const scope = process.env.PI_AGENT_DISCOVERY_SCOPE ?? 'user';
24
+ const cwd = process.env.PI_AGENT_DISCOVERY_CWD ?? process.cwd();
25
+ const name = process.env.PI_AGENT_DISCOVERY_NAME ?? '';
26
+ const found = discoverAgents(cwd, scope).agents.find(agent => agent.name === name);
27
+ result = found
28
+ ? { ok: true, agent: found }
29
+ : { ok: false, error: `Agent not found: ${name}` };
30
+ } catch (error) {
31
+ result = { ok: false, error: String(error?.message ?? error) };
32
+ }
33
+
34
+ try {
35
+ mkdirSync(dirname(target), { recursive: true });
36
+ const temporary = `${target}.${randomUUID()}.tmp`;
37
+ writeFileSync(temporary, JSON.stringify(result), { encoding: 'utf8', mode: 0o600 });
38
+ renameSync(temporary, target);
39
+ } finally {
40
+ ctx.shutdown();
41
+ }
42
+ });
43
+ }
@@ -0,0 +1,58 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Inspect the model-facing Shepherd tool registration used by the parent
4
+ * (shepherd) pi session.
5
+ *
6
+ * Usage:
7
+ * node --experimental-strip-types scripts/show-shepherd-orchestrator.mjs
8
+ * node --experimental-strip-types scripts/show-shepherd-orchestrator.mjs --json
9
+ *
10
+ * Note: Shepherd is registered as a tool. Its description and parameter schema
11
+ * are sent as tool metadata; they are not persisted as a normal conversation
12
+ * message. Pi adds promptSnippet and promptGuidelines to the textual system
13
+ * prompt when the tool is active.
14
+ */
15
+
16
+ import process from 'node:process';
17
+ import {
18
+ SHEPHERD_TOOL_DESCRIPTION,
19
+ SHEPHERD_TOOL_PROMPT_GUIDELINES,
20
+ SHEPHERD_TOOL_PROMPT_SNIPPET,
21
+ ShepherdParams,
22
+ } from '../src/extension/shepherd.ts';
23
+
24
+ const json = process.argv.includes('--json');
25
+ const help = process.argv.includes('--help') || process.argv.includes('-h');
26
+ if (help || process.argv.slice(2).some(arg => arg !== '--json')) {
27
+ console.log(`Usage: show-shepherd-orchestrator [--json]
28
+
29
+ Prints the exact model-facing Shepherd tool description and parameter schema.
30
+ `);
31
+ process.exit(help ? 0 : 2);
32
+ }
33
+
34
+ const registration = {
35
+ name: 'shepherd',
36
+ label: 'Shepherd (manage Herdr agents)',
37
+ description: SHEPHERD_TOOL_DESCRIPTION,
38
+ promptSnippet: SHEPHERD_TOOL_PROMPT_SNIPPET,
39
+ promptGuidelines: SHEPHERD_TOOL_PROMPT_GUIDELINES,
40
+ parameters: ShepherdParams,
41
+ };
42
+
43
+ if (json) {
44
+ console.log(JSON.stringify(registration, null, 2));
45
+ process.exit(0);
46
+ }
47
+
48
+ console.log('=== Parent/shepherd Shepherd tool ===');
49
+ console.log(`Name: ${registration.name}`);
50
+ console.log(`Label: ${registration.label}`);
51
+ console.log('\n=== Textual system-prompt contribution ===\n');
52
+ console.log(`Available tools entry: - shepherd: ${registration.promptSnippet}`);
53
+ console.log('Guidelines:');
54
+ for (const guideline of registration.promptGuidelines) console.log(`- ${guideline}`);
55
+ console.log('\n=== Tool description ===\n');
56
+ console.log(registration.description);
57
+ console.log('\n=== Tool parameter schema ===\n');
58
+ console.log(JSON.stringify(registration.parameters, null, 2));