@howaboua/pi-shepherdr 0.2.24 → 0.2.26

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 (85) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +20 -12
  3. package/index.ts +2 -2
  4. package/package.json +10 -11
  5. package/src/agent-identity.ts +75 -0
  6. package/src/agents-contract.ts +20 -12
  7. package/src/agents-discovery.ts +79 -34
  8. package/src/agents-focus.ts +15 -9
  9. package/src/agents-spawn.ts +25 -7
  10. package/src/agents-tool.ts +35 -7
  11. package/src/agents-work.ts +2 -2
  12. package/src/attachment-notes.ts +25 -24
  13. package/src/attachment-protocol.ts +35 -15
  14. package/src/attachment-routing.ts +28 -24
  15. package/src/attachment-target.ts +58 -19
  16. package/src/attachment.ts +13 -17
  17. package/src/board/host.ts +19 -20
  18. package/src/board/membership.ts +49 -30
  19. package/src/close-idle.ts +89 -0
  20. package/src/context-routing.ts +196 -0
  21. package/src/control-panel/index.ts +3 -1
  22. package/src/control-panel/items.ts +14 -2
  23. package/src/control-panel/view.ts +6 -2
  24. package/src/controller.ts +11 -2
  25. package/src/core/AGENTS.md +5 -0
  26. package/src/core/backend.ts +266 -0
  27. package/src/core/client.ts +249 -0
  28. package/src/core/context-relay.mjs +111 -0
  29. package/src/core/focus-channel-helper.mjs +165 -0
  30. package/src/core/focus-channel-stream.ts +140 -0
  31. package/src/core/focus-channel-wire.mjs +160 -0
  32. package/src/core/focus-channel.ts +213 -0
  33. package/src/core/focus-window.ts +192 -0
  34. package/src/core/pi-executable.mjs +34 -0
  35. package/src/core/protocol.ts +116 -0
  36. package/src/core/registration.ts +51 -0
  37. package/src/core/remote-endpoint.ts +119 -0
  38. package/src/core/remote-exec.ts +122 -0
  39. package/src/core/remote-helper.mjs +244 -0
  40. package/src/core/remote-reader.ts +67 -0
  41. package/src/core/remote-relay.ts +191 -0
  42. package/src/core/request.ts +124 -0
  43. package/src/core/spawn.ts +177 -0
  44. package/src/core/status.ts +68 -0
  45. package/src/core/terminal.ts +103 -0
  46. package/src/fleet/catalog.ts +83 -0
  47. package/src/fleet/connection.ts +111 -0
  48. package/src/fleet/index.ts +161 -122
  49. package/src/fleet/inspection.ts +19 -1
  50. package/src/fleet/machine.ts +3 -0
  51. package/src/fleet/monitor.ts +18 -4
  52. package/src/fleet/persistence.ts +26 -3
  53. package/src/fleet/setup.ts +54 -13
  54. package/src/herdr.ts +25 -5
  55. package/src/launch-contract.ts +48 -0
  56. package/src/launch-location.ts +151 -0
  57. package/src/launch.ts +30 -183
  58. package/src/messages/attribution.ts +15 -6
  59. package/src/messages/events.ts +10 -4
  60. package/src/messages/focus.ts +11 -2
  61. package/src/messages/guidance.ts +22 -16
  62. package/src/monitor-extension-messages.ts +9 -2
  63. package/src/monitor-record.ts +13 -6
  64. package/src/monitor-state.ts +18 -4
  65. package/src/monitor.ts +31 -0
  66. package/src/peer-commands.ts +11 -0
  67. package/src/peer-inbox-delivery.ts +171 -0
  68. package/src/peer-inbox-focus.ts +113 -0
  69. package/src/peer-inbox.ts +126 -208
  70. package/src/remote/deployment.ts +1 -1
  71. package/src/remote/shepherdr-checkpoints.mjs +20 -2
  72. package/src/remote/shepherdr-context.mjs +15 -3
  73. package/src/remote/shepherdr-peer.mjs +18 -5
  74. package/src/remote/shepherdr-session.mjs +9 -2
  75. package/src/remote/shepherdr.mjs +1 -1
  76. package/src/settlement/collector.ts +2 -2
  77. package/src/settlement/index.ts +12 -0
  78. package/src/shared-context-host.ts +7 -18
  79. package/src/shared-context.ts +139 -12
  80. package/src/spawn-context.ts +10 -5
  81. package/src/spawn-ownership.ts +91 -0
  82. package/src/types.ts +10 -5
  83. package/src/worker-ownership.ts +92 -0
  84. package/src/worker-service.ts +13 -82
  85. package/changelog.ts +0 -337
@@ -22,6 +22,13 @@ interface MonitorExtensionMessagesOptions {
22
22
  persist: () => void;
23
23
  }
24
24
 
25
+ function isMissingAgent(error: unknown): boolean {
26
+ return (
27
+ isHerdrErrorCode(error, "agent_not_found") ||
28
+ (error instanceof Error && "kind" in error && error.kind === "not_found")
29
+ );
30
+ }
31
+
25
32
  // Extension messages are attention events, not settlements of delegated work.
26
33
  export class MonitorExtensionMessages {
27
34
  private context: ExtensionContext | undefined;
@@ -130,7 +137,7 @@ export class MonitorExtensionMessages {
130
137
  panel.pane_id,
131
138
  ).catch((error: unknown) => {
132
139
  // Pane closure can precede its lifecycle event or finish an in-flight read.
133
- if (isHerdrErrorCode(error, "agent_not_found")) return undefined;
140
+ if (isMissingAgent(error)) return undefined;
134
141
  throw error;
135
142
  });
136
143
  if (!current) continue;
@@ -141,7 +148,7 @@ export class MonitorExtensionMessages {
141
148
  this.options.client,
142
149
  panel.pane_id,
143
150
  ).catch((error: unknown) => {
144
- if (isHerdrErrorCode(error, "agent_not_found")) return undefined;
151
+ if (isMissingAgent(error)) return undefined;
145
152
  throw error;
146
153
  });
147
154
  if (generation !== this.generation || !this.context) return;
@@ -97,8 +97,9 @@ export function parseMonitoredAgent(
97
97
  (record["scope"] !== "task" && record["scope"] !== "persistent") ||
98
98
  typeof record["paneId"] !== "string" ||
99
99
  typeof record["terminalId"] !== "string" ||
100
- typeof record["workspaceId"] !== "string" ||
101
- typeof record["tabId"] !== "string"
100
+ (record["workspaceId"] !== undefined &&
101
+ typeof record["workspaceId"] !== "string") ||
102
+ (record["tabId"] !== undefined && typeof record["tabId"] !== "string")
102
103
  ) {
103
104
  return undefined;
104
105
  }
@@ -115,6 +116,7 @@ export function parseMonitoredAgent(
115
116
  : false;
116
117
  const name = optionalString(record, "name");
117
118
  const instructions = optionalString(record, "instructions");
119
+ const latestInstruction = optionalString(record, "latestInstruction");
118
120
  const activity = parsedActivity(record["activity"]);
119
121
  if (
120
122
  cwd === false ||
@@ -122,6 +124,7 @@ export function parseMonitoredAgent(
122
124
  notifiedExtensionMessages === false ||
123
125
  name === false ||
124
126
  instructions === false ||
127
+ latestInstruction === false ||
125
128
  !activity
126
129
  ) {
127
130
  return undefined;
@@ -129,11 +132,14 @@ export function parseMonitoredAgent(
129
132
  return {
130
133
  scope: record["scope"],
131
134
  ...(instructions ? { instructions } : {}),
135
+ ...(latestInstruction ? { latestInstruction } : {}),
132
136
  activity,
133
137
  paneId: record["paneId"],
134
138
  terminalId: record["terminalId"],
135
- workspaceId: record["workspaceId"],
136
- tabId: record["tabId"],
139
+ ...(record["workspaceId"] !== undefined
140
+ ? { workspaceId: record["workspaceId"] }
141
+ : {}),
142
+ ...(record["tabId"] !== undefined ? { tabId: record["tabId"] } : {}),
137
143
  ...(cwd ? { cwd } : {}),
138
144
  ...(lastAssistantId ? { lastAssistantId } : {}),
139
145
  ...(notifiedExtensionMessages ? { notifiedExtensionMessages } : {}),
@@ -154,8 +160,8 @@ export function recordForPanel(
154
160
  activity,
155
161
  paneId: panel.pane_id,
156
162
  terminalId: panel.terminal_id,
157
- workspaceId: panel.workspace_id,
158
- tabId: panel.tab_id,
163
+ ...(panel.workspace_id ? { workspaceId: panel.workspace_id } : {}),
164
+ ...(panel.tab_id ? { tabId: panel.tab_id } : {}),
159
165
  ...(panel.name ? { name: panel.name } : {}),
160
166
  ...(cwd ? { cwd } : {}),
161
167
  ...(lastAssistantId ? { lastAssistantId } : {}),
@@ -170,6 +176,7 @@ export function sameMonitorRecord(
170
176
  return (
171
177
  left.scope === right.scope &&
172
178
  left.instructions === right.instructions &&
179
+ left.latestInstruction === right.latestInstruction &&
173
180
  left.paneId === right.paneId &&
174
181
  left.terminalId === right.terminalId &&
175
182
  left.workspaceId === right.workspaceId &&
@@ -126,6 +126,9 @@ export class MonitorState {
126
126
  ...(existing?.instructions
127
127
  ? { instructions: existing.instructions }
128
128
  : {}),
129
+ ...(existing?.latestInstruction
130
+ ? { latestInstruction: existing.latestInstruction }
131
+ : {}),
129
132
  ...recordForPanel(
130
133
  panel,
131
134
  activity,
@@ -185,11 +188,19 @@ export class MonitorState {
185
188
  noteMessage(paneId: string, message: string): boolean {
186
189
  const record = this.byPane(paneId);
187
190
  if (!record) return false;
188
- const prior = record.instructions ?? activityTask(record.activity);
191
+ const instructions =
192
+ record.instructions ?? activityTask(record.activity) ?? message;
193
+ const latestInstruction = message !== instructions ? message : undefined;
194
+ const { latestInstruction: previousInstruction, ...prior } = record;
195
+ if (
196
+ record.instructions === instructions &&
197
+ previousInstruction === latestInstruction
198
+ )
199
+ return false;
189
200
  this.agents.set(record.terminalId, {
190
- ...record,
191
- instructions:
192
- prior && prior !== message ? `${prior}\n\n${message}` : message,
201
+ ...prior,
202
+ instructions,
203
+ ...(latestInstruction ? { latestInstruction } : {}),
193
204
  });
194
205
  return true;
195
206
  }
@@ -390,6 +401,9 @@ export class MonitorState {
390
401
 
391
402
  const updated = {
392
403
  ...(record.instructions ? { instructions: record.instructions } : {}),
404
+ ...(record.latestInstruction
405
+ ? { latestInstruction: record.latestInstruction }
406
+ : {}),
393
407
  ...recordForPanel(
394
408
  panel,
395
409
  activity,
package/src/monitor.ts CHANGED
@@ -51,6 +51,8 @@ export class AgentMonitor {
51
51
  private readonly extensionMessages: MonitorExtensionMessages;
52
52
  private context: ExtensionContext | undefined;
53
53
  private activationGeneration = 0;
54
+ private coreReconcile: Promise<void> | undefined;
55
+ private coreDirty = false;
54
56
 
55
57
  constructor(pi: ExtensionAPI, options: AgentMonitorOptions) {
56
58
  this.client = options.client;
@@ -130,6 +132,8 @@ export class AgentMonitor {
130
132
 
131
133
  deactivate(): void {
132
134
  this.activationGeneration += 1;
135
+ this.coreDirty = false;
136
+ this.coreReconcile = undefined;
133
137
  this.context = undefined;
134
138
  this.events.stop();
135
139
  this.extensionMessages.stop();
@@ -292,6 +296,33 @@ export class AgentMonitor {
292
296
  }
293
297
 
294
298
  private handleEvent(event: HerdrEvent): void {
299
+ if (event.event === "core.reconcile") {
300
+ const generation = this.activationGeneration;
301
+ const context = this.context;
302
+ this.coreDirty = true;
303
+ if (this.coreReconcile) return;
304
+ this.coreReconcile = Promise.resolve()
305
+ .then(async () => {
306
+ while (this.coreDirty && generation === this.activationGeneration) {
307
+ this.coreDirty = false;
308
+ await this.reconcile(generation, context);
309
+ }
310
+ })
311
+ .catch((error) => {
312
+ if (generation === this.activationGeneration) {
313
+ this.context?.ui.notify(
314
+ `Core monitoring reconciliation failed: ${String(error)}`,
315
+ "warning",
316
+ );
317
+ void this.events.retry().catch(() => undefined);
318
+ }
319
+ })
320
+ .finally(() => {
321
+ if (generation === this.activationGeneration)
322
+ this.coreReconcile = undefined;
323
+ });
324
+ return;
325
+ }
295
326
  const parsed = parseMonitorEvent(event);
296
327
  if (!parsed) return;
297
328
  if (parsed.type === "closed") {
@@ -51,6 +51,17 @@ export function createPeerCommands(pi: ExtensionAPI) {
51
51
  };
52
52
  return {
53
53
  available,
54
+ closeIdle(
55
+ ctx: ExtensionContext,
56
+ run: (ctx: ExtensionCommandContext) => Promise<void>,
57
+ ): void {
58
+ const token = randomUUID();
59
+ pending.set(token, {
60
+ session: ctx.sessionManager.getSessionFile(),
61
+ run,
62
+ });
63
+ pi.sendUserMessage(`/herdr ${token}`, { expandPromptTemplates: true });
64
+ },
54
65
  async handle(args: string, ctx: ExtensionCommandContext): Promise<boolean> {
55
66
  const intent = pending.get(args);
56
67
  if (!intent) return false;
@@ -0,0 +1,171 @@
1
+ import type { Socket } from "node:net";
2
+ import type {
3
+ ExtensionAPI,
4
+ ExtensionContext,
5
+ } from "@earendil-works/pi-coding-agent";
6
+ import { sendPolicyMessage } from "./delivery.js";
7
+ import { announcePeerMessage } from "./messages/voice-announcements.js";
8
+ import type { createPeerCommands } from "./peer-commands.js";
9
+ import { PEER_PROTOCOL } from "./remote/shepherdr-peer.mjs";
10
+
11
+ /** Serialises prompt catch-up/acceptance, but never serialises lifecycle commands. */
12
+ export class PeerInboxDelivery {
13
+ private promptDelivery = Promise.resolve();
14
+ pendingPrompts = 0;
15
+
16
+ private readonly sessionFile: string;
17
+ private readonly isRunning: () => boolean;
18
+ private readonly isOpen: () => boolean;
19
+ private readonly quitting: (socket: Socket) => void;
20
+ private readonly commands: ReturnType<typeof createPeerCommands>;
21
+ private readonly catchup: (
22
+ ctx: ExtensionContext,
23
+ ) => Promise<{ content: string; accepted: () => void }>;
24
+ constructor(
25
+ sessionFile: string,
26
+ isRunning: () => boolean,
27
+ isOpen: () => boolean,
28
+ quitting: (socket: Socket) => void,
29
+ commands: ReturnType<typeof createPeerCommands>,
30
+ catchup: (
31
+ ctx: ExtensionContext,
32
+ ) => Promise<{ content: string; accepted: () => void }>,
33
+ ) {
34
+ this.sessionFile = sessionFile;
35
+ this.isRunning = isRunning;
36
+ this.isOpen = isOpen;
37
+ this.quitting = quitting;
38
+ this.commands = commands;
39
+ this.catchup = catchup;
40
+ }
41
+
42
+ async receive(
43
+ pi: ExtensionAPI,
44
+ ctx: ExtensionContext,
45
+ socket: Socket,
46
+ request: Record<string, unknown>,
47
+ reply: (value: object, flushed?: () => void) => void,
48
+ ): Promise<void> {
49
+ let submitted = false;
50
+ try {
51
+ const idle = ctx.isIdle();
52
+ // Manual compaction/tree navigation can be busy without an agent
53
+ // loop to consume steering. Do not acknowledge a stranded message.
54
+ if (!idle && !this.isRunning()) {
55
+ reply({
56
+ ok: false,
57
+ rejected: true,
58
+ error: "Target is changing context; retry after it settles",
59
+ });
60
+ return;
61
+ }
62
+ const text = request["text"] as string;
63
+ const sender = request["context"]
64
+ ? `${request["sender"]}\n${request["context"]}`
65
+ : (request["sender"] as string);
66
+ if (text.startsWith("/")) {
67
+ const route = this.commands.prepare(text, ctx);
68
+ const { command } = route;
69
+ const submit = () => {
70
+ submitted = true;
71
+ sendPolicyMessage(
72
+ pi,
73
+ {
74
+ customType: "herdr-agent-source",
75
+ content: sender,
76
+ display: true,
77
+ },
78
+ {
79
+ triggerTurn: false,
80
+ deliverAs: idle && !command ? "nextTurn" : "steer",
81
+ },
82
+ );
83
+ route.submit();
84
+ };
85
+ if (command) {
86
+ // Lifecycle commands can tear down this inbox. Flush acceptance first.
87
+ const execute = () => {
88
+ try {
89
+ submit();
90
+ } catch (error) {
91
+ ctx.ui.notify(
92
+ `Command submission failed: ${String(error)}`,
93
+ "error",
94
+ );
95
+ }
96
+ };
97
+ if (text.trim() === "/quit") {
98
+ // Hold this authenticated connection until process exit, not
99
+ // session_shutdown (which precedes Pi's runtime teardown).
100
+ this.quitting(socket);
101
+ socket.write(
102
+ `${JSON.stringify({ protocol: PEER_PROTOCOL, id: request["id"], ok: true, command, closing: true })}\n`,
103
+ execute,
104
+ );
105
+ } else reply({ ok: true, command }, execute);
106
+ return;
107
+ }
108
+ submit();
109
+ reply({ ok: true, command });
110
+ return;
111
+ }
112
+ // Catch-up sampling and acceptance form one prompt boundary, including
113
+ // bursts arriving on separate authenticated sockets.
114
+ const previous = this.promptDelivery;
115
+ this.pendingPrompts += 1;
116
+ let release!: () => void;
117
+ this.promptDelivery = new Promise<void>((resolve) => {
118
+ release = resolve;
119
+ });
120
+ await previous;
121
+ try {
122
+ const notice = await this.catchup(ctx);
123
+ if (
124
+ !this.isOpen() ||
125
+ ctx.sessionManager.getSessionFile() !== this.sessionFile ||
126
+ (!ctx.isIdle() && !this.isRunning())
127
+ ) {
128
+ reply({
129
+ ok: false,
130
+ rejected: true,
131
+ error: "Target changed context; retry after it settles",
132
+ });
133
+ return;
134
+ }
135
+ submitted = true;
136
+ sendPolicyMessage(
137
+ pi,
138
+ {
139
+ customType: "herdr-agent-message",
140
+ content: `${sender}\n${text}${notice.content}`,
141
+ display: true,
142
+ },
143
+ { triggerTurn: true, deliverAs: "steer" },
144
+ );
145
+ notice.accepted();
146
+ // Voice failure must not turn accepted delivery into a retry.
147
+ try {
148
+ announcePeerMessage(pi, {
149
+ sender: request["sender"] as string,
150
+ text,
151
+ });
152
+ } catch (error) {
153
+ ctx.ui.notify(
154
+ `Peer voice update failed: ${String(error)}`,
155
+ "warning",
156
+ );
157
+ }
158
+ reply({ ok: true, command: false });
159
+ } finally {
160
+ this.pendingPrompts -= 1;
161
+ release();
162
+ }
163
+ } catch (error) {
164
+ reply({
165
+ ok: false,
166
+ rejected: !submitted,
167
+ error: `${submitted ? "Peer delivery failed; inspect the target before retrying" : "Peer delivery rejected"}: ${error instanceof Error ? error.message : String(error)}`,
168
+ });
169
+ }
170
+ }
171
+ }
@@ -0,0 +1,113 @@
1
+ import type { Socket } from "node:net";
2
+ import type {
3
+ ExtensionAPI,
4
+ ExtensionContext,
5
+ } from "@earendil-works/pi-coding-agent";
6
+ import { acceptFocus, readFocus } from "./agents-focus.js";
7
+ import type { AgentFleet } from "./fleet/index.js";
8
+ import { acceptFocusChannel } from "./peer-channel.js";
9
+ import {
10
+ MAX_CHANNEL_FRAME_BYTES,
11
+ socketChannel,
12
+ } from "./remote/shepherdr-channel.mjs";
13
+ import { PEER_PROTOCOL } from "./remote/shepherdr-peer.mjs";
14
+ import type { PaneInfo } from "./types.js";
15
+
16
+ /** Focus admission owns its duplex buffering; the inbox retains authenticated socket lifetime. */
17
+ export function receivePeerFocus(
18
+ pi: ExtensionAPI,
19
+ ctx: ExtensionContext,
20
+ fleet: AgentFleet,
21
+ pane: PaneInfo,
22
+ socket: Socket,
23
+ request: Record<string, unknown>,
24
+ trailing: string,
25
+ reply: (value: object, flushed?: () => void) => void,
26
+ ): void {
27
+ if (request["kind"] === "channel" && pane) {
28
+ let focus;
29
+ try {
30
+ focus = readFocus(request["focus"]);
31
+ } catch (error) {
32
+ reply({ ok: false, rejected: true, error: String(error) });
33
+ return;
34
+ }
35
+ // Hold outbound frames until the admission reply precedes them.
36
+ const pending: unknown[] = [];
37
+ let admitted = false;
38
+ const channel = socketChannel(socket, trailing);
39
+ const receiverChannel = {
40
+ ...channel,
41
+ send(message: unknown) {
42
+ const json = JSON.stringify(message);
43
+ if (
44
+ json === undefined ||
45
+ Buffer.byteLength(json) > MAX_CHANNEL_FRAME_BYTES
46
+ ) {
47
+ channel.close();
48
+ throw new Error("Focus channel frame is too large or not JSON");
49
+ }
50
+ if (admitted) channel.send(message);
51
+ else {
52
+ pending.push(message);
53
+ if (
54
+ pending.length > 64 ||
55
+ Buffer.byteLength(JSON.stringify(pending)) > 1024 * 1024
56
+ ) {
57
+ channel.close();
58
+ throw new Error(
59
+ "Focus channel admission output exceeded its buffer",
60
+ );
61
+ }
62
+ }
63
+ },
64
+ };
65
+ void acceptFocusChannel(pi, receiverChannel, focus, ctx, pane).then(
66
+ () => {
67
+ try {
68
+ socket.write(
69
+ `${JSON.stringify({ protocol: PEER_PROTOCOL, id: request["id"], ok: true })}\n`,
70
+ );
71
+ admitted = true;
72
+ for (const message of pending) channel.send(message);
73
+ pending.length = 0;
74
+ } catch {
75
+ channel.close();
76
+ }
77
+ },
78
+ (error: unknown) => {
79
+ reply(
80
+ {
81
+ ok: false,
82
+ rejected: true,
83
+ error: error instanceof Error ? error.message : String(error),
84
+ },
85
+ () => channel.close(),
86
+ );
87
+ },
88
+ );
89
+ return;
90
+ }
91
+ if (request["kind"] === "focus" && pane) {
92
+ try {
93
+ if (readFocus(request["focus"]).voice === true)
94
+ throw new Error(
95
+ "Voice transfer was not admitted; retry using agents focus with voice:true",
96
+ );
97
+ } catch (error) {
98
+ reply({ ok: false, rejected: true, error: String(error) });
99
+ return;
100
+ }
101
+ socket.setTimeout(60_000, () => socket.destroy());
102
+ void acceptFocus(pi, ctx, fleet, pane, request["focus"]).then(
103
+ () => reply({ ok: true, command: false }),
104
+ (error: unknown) =>
105
+ reply({
106
+ ok: false,
107
+ rejected: !(error instanceof Error && "focusChanged" in error),
108
+ error: error instanceof Error ? error.message : String(error),
109
+ }),
110
+ );
111
+ return;
112
+ }
113
+ }