@howaboua/pi-shepherdr 0.2.27 → 0.2.28-core.12.1.gda85fa2e8a0f

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 (112) hide show
  1. package/README.md +48 -48
  2. package/index.ts +7 -1
  3. package/package.json +2 -9
  4. package/src/agent-identity.ts +3 -3
  5. package/src/agents-contract.ts +10 -14
  6. package/src/agents-discovery.ts +34 -54
  7. package/src/agents-focus.ts +23 -35
  8. package/src/agents-spawn.ts +24 -23
  9. package/src/agents-tool.ts +4 -19
  10. package/src/agents-work.ts +4 -3
  11. package/src/attachment-notes.ts +8 -7
  12. package/src/attachment-protocol.ts +3 -2
  13. package/src/attachment-routing.ts +1 -1
  14. package/src/attachment-target.ts +10 -18
  15. package/src/attachment.ts +14 -9
  16. package/src/board/discovery.ts +67 -0
  17. package/src/board/host.ts +93 -63
  18. package/src/board/membership.ts +16 -11
  19. package/src/board/records.ts +185 -0
  20. package/src/close-idle.ts +2 -9
  21. package/src/context-briefing.ts +230 -0
  22. package/src/context-routing.ts +1 -1
  23. package/src/control-panel/index.ts +2 -4
  24. package/src/control-panel/items.ts +1 -11
  25. package/src/control-panel/view.ts +3 -9
  26. package/src/controller.ts +50 -63
  27. package/src/core/AGENTS.md +7 -4
  28. package/src/core/admission-broker.mjs +235 -0
  29. package/src/core/admission-endpoint.ts +180 -0
  30. package/src/core/admission-owner.mjs +52 -0
  31. package/src/core/admission-startup.ts +130 -0
  32. package/src/core/admission.ts +181 -0
  33. package/src/core/agents.ts +102 -0
  34. package/src/core/backend.ts +110 -84
  35. package/src/core/client.ts +16 -0
  36. package/src/core/focus-channel-helper.mjs +6 -27
  37. package/src/core/focus-channel-wire.mjs +9 -6
  38. package/src/core/focus-channel.ts +5 -3
  39. package/src/core/focus-window.ts +15 -4
  40. package/src/core/helper-bootstrap.mjs +70 -0
  41. package/src/core/helper-context.mjs +98 -0
  42. package/src/core/helper-core.mjs +121 -0
  43. package/src/core/machines.ts +30 -0
  44. package/src/core/registration.ts +7 -2
  45. package/src/core/remote-endpoint.ts +80 -74
  46. package/src/core/remote-helper.ts +330 -0
  47. package/src/core/remote-reader.ts +3 -42
  48. package/src/core/remote-service.mjs +239 -0
  49. package/src/core/remote-transport.ts +290 -0
  50. package/src/core/spawn.ts +20 -20
  51. package/src/core/terminal-peer.mjs +57 -0
  52. package/src/core/terminal.ts +4 -2
  53. package/src/delivery.ts +39 -0
  54. package/src/fleet/catalog.ts +16 -58
  55. package/src/fleet/connection.ts +9 -18
  56. package/src/fleet/index.ts +38 -76
  57. package/src/fleet/inspection.ts +9 -22
  58. package/src/fleet/machine.ts +28 -12
  59. package/src/fleet/monitor.ts +8 -29
  60. package/src/fleet/persistence.ts +2 -2
  61. package/src/fleet/reconnect.ts +5 -3
  62. package/src/fleet/setup.ts +6 -16
  63. package/src/launch-contract.ts +0 -3
  64. package/src/launch-location.ts +4 -132
  65. package/src/launch.ts +18 -144
  66. package/src/messages/attachments.ts +1 -1
  67. package/src/messages/attribution.ts +9 -14
  68. package/src/messages/events.ts +5 -9
  69. package/src/messages/focus.ts +2 -7
  70. package/src/messages/guidance.ts +2 -43
  71. package/src/messages/peer-sharing.ts +133 -0
  72. package/src/monitor-events.ts +14 -43
  73. package/src/monitor-extension-messages.ts +5 -6
  74. package/src/monitor-record.ts +4 -0
  75. package/src/monitor-state.ts +1 -101
  76. package/src/monitor.ts +38 -66
  77. package/src/notes-discovery.ts +67 -0
  78. package/src/peer-inbox.ts +21 -27
  79. package/src/remote/context-relay.ts +25 -10
  80. package/src/remote/notes-reader.mjs +67 -0
  81. package/src/remote/shepherdr-channel.mjs +1 -1
  82. package/src/remote/shepherdr-checkpoints.mjs +49 -102
  83. package/src/remote/shepherdr-context.mjs +1 -1
  84. package/src/remote/shepherdr-peer.mjs +19 -24
  85. package/src/remote/shepherdr-session.mjs +18 -7
  86. package/src/saved-context.ts +62 -0
  87. package/src/settlement/collector.ts +29 -9
  88. package/src/settlement/index.ts +35 -6
  89. package/src/shared-context-host.ts +27 -33
  90. package/src/shared-context.ts +44 -15
  91. package/src/spawn-context.ts +11 -3
  92. package/src/spawn-ownership.ts +1 -1
  93. package/src/ssh-setup.ts +40 -73
  94. package/src/types.ts +4 -8
  95. package/src/voice-handoff.ts +1 -1
  96. package/src/widget.ts +7 -2
  97. package/src/worker-ownership.ts +2 -8
  98. package/src/worker-service.ts +6 -14
  99. package/src/core/context-relay.mjs +0 -111
  100. package/src/core/remote-exec.ts +0 -122
  101. package/src/core/remote-helper.mjs +0 -244
  102. package/src/core/remote-relay.ts +0 -191
  103. package/src/core/request.ts +0 -124
  104. package/src/herdr-client.ts +0 -364
  105. package/src/herdr.ts +0 -268
  106. package/src/machine-catalog.ts +0 -83
  107. package/src/monitor-event.ts +0 -84
  108. package/src/remote/client.ts +0 -127
  109. package/src/remote/deployment.ts +0 -179
  110. package/src/remote/focus-channels.ts +0 -89
  111. package/src/remote/shepherdr.mjs +0 -504
  112. package/src/remote/transport.ts +0 -369
@@ -17,9 +17,7 @@ import {
17
17
  toolResult,
18
18
  } from "./agents-work.js";
19
19
  import type { AgentBoard } from "./board/host.js";
20
- import { CoreConnection } from "./core/backend.js";
21
20
  import type { AgentFleet, ConnectedMachine } from "./fleet/index.js";
22
- import { isDispatchRejected } from "./herdr-client.js";
23
21
  import {
24
22
  resolvePreparationDirectory,
25
23
  rollbackStartedAgent,
@@ -31,6 +29,7 @@ import {
31
29
  prepareProfileMessage,
32
30
  profileAgentArgs,
33
31
  } from "./profiles.js";
32
+ import { isDispatchRejected } from "./remote/shepherdr-peer.mjs";
34
33
  import type { SharedAgentContext } from "./shared-context.js";
35
34
  import { prepareSpawnOwnership } from "./spawn-ownership.js";
36
35
 
@@ -74,28 +73,16 @@ export async function spawnAgent(
74
73
  const reservation = await reserveAgentName(runtime, label, params.name);
75
74
  const { name } = reservation;
76
75
  try {
77
- const placement =
78
- params.placement ??
79
- (runtime.client instanceof CoreConnection
80
- ? "terminal"
81
- : runtime.local && process.env["HERDR_WORKSPACE_ID"]
82
- ? "new_tab"
83
- : "new_workspace");
84
- const workspace =
85
- params.workspace ??
86
- (placement === "new_tab" && runtime.local
87
- ? process.env["HERDR_WORKSPACE_ID"]
88
- : undefined);
76
+ const placement = params.placement ?? "terminal";
77
+ const workspace = params.workspace;
89
78
  const startParams = {
90
79
  name,
91
80
  label,
92
81
  placement,
93
82
  ...(workspace ? { workspace } : {}),
94
- ...(params.pane ? { pane: params.pane } : {}),
95
83
  ...(params.cwd ? { cwd: params.cwd } : {}),
96
84
  };
97
85
  const cwd = await resolvePreparationDirectory(
98
- runtime.client,
99
86
  startParams,
100
87
  runtime.fallbackCwd,
101
88
  runtime.resolveDirectory,
@@ -122,7 +109,7 @@ export async function spawnAgent(
122
109
  if (boardThreadId !== undefined)
123
110
  attributedMessage.context = [
124
111
  attributedMessage.context,
125
- `Read shared board thread with board({action:"read_thread",thread_id:${JSON.stringify(boardThreadId)}}) for task context`,
112
+ `Read shared board thread with board({action:"read_thread",thread_id:${JSON.stringify(boardThreadId)}}) for task context. To follow ongoing peer findings, subscribe to that thread for replies.`,
126
113
  ]
127
114
  .filter(Boolean)
128
115
  .join("\n\n");
@@ -143,18 +130,22 @@ export async function spawnAgent(
143
130
  ? undefined
144
131
  : await sharedContext.spawns.prepare(ctx, runtime, agentArgs);
145
132
  const boardBinding = await board.prepare(ctx, runtime, name, agentArgs);
133
+ if (boardThreadId !== undefined && !boardBinding)
134
+ throw new Error(
135
+ "Board thread context requires shared Board to be enabled before spawning",
136
+ );
146
137
  const started = await startAgent(
147
138
  runtime.client,
148
139
  startParams,
149
140
  runtime.fallbackCwd,
150
141
  runtime.resolveDirectory,
151
- { agentArgs },
142
+ { agentArgs, signal },
152
143
  );
153
144
  let promptSubmissionStarted = false;
154
145
  let promptAccepted = false;
155
146
  let dispatch;
156
147
  let shared: { agentName?: string; warning?: string } | undefined;
157
- let boardAgent: string | undefined;
148
+ let boardShared: { agentName?: string; warning?: string } | undefined;
158
149
  let agentName: string | undefined;
159
150
  let relationshipWarning: string | undefined;
160
151
  const blocking = shouldBlockAgentSpawn(profile.blocking, params.blocking);
@@ -163,8 +154,13 @@ export async function spawnAgent(
163
154
  await recordSpawn(started.agent, agentArgs);
164
155
  relationshipWarning = (await relationship?.accept(started.agent))
165
156
  ?.warning;
166
- boardAgent = await boardBinding?.accept(started.agent);
157
+ boardShared = await boardBinding?.accept(started.agent);
158
+ if (boardThreadId !== undefined && !boardShared?.agentName)
159
+ throw new Error(
160
+ "Worker cannot read the requested Board thread: the target needs Agent Board or Agent Comms. Load it and reload Pi before retrying",
161
+ );
167
162
  shared = await sharing?.accept(started.agent);
163
+ attributedMessage.context += `\n${await sharedContext.peerReplyContext(ctx, runtime, started.agent, signal)}`;
168
164
  dispatch = await dispatchAgentWork(
169
165
  runtime,
170
166
  started.agent,
@@ -216,16 +212,21 @@ export async function spawnAgent(
216
212
  next: "Do other work or end this turn; completion/blockage arrives automatically. Do not poll or await timers/extra Promises for reports",
217
213
  }),
218
214
  agent: agentName,
219
- ...(boardAgent || shared?.agentName
215
+ ...(boardBinding || sharing
220
216
  ? {
221
217
  sharing: {
222
- board: !!boardAgent,
218
+ board: !!boardShared?.agentName,
223
219
  context: !!shared?.agentName,
224
220
  },
225
221
  }
226
222
  : {}),
227
223
  },
228
- [dispatch.warning, shared?.warning, relationshipWarning]
224
+ [
225
+ dispatch.warning,
226
+ boardShared?.warning,
227
+ shared?.warning,
228
+ relationshipWarning,
229
+ ]
229
230
  .filter(Boolean)
230
231
  .join("\n") || undefined,
231
232
  );
@@ -27,9 +27,8 @@ import {
27
27
  toolResult,
28
28
  } from "./agents-work.js";
29
29
  import type { AgentBoard } from "./board/host.js";
30
- import { CoreConnection } from "./core/backend.js";
30
+ import { resolvePiAgent } from "./core/agents.js";
31
31
  import type { AgentFleet } from "./fleet/index.js";
32
- import { resolvePiAgent } from "./herdr.js";
33
32
  import { attributeAgentPrompt } from "./messages/attribution.js";
34
33
  import type { createPeerCommands } from "./peer-commands.js";
35
34
  import type { SharedAgentContext } from "./shared-context.js";
@@ -58,16 +57,7 @@ export function createAgentsTool(
58
57
  const executionSignal = signal ?? new AbortController().signal;
59
58
  const update = onUpdate ?? (() => undefined);
60
59
  if (params.action === "help" && !params.commands) {
61
- return toolResult(
62
- await agentsHelp(
63
- board.enabled(ctx),
64
- gpt(),
65
- Boolean(
66
- process.env["HC_TERMINAL_ID"] &&
67
- process.env["HC_TERMINAL_SOCKET"],
68
- ),
69
- ),
70
- );
60
+ return toolResult(await agentsHelp(board.enabled(ctx), gpt()));
71
61
  }
72
62
  if (params.commands && params.target === undefined)
73
63
  return toolResult({ commands: commands.available() });
@@ -148,13 +138,7 @@ export function createAgentsTool(
148
138
  const panel = await resolvePiAgent(
149
139
  runtime.client,
150
140
  target,
151
- runtime.local
152
- ? process.env[
153
- runtime.client instanceof CoreConnection
154
- ? "HC_TERMINAL_ID"
155
- : "HERDR_PANE_ID"
156
- ]
157
- : "",
141
+ runtime.local ? process.env["HC_TERMINAL_ID"] : "",
158
142
  );
159
143
  if (params.commands) {
160
144
  return toolResult({
@@ -210,6 +194,7 @@ export function createAgentsTool(
210
194
  message,
211
195
  params.action === "send" ? "message" : "task",
212
196
  );
197
+ attributedMessage.context += `\n${await sharedContext.peerReplyContext(ctx, runtime, panel, executionSignal)}`;
213
198
  if (params.action === "send") {
214
199
  executionSignal.throwIfAborted();
215
200
  const receipt = await runtime.client.sendMessage(
@@ -1,10 +1,11 @@
1
1
  import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
2
2
  import { activityTask } from "./activity.js";
3
+ import { getSnapshot } from "./core/agents.js";
4
+ import type { CoreConnection } from "./core/backend.js";
3
5
  import type { ConnectedMachine } from "./fleet/index.js";
4
- import { getSnapshot } from "./herdr.js";
5
- import { type HerdrConnection, isDispatchRejected } from "./herdr-client.js";
6
6
  import { agentSource } from "./messages/attribution.js";
7
7
  import type { WorkAttempt } from "./monitor-state.js";
8
+ import { isDispatchRejected } from "./remote/shepherdr-peer.mjs";
8
9
  import type { ClaimedSettlement } from "./settlement/index.js";
9
10
  import type { ExtensionReply, PaneInfo, PeerDelivery } from "./types.js";
10
11
 
@@ -38,7 +39,7 @@ function slugify(value: string): string {
38
39
  return named.slice(0, 32).replace(/-+$/u, "") || "agent";
39
40
  }
40
41
 
41
- const startingNames = new WeakMap<HerdrConnection, Set<string>>();
42
+ const startingNames = new WeakMap<CoreConnection, Set<string>>();
42
43
 
43
44
  export async function reserveAgentName(
44
45
  runtime: ConnectedMachine,
@@ -4,9 +4,10 @@ import type {
4
4
  ContextSharingService,
5
5
  SharedContextRequest,
6
6
  SharedContextResult,
7
- } from "@howaboua/pi-notes-compaction/context-sharing";
7
+ } from "@howaboua/pi-agent-comms/context-sharing";
8
+ import { NOTES_UNAVAILABLE } from "./notes-discovery.js";
8
9
 
9
- /** Read-only continuity when a live owner disappears. Parsing remains Conversion-owned. */
10
+ /** Read-only continuity when a live owner disappears. Notes owns parsing. */
10
11
  export class AttachmentNotes {
11
12
  private readonly getService: () => ContextSharingService | undefined;
12
13
  constructor(getService: () => ContextSharingService | undefined) {
@@ -19,7 +20,7 @@ export class AttachmentNotes {
19
20
  !service.parseAttachmentNotes ||
20
21
  !service.readAttachmentNotes
21
22
  )
22
- throw new Error("Update Codex Conversion to retain attached checkpoints");
23
+ throw new Error(NOTES_UNAVAILABLE);
23
24
  return {
24
25
  export: service.exportAttachmentNotes,
25
26
  parse: service.parseAttachmentNotes,
@@ -177,10 +178,10 @@ export class AttachmentNotes {
177
178
  warning,
178
179
  });
179
180
  if (
180
- !result.structuredContent ||
181
- typeof result.structuredContent !== "object" ||
182
- !("warning" in result.structuredContent) ||
183
- result.structuredContent["warning"] !== warning
181
+ !result.details.codexHistoryNotes ||
182
+ typeof result.details.codexHistoryNotes !== "object" ||
183
+ !("warning" in result.details.codexHistoryNotes) ||
184
+ result.details.codexHistoryNotes["warning"] !== warning
184
185
  )
185
186
  throw new Error("Update Notes to read retained attached checkpoints");
186
187
  return {
@@ -1,9 +1,9 @@
1
1
  import { isDeepStrictEqual } from "node:util";
2
2
  import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
3
- import { BindingSchema } from "@howaboua/pi-agent-board/integration";
4
- import type { SharedContextResult } from "@howaboua/pi-notes-compaction/context-sharing";
3
+ import type { SharedContextResult } from "@howaboua/pi-agent-comms/context-sharing";
5
4
  import { type Static, type TSchema, Type } from "typebox";
6
5
  import { Check } from "typebox/value";
6
+ import { BindingSchema } from "./board/records.js";
7
7
 
8
8
  const AgentPath = Type.String({
9
9
  pattern: "^/(?:[a-zA-Z0-9_.-]+|root(?:/[a-zA-Z0-9_-]+)*)$",
@@ -38,6 +38,7 @@ const ContextLink = Type.Object({
38
38
  alias: AgentPath,
39
39
  controllerAlias: AgentPath,
40
40
  controllerFile: Type.Optional(Type.String()),
41
+ controllerMachine: Type.Optional(Type.String({ minLength: 1 })),
41
42
  controllerNotes: Type.Unknown(),
42
43
  targetNotes: Type.Unknown(),
43
44
  });
@@ -4,7 +4,7 @@ import type {
4
4
  ContextSharingService,
5
5
  SharedContextRequest,
6
6
  SharedContextResult,
7
- } from "@howaboua/pi-notes-compaction/context-sharing";
7
+ } from "@howaboua/pi-agent-comms/context-sharing";
8
8
  import type { AttachmentNotes } from "./attachment-notes.js";
9
9
  import {
10
10
  type AttachmentRoute,
@@ -3,12 +3,7 @@ import type {
3
3
  ExtensionAPI,
4
4
  ExtensionContext,
5
5
  } from "@earendil-works/pi-coding-agent";
6
- import {
7
- type BoardBinding,
8
- binding,
9
- canonicalBoardBinding,
10
- } from "@howaboua/pi-agent-board/integration";
11
- import type { ContextSharingService } from "@howaboua/pi-notes-compaction/context-sharing";
6
+ import type { ContextSharingService } from "@howaboua/pi-agent-comms/context-sharing";
12
7
  import type { Static } from "typebox";
13
8
  import { Check } from "typebox/value";
14
9
  import { AttachmentNotes } from "./attachment-notes.js";
@@ -25,11 +20,13 @@ import {
25
20
  Plan,
26
21
  } from "./attachment-protocol.js";
27
22
  import type { AgentBoard } from "./board/host.js";
23
+ import { type BoardBinding, canonicalBoardBinding } from "./board/records.js";
28
24
  import { sendPolicyMessage } from "./delivery.js";
29
25
  import {
30
26
  attachmentMessage,
31
27
  detachmentMessage,
32
28
  } from "./messages/attachments.js";
29
+ import { NOTES_UNAVAILABLE } from "./notes-discovery.js";
33
30
 
34
31
  function sameBoard(left: BoardBinding, right: BoardBinding) {
35
32
  const { legacyAgentName: _left, ...a } = canonicalBoardBinding(left);
@@ -57,7 +54,7 @@ export class AttachmentTarget {
57
54
  async context(ctx: ExtensionContext, target: boolean) {
58
55
  const service = this.getService();
59
56
  if (!service?.inspectAttachment || !service.retainAttachmentIdentity)
60
- throw new Error("Update Codex Conversion to attach existing context");
57
+ throw new Error(NOTES_UNAVAILABLE);
61
58
  const identity = await service.inspectAttachment(ctx, target);
62
59
  if (!identity || !Check(Identity, identity))
63
60
  throw new Error(
@@ -67,10 +64,7 @@ export class AttachmentTarget {
67
64
  }
68
65
  retainIdentity(ctx: ExtensionContext) {
69
66
  const service = this.getService();
70
- if (!service?.retainAttachmentIdentity)
71
- throw new Error(
72
- "Context attachment support became unavailable; reload and retry",
73
- );
67
+ if (!service?.retainAttachmentIdentity) throw new Error(NOTES_UNAVAILABLE);
74
68
  return service.retainAttachmentIdentity(ctx);
75
69
  }
76
70
  private async inspect(ctx: ExtensionContext) {
@@ -106,7 +100,7 @@ export class AttachmentTarget {
106
100
  }
107
101
  return {
108
102
  sessionId: ctx.sessionManager.getSessionId(),
109
- board: binding(ctx),
103
+ board: this.board.binding(ctx),
110
104
  ...(context ? { context, notes: await this.notes.export(ctx) } : {}),
111
105
  ...(contextError ? { contextError } : {}),
112
106
  ...(boardError ? { boardError } : {}),
@@ -229,7 +223,8 @@ export class AttachmentTarget {
229
223
  identity,
230
224
  canonicalContextIdentity(plan.context.target),
231
225
  ) ||
232
- (plan.board && !sameBoard(binding(ctx), plan.board.previous))
226
+ (plan.board &&
227
+ !sameBoard(this.board.binding(ctx), plan.board.previous))
233
228
  )
234
229
  throw new Error(
235
230
  "Target changed during attachment authentication; retry after it settles",
@@ -267,12 +262,10 @@ export class AttachmentTarget {
267
262
  canonicalContextIdentity(plan.context.target),
268
263
  )
269
264
  )
270
- throw new Error(
271
- "Shared notes are unavailable. Use messages to exchange the context you need.",
272
- );
265
+ throw new Error(NOTES_UNAVAILABLE);
273
266
  if (
274
267
  plan.board &&
275
- !sameBoard(binding(ctx), {
268
+ !sameBoard(this.board.binding(ctx), {
276
269
  ...plan.board.desired,
277
270
  sessionId: plan.targetSessionId,
278
271
  parentSessionId: plan.controllerSessionId,
@@ -317,7 +310,6 @@ export class AttachmentTarget {
317
310
  )
318
311
  )
319
312
  throw new Error("Target context changed before detach");
320
- this.notes.validate(requested.context, plan.context.controller);
321
313
  await this.notes.verify(
322
314
  ctx,
323
315
  requested.context,
package/src/attachment.ts CHANGED
@@ -3,8 +3,7 @@ import type {
3
3
  ExtensionAPI,
4
4
  ExtensionContext,
5
5
  } from "@earendil-works/pi-coding-agent";
6
- import { binding } from "@howaboua/pi-agent-board/integration";
7
- import type { ContextSharingService } from "@howaboua/pi-notes-compaction/context-sharing";
6
+ import type { ContextSharingService } from "@howaboua/pi-agent-comms/context-sharing";
8
7
  import type { Static } from "typebox";
9
8
  import { Check } from "typebox/value";
10
9
  import type { AgentsParams } from "./agents-contract.js";
@@ -20,8 +19,8 @@ import {
20
19
  import { AttachmentRouting } from "./attachment-routing.js";
21
20
  import { AttachmentTarget } from "./attachment-target.js";
22
21
  import type { AgentBoard } from "./board/host.js";
22
+ import { sessionPath } from "./core/agents.js";
23
23
  import type { ConnectedMachine } from "./fleet/index.js";
24
- import { sessionPath } from "./herdr.js";
25
24
  import { sessionContextPath } from "./remote/shepherdr-context.mjs";
26
25
  import type { PaneInfo } from "./types.js";
27
26
 
@@ -30,16 +29,19 @@ export class AgentAttachment {
30
29
  private readonly pi: ExtensionAPI;
31
30
  private readonly board: AgentBoard;
32
31
  private readonly notes: AttachmentNotes;
32
+ private readonly localMachine: () => string;
33
33
  readonly target: AttachmentTarget;
34
34
  readonly routing: AttachmentRouting;
35
35
  constructor(
36
36
  pi: ExtensionAPI,
37
37
  board: AgentBoard,
38
38
  getService: () => ContextSharingService | undefined,
39
+ localMachine: () => string,
39
40
  ) {
40
41
  this.pi = pi;
41
42
  this.board = board;
42
43
  this.notes = new AttachmentNotes(getService);
44
+ this.localMachine = localMachine;
43
45
  this.target = new AttachmentTarget(pi, board, getService, this.notes);
44
46
  this.routing = new AttachmentRouting(getService, this.notes);
45
47
  }
@@ -67,7 +69,7 @@ export class AgentAttachment {
67
69
  const controllerContext = context
68
70
  ? await this.target.context(ctx, false)
69
71
  : undefined;
70
- const controllerBoard = useBoard ? binding(ctx) : undefined;
72
+ const controllerBoard = useBoard ? this.board.binding(ctx) : undefined;
71
73
  const check = async () => {
72
74
  const currentContext = controllerContext
73
75
  ? await this.target.context(ctx, false)
@@ -77,7 +79,8 @@ export class AgentAttachment {
77
79
  ctx.sessionManager.getSessionId() !== controllerSessionId ||
78
80
  (controllerContext &&
79
81
  !isDeepStrictEqual(currentContext, controllerContext)) ||
80
- (controllerBoard && !isDeepStrictEqual(binding(ctx), controllerBoard))
82
+ (controllerBoard &&
83
+ !isDeepStrictEqual(this.board.binding(ctx), controllerBoard))
81
84
  )
82
85
  throw new Error(
83
86
  "Controller changed during attachment; resume the original session and retry",
@@ -134,7 +137,8 @@ export class AgentAttachment {
134
137
  target: current.context,
135
138
  alias: `/${current.sessionId}`,
136
139
  controllerAlias: `/${controllerSessionId}`,
137
- ...(runtime.local ? { controllerFile } : {}),
140
+ controllerFile,
141
+ controllerMachine: this.localMachine(),
138
142
  controllerNotes: await this.notes.export(ctx),
139
143
  targetNotes: current.notes,
140
144
  },
@@ -149,7 +153,7 @@ export class AgentAttachment {
149
153
  upstream,
150
154
  current.sessionId,
151
155
  ),
152
- controller: binding(ctx),
156
+ controller: this.board.binding(ctx),
153
157
  },
154
158
  }
155
159
  : {}),
@@ -219,7 +223,7 @@ export class AgentAttachment {
219
223
  const { plan } = route;
220
224
  if ((params.context && !plan.context) || (params.board && !plan.board))
221
225
  throw new Error("Cannot detach a choice that was not attached");
222
- const controllerBoard = params.board ? binding(ctx) : undefined;
226
+ const controllerBoard = params.board ? this.board.binding(ctx) : undefined;
223
227
  const check = async (checkRoute = true) => {
224
228
  const currentContext =
225
229
  params.context && plan.context
@@ -243,7 +247,8 @@ export class AgentAttachment {
243
247
  currentContext,
244
248
  canonicalContextIdentity(plan.context.controller),
245
249
  )) ||
246
- (controllerBoard && !isDeepStrictEqual(binding(ctx), controllerBoard))
250
+ (controllerBoard &&
251
+ !isDeepStrictEqual(this.board.binding(ctx), controllerBoard))
247
252
  )
248
253
  throw new Error(
249
254
  "Controller changed during detach; resume it and retry",
@@ -0,0 +1,67 @@
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+ import type { BoardRuntime } from "@howaboua/pi-agent-comms/runtime";
3
+
4
+ const CLAIM = "@howaboua/pi-agent-board.owner/v1";
5
+ const AVAILABLE = "@howaboua/pi-agent-board.available/v1";
6
+
7
+ /** The existing owner protocol works across package locations and either load order. */
8
+ export function discoverBoard(
9
+ pi: ExtensionAPI,
10
+ attach: (runtime: BoardRuntime) => void,
11
+ failed: (error: Error) => void,
12
+ ) {
13
+ let attached = false;
14
+ let disposed = false;
15
+ const request = () =>
16
+ pi.events.emit(CLAIM, {
17
+ accept(claim: unknown) {
18
+ if (!claim || typeof claim !== "object" || !("runtime" in claim)) {
19
+ failed(
20
+ new Error(
21
+ "Shared boards could not connect. Update their extension and reload Pi. Other agent operations remain available.",
22
+ ),
23
+ );
24
+ return;
25
+ }
26
+ void Promise.resolve(claim.runtime)
27
+ .then((runtime: unknown) => {
28
+ if (disposed || attached) return;
29
+ if (
30
+ !runtime ||
31
+ typeof runtime !== "object" ||
32
+ ![
33
+ "attach",
34
+ "enabled",
35
+ "refresh",
36
+ "execute",
37
+ "handle",
38
+ "promptCatchup",
39
+ "toOwner",
40
+ ].every(
41
+ (key) =>
42
+ key in runtime &&
43
+ typeof Reflect.get(runtime, key) === "function",
44
+ ) ||
45
+ !("active" in runtime) ||
46
+ !(runtime.active instanceof Map)
47
+ ) {
48
+ throw new Error(
49
+ "Shared boards could not connect. Update their extension and reload Pi. Other agent operations remain available.",
50
+ );
51
+ }
52
+ attach(runtime as BoardRuntime);
53
+ attached = true;
54
+ })
55
+ .catch((error: unknown) => {
56
+ if (!disposed)
57
+ failed(error instanceof Error ? error : new Error(String(error)));
58
+ });
59
+ },
60
+ });
61
+ const stop = pi.events.on(AVAILABLE, request);
62
+ request();
63
+ pi.on("session_shutdown", () => {
64
+ disposed = true;
65
+ stop();
66
+ });
67
+ }