@howaboua/pi-shepherdr 0.2.9 → 0.2.10

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,100 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import type {
3
+ ExtensionAPI,
4
+ ExtensionContext,
5
+ } from "@earendil-works/pi-coding-agent";
6
+ import { sendPolicyMessage } from "../delivery.js";
7
+ import { type BoardBinding, binding } from "./identity.js";
8
+ import type { BoardEnvelope } from "./protocol.js";
9
+
10
+ type ActiveEnvelope = Extract<BoardEnvelope, { operation: "board-active" }>;
11
+ type NoticeEnvelope = Extract<BoardEnvelope, { operation: "board-notify" }>;
12
+
13
+ /** Turn IDs are transient capabilities. A stale snapshot cannot reach a later turn. */
14
+ export class BoardTurns {
15
+ private current: { ctx: ExtensionContext; turnId: string } | undefined;
16
+ readonly active = new Map<string, { sessionId: string; turnId: string }>();
17
+ constructor(
18
+ pi: ExtensionAPI,
19
+ register: (
20
+ ctx: ExtensionContext,
21
+ request: ActiveEnvelope,
22
+ ) => Promise<unknown>,
23
+ ) {
24
+ pi.on("session_start", () => {
25
+ this.current = undefined;
26
+ this.active.clear();
27
+ });
28
+ pi.on("agent_start", async (_event, ctx) => {
29
+ const own = binding(ctx);
30
+ if (!own.enabled) return;
31
+ const turnId = randomUUID();
32
+ this.current = { ctx, turnId };
33
+ try {
34
+ await register(ctx, { operation: "board-active", caller: own, turnId });
35
+ } catch (error) {
36
+ ctx.ui.notify(
37
+ `Board notifications unavailable: ${String(error)}`,
38
+ "warning",
39
+ );
40
+ }
41
+ });
42
+ const stop = async () => {
43
+ const current = this.current;
44
+ this.current = undefined;
45
+ if (!current) return;
46
+ try {
47
+ await register(current.ctx, {
48
+ operation: "board-active",
49
+ caller: binding(current.ctx),
50
+ turnId: null,
51
+ previousTurnId: current.turnId,
52
+ });
53
+ } catch {
54
+ /* No retry or delayed removal may affect a later turn. */
55
+ }
56
+ };
57
+ pi.on("agent_end", stop);
58
+ pi.on("agent_settled", stop);
59
+ pi.on("session_shutdown", async () => {
60
+ await stop();
61
+ this.active.clear();
62
+ });
63
+ this.deliver = (request) => {
64
+ const current = this.current;
65
+ if (!current || current.turnId !== request.turnId || current.ctx.isIdle())
66
+ return false;
67
+ const own = binding(current.ctx);
68
+ if (
69
+ !own.enabled ||
70
+ own.boardId !== request.boardId ||
71
+ own.sessionId !== request.sessionId ||
72
+ own.agentName !== request.target
73
+ )
74
+ return false;
75
+ // No await between running-turn check and steering. Never use the idle kickoff.
76
+ sendPolicyMessage(
77
+ pi,
78
+ {
79
+ customType: "shepherdr-board-post",
80
+ content: `Board post ${JSON.stringify(request.notice)}`,
81
+ display: true,
82
+ },
83
+ { deliverAs: "steer" },
84
+ );
85
+ return true;
86
+ };
87
+ }
88
+ readonly deliver: (request: NoticeEnvelope) => boolean;
89
+ register(caller: BoardBinding, request: ActiveEnvelope) {
90
+ if (request.turnId)
91
+ this.active.set(caller.agentName, {
92
+ sessionId: caller.sessionId,
93
+ turnId: request.turnId,
94
+ });
95
+ else if (
96
+ this.active.get(caller.agentName)?.turnId === request.previousTurnId
97
+ )
98
+ this.active.delete(caller.agentName);
99
+ }
100
+ }
package/src/controller.ts CHANGED
@@ -2,6 +2,8 @@ import type {
2
2
  ExtensionAPI,
3
3
  ExtensionContext,
4
4
  } from "@earendil-works/pi-coding-agent";
5
+ import type { AgentBoard } from "./board/host.js";
6
+ import { openBoardSettings } from "./board/settings.js";
5
7
  import { sendPolicyMessage } from "./delivery.js";
6
8
  import type { AgentFleet } from "./fleet.js";
7
9
  import { loadAgentProfiles } from "./profiles.js";
@@ -16,12 +18,24 @@ const NORMAL_MESSAGE = "Work normally. Delegate only when useful or requested.";
16
18
  export function registerAgentController(
17
19
  pi: ExtensionAPI,
18
20
  fleet: AgentFleet,
21
+ board: AgentBoard,
19
22
  ): void {
20
23
  let orchestrationEnabled = false;
21
24
  pi.registerCommand("herdr", {
22
- description: "Toggle agent orchestration or reconnect machines",
25
+ description: "Toggle orchestration, message board, or reconnect machines",
23
26
  getArgumentCompletions: (prefix) =>
24
- ["connect"]
27
+ [
28
+ "connect",
29
+ "board",
30
+ "board on",
31
+ "board off",
32
+ "board inherit",
33
+ "board on folder",
34
+ "board off folder",
35
+ "board inherit folder",
36
+ "board on global",
37
+ "board off global",
38
+ ]
25
39
  .filter((action) => action.startsWith(prefix.trim().toLowerCase()))
26
40
  .map((value) => ({ label: value, value })),
27
41
  handler: async (args, ctx) => {
@@ -66,7 +80,37 @@ export function registerAgentController(
66
80
  }
67
81
  return;
68
82
  }
69
- ctx.ui.notify("Usage: /herdr [connect [machine]]", "warning");
83
+ if (action === "board") {
84
+ try {
85
+ if (rest.length === 0) {
86
+ if (ctx.mode === "tui") await openBoardSettings(ctx, board);
87
+ else ctx.ui.notify(board.status(ctx), "info");
88
+ } else if (
89
+ rest.length <= 2 &&
90
+ (rest[0] === "on" || rest[0] === "off" || rest[0] === "inherit") &&
91
+ (rest[1] === undefined ||
92
+ rest[1] === "session" ||
93
+ rest[1] === "folder" ||
94
+ rest[1] === "global") &&
95
+ !(rest[0] === "inherit" && rest[1] === "global")
96
+ ) {
97
+ await board.setSetting(
98
+ ctx,
99
+ rest[1] ?? "session",
100
+ rest[0] === "inherit" ? undefined : rest[0] === "on",
101
+ );
102
+ ctx.ui.notify(board.status(ctx), "info");
103
+ } else
104
+ ctx.ui.notify(
105
+ "Usage: /herdr board [on|off|inherit [session|folder] | on|off global]",
106
+ "warning",
107
+ );
108
+ } catch (error) {
109
+ ctx.ui.notify(String(error), "error");
110
+ }
111
+ return;
112
+ }
113
+ ctx.ui.notify("Usage: /herdr [connect [machine] | board]", "warning");
70
114
  },
71
115
  });
72
116
 
package/src/delivery.ts CHANGED
@@ -142,7 +142,14 @@ export function sendPolicyMessage(
142
142
  options: CodexDeveloperMessageOptions,
143
143
  ): void {
144
144
  if (senders.get(pi)?.(pi, message, options)) return;
145
- pi.sendMessage(message, options);
145
+ // Without Conversion there is no Notes admission to defer. Persist before
146
+ // kickoff so failed preflight cannot strand an accepted report in memory.
147
+ pi.sendMessage(
148
+ message,
149
+ options.deliverAs === "nextTurn"
150
+ ? { ...options, deliverAs: "steer" }
151
+ : options,
152
+ );
146
153
  }
147
154
 
148
155
  function isUnavailable(error: unknown): boolean {
package/src/messages.ts CHANGED
@@ -23,7 +23,7 @@ const REALTIME_VOICE_PROMPT_CHANNEL =
23
23
  "@howaboua/pi-codex-conversion/realtime-voice-prompt/v1";
24
24
  const MAX_REALTIME_VOICE_PROMPT_BYTES = 8 * 1_024;
25
25
  const DELEGATED_WORKER_GUIDANCE =
26
- "When finished or blocked from progressing, end with an assistant reply. Use send only for useful mid-run updates while work can continue. Do not watch your parent or use messaging to wait for a reply.";
26
+ "If blocked mid-run, use a question-asking tool, not peer messages. Without one, end with the blocker. Finish with an assistant reply, not a separate send report; never watch your parent.";
27
27
 
28
28
  function xml(value: string): string {
29
29
  return value
@@ -385,7 +385,7 @@ export function injectAgentEvent(
385
385
  const message = agentEvent(options);
386
386
  const idle = ctx.isIdle();
387
387
  const delivery = idle
388
- ? { triggerTurn: false, deliverAs: "steer" as const }
388
+ ? { triggerTurn: false, deliverAs: "nextTurn" as const }
389
389
  : { deliverAs: "steer" as const };
390
390
  sendPolicyMessage(
391
391
  pi,
package/src/peer-inbox.ts CHANGED
@@ -142,7 +142,10 @@ async function openInbox(
142
142
  content: sender,
143
143
  display: true,
144
144
  },
145
- { triggerTurn: false, deliverAs: "steer" },
145
+ {
146
+ triggerTurn: false,
147
+ deliverAs: idle && !command ? "nextTurn" : "steer",
148
+ },
146
149
  );
147
150
  pi.sendUserMessage(text, {
148
151
  expandPromptTemplates: true,
@@ -163,11 +166,11 @@ async function openInbox(
163
166
  display: true,
164
167
  },
165
168
  idle
166
- ? { triggerTurn: false, deliverAs: "steer" }
169
+ ? { triggerTurn: false, deliverAs: "nextTurn" }
167
170
  : { deliverAs: "steer" },
168
171
  );
169
- // Appending then claiming the shared kickoff also coalesces arrivals
170
- // during async preparation, when Pi still reports itself idle.
172
+ // Keep arrivals out of history until idle rollover and preparation
173
+ // finish. The shared kickoff coalesces arrivals during preparation.
171
174
  if (idle) startPreparedIdleTurn(pi, ctx);
172
175
  // Voice failure must not turn accepted delivery into a retry.
173
176
  try {
@@ -7,6 +7,8 @@ import type {
7
7
  SharedContextRequest,
8
8
  SharedContextResult,
9
9
  } from "@howaboua/pi-codex-conversion/context-sharing";
10
+ import type { AgentBoard } from "./board/host.js";
11
+ import { isBoardEnvelope } from "./board/protocol.js";
10
12
  import type { AgentFleet, ConnectedMachine } from "./fleet.js";
11
13
  import { sessionPath } from "./herdr.js";
12
14
  import {
@@ -38,16 +40,19 @@ export class SharedAgentContext {
38
40
  private readonly pi: ExtensionAPI;
39
41
  private readonly fleet: AgentFleet;
40
42
  private readonly getService: () => ContextSharingService | undefined;
43
+ private readonly board: AgentBoard;
41
44
  private running = false;
42
45
 
43
46
  constructor(
44
47
  pi: ExtensionAPI,
45
48
  fleet: AgentFleet,
46
49
  getService: () => ContextSharingService | undefined,
50
+ board: AgentBoard,
47
51
  ) {
48
52
  this.pi = pi;
49
53
  this.fleet = fleet;
50
54
  this.getService = getService;
55
+ this.board = board;
51
56
  pi.on("agent_start", () => {
52
57
  this.running = true;
53
58
  });
@@ -61,6 +66,7 @@ export class SharedAgentContext {
61
66
  value: unknown,
62
67
  signal?: AbortSignal,
63
68
  ): Promise<unknown> {
69
+ if (isBoardEnvelope(value)) return this.board.handle(ctx, value, signal);
64
70
  if (!value || typeof value !== "object")
65
71
  throw new Error("Invalid shared context request");
66
72
  const service = this.getService();
@@ -219,6 +225,7 @@ export class SharedAgentContext {
219
225
  export async function registerSharedAgentContext(
220
226
  pi: ExtensionAPI,
221
227
  fleet: AgentFleet,
228
+ board: AgentBoard,
222
229
  ): Promise<SharedAgentContext> {
223
230
  let api:
224
231
  | typeof import("@howaboua/pi-codex-conversion/context-sharing")
@@ -247,7 +254,12 @@ export async function registerSharedAgentContext(
247
254
  );
248
255
  }
249
256
  const connection = api?.connectCodexContextSharing(pi);
250
- const shared = new SharedAgentContext(pi, fleet, () => connection?.service);
257
+ const shared = new SharedAgentContext(
258
+ pi,
259
+ fleet,
260
+ () => connection?.service,
261
+ board,
262
+ );
251
263
  let close: (() => Promise<void>) | undefined;
252
264
  let unregister: (() => void) | undefined;
253
265
  pi.on("session_start", async (_event, ctx) => {
@@ -275,9 +287,8 @@ export async function registerSharedAgentContext(
275
287
  await close?.();
276
288
  connection?.dispose();
277
289
  });
278
- if (connection)
279
- fleet.setContextRelay((ctx, request, signal) =>
280
- shared.handle(ctx, request, signal),
281
- );
290
+ fleet.setContextRelay((ctx, request, signal) =>
291
+ shared.handle(ctx, request, signal),
292
+ );
282
293
  return shared;
283
294
  }