@howaboua/pi-shepherdr 0.2.11 → 0.2.12

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.
@@ -0,0 +1,299 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { isDeepStrictEqual } from "node:util";
3
+ import type {
4
+ ExtensionAPI,
5
+ ExtensionContext,
6
+ } from "@earendil-works/pi-coding-agent";
7
+ import type { ContextSharingService } from "@howaboua/pi-codex-conversion/context-sharing";
8
+ import type { Static } from "typebox";
9
+ import { Check } from "typebox/value";
10
+ import type { AgentsParams } from "./agents-contract.js";
11
+ import { AttachmentNotes } from "./attachment-notes.js";
12
+ import {
13
+ type AttachmentPlan,
14
+ attachmentOwner,
15
+ attachmentRoutes,
16
+ ROUTE,
17
+ Snapshot,
18
+ } from "./attachment-protocol.js";
19
+ import { AttachmentRouting } from "./attachment-routing.js";
20
+ import { AttachmentTarget } from "./attachment-target.js";
21
+ import type { AgentBoard } from "./board/host.js";
22
+ import { binding } from "./board/identity.js";
23
+ import type { ConnectedMachine } from "./fleet.js";
24
+ import { sessionPath } from "./herdr.js";
25
+ import { sessionContextPath } from "./remote/shepherdr-context.mjs";
26
+ import type { PaneInfo } from "./types.js";
27
+
28
+ /** Coordinates retry-safe attach/detach from the controlling session. */
29
+ export class AgentAttachment {
30
+ private readonly pi: ExtensionAPI;
31
+ private readonly board: AgentBoard;
32
+ private readonly notes: AttachmentNotes;
33
+ readonly target: AttachmentTarget;
34
+ readonly routing: AttachmentRouting;
35
+ constructor(
36
+ pi: ExtensionAPI,
37
+ board: AgentBoard,
38
+ getService: () => ContextSharingService | undefined,
39
+ ) {
40
+ this.pi = pi;
41
+ this.board = board;
42
+ this.notes = new AttachmentNotes(getService);
43
+ this.target = new AttachmentTarget(pi, board, getService, this.notes);
44
+ this.routing = new AttachmentRouting(getService, this.notes);
45
+ }
46
+ async attach(
47
+ ctx: ExtensionContext,
48
+ runtime: ConnectedMachine,
49
+ panel: PaneInfo,
50
+ params: AgentsParams,
51
+ signal: AbortSignal,
52
+ ) {
53
+ const sessionFile = sessionPath(panel);
54
+ const controllerFile = ctx.sessionManager.getSessionFile();
55
+ const controllerSessionId = ctx.sessionManager.getSessionId();
56
+ if (!sessionFile || !controllerFile)
57
+ throw new Error("Attachment requires saved Pi sessions");
58
+ if (runtime.local && sessionFile === controllerFile)
59
+ throw new Error("Cannot attach this session to itself");
60
+ if (attachmentOwner(ctx))
61
+ throw new Error(
62
+ "An attached agent cannot attach another controller; use its existing controller",
63
+ );
64
+ const context = params.context === true;
65
+ const useBoard = params.board === true;
66
+ const controllerContext = context
67
+ ? this.target.context(ctx, false)
68
+ : undefined;
69
+ const controllerBoard = useBoard ? binding(ctx) : undefined;
70
+ const check = () => {
71
+ signal.throwIfAborted();
72
+ if (
73
+ ctx.sessionManager.getSessionId() !== controllerSessionId ||
74
+ (controllerContext &&
75
+ !isDeepStrictEqual(
76
+ this.target.context(ctx, false),
77
+ controllerContext,
78
+ )) ||
79
+ (controllerBoard && !isDeepStrictEqual(binding(ctx), controllerBoard))
80
+ )
81
+ throw new Error(
82
+ "Controller changed during attachment; resume the original session and retry",
83
+ );
84
+ };
85
+ const prior = attachmentRoutes(ctx).find(
86
+ (route) =>
87
+ route.machine === runtime.machine && route.sessionFile === sessionFile,
88
+ );
89
+ if (prior?.detached)
90
+ throw new Error("Attachment was detached; reattachment is unsupported");
91
+ if (
92
+ prior &&
93
+ (!!prior.plan.context !== context || !!prior.plan.board !== useBoard)
94
+ )
95
+ throw new Error(
96
+ "Target has different attachment choices; changing an attachment is unsupported",
97
+ );
98
+ let route = prior;
99
+ if (!route) {
100
+ const snapshot = await runtime.client.requestContext(
101
+ sessionContextPath(sessionFile),
102
+ { operation: "attach-inspect" },
103
+ signal,
104
+ );
105
+ check();
106
+ if (!Check(Snapshot, snapshot))
107
+ throw new Error(
108
+ "Target does not support attachment; update and reload Shepherdr",
109
+ );
110
+ const current = snapshot as Static<typeof Snapshot>;
111
+ if (context && !current.context)
112
+ throw new Error(
113
+ current.contextError ?? "Target context is unavailable",
114
+ );
115
+ if (useBoard && current.boardError) throw new Error(current.boardError);
116
+ const upstream = runtime.local
117
+ ? sessionContextPath(controllerFile)
118
+ : runtime.client.contextRelayPath();
119
+ const segment = `attached-${randomUUID()}`;
120
+ const plan: AttachmentPlan = {
121
+ controllerSessionId,
122
+ targetSessionId: current.sessionId,
123
+ upstream,
124
+ ...(controllerContext && current.context
125
+ ? {
126
+ context: {
127
+ controller: controllerContext,
128
+ target: current.context,
129
+ alias: `${controllerContext.agentName}/${segment}`,
130
+ controllerAlias: `${current.context.agentName}/controller-${randomUUID()}`,
131
+ ...(runtime.local ? { controllerFile } : {}),
132
+ controllerNotes: this.notes.export(ctx),
133
+ targetNotes: current.notes,
134
+ },
135
+ }
136
+ : {}),
137
+ ...(useBoard
138
+ ? {
139
+ board: {
140
+ previous: current.board,
141
+ desired: this.board.membership.prepareAttachment(
142
+ ctx,
143
+ upstream,
144
+ segment,
145
+ ),
146
+ controller: binding(ctx),
147
+ },
148
+ }
149
+ : {}),
150
+ };
151
+ route = { plan, machine: runtime.machine, sessionFile, phase: "pending" };
152
+ this.notes.checkTransport({ operation: "attach-commit", plan });
153
+ // A retry after a lost response reuses the same aliases and board identity.
154
+ this.pi.appendEntry(ROUTE, route);
155
+ }
156
+ try {
157
+ const accepted = await runtime.client.requestContext(
158
+ sessionContextPath(sessionFile),
159
+ { operation: "attach-commit", plan: route.plan },
160
+ signal,
161
+ );
162
+ check();
163
+ if (!isDeepStrictEqual(accepted, route.plan))
164
+ throw new Error("Target did not accept the requested attachment");
165
+ if (route.plan.board)
166
+ await this.board.membership.registerAttachment(
167
+ ctx,
168
+ runtime,
169
+ sessionFile,
170
+ {
171
+ ...route.plan.board.desired,
172
+ sessionId: route.plan.targetSessionId,
173
+ },
174
+ route.plan.board.controller,
175
+ );
176
+ check();
177
+ if (route.plan.context) this.target.retainIdentity(ctx);
178
+ if (route.phase !== "ready")
179
+ this.pi.appendEntry(ROUTE, { ...route, phase: "ready" });
180
+ } catch (error) {
181
+ throw new Error(
182
+ `Attachment incomplete; the target may already be attached. Retry attach with the same controller, target and choices after both sessions settle. ${String(error)}`,
183
+ { cause: error },
184
+ );
185
+ }
186
+ return {
187
+ attached: true,
188
+ machine: runtime.machine,
189
+ target: panel.pane_id,
190
+ ...(route.plan.context
191
+ ? {
192
+ contextAgent: route.plan.context.alias,
193
+ controllerContextAgent: route.plan.context.controllerAlias,
194
+ }
195
+ : {}),
196
+ ...(route.plan.board
197
+ ? {
198
+ boardAgent: route.plan.board.desired.agentName,
199
+ previousBoard: route.plan.board.previous.boardId,
200
+ }
201
+ : {}),
202
+ };
203
+ }
204
+ async detach(
205
+ ctx: ExtensionContext,
206
+ runtime: ConnectedMachine,
207
+ panel: PaneInfo,
208
+ params: AgentsParams,
209
+ signal: AbortSignal,
210
+ ) {
211
+ const route = attachmentRoutes(ctx).find(
212
+ (entry) =>
213
+ entry.machine === runtime.machine &&
214
+ entry.sessionFile === sessionPath(panel),
215
+ );
216
+ if (!route || route.phase !== "ready")
217
+ throw new Error(
218
+ "No completed attachment for this target in this controller session",
219
+ );
220
+ const { plan } = route;
221
+ if ((params.context && !plan.context) || (params.board && !plan.board))
222
+ throw new Error("Cannot detach a choice that was not attached");
223
+ const check = () => {
224
+ signal.throwIfAborted();
225
+ if (
226
+ ctx.sessionManager.getSessionId() !== plan.controllerSessionId ||
227
+ (params.context &&
228
+ plan.context &&
229
+ !isDeepStrictEqual(
230
+ this.target.context(ctx, false),
231
+ plan.context.controller,
232
+ ))
233
+ )
234
+ throw new Error(
235
+ "Controller changed during detach; resume it and retry",
236
+ );
237
+ };
238
+ check();
239
+ try {
240
+ const context = params.context ? this.notes.export(ctx) : undefined;
241
+ this.notes.checkTransport({
242
+ operation: "detach-commit",
243
+ plan,
244
+ context,
245
+ board: params.board,
246
+ });
247
+ const result = await runtime.client.requestContext(
248
+ sessionContextPath(route.sessionFile),
249
+ {
250
+ operation: "detach-commit",
251
+ plan,
252
+ ...(context ? { context } : {}),
253
+ ...(params.board ? { board: true } : {}),
254
+ },
255
+ signal,
256
+ );
257
+ check();
258
+ if (
259
+ !result ||
260
+ typeof result !== "object" ||
261
+ !("detached" in result) ||
262
+ result.detached !== true
263
+ )
264
+ throw new Error("Target did not confirm detach");
265
+ let notes: unknown;
266
+ if (params.context && plan.context) {
267
+ if (!("notes" in result))
268
+ throw new Error("Target checkpoints were not retained");
269
+ this.notes.validate(result.notes, plan.context.target);
270
+ notes = result.notes;
271
+ }
272
+ this.pi.appendEntry(ROUTE, {
273
+ ...route,
274
+ detached: {
275
+ ...route.detached,
276
+ ...(notes ? { context: notes } : {}),
277
+ ...(params.board ? { board: true } : {}),
278
+ },
279
+ });
280
+ if (params.board && plan.board)
281
+ await this.board.membership.unregisterAttachment(ctx, {
282
+ ...plan.board.desired,
283
+ sessionId: plan.targetSessionId,
284
+ });
285
+ check();
286
+ } catch (error) {
287
+ throw new Error(
288
+ `Detach incomplete; retry from the same controller and target with the same choices. ${String(error)}`,
289
+ { cause: error },
290
+ );
291
+ }
292
+ return {
293
+ detached: true,
294
+ target: panel.pane_id,
295
+ context: !!params.context,
296
+ board: !!params.board,
297
+ };
298
+ }
299
+ }
@@ -3,6 +3,7 @@ import {
3
3
  existsSync,
4
4
  mkdirSync,
5
5
  readFileSync,
6
+ realpathSync,
6
7
  renameSync,
7
8
  rmSync,
8
9
  writeFileSync,
@@ -46,9 +47,17 @@ function readEnabled(path: string, scope: "folder" | "global") {
46
47
  }
47
48
 
48
49
  function boardConfigPaths(folder: string) {
50
+ // Keep aliases on one write target so atomic saves do not replace symlinks.
51
+ function configPath(directory: string) {
52
+ const path = resolve(directory, CONFIG_FILE);
53
+ return existsSync(path) ? realpathSync(path) : path;
54
+ }
55
+ const global = configPath(getAgentDir());
56
+ const local = configPath(resolve(folder, ".pi"));
49
57
  return {
50
- global: resolve(getAgentDir(), CONFIG_FILE),
51
- folder: resolve(folder, ".pi", CONFIG_FILE),
58
+ global,
59
+ // The global config is never also a folder config.
60
+ folder: local === global ? undefined : local,
52
61
  };
53
62
  }
54
63
 
@@ -74,7 +83,7 @@ export function readBoardConfig(folder: string) {
74
83
  const paths = boardConfigPaths(folder);
75
84
  return {
76
85
  paths,
77
- folder: readEnabled(paths.folder, "folder"),
86
+ folder: paths.folder ? readEnabled(paths.folder, "folder") : undefined,
78
87
  global: readEnabled(paths.global, "global") ?? false,
79
88
  };
80
89
  }
@@ -87,6 +96,10 @@ export function writeBoardConfig(
87
96
  if (scope === "global" && enabled === undefined)
88
97
  throw new Error("Global enablement must be on or off");
89
98
  const path = boardConfigPaths(folder)[scope];
99
+ if (!path)
100
+ throw new Error(
101
+ "This folder's config is the global config; use a session override instead",
102
+ );
90
103
  readEnabled(path, scope);
91
104
  const document = readDocument(path);
92
105
  const board = object(document["board"]) ? { ...document["board"] } : {};
package/src/board/host.ts CHANGED
@@ -30,13 +30,24 @@ import {
30
30
  saveBinding,
31
31
  saveBoardSetting,
32
32
  saveChild,
33
- saveMember,
34
33
  sessionBoardSetting,
35
34
  } from "./identity.js";
35
+ import { BoardMembership } from "./membership.js";
36
36
  import { type BoardEnvelope, parseEnvelope } from "./protocol.js";
37
37
  import { BoardTurns } from "./turns.js";
38
38
 
39
39
  export class AgentBoard {
40
+ private readonly listeners = new Set<() => void>();
41
+ subscribe(listener: () => void): () => void {
42
+ this.listeners.add(listener);
43
+ return () => {
44
+ this.listeners.delete(listener);
45
+ };
46
+ }
47
+ private changed() {
48
+ for (const listener of this.listeners) listener();
49
+ }
50
+ readonly membership: BoardMembership;
40
51
  private readonly pi: ExtensionAPI;
41
52
  private readonly fleet: AgentFleet;
42
53
  private readonly turns: BoardTurns;
@@ -49,6 +60,11 @@ export class AgentBoard {
49
60
  this.turns = new BoardTurns(pi, (ctx, request) =>
50
61
  this.toOwner(ctx, request),
51
62
  );
63
+ this.membership = new BoardMembership(
64
+ pi,
65
+ (ctx, request) => this.toOwner(ctx, request),
66
+ this.turns.active,
67
+ );
52
68
  pi.on("session_start", (_event, ctx) => this.refresh(ctx));
53
69
  pi.on("before_agent_start", async (_event, ctx) => {
54
70
  // Reconcile resumed/offline children before tool/prompt preparation.
@@ -86,7 +102,7 @@ export class AgentBoard {
86
102
  enabled(ctx: ExtensionContext | undefined) {
87
103
  return ctx ? binding(ctx).enabled : false;
88
104
  }
89
- private async refresh(ctx: ExtensionContext) {
105
+ async refresh(ctx: ExtensionContext) {
90
106
  const own = binding(ctx);
91
107
  const setting = own.upstream ? undefined : rootBoardSetting(ctx);
92
108
  if (setting?.error && setting.error !== this.configError)
@@ -101,6 +117,7 @@ export class AgentBoard {
101
117
  this.lastSetting?.sessionId !== own.sessionId ||
102
118
  this.lastSetting.enabled !== own.enabled;
103
119
  this.lastSetting = { sessionId: own.sessionId, enabled: own.enabled };
120
+ this.changed();
104
121
  if (changed && !own.upstream) await this.propagateEnabled(ctx, own.enabled);
105
122
  }
106
123
  settings(ctx: ExtensionContext) {
@@ -126,10 +143,10 @@ export class AgentBoard {
126
143
  else writeBoardConfig(own.ownerFolder, scope, enabled);
127
144
  await this.refresh(ctx);
128
145
  }
129
- status(ctx: ExtensionContext) {
146
+ status(ctx: ExtensionContext, includeArchive = true) {
130
147
  const own = binding(ctx);
131
148
  const setting = own.upstream ? undefined : rootBoardSetting(ctx);
132
- return `Board ${own.enabled ? "on" : "off"} (${setting?.source ?? "inherited from owner"}). ${own.boardId}\nArchive: ${own.databasePath}${setting?.error ? `\n${setting.error}` : ""}`;
149
+ return `Board ${own.enabled ? "on" : "off"} (${setting?.source ?? "inherited from owner"})${includeArchive ? `. ${own.boardId}\nArchive: ${own.databasePath}` : ""}${setting?.error ? `\n${setting.error}` : ""}`;
133
150
  }
134
151
  async execute(ctx: ExtensionContext, input: unknown, requestId: string) {
135
152
  const params = parseBoardRequest(input);
@@ -140,7 +157,7 @@ export class AgentBoard {
140
157
  }
141
158
  if (!caller.enabled)
142
159
  throw new Error(
143
- "Board is off; the user can enable it with /herdr board on",
160
+ "Board is off; the user can enable it in /herdr → Settings",
144
161
  );
145
162
  return this.toOwner(ctx, {
146
163
  operation: "board-call",
@@ -302,26 +319,11 @@ export class AgentBoard {
302
319
  request.caller.databasePath !== own.databasePath
303
320
  )
304
321
  throw new Error("Caller not bound to this board");
305
- if (request.operation === "board-register") {
306
- const member = request.member;
307
- if (
308
- member.boardId !== own.boardId ||
309
- member.databasePath !== own.databasePath ||
310
- member.rootSessionId !== own.rootSessionId ||
311
- !member.agentName.startsWith(`${caller.agentName}/`)
312
- )
313
- throw new Error("Invalid board member registration");
314
- if (
315
- directory.some(
316
- (entry) =>
317
- entry.agentName === member.agentName ||
318
- entry.sessionId === member.sessionId,
319
- )
320
- )
321
- throw new Error("Board member already bound");
322
- saveMember(this.pi, member);
323
- return true;
324
- }
322
+ if (
323
+ request.operation === "board-unregister" ||
324
+ request.operation === "board-register"
325
+ )
326
+ return this.membership.commitDirectory(own, directory, caller, request);
325
327
  if (request.operation === "board-active") {
326
328
  if (own.enabled) this.turns.register(caller, request);
327
329
  return true;
@@ -332,7 +334,7 @@ export class AgentBoard {
332
334
  if (params.action === "help") return { ...boardHelp, enabled: own.enabled };
333
335
  if (!own.enabled)
334
336
  throw new Error(
335
- "Board is off; the user can enable it with /herdr board on",
337
+ "Board is off; the user can enable it in /herdr → Settings",
336
338
  );
337
339
  const prepared: BoardParams =
338
340
  params.author === undefined
@@ -35,6 +35,7 @@ const BINDING = "shepherdr-board-binding";
35
35
  const MEMBER = "shepherdr-board-member";
36
36
  const CHILD = "shepherdr-board-child";
37
37
  const SETTING = "shepherdr-board-setting";
38
+ const REMOVED = "shepherdr-board-removed";
38
39
  const SettingSchema = Type.Object({
39
40
  sessionId: uuid,
40
41
  enabled: Type.Union([Type.Boolean(), Type.Null()]),
@@ -124,6 +125,11 @@ export function members(ctx: ExtensionContext): BoardBinding[] {
124
125
  const own = binding(ctx);
125
126
  const found = new Map([[own.agentName, own]]);
126
127
  for (const entry of ctx.sessionManager.getEntries()) {
128
+ if (entry.type === "custom" && entry.customType === REMOVED) {
129
+ const value = parseBinding(entry.data);
130
+ if (value.boardId === own.boardId) found.delete(value.agentName);
131
+ continue;
132
+ }
127
133
  if (entry.type !== "custom" || entry.customType !== MEMBER) continue;
128
134
  const value = parseBinding(entry.data);
129
135
  if (value.rootSessionId === own.sessionId && value.boardId === own.boardId)
@@ -138,6 +144,11 @@ export function children(ctx: ExtensionContext): BoardChild[] {
138
144
  const own = binding(ctx);
139
145
  const found = new Map<string, BoardChild>();
140
146
  for (const entry of ctx.sessionManager.getEntries()) {
147
+ if (entry.type === "custom" && entry.customType === REMOVED) {
148
+ const value = parseBinding(entry.data);
149
+ if (value.boardId === own.boardId) found.delete(value.agentName);
150
+ continue;
151
+ }
141
152
  if (entry.type !== "custom" || entry.customType !== CHILD) continue;
142
153
  if (!Check(ChildSchema, entry.data))
143
154
  throw new Error("Invalid saved board child route");
@@ -153,3 +164,6 @@ export function children(ctx: ExtensionContext): BoardChild[] {
153
164
  export function saveChild(pi: ExtensionAPI, value: BoardChild) {
154
165
  pi.appendEntry(CHILD, value);
155
166
  }
167
+ export function removeMember(pi: ExtensionAPI, value: BoardBinding) {
168
+ pi.appendEntry(REMOVED, value);
169
+ }
@@ -0,0 +1,187 @@
1
+ import { isDeepStrictEqual } from "node:util";
2
+ import type {
3
+ ExtensionAPI,
4
+ ExtensionContext,
5
+ } from "@earendil-works/pi-coding-agent";
6
+ import type { ConnectedMachine } from "../fleet.js";
7
+ import {
8
+ type BoardBinding,
9
+ binding,
10
+ children,
11
+ members,
12
+ removeMember,
13
+ saveBinding,
14
+ saveChild,
15
+ saveMember,
16
+ } from "./identity.js";
17
+ import type { BoardEnvelope } from "./protocol.js";
18
+
19
+ function sameMembership(left: BoardBinding, right: BoardBinding) {
20
+ return isDeepStrictEqual(
21
+ { ...left, enabled: false },
22
+ { ...right, enabled: false },
23
+ );
24
+ }
25
+
26
+ /** Owns board attachment adoption, registration, restoration and removal. */
27
+ export class BoardMembership {
28
+ private readonly pi: ExtensionAPI;
29
+ private readonly toOwner: (
30
+ ctx: ExtensionContext,
31
+ request: BoardEnvelope,
32
+ ) => Promise<unknown>;
33
+ private readonly active: Map<string, unknown>;
34
+ constructor(
35
+ pi: ExtensionAPI,
36
+ toOwner: (
37
+ ctx: ExtensionContext,
38
+ request: BoardEnvelope,
39
+ ) => Promise<unknown>,
40
+ active: Map<string, unknown>,
41
+ ) {
42
+ this.pi = pi;
43
+ this.toOwner = toOwner;
44
+ this.active = active;
45
+ }
46
+ inspectAttachment(ctx: ExtensionContext) {
47
+ const own = binding(ctx);
48
+ if (own.upstream || children(ctx).length || members(ctx).length > 1)
49
+ throw new Error("Target already owns or belongs to a board family");
50
+ return own;
51
+ }
52
+ prepareAttachment(ctx: ExtensionContext, upstream: string, name: string) {
53
+ const own = binding(ctx);
54
+ if (!own.enabled)
55
+ throw new Error(
56
+ "Enable the controller's board before attaching a member",
57
+ );
58
+ if (!ctx.sessionManager.getSessionFile())
59
+ throw new Error("Board attachment requires a saved controller session");
60
+ return { ...own, agentName: `${own.agentName}/${name}`, upstream };
61
+ }
62
+ commitAttachment(
63
+ ctx: ExtensionContext,
64
+ expected: BoardBinding,
65
+ desired: BoardBinding,
66
+ ) {
67
+ if (!ctx.isIdle())
68
+ throw new Error("Attach a board only after the target settles");
69
+ const own = binding(ctx);
70
+ const adopted = { ...desired, sessionId: own.sessionId };
71
+ if (isDeepStrictEqual(own, adopted)) return adopted;
72
+ if (!isDeepStrictEqual(this.inspectAttachment(ctx), expected))
73
+ throw new Error(
74
+ "Target board changed during attachment; resolve it again",
75
+ );
76
+ saveBinding(this.pi, adopted);
77
+ return adopted;
78
+ }
79
+ async registerAttachment(
80
+ ctx: ExtensionContext,
81
+ runtime: ConnectedMachine,
82
+ sessionFile: string,
83
+ adopted: BoardBinding,
84
+ expected: BoardBinding,
85
+ ) {
86
+ if (!isDeepStrictEqual(binding(ctx), expected))
87
+ throw new Error("Controller board changed during attachment");
88
+ saveBinding(this.pi, expected);
89
+ await this.toOwner(ctx, {
90
+ operation: "board-register",
91
+ caller: expected,
92
+ member: adopted,
93
+ });
94
+ if (!isDeepStrictEqual(binding(ctx), expected))
95
+ throw new Error("Controller board changed during attachment");
96
+ saveChild(this.pi, {
97
+ parentSessionId: expected.sessionId,
98
+ binding: adopted,
99
+ machine: runtime.machine,
100
+ sessionFile,
101
+ });
102
+ }
103
+ detachTarget(
104
+ ctx: ExtensionContext,
105
+ desired: BoardBinding,
106
+ previous: BoardBinding,
107
+ ) {
108
+ if (children(ctx).length)
109
+ throw new Error(
110
+ "Detach a board member only when it has no board children",
111
+ );
112
+ if (
113
+ !sameMembership(binding(ctx), {
114
+ ...desired,
115
+ sessionId: previous.sessionId,
116
+ })
117
+ )
118
+ throw new Error("Target board changed before detach");
119
+ saveBinding(this.pi, previous);
120
+ this.active.clear();
121
+ }
122
+ async unregisterAttachment(ctx: ExtensionContext, member: BoardBinding) {
123
+ const own = binding(ctx);
124
+ await this.toOwner(ctx, {
125
+ operation: "board-unregister",
126
+ caller: own,
127
+ member,
128
+ });
129
+ if (!sameMembership(binding(ctx), own))
130
+ throw new Error("Controller board changed during detach");
131
+ removeMember(this.pi, member);
132
+ }
133
+ commitDirectory(
134
+ own: BoardBinding,
135
+ directory: BoardBinding[],
136
+ caller: BoardBinding,
137
+ request: Extract<
138
+ BoardEnvelope,
139
+ { operation: "board-register" | "board-unregister" }
140
+ >,
141
+ ) {
142
+ if (request.operation === "board-unregister") {
143
+ const member = request.member;
144
+ if (
145
+ member.boardId !== own.boardId ||
146
+ member.databasePath !== own.databasePath ||
147
+ !member.agentName.startsWith(`${caller.agentName}/`)
148
+ )
149
+ throw new Error("Invalid board member removal");
150
+ if (
151
+ directory.some((entry) =>
152
+ entry.agentName.startsWith(`${member.agentName}/`),
153
+ )
154
+ )
155
+ throw new Error(
156
+ "Detach a board member only when it has no board children",
157
+ );
158
+ const existing = directory.find(
159
+ (entry) => entry.agentName === member.agentName,
160
+ );
161
+ if (existing && !sameMembership(existing, member))
162
+ throw new Error("Board member changed before detach");
163
+ removeMember(this.pi, member);
164
+ this.active.delete(member.agentName);
165
+ return true;
166
+ }
167
+ if (request.operation === "board-register") {
168
+ const member = request.member;
169
+ if (
170
+ member.boardId !== own.boardId ||
171
+ member.databasePath !== own.databasePath ||
172
+ member.rootSessionId !== own.rootSessionId ||
173
+ !member.agentName.startsWith(`${caller.agentName}/`)
174
+ )
175
+ throw new Error("Invalid board member registration");
176
+ const existing = directory.find(
177
+ (entry) =>
178
+ entry.agentName === member.agentName ||
179
+ entry.sessionId === member.sessionId,
180
+ );
181
+ if (existing && isDeepStrictEqual(existing, member)) return true;
182
+ if (existing) throw new Error("Board member already bound");
183
+ saveMember(this.pi, member);
184
+ return true;
185
+ }
186
+ }
187
+ }
@@ -26,6 +26,11 @@ const Protocol = Type.Union([
26
26
  caller: BindingSchema,
27
27
  member: BindingSchema,
28
28
  }),
29
+ Type.Object({
30
+ operation: Type.Literal("board-unregister"),
31
+ caller: BindingSchema,
32
+ member: BindingSchema,
33
+ }),
29
34
  Type.Object({
30
35
  operation: Type.Literal("board-enabled"),
31
36
  boardId: Type.String(),