@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
@@ -0,0 +1,794 @@
1
+ /**
2
+ * OpenCode action dispatcher (spec 013, Phase 2).
3
+ *
4
+ * Pi-owned surface for OpenCode: mirrors the `spawn` / `status` / `read` /
5
+ * `close` / `herd` / `agents` / `prune` branches of the Pi `doAction()`
6
+ * against the same shared engine (discovery, runtimes, broker, registries).
7
+ * The Pi dispatcher is not reused because it is entangled with Pi UI types;
8
+ * the lifecycle semantics are identical.
9
+ *
10
+ * Every function takes an explicit { cwd, sessionId } context (resolved
11
+ * from the OpenCode session by server.ts) and returns plain text for the
12
+ * tool result. Thrown errors carry the user-facing message.
13
+ */
14
+
15
+ import { execFile } from 'node:child_process';
16
+ import { promisify } from 'node:util';
17
+ import { loadSettings } from '../core/config.ts';
18
+ import { discoverAgents } from '../core/discovery.ts';
19
+ import { unseenCompletionLedger } from '../core/unseen-completions.ts';
20
+ import { resolveBackend, HC_SETUP_HINT, type ResolvedBackend } from '../runtimes/backend.ts';
21
+ import { detectCaller } from '../runtimes/detect.ts';
22
+ import { createHerdrRuntime } from '../runtimes/herdr/runtime.ts';
23
+ import {
24
+ createHcRuntime,
25
+ describeHcAgent,
26
+ describeHcSheepMailbox,
27
+ describeHcStatusView,
28
+ describeHcTask,
29
+ drainHcInboxForSession,
30
+ hcTaskWatcherService,
31
+ isHcTaskId,
32
+ resolveHcAgentId,
33
+ resolveHcTerminalId,
34
+ } from '../runtimes/hc/runtime.ts';
35
+ import { isHcAvailable } from '../runtimes/hc/hc.ts';
36
+ import { hcExecSync } from '../runtimes/hc/hc.ts';
37
+ import { bindSessionOwner, lifecycleRegistry } from '../runtimes/herdr/orchestration.ts';
38
+ import { ensureParentBroker, sendParentMessage, statusAgent } from '../runtimes/herdr/lifecycle.ts';
39
+ import {
40
+ HERDR_SETUP_HINT,
41
+ agentSummaries,
42
+ formatSummary,
43
+ herdrExecSync,
44
+ isHerdrAvailable,
45
+ loadCreatedPanes,
46
+ pruneStaleCreatedPanes,
47
+ } from '../runtimes/herdr/herdr.ts';
48
+ import { OPENCODE_LAUNCH_OVERRIDES } from './host.ts';
49
+ import { parentArtifactSession } from './fieldnotes.ts';
50
+ import {
51
+ agentForChildSession,
52
+ bindChildSession,
53
+ clearUnseenForWatch,
54
+ deliverToSheep,
55
+ ensureSheepBroker,
56
+ forgetSheep,
57
+ isParentSession,
58
+ kickoffSheepBind,
59
+ messageTextForSheep,
60
+ noteTaskParent,
61
+ publishSheepDone,
62
+ publishSheepMessage,
63
+ recipientOfRelayedMessage,
64
+ recordSheepSpawn,
65
+ sheepDisplay,
66
+ sheepRecord,
67
+ taskTextForSheep,
68
+ } from './bridge.ts';
69
+ import { taskWatcherService } from '../runtimes/herdr/lifecycle.ts';
70
+
71
+ const execFileAsync = promisify(execFile);
72
+
73
+ export interface OpencodeActionContext {
74
+ cwd: string;
75
+ sessionId?: string;
76
+ }
77
+
78
+ const PLACEMENTS = ['pane_right', 'pane_down', 'tab', 'workspace'] as const;
79
+ type Placement = (typeof PLACEMENTS)[number];
80
+
81
+ /** Resolve the backend for one call; throws the setup hint when unreachable. */
82
+ function backendFor(ctx: OpencodeActionContext): ResolvedBackend {
83
+ let backend: ResolvedBackend;
84
+ try {
85
+ backend = resolveBackend(loadSettings(ctx.cwd).backend, detectCaller());
86
+ } catch (error: any) {
87
+ throw new Error(`Herd unavailable: ${error?.message ?? error}`);
88
+ }
89
+ if (backend === 'hc') {
90
+ if (!isHcAvailable()) throw new Error(`Herd unavailable: backend "hc" is unreachable. ${HC_SETUP_HINT}`);
91
+ } else if (!isHerdrAvailable()) {
92
+ throw new Error(`Herd requires a running Herdr session.\n${HERDR_SETUP_HINT}`);
93
+ }
94
+ return backend;
95
+ }
96
+
97
+ /**
98
+ * Scope registries to this OpenCode session. Same-session calls are a
99
+ * no-op; a different session rotates the namespace exactly like Pi's
100
+ * session switch.
101
+ */
102
+ function bindSession(ctx: OpencodeActionContext): void {
103
+ lifecycleRegistry.beginSession(ctx.sessionId);
104
+ bindSessionOwner(ctx.sessionId);
105
+ }
106
+
107
+ function displayName(agent: string, label: string): string {
108
+ return label ? `${agent}: ${label}` : agent;
109
+ }
110
+
111
+ export async function spawnSheep(
112
+ ctx: OpencodeActionContext,
113
+ opts: { agent: string; label: string; placement?: string; cwd?: string }
114
+ ): Promise<string> {
115
+ if (opts.placement !== undefined && !(PLACEMENTS as readonly string[]).includes(opts.placement)) {
116
+ throw new Error(
117
+ `Unknown placement "${opts.placement}". Use one of: ${PLACEMENTS.join(', ')}.`
118
+ );
119
+ }
120
+ const backend = backendFor(ctx);
121
+ bindSession(ctx);
122
+ const spawnCwd = opts.cwd ?? ctx.cwd;
123
+ const placement = (opts.placement ?? undefined) as Placement | undefined;
124
+ // Resolve the parent fieldnotes session once for this spawn, on the same
125
+ // layout Pi uses. Both runtimes store it on the agent so later delegates
126
+ // reserve their notes in the shared collection.
127
+ const artifactSession = parentArtifactSession(ctx);
128
+ const fieldnoteLine = artifactSession ? `\nfieldnote: ${artifactSession.sessionRelativePath}` : '';
129
+ if (backend === 'hc') {
130
+ const runtime = createHcRuntime({
131
+ cwd: spawnCwd,
132
+ sessionId: ctx.sessionId,
133
+ artifactSession,
134
+ launch: { ...OPENCODE_LAUNCH_OVERRIDES },
135
+ });
136
+ const id = await runtime.spawn({ name: opts.agent } as any, {
137
+ cwd: spawnCwd,
138
+ label: opts.label,
139
+ placement,
140
+ });
141
+ const handle = describeHcAgent(id);
142
+ const mailbox = describeHcSheepMailbox(id);
143
+ if (!mailbox) throw new Error(`Sheep "${id}" registered without a mailbox capability.`);
144
+ recordSheepSpawn({
145
+ agentId: handle.id,
146
+ backend: 'hc',
147
+ terminalId: resolveHcTerminalId(id),
148
+ cwd: spawnCwd,
149
+ parentSessionId: ctx.sessionId ?? '',
150
+ childCapability: mailbox.childCapability,
151
+ brokerRootDir: mailbox.rootDir,
152
+ brokerSessionId: mailbox.sessionId,
153
+ brokerId: mailbox.brokerId,
154
+ parentBrokerId: mailbox.parentId,
155
+ });
156
+ return `shepherd_spawn spawned ${displayName(handle.agent, handle.label)}\nagent id: ${handle.id}${fieldnoteLine}`;
157
+ }
158
+ const runtime = createHerdrRuntime({
159
+ cwd: spawnCwd,
160
+ sessionId: ctx.sessionId,
161
+ artifactSession,
162
+ launch: { ...OPENCODE_LAUNCH_OVERRIDES },
163
+ });
164
+ const id = await runtime.spawn({ name: opts.agent } as any, {
165
+ cwd: spawnCwd,
166
+ label: opts.label,
167
+ placement,
168
+ });
169
+ const handle = lifecycleRegistry.getAgent(id).handle;
170
+ const broker = ensureParentBroker(ctx.sessionId);
171
+ const capability = lifecycleRegistry.agentChildCapability(id);
172
+ if (!capability) throw new Error(`Sheep "${id}" registered without a mailbox capability.`);
173
+ recordSheepSpawn({
174
+ agentId: handle.id,
175
+ backend: 'herdr',
176
+ paneId: handle.paneId,
177
+ cwd: spawnCwd,
178
+ parentSessionId: ctx.sessionId ?? '',
179
+ childCapability: capability,
180
+ brokerRootDir: broker.rootDir,
181
+ brokerSessionId: broker.sessionId,
182
+ brokerId: broker.brokerId,
183
+ parentBrokerId: broker.parentId,
184
+ });
185
+ return `shepherd_spawn spawned ${displayName(handle.agent, handle.label)}\nagent id: ${handle.id}${fieldnoteLine}`;
186
+ }
187
+
188
+ export async function statusSheep(
189
+ ctx: OpencodeActionContext,
190
+ opts: { id: string }
191
+ ): Promise<string> {
192
+ const backend = backendFor(ctx);
193
+ bindSession(ctx);
194
+ if (backend === 'hc') {
195
+ try {
196
+ drainHcInboxForSession(ctx.sessionId);
197
+ } catch {
198
+ /* reads stay best-effort */
199
+ }
200
+ const view = describeHcStatusView(opts.id);
201
+ const taskNote = view.task ? `; task ${view.task.id} ${view.task.state}` : '';
202
+ return `agent ${view.state}${taskNote}.\nagent id: ${view.handle.id}`;
203
+ }
204
+ const result = statusAgent(opts.id);
205
+ const taskNote = result.task ? `; task ${result.task.id} ${result.task.state}` : '';
206
+ return `agent ${result.state}${taskNote}.\nagent id: ${result.handle.id}`;
207
+ }
208
+
209
+ export async function readSheep(
210
+ ctx: OpencodeActionContext,
211
+ opts: { target: string; lines?: number; source?: string }
212
+ ): Promise<string> {
213
+ const target = opts.target?.trim();
214
+ if (!target) throw new Error('Provide an agent id, name, or pane target to read.');
215
+ const lines = opts.lines ?? 40;
216
+ const source = opts.source ?? 'recent-unwrapped';
217
+ const backend = backendFor(ctx);
218
+ bindSession(ctx);
219
+ if (backend === 'hc') {
220
+ const agentId = resolveHcAgentId(target);
221
+ if (!agentId) return `Could not read "${target}": unknown hc agent, terminal, or name.`;
222
+ try {
223
+ const runtime = createHcRuntime({ cwd: ctx.cwd, sessionId: ctx.sessionId });
224
+ const tail = await runtime.read(agentId, { lines });
225
+ return (tail as string).trim() || '(no terminal output)';
226
+ } catch (error: any) {
227
+ return `Could not read "${target}": ${error?.message ?? String(error)}`;
228
+ }
229
+ }
230
+ const created = loadCreatedPanes();
231
+ const match = created.find(p => p.paneId === target || p.name === target);
232
+ let resolved = match?.paneId ?? target;
233
+ if (!match) {
234
+ try {
235
+ resolved = lifecycleRegistry.getAgent({ id: target }).handle.paneId ?? target;
236
+ } catch {
237
+ // Keep the original target so Herdr returns the useful not-found error.
238
+ }
239
+ }
240
+ try {
241
+ const { stdout } = await execFileAsync(
242
+ 'herdr',
243
+ [
244
+ 'agent',
245
+ 'read',
246
+ resolved,
247
+ '--source',
248
+ source,
249
+ '--lines',
250
+ String(lines),
251
+ '--format',
252
+ 'text',
253
+ ],
254
+ { encoding: 'utf8' }
255
+ );
256
+ return (stdout as string).trim() || '(no terminal output)';
257
+ } catch {
258
+ // Agent detection is dropped once the pane's child exited — fall back
259
+ // to a plain terminal read so finished runs stay inspectable.
260
+ try {
261
+ const { stdout } = await execFileAsync(
262
+ 'herdr',
263
+ ['pane', 'read', resolved, '--lines', String(lines), '--format', 'text'],
264
+ { encoding: 'utf8' }
265
+ );
266
+ return (stdout as string).trim() || '(no terminal output)';
267
+ } catch {
268
+ return `Could not read "${target}": Herdr has no such agent or pane.`;
269
+ }
270
+ }
271
+ }
272
+
273
+ export async function closeSheep(
274
+ ctx: OpencodeActionContext,
275
+ opts: { id: string }
276
+ ): Promise<string> {
277
+ const backend = backendFor(ctx);
278
+ bindSession(ctx);
279
+ const runtime =
280
+ backend === 'hc'
281
+ ? createHcRuntime({ cwd: ctx.cwd, sessionId: ctx.sessionId })
282
+ : createHerdrRuntime({ cwd: ctx.cwd, sessionId: ctx.sessionId });
283
+ await runtime.close(opts.id);
284
+ forgetSheep(opts.id);
285
+ const identity =
286
+ backend === 'hc'
287
+ ? describeHcAgent(opts.id)
288
+ : (() => {
289
+ const handle = lifecycleRegistry.getAgent(opts.id).handle;
290
+ return { id: handle.id, agent: handle.agent, label: handle.label };
291
+ })();
292
+ const cleared = unseenCompletionLedger.clearForAgent(identity.id);
293
+ const clearedNote =
294
+ cleared.length > 0
295
+ ? `; cleared ${cleared.length} unseen completion(s): ${cleared.join(', ')}`
296
+ : '';
297
+ return `closed ${displayName(identity.agent, identity.label)}${clearedNote}\nagent id: ${identity.id}`;
298
+ }
299
+
300
+ export async function listAgents(
301
+ ctx: OpencodeActionContext,
302
+ opts: { agentScope?: string }
303
+ ): Promise<string> {
304
+ bindSession(ctx);
305
+ const settings = loadSettings(ctx.cwd);
306
+ const scope = (opts.agentScope ?? settings.agentScope) as 'user' | 'project' | 'both';
307
+ if (!['user', 'project', 'both'].includes(scope)) {
308
+ throw new Error(`Unknown agent scope "${opts.agentScope}". Use one of: user, project, both.`);
309
+ }
310
+ const { agents } = discoverAgents(ctx.cwd, scope, {
311
+ includeBundled: settings.includeBundledAgents,
312
+ });
313
+ if (agents.length === 0) {
314
+ return `No agent definitions found in ${scope} scope. Do not guess an agent name; add a definition or choose another scope.`;
315
+ }
316
+ const lines = agents.map(a => `${a.name} (${a.source}): ${a.description}`);
317
+ return `Available agent names (copy the name exactly; names are case-sensitive):\n${lines.join('\n')}`;
318
+ }
319
+
320
+ export async function listHerd(ctx: OpencodeActionContext): Promise<string> {
321
+ backendFor(ctx);
322
+ bindSession(ctx);
323
+ pruneStaleCreatedPanes();
324
+ const out = herdrExecSync(['agent', 'list']);
325
+ const agents = agentSummaries(out);
326
+ if (agents.length === 0) return 'No agents detected in Herdr.';
327
+ return agents.map(formatSummary).join('\n');
328
+ }
329
+
330
+ export async function pruneRegistrations(ctx: OpencodeActionContext): Promise<string> {
331
+ bindSession(ctx);
332
+ const pruned = pruneStaleCreatedPanes();
333
+ const remaining = loadCreatedPanes().length;
334
+ return pruned === 0
335
+ ? `No stale pi-shepherd panes found (${remaining} registered).`
336
+ : `Removed ${pruned} stale pane registration(s); ${remaining} remain.`;
337
+ }
338
+
339
+ function runtimeFor(
340
+ ctx: OpencodeActionContext,
341
+ backend: 'herdr' | 'hc',
342
+ artifactSession?: import('../core/artifact-sessions.ts').ArtifactSession
343
+ ) {
344
+ return backend === 'hc'
345
+ ? createHcRuntime({ cwd: ctx.cwd, sessionId: ctx.sessionId, artifactSession })
346
+ : createHerdrRuntime({ cwd: ctx.cwd, sessionId: ctx.sessionId, artifactSession });
347
+ }
348
+
349
+ function requireSheep(agentId: string): import('./bridge.ts').SheepRecord {
350
+ const record = sheepRecord(agentId);
351
+ if (!record) {
352
+ throw new Error(
353
+ `Unknown agent id "${agentId}". Lifecycle ids are scoped to this Shepherd; use the id from the latest shepherd_spawn result, not an agent name, label, or pane id.`
354
+ );
355
+ }
356
+ return record;
357
+ }
358
+
359
+ /** Owning agent of a task; throws the unknown-task error for foreign ids. */
360
+ function taskOwnerAgent(taskId: string, backend: 'herdr' | 'hc'): string {
361
+ if (backend === 'hc') {
362
+ const task = describeHcTask(taskId);
363
+ if (!task) {
364
+ throw new Error(
365
+ `Unknown task id "${taskId}". Use the id returned by shepherd_delegate, not an agent id or terminal address.`
366
+ );
367
+ }
368
+ return task.agentId;
369
+ }
370
+ try {
371
+ return lifecycleRegistry.getTask(taskId).agentId;
372
+ } catch {
373
+ throw new Error(
374
+ `Unknown task id "${taskId}". Use the id returned by shepherd_delegate, not an agent id or pane id.`
375
+ );
376
+ }
377
+ }
378
+
379
+ /** Open (unsettled) task currently owned by a sheep, if any. */
380
+ function activeTaskForSheep(agentId: string, backend: 'herdr' | 'hc'): string | undefined {
381
+ try {
382
+ if (backend === 'hc') {
383
+ const task = describeHcStatusView(agentId).task;
384
+ return task ? task.id : undefined;
385
+ }
386
+ const task = lifecycleRegistry.activeTaskForAgent({ id: agentId });
387
+ return task && !['completed', 'blocked', 'failed', 'cancelled', 'timed_out'].includes(task.state)
388
+ ? task.id
389
+ : undefined;
390
+ } catch {
391
+ return undefined;
392
+ }
393
+ }
394
+
395
+ export async function delegateSheep(
396
+ ctx: OpencodeActionContext,
397
+ opts: { target: string; task: string; timeout?: number }
398
+ ): Promise<string> {
399
+ if (!opts.task?.trim()) throw new Error('Delegated task description must not be empty.');
400
+ const backend = backendFor(ctx);
401
+ bindSession(ctx);
402
+ const record = requireSheep(opts.target);
403
+ if (record.backend !== backend) {
404
+ throw new Error(
405
+ `Agent "${opts.target}" lives on the "${record.backend}" backend; the resolved backend is "${backend}". Opaque ids never cross backends.`
406
+ );
407
+ }
408
+ const timeoutMinutes = opts.timeout ?? loadSettings(ctx.cwd).timeout;
409
+ if (!Number.isFinite(timeoutMinutes) || timeoutMinutes <= 0) {
410
+ throw new Error('Delegated task timeout must be a positive number of minutes.');
411
+ }
412
+ ensureSheepBroker(record);
413
+ // Re-resolve on delegate so a task always reserves its note in the shared
414
+ // collection, even if the agent record predates fieldnotes resolution.
415
+ const runtime = runtimeFor(ctx, backend, parentArtifactSession(ctx));
416
+ const taskId = await runtime.delegate(opts.target, opts.task, { timeoutMin: timeoutMinutes });
417
+ noteTaskParent(taskId, ctx.sessionId ?? '');
418
+ const display = sheepDisplay(opts.target);
419
+ // deliver task text via terminal input
420
+ let deliveryNote = '';
421
+ try {
422
+ await deliverToSheep(record, taskTextForSheep(opts.task, taskId));
423
+ // The first terminal input creates the child's server session lazily;
424
+ // bind it in the background for the done-nudge trigger (the delegating
425
+ // parent session itself is excluded from candidates).
426
+ kickoffSheepBind(record, ctx.sessionId);
427
+ } catch (error: any) {
428
+ deliveryNote = ` Task text delivery failed (${error?.message ?? error}); the task is open — retry the text via shepherd_message or wait for the deadline.`;
429
+ }
430
+ return `Delegated task to ${display}\ntask id: ${taskId}${deliveryNote}`;
431
+ }
432
+
433
+ function formatInlineCompletion(completion: {
434
+ taskId: string;
435
+ agentId: string;
436
+ status: string;
437
+ text?: string;
438
+ error?: string;
439
+ }): string {
440
+ const lines = [`- ${completion.taskId}: ${completion.status}`];
441
+ if (completion.text) lines.push(` ${completion.text.split('\n')[0]}`);
442
+ if (completion.error) lines.push(` error: ${completion.error}`);
443
+ return lines.join('\n');
444
+ }
445
+
446
+ export async function watchSheep(
447
+ ctx: OpencodeActionContext,
448
+ opts: { id: string | string[] }
449
+ ): Promise<string> {
450
+ const ids: string[] = Array.isArray(opts.id) ? opts.id : [opts.id];
451
+ if (ids.length === 0) throw new Error('Expected one or more task ids to watch.');
452
+ const backend = backendFor(ctx);
453
+ bindSession(ctx);
454
+ for (const id of ids) {
455
+ const known = backend === 'hc' ? isHcTaskId(id) : lifecycleRegistry.isTaskId(id);
456
+ if (!known) {
457
+ throw new Error(
458
+ `Unknown watcher target "${id}". Pass a task id from shepherd_delegate; agent ids and pane/terminal addresses are not valid watcher targets.`
459
+ );
460
+ }
461
+ }
462
+ if (new Set(ids).size !== ids.length) {
463
+ throw new Error('A watcher cannot contain duplicate task ids.');
464
+ }
465
+ if (backend === 'hc') {
466
+ try {
467
+ drainHcInboxForSession(ctx.sessionId);
468
+ } catch {
469
+ /* reads stay best-effort */
470
+ }
471
+ }
472
+ const registration =
473
+ backend === 'hc' ? hcTaskWatcherService.watch(ids) : taskWatcherService.watch(ids);
474
+ for (const id of ids) noteTaskParent(id, ctx.sessionId ?? '');
475
+ // Retrieval clear: an explicit watch pulls already-settled results, so no
476
+ // later notice may fire for them (onTaskSettled prompts exactly once per
477
+ // settlement; already-settled tasks are reported inline here instead).
478
+ clearUnseenForWatch(ids);
479
+ const summary =
480
+ registration.pending.length > 0
481
+ ? `watching ${registration.pending.length} task${registration.pending.length === 1 ? '' : 's'} asynchronously; completion arrives automatically`
482
+ : 'watch registered; all tasks were already settled';
483
+ const lines = [summary, `watcher id: ${registration.watcherId}`];
484
+ if (registration.pending.length > 0) lines.push(`pending: ${registration.pending.join(', ')}`);
485
+ for (const done of registration.completed as any[]) {
486
+ lines.push(formatInlineCompletion(done));
487
+ }
488
+ return lines.join('\n');
489
+ }
490
+
491
+ export async function messageSheep(
492
+ ctx: OpencodeActionContext,
493
+ opts: {
494
+ target: string;
495
+ message: string;
496
+ taskId?: string;
497
+ threadId?: string;
498
+ replyTo?: string;
499
+ expectsReply?: boolean;
500
+ delivery?: 'followUp' | 'steer';
501
+ }
502
+ ): Promise<string> {
503
+ if (!opts.message?.trim()) throw new Error('Message content must not be empty.');
504
+ if (opts.target === 'parent' || opts.target === 'shepherd') {
505
+ throw new Error('Cannot message the parent session from here; target must be a sheep agent id.');
506
+ }
507
+ const backend = backendFor(ctx);
508
+ bindSession(ctx);
509
+ const record = requireSheep(opts.target);
510
+ if (record.backend !== backend) {
511
+ throw new Error(
512
+ `Agent "${opts.target}" lives on the "${record.backend}" backend; the resolved backend is "${backend}". Opaque ids never cross backends.`
513
+ );
514
+ }
515
+ let messageId: string;
516
+ let targetTaskState: string | undefined;
517
+ ensureSheepBroker(record);
518
+ if (backend === 'hc') {
519
+ const runtime = runtimeFor(ctx, backend);
520
+ messageId = await runtime.message(opts.target, opts.message, {
521
+ taskId: opts.taskId,
522
+ threadId: opts.threadId,
523
+ replyTo: opts.replyTo,
524
+ expectsReply: opts.expectsReply,
525
+ delivery: opts.delivery,
526
+ });
527
+ try {
528
+ const view = describeHcStatusView(opts.target);
529
+ if (view.task && (opts.taskId === undefined || view.task.id === opts.taskId)) {
530
+ targetTaskState = view.task.state;
531
+ }
532
+ } catch {
533
+ /* display hint is best effort */
534
+ }
535
+ if (!targetTaskState && opts.expectsReply && opts.taskId) targetTaskState = 'waiting';
536
+ } else {
537
+ const result = sendParentMessage({
538
+ target: opts.target,
539
+ message: opts.message,
540
+ taskId: opts.taskId,
541
+ threadId: opts.threadId,
542
+ replyTo: opts.replyTo,
543
+ expectsReply: opts.expectsReply,
544
+ delivery: opts.delivery,
545
+ });
546
+ messageId = result.messageId;
547
+ targetTaskState = result.targetTaskState;
548
+ }
549
+ const display = sheepDisplay(opts.target);
550
+ const relayText = messageTextForSheep({
551
+ sender: 'Shepherd',
552
+ messageId,
553
+ taskId: opts.taskId,
554
+ threadId: opts.threadId,
555
+ replyTo: opts.replyTo,
556
+ content: opts.message,
557
+ });
558
+ record.receivedMessages.set(messageId, opts.taskId);
559
+ let deliveryNote = '';
560
+ try {
561
+ await deliverToSheep(record, relayText);
562
+ } catch (error: any) {
563
+ if (opts.expectsReply && opts.taskId) {
564
+ // The question never reached the sheep: release the wait it opened so
565
+ // the task does not park on an undelivered request.
566
+ try {
567
+ lifecycleRegistry.clearPendingReply(opts.taskId);
568
+ } catch {
569
+ /* best effort */
570
+ }
571
+ throw new Error(
572
+ `Message delivery to ${display} failed (${error?.message ?? error}); the tracked request was released.`
573
+ );
574
+ }
575
+ deliveryNote = ` Message delivery failed (${error?.message ?? error}); the message was not received.`;
576
+ }
577
+ return (
578
+ `Message queued to ${display}` +
579
+ (targetTaskState ? ` (task ${targetTaskState})` : '') +
580
+ `\nmessage id: ${messageId}${deliveryNote}`
581
+ );
582
+ }
583
+
584
+ /**
585
+ * Child-side message: the caller is a sheep session. The sender resolves
586
+ * through the bound session, falling back to the task owner when the
587
+ * session is not (yet) bound.
588
+ */
589
+ export async function sheepMessage(
590
+ ctx: OpencodeActionContext,
591
+ opts: {
592
+ target: string;
593
+ message: string;
594
+ taskId?: string;
595
+ threadId?: string;
596
+ replyTo?: string;
597
+ expectsReply?: boolean;
598
+ delivery?: 'followUp' | 'steer';
599
+ },
600
+ childSessionId: string
601
+ ): Promise<{ text: string; parentPrompt?: string; parentSessionId?: string }> {
602
+ if (!opts.message?.trim()) throw new Error('Message content must not be empty.');
603
+ if (isParentSession(childSessionId)) {
604
+ throw new Error(
605
+ 'shepherd_message from a parent session uses the parent form (target a sheep agent id); ' +
606
+ 'the sheep form is for delegated sheep sessions only.'
607
+ );
608
+ }
609
+ const backend = backendFor(ctx);
610
+ bindSession(ctx);
611
+ const bound = sheepRecord(agentForChildSessionSafe(childSessionId) ?? '');
612
+ let sender = bound;
613
+ let effectiveTaskId = opts.taskId;
614
+ if (!sender && opts.replyTo) {
615
+ // Peer reply from a not-yet-bound session: only the terminal that
616
+ // received the request can know its message id.
617
+ sender = recipientOfRelayedMessage(opts.replyTo);
618
+ }
619
+ if (!sender && opts.taskId) {
620
+ const owner = taskOwnerAgent(opts.taskId, backend);
621
+ sender = sheepRecord(owner);
622
+ }
623
+ if (!sender) {
624
+ throw new Error(
625
+ 'No delegated task found for this session. shepherd_message applies to a task delivered through the Shepherd; include its Task ID.'
626
+ );
627
+ }
628
+ if (!effectiveTaskId) {
629
+ effectiveTaskId = activeTaskForSheep(sender.agentId, backend);
630
+ }
631
+ // replyTo must belong to the effective task (mirrors the child-surface
632
+ // task-mismatch guard).
633
+ if (opts.replyTo) {
634
+ const knownTask = sender.receivedMessages.get(opts.replyTo);
635
+ if (knownTask !== undefined && effectiveTaskId !== undefined && knownTask !== effectiveTaskId) {
636
+ throw new Error(
637
+ `Reply ${opts.replyTo} belongs to task ${knownTask ?? 'none'}; use that task id, not ${effectiveTaskId}.`
638
+ );
639
+ }
640
+ if (knownTask === undefined && sender.receivedMessages.has(opts.replyTo)) {
641
+ // Reply to a message with no task: adopt the effective task.
642
+ }
643
+ if (effectiveTaskId === undefined) effectiveTaskId = knownTask ?? undefined;
644
+ }
645
+ bindChildSessionSafe(sender.agentId, childSessionId);
646
+ ensureSheepBroker(sender);
647
+ const isParentTarget = opts.target === 'parent' || opts.target === 'shepherd';
648
+ const targetAgentId = isParentTarget ? sender.parentBrokerId : opts.target;
649
+ if (!isParentTarget) requireSheep(opts.target);
650
+ const published = publishSheepMessage(sender, {
651
+ target: targetAgentId,
652
+ message: opts.message,
653
+ taskId: effectiveTaskId,
654
+ threadId: opts.threadId,
655
+ replyTo: opts.replyTo,
656
+ expectsReply: opts.expectsReply,
657
+ delivery: opts.delivery,
658
+ });
659
+ if (!published.mirrorDelivered && opts.expectsReply) {
660
+ return {
661
+ text: 'Shepherd message accepted; reply tracking degraded (request mirror failed).',
662
+ parentPrompt: undefined,
663
+ };
664
+ }
665
+ // Resolve the requester's wait when this answers it.
666
+ if (opts.replyTo && effectiveTaskId) {
667
+ try {
668
+ const owner = sheepRecord(taskOwnerAgent(effectiveTaskId, backend));
669
+ owner?.outstandingRequests.delete(opts.replyTo);
670
+ } catch {
671
+ /* best effort */
672
+ }
673
+ }
674
+ if (isParentTarget) {
675
+ const senderDisplay = sheepDisplay(sender.agentId);
676
+ return {
677
+ text: `Shepherd message accepted for asynchronous delivery.\nmessage id: ${published.messageId}`,
678
+ parentPrompt:
679
+ `Shepherd message from ${senderDisplay}\n` +
680
+ `message id: ${published.messageId}` +
681
+ (effectiveTaskId ? `\ntask id: ${effectiveTaskId}` : '') +
682
+ (opts.replyTo ? `\nreply to: ${opts.replyTo}` : '') +
683
+ `\n\n${opts.message}`,
684
+ parentSessionId: sender.parentSessionId || undefined,
685
+ };
686
+ }
687
+ const recipient = requireSheep(opts.target);
688
+ const relayText = messageTextForSheep({
689
+ sender: sheepDisplay(sender.agentId),
690
+ senderId: sender.agentId,
691
+ messageId: published.messageId,
692
+ taskId: effectiveTaskId,
693
+ threadId: opts.threadId,
694
+ replyTo: opts.replyTo,
695
+ content: opts.message,
696
+ });
697
+ recipient.receivedMessages.set(published.messageId, effectiveTaskId);
698
+ let deliveryNote = '';
699
+ try {
700
+ await deliverToSheep(recipient, relayText);
701
+ } catch (error: any) {
702
+ deliveryNote = ` (delivery to the peer failed: ${error?.message ?? error})`;
703
+ }
704
+ return {
705
+ text:
706
+ `Shepherd message accepted for asynchronous delivery.\nmessage id: ${published.messageId}` +
707
+ deliveryNote,
708
+ parentPrompt: undefined,
709
+ };
710
+ }
711
+
712
+ /**
713
+ * Child-side completion: only the sheep session bound to the task's owner
714
+ * may complete it. Mirrors the one-shot correction rule: a misremembered id
715
+ * is corrected to the sheep's own open task, never to another agent's.
716
+ */
717
+ export async function sheepDone(
718
+ ctx: OpencodeActionContext,
719
+ opts: { taskId?: string; status: string; summary?: string },
720
+ childSessionId: string
721
+ ): Promise<{ text: string }> {
722
+ if (isParentSession(childSessionId)) {
723
+ throw new Error(
724
+ 'shepherd_done is a sheep-only tool: only the delegated sheep session may complete its task.'
725
+ );
726
+ }
727
+ if (!['completed', 'blocked', 'failed'].includes(opts.status)) {
728
+ throw new Error(
729
+ `Invalid status "${opts.status}"; use completed, blocked, or failed.`
730
+ );
731
+ }
732
+ const backend = backendFor(ctx);
733
+ bindSession(ctx);
734
+ const boundAgentId = agentForChildSessionSafe(childSessionId);
735
+ const bound = boundAgentId ? sheepRecord(boundAgentId) : undefined;
736
+ const ownOpenTask = bound ? activeTaskForSheep(bound.agentId, backend) : undefined;
737
+ let effectiveTaskId = opts.taskId;
738
+ if (effectiveTaskId === undefined) effectiveTaskId = ownOpenTask;
739
+ if (effectiveTaskId === undefined) {
740
+ throw new Error(
741
+ 'No delegated task found for this session. shepherd_done only applies to a task delivered through the Shepherd; include its Task ID.'
742
+ );
743
+ }
744
+ const ownerAgentId = taskOwnerAgent(effectiveTaskId, backend);
745
+ const owner = requireSheep(ownerAgentId);
746
+ if (bound && bound.agentId !== ownerAgentId) {
747
+ throw new Error(
748
+ `Task "${effectiveTaskId}" is not owned by this sheep session. Complete only your own delegated task.`
749
+ );
750
+ }
751
+ if (!bound && opts.taskId === undefined) {
752
+ throw new Error(
753
+ 'This session is not recognized as a sheep session; include the Task ID from the delegated task text.'
754
+ );
755
+ }
756
+ bindChildSessionSafe(ownerAgentId, childSessionId);
757
+ ensureSheepBroker(owner);
758
+ publishSheepDone(owner, {
759
+ taskId: effectiveTaskId,
760
+ status: opts.status as 'completed' | 'blocked' | 'failed',
761
+ summary: opts.summary,
762
+ });
763
+ // A completed status with outstanding required replies is not applied by
764
+ // the registry (the reply or an explicit blocked/failed result must land
765
+ // first). Surface that instead of claiming success.
766
+ const stillOpen = activeTaskForSheep(ownerAgentId, backend) === effectiveTaskId;
767
+ if (opts.status === 'completed' && stillOpen) {
768
+ return {
769
+ text:
770
+ `Shepherd task completion NOT recorded: task ${effectiveTaskId} still has an outstanding required reply. ` +
771
+ 'Answer it first, or report blocked/failed with the reason.',
772
+ };
773
+ }
774
+ const display = sheepDisplay(ownerAgentId);
775
+ return {
776
+ text: `Shepherd task completion accepted for ${display}.\ntask id: ${effectiveTaskId}\nstatus: ${opts.status}`,
777
+ };
778
+ }
779
+
780
+ function agentForChildSessionSafe(childSessionId: string): string | undefined {
781
+ try {
782
+ return agentForChildSession(childSessionId);
783
+ } catch {
784
+ return undefined;
785
+ }
786
+ }
787
+
788
+ function bindChildSessionSafe(agentId: string, childSessionId: string): void {
789
+ try {
790
+ bindChildSession(agentId, childSessionId);
791
+ } catch {
792
+ /* binding is best effort */
793
+ }
794
+ }