@howaboua/pi-shepherdr 0.2.6 → 0.2.8

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.
@@ -14,10 +14,11 @@ import type {
14
14
  SessionView,
15
15
  } from "./types.js";
16
16
 
17
- const BRIDGE_VERSION = 7;
17
+ const BRIDGE_VERSION = 11;
18
18
  const REMOTE_HELPER = "~/.pi/agent/shepherdr.mjs";
19
19
  const REMOTE_PEER_HELPER = "~/.pi/agent/shepherdr-peer.mjs";
20
20
  const REMOTE_SESSION_HELPER = "~/.pi/agent/shepherdr-session.mjs";
21
+ const REMOTE_CONTEXT_HELPER = "~/.pi/agent/shepherdr-context.mjs";
21
22
  const MAX_FRAME_BYTES = 8 * 1024 * 1024;
22
23
  const MAX_DIAGNOSTIC_BYTES = 8 * 1024;
23
24
  const DEPLOY_TIMEOUT_MS = 20_000;
@@ -59,6 +60,7 @@ interface PendingCall {
59
60
  reject: (error: Error) => void;
60
61
  resolve: (value: unknown) => void;
61
62
  timer: NodeJS.Timeout;
63
+ cleanup?: () => void;
62
64
  }
63
65
 
64
66
  interface SubscriptionCallbacks {
@@ -160,6 +162,11 @@ async function deploy(
160
162
  }
161
163
 
162
164
  export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
165
+ private contextHandler:
166
+ | ((request: unknown, signal: AbortSignal) => Promise<unknown>)
167
+ | undefined;
168
+ private readonly incomingContext = new Map<string, AbortController>();
169
+ private relayPath: string | undefined;
163
170
  private readonly child: ChildProcessWithoutNullStreams;
164
171
  private closed = false;
165
172
  private diagnostics = "";
@@ -194,21 +201,30 @@ export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
194
201
  config: SshMachine,
195
202
  onClose: (error: Error) => void,
196
203
  ): Promise<RemoteHerdrClient> {
197
- const [source, peerSource, sessionSource] = await Promise.all([
198
- readFile(
199
- fileURLToPath(new URL("./remote/shepherdr.mjs", import.meta.url)),
200
- ),
201
- readFile(
202
- fileURLToPath(new URL("./remote/shepherdr-peer.mjs", import.meta.url)),
203
- ),
204
- readFile(
205
- fileURLToPath(
206
- new URL("./remote/shepherdr-session.mjs", import.meta.url),
204
+ const [source, peerSource, sessionSource, contextSource] =
205
+ await Promise.all([
206
+ readFile(
207
+ fileURLToPath(new URL("./remote/shepherdr.mjs", import.meta.url)),
207
208
  ),
208
- ),
209
- ]);
209
+ readFile(
210
+ fileURLToPath(
211
+ new URL("./remote/shepherdr-peer.mjs", import.meta.url),
212
+ ),
213
+ ),
214
+ readFile(
215
+ fileURLToPath(
216
+ new URL("./remote/shepherdr-session.mjs", import.meta.url),
217
+ ),
218
+ ),
219
+ readFile(
220
+ fileURLToPath(
221
+ new URL("./remote/shepherdr-context.mjs", import.meta.url),
222
+ ),
223
+ ),
224
+ ]);
210
225
  await deploy(config, peerSource, REMOTE_PEER_HELPER);
211
226
  await deploy(config, sessionSource, REMOTE_SESSION_HELPER);
227
+ await deploy(config, contextSource, REMOTE_CONTEXT_HELPER);
212
228
  await deploy(config, source, REMOTE_HELPER);
213
229
  const child = spawnConnector(config, remoteCommand(config));
214
230
  const client = new RemoteHerdrClient(child, onClose);
@@ -232,6 +248,35 @@ export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
232
248
  )) as T;
233
249
  }
234
250
 
251
+ async requestContext(
252
+ path: string,
253
+ request: unknown,
254
+ signal?: AbortSignal,
255
+ ): Promise<unknown> {
256
+ signal?.throwIfAborted();
257
+ return this.call({ op: "context", path, request }, 36_000, signal);
258
+ }
259
+
260
+ async startContextRelay(
261
+ threadId: string,
262
+ routeId: string,
263
+ handler: (request: unknown, signal: AbortSignal) => Promise<unknown>,
264
+ ): Promise<void> {
265
+ this.contextHandler = handler;
266
+ const path = await this.call({ op: "context_relay", threadId, routeId });
267
+ if (typeof path !== "string")
268
+ throw new Error("Invalid shared context relay path");
269
+ this.relayPath = path;
270
+ }
271
+
272
+ contextRelayPath(): string {
273
+ if (!this.relayPath)
274
+ throw new Error(
275
+ "Shared context relay is unavailable; run /herdr connect to retry",
276
+ );
277
+ return this.relayPath;
278
+ }
279
+
235
280
  async sendMessage(
236
281
  agent: PaneInfo,
237
282
  message: PeerMessage,
@@ -329,7 +374,9 @@ export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
329
374
  private call(
330
375
  message: Record<string, unknown>,
331
376
  timeoutMs = 10_000,
377
+ signal?: AbortSignal,
332
378
  ): Promise<unknown> {
379
+ signal?.throwIfAborted();
333
380
  if (this.closed)
334
381
  return Promise.reject(
335
382
  new Error("remote Shepherdr bridge is unavailable"),
@@ -337,21 +384,37 @@ export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
337
384
  const id = typeof message["id"] === "string" ? message["id"] : randomUUID();
338
385
  return new Promise((resolve, reject) => {
339
386
  const timer = setTimeout(() => {
340
- this.disconnected(
341
- new Error(`remote Shepherdr ${String(message["op"])} timed out`),
387
+ const error = new Error(
388
+ `remote Shepherdr ${String(message["op"])} timed out`,
342
389
  );
390
+ if (message["op"] === "context_relay") this.rejectPending(id, error);
391
+ else this.disconnected(error);
343
392
  }, timeoutMs);
344
393
  timer.unref();
345
- this.pending.set(id, { resolve, reject, timer });
394
+ const abort = () => {
395
+ if (!this.pending.has(id)) return;
396
+ this.rejectPending(
397
+ id,
398
+ new Error(
399
+ "Shared context request cancelled; a write may have completed. Reread the note before retrying",
400
+ ),
401
+ );
402
+ this.child.stdin.write(
403
+ `${JSON.stringify({ op: "context_cancel", id })}\n`,
404
+ );
405
+ };
406
+ this.pending.set(id, {
407
+ resolve,
408
+ reject,
409
+ timer,
410
+ cleanup: () => signal?.removeEventListener("abort", abort),
411
+ });
412
+ signal?.addEventListener("abort", abort, { once: true });
346
413
  this.child.stdin.write(
347
414
  `${JSON.stringify({ ...message, id })}\n`,
348
415
  (error) => {
349
416
  if (!error) return;
350
- const pending = this.pending.get(id);
351
- if (!pending) return;
352
- this.pending.delete(id);
353
- clearTimeout(pending.timer);
354
- pending.reject(error);
417
+ this.rejectPending(id, error);
355
418
  },
356
419
  );
357
420
  });
@@ -407,6 +470,40 @@ export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
407
470
  }
408
471
  const id = value["id"];
409
472
  if (typeof id !== "string") continue;
473
+ if (value["type"] === "context_cancel") {
474
+ this.incomingContext.get(id)?.abort();
475
+ continue;
476
+ }
477
+ if (value["type"] === "context_request") {
478
+ const controller = new AbortController();
479
+ this.incomingContext.set(id, controller);
480
+ const reply = (data: object) => {
481
+ if (this.closed || controller.signal.aborted) return;
482
+ let frame = `${JSON.stringify({ op: "context_reply", id, ...data })}\n`;
483
+ if (Buffer.byteLength(frame) > MAX_FRAME_BYTES)
484
+ frame = `${JSON.stringify({ op: "context_reply", id, ok: false, error: "Shared context response is too large" })}\n`;
485
+ this.child.stdin.write(frame);
486
+ };
487
+ void Promise.resolve()
488
+ .then(() => {
489
+ if (!this.contextHandler)
490
+ throw new Error("Shared context controller is unavailable");
491
+ controller.signal.throwIfAborted();
492
+ return this.contextHandler(value["request"], controller.signal);
493
+ })
494
+ .then(
495
+ (result) => reply({ ok: true, result }),
496
+ (error: unknown) =>
497
+ reply({
498
+ ok: false,
499
+ error: error instanceof Error ? error.message : String(error),
500
+ }),
501
+ )
502
+ .finally(() => {
503
+ this.incomingContext.delete(id);
504
+ });
505
+ continue;
506
+ }
410
507
  if (value["ok"] === true) this.resolvePending(id, value["result"]);
411
508
  else {
412
509
  const detail = value["error"] as BridgeError | undefined;
@@ -428,6 +525,7 @@ export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
428
525
  if (!pending) return;
429
526
  this.pending.delete(id);
430
527
  clearTimeout(pending.timer);
528
+ pending.cleanup?.();
431
529
  pending.resolve(value);
432
530
  }
433
531
 
@@ -436,6 +534,7 @@ export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
436
534
  if (!pending) return;
437
535
  this.pending.delete(id);
438
536
  clearTimeout(pending.timer);
537
+ pending.cleanup?.();
439
538
  pending.reject(error);
440
539
  }
441
540
 
@@ -447,8 +546,11 @@ export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
447
546
  }
448
547
 
449
548
  private failPending(error: Error, notify: boolean): void {
549
+ for (const controller of this.incomingContext.values()) controller.abort();
550
+ this.incomingContext.clear();
450
551
  for (const pending of this.pending.values()) {
451
552
  clearTimeout(pending.timer);
553
+ pending.cleanup?.();
452
554
  pending.reject(error);
453
555
  }
454
556
  this.pending.clear();
@@ -0,0 +1,283 @@
1
+ import type {
2
+ ExtensionAPI,
3
+ ExtensionContext,
4
+ } from "@earendil-works/pi-coding-agent";
5
+ import type {
6
+ ContextSharingService,
7
+ SharedContextRequest,
8
+ SharedContextResult,
9
+ } from "@howaboua/pi-codex-conversion/context-sharing";
10
+ import type { AgentFleet, ConnectedMachine } from "./fleet.js";
11
+ import { sessionPath } from "./herdr.js";
12
+ import {
13
+ listenContext,
14
+ requestContext,
15
+ sessionContextPath,
16
+ } from "./remote/shepherdr-context.mjs";
17
+ import type { PaneInfo } from "./types.js";
18
+
19
+ const MEMBER_ENTRY = "herdr-context-child";
20
+ interface Member {
21
+ agentName: string;
22
+ sessionId: string;
23
+ threadId: string;
24
+ machine: string;
25
+ sessionFile: string;
26
+ }
27
+ interface Routing {
28
+ transport: "shepherdr";
29
+ parent: string;
30
+ }
31
+ interface ContextEnvelope {
32
+ operation: "context";
33
+ request: SharedContextRequest;
34
+ visited: string[];
35
+ }
36
+
37
+ export class SharedAgentContext {
38
+ private readonly pi: ExtensionAPI;
39
+ private readonly fleet: AgentFleet;
40
+ private readonly getService: () => ContextSharingService | undefined;
41
+ private running = false;
42
+
43
+ constructor(
44
+ pi: ExtensionAPI,
45
+ fleet: AgentFleet,
46
+ getService: () => ContextSharingService | undefined,
47
+ ) {
48
+ this.pi = pi;
49
+ this.fleet = fleet;
50
+ this.getService = getService;
51
+ pi.on("agent_start", () => {
52
+ this.running = true;
53
+ });
54
+ pi.on("agent_settled", () => {
55
+ this.running = false;
56
+ });
57
+ }
58
+
59
+ async handle(
60
+ ctx: ExtensionContext,
61
+ value: unknown,
62
+ signal?: AbortSignal,
63
+ ): Promise<unknown> {
64
+ if (!value || typeof value !== "object")
65
+ throw new Error("Invalid shared context request");
66
+ const service = this.getService();
67
+ const identity = service?.describe(ctx);
68
+ if ("operation" in value && value.operation === "bind") {
69
+ if (!service || !identity) return null;
70
+ return service.bind(ctx, "binding" in value ? value.binding : undefined);
71
+ }
72
+ if (!identity || !service)
73
+ throw new Error("Context sharing is unavailable in this session");
74
+ const envelope = value as Partial<ContextEnvelope>;
75
+ const request = envelope.request;
76
+ if (
77
+ envelope.operation !== "context" ||
78
+ !request ||
79
+ request.sessionId !== identity.sessionId ||
80
+ typeof request.agentName !== "string" ||
81
+ !Array.isArray(envelope.visited) ||
82
+ envelope.visited.some((item) => typeof item !== "string") ||
83
+ envelope.visited.length >= 64 ||
84
+ envelope.visited.includes(identity.threadId)
85
+ )
86
+ throw new Error("Invalid shared context route or session family");
87
+ if (identity.agentName === request.agentName) {
88
+ if (!ctx.isIdle() && !this.running)
89
+ throw new Error(
90
+ "Context owner is changing branches; retry after it settles",
91
+ );
92
+ return service.execute(ctx, request, signal);
93
+ }
94
+ const forwarded = {
95
+ ...envelope,
96
+ visited: [...envelope.visited, identity.threadId],
97
+ };
98
+ const member = ctx.sessionManager.getEntries().findLast((entry) => {
99
+ if (entry.type !== "custom" || entry.customType !== MEMBER_ENTRY)
100
+ return false;
101
+ const candidate = entry.data as Member;
102
+ return (
103
+ candidate?.threadId === identity.threadId &&
104
+ candidate.sessionId === identity.sessionId &&
105
+ typeof candidate.agentName === "string" &&
106
+ (request.agentName === candidate.agentName ||
107
+ request.agentName.startsWith(`${candidate.agentName}/`))
108
+ );
109
+ });
110
+ if (member?.type === "custom") {
111
+ const child = member.data as Member;
112
+ if (
113
+ typeof child.machine !== "string" ||
114
+ typeof child.sessionFile !== "string" ||
115
+ !child.sessionFile
116
+ )
117
+ throw new Error("Invalid saved shared context route");
118
+ const runtime = this.fleet.connected(child.machine);
119
+ return runtime.client.requestContext(
120
+ sessionContextPath(child.sessionFile),
121
+ forwarded,
122
+ signal,
123
+ );
124
+ }
125
+ const routing = identity.routing as Partial<Routing> | undefined;
126
+ if (
127
+ routing?.transport === "shepherdr" &&
128
+ typeof routing.parent === "string"
129
+ )
130
+ return requestContext(routing.parent, forwarded, signal);
131
+ throw new Error(
132
+ `No shared context agent ${request.agentName} in this session family`,
133
+ );
134
+ }
135
+
136
+ async prepare(
137
+ ctx: ExtensionContext,
138
+ runtime: ConnectedMachine,
139
+ name: string,
140
+ args: readonly string[] = [],
141
+ ) {
142
+ const service = this.getService();
143
+ if (!service?.canCreateChild(ctx)) return undefined;
144
+ const parent = service.describe(ctx);
145
+ if (!parent) return undefined;
146
+ if (
147
+ args.some((arg) =>
148
+ /^(?:--(?:session(?:-id)?|continue|resume|no-session|fork)(?:=|$)|-[cr]$)/.test(
149
+ arg,
150
+ ),
151
+ )
152
+ )
153
+ throw new Error(
154
+ "Shared context spawn cannot use profile session-selection arguments; use assign for existing agents",
155
+ );
156
+ const parentFile = ctx.sessionManager.getSessionFile();
157
+ if (!parentFile)
158
+ throw new Error(
159
+ "Shared context spawn requires a saved controller session",
160
+ );
161
+ const routing: Routing | undefined =
162
+ parent.storage === "session"
163
+ ? {
164
+ transport: "shepherdr",
165
+ parent: runtime.local
166
+ ? sessionContextPath(parentFile)
167
+ : runtime.client.contextRelayPath(),
168
+ }
169
+ : undefined;
170
+ const { binding, adopt } = await service.createChild(ctx, {
171
+ name,
172
+ ...(routing ? { routing } : {}),
173
+ });
174
+ return {
175
+ accept: async (agent: PaneInfo) => {
176
+ const sessionFile = sessionPath(agent);
177
+ if (!sessionFile)
178
+ throw new Error("Spawned agent has no native Pi session path");
179
+ const value = await runtime.client.requestContext(
180
+ sessionContextPath(sessionFile),
181
+ { operation: "bind", binding },
182
+ );
183
+ if (!value)
184
+ return {
185
+ warning:
186
+ "Spawned without shared context: the target needs Codex conversion with notes-based continuity",
187
+ };
188
+ if (
189
+ typeof value !== "object" ||
190
+ !("sessionId" in value) ||
191
+ value.sessionId !== binding.sessionId ||
192
+ !("agentName" in value) ||
193
+ value.agentName !== binding.agentName ||
194
+ !("storage" in value) ||
195
+ value.storage !== binding.storage ||
196
+ (binding.accountScope !== undefined &&
197
+ (!("accountScope" in value) ||
198
+ value.accountScope !== binding.accountScope))
199
+ )
200
+ throw new Error(
201
+ "Spawned agent did not adopt its shared context identity and storage mode",
202
+ );
203
+ if (ctx.sessionManager.getSessionId() !== parent.threadId)
204
+ throw new Error("Controller session changed during spawn");
205
+ await adopt();
206
+ this.pi.appendEntry<Member>(MEMBER_ENTRY, {
207
+ agentName: binding.agentName,
208
+ sessionId: parent.sessionId,
209
+ threadId: parent.threadId,
210
+ machine: runtime.machine,
211
+ sessionFile,
212
+ });
213
+ return { agentName: binding.agentName };
214
+ },
215
+ };
216
+ }
217
+ }
218
+
219
+ export async function registerSharedAgentContext(
220
+ pi: ExtensionAPI,
221
+ fleet: AgentFleet,
222
+ ): Promise<SharedAgentContext> {
223
+ let api:
224
+ | typeof import("@howaboua/pi-codex-conversion/context-sharing")
225
+ | undefined;
226
+ try {
227
+ api = await import("@howaboua/pi-codex-conversion/context-sharing");
228
+ } catch (error) {
229
+ const failure = error as { code?: string; message?: string };
230
+ const missing = failure.message?.match(
231
+ /Cannot find (?:package|module) ['"]([^'"]+)['"]/,
232
+ )?.[1];
233
+ const module = "@howaboua/pi-codex-conversion/context-sharing";
234
+ const unavailable =
235
+ ((failure.code === "ERR_MODULE_NOT_FOUND" ||
236
+ failure.code === "MODULE_NOT_FOUND") &&
237
+ (missing === "@howaboua/pi-codex-conversion" ||
238
+ missing === module ||
239
+ missing?.endsWith(`/${module}`))) ||
240
+ (failure.code === "ERR_PACKAGE_PATH_NOT_EXPORTED" &&
241
+ failure.message?.includes("@howaboua/pi-codex-conversion") &&
242
+ failure.message.includes("./context-sharing"));
243
+ if (!unavailable)
244
+ throw new Error(
245
+ "Update pi-codex-conversion to use shared agent context",
246
+ { cause: error },
247
+ );
248
+ }
249
+ const connection = api?.connectCodexContextSharing(pi);
250
+ const shared = new SharedAgentContext(pi, fleet, () => connection?.service);
251
+ let close: (() => Promise<void>) | undefined;
252
+ let unregister: (() => void) | undefined;
253
+ pi.on("session_start", async (_event, ctx) => {
254
+ await close?.();
255
+ close = undefined;
256
+ unregister?.();
257
+ unregister = connection?.service?.registerRouter(
258
+ async (context, request, signal) =>
259
+ shared.handle(
260
+ context,
261
+ { operation: "context", request, visited: [] },
262
+ signal,
263
+ ) as Promise<SharedContextResult>,
264
+ );
265
+ const file = ctx.sessionManager.getSessionFile();
266
+ if (file)
267
+ close = await listenContext(
268
+ sessionContextPath(file),
269
+ (request: unknown, signal: AbortSignal) =>
270
+ shared.handle(ctx, request, signal),
271
+ );
272
+ });
273
+ pi.on("session_shutdown", async () => {
274
+ unregister?.();
275
+ await close?.();
276
+ connection?.dispose();
277
+ });
278
+ if (connection)
279
+ fleet.setContextRelay((ctx, request, signal) =>
280
+ shared.handle(ctx, request, signal),
281
+ );
282
+ return shared;
283
+ }