@howaboua/pi-shepherdr 0.2.12 → 0.2.14

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.
package/src/attachment.ts CHANGED
@@ -64,18 +64,18 @@ export class AgentAttachment {
64
64
  const context = params.context === true;
65
65
  const useBoard = params.board === true;
66
66
  const controllerContext = context
67
- ? this.target.context(ctx, false)
67
+ ? await this.target.context(ctx, false)
68
68
  : undefined;
69
69
  const controllerBoard = useBoard ? binding(ctx) : undefined;
70
- const check = () => {
70
+ const check = async () => {
71
+ const currentContext = controllerContext
72
+ ? await this.target.context(ctx, false)
73
+ : undefined;
71
74
  signal.throwIfAborted();
72
75
  if (
73
76
  ctx.sessionManager.getSessionId() !== controllerSessionId ||
74
77
  (controllerContext &&
75
- !isDeepStrictEqual(
76
- this.target.context(ctx, false),
77
- controllerContext,
78
- )) ||
78
+ !isDeepStrictEqual(currentContext, controllerContext)) ||
79
79
  (controllerBoard && !isDeepStrictEqual(binding(ctx), controllerBoard))
80
80
  )
81
81
  throw new Error(
@@ -102,7 +102,7 @@ export class AgentAttachment {
102
102
  { operation: "attach-inspect" },
103
103
  signal,
104
104
  );
105
- check();
105
+ await check();
106
106
  if (!Check(Snapshot, snapshot))
107
107
  throw new Error(
108
108
  "Target does not support attachment; update and reload Shepherdr",
@@ -113,6 +113,10 @@ export class AgentAttachment {
113
113
  current.contextError ?? "Target context is unavailable",
114
114
  );
115
115
  if (useBoard && current.boardError) throw new Error(current.boardError);
116
+ if (controllerContext && current.context) {
117
+ await this.notes.verify(ctx, current.notes, current.context);
118
+ await check();
119
+ }
116
120
  const upstream = runtime.local
117
121
  ? sessionContextPath(controllerFile)
118
122
  : runtime.client.contextRelayPath();
@@ -129,7 +133,7 @@ export class AgentAttachment {
129
133
  alias: `${controllerContext.agentName}/${segment}`,
130
134
  controllerAlias: `${current.context.agentName}/controller-${randomUUID()}`,
131
135
  ...(runtime.local ? { controllerFile } : {}),
132
- controllerNotes: this.notes.export(ctx),
136
+ controllerNotes: await this.notes.export(ctx),
133
137
  targetNotes: current.notes,
134
138
  },
135
139
  }
@@ -148,6 +152,7 @@ export class AgentAttachment {
148
152
  }
149
153
  : {}),
150
154
  };
155
+ await check();
151
156
  route = { plan, machine: runtime.machine, sessionFile, phase: "pending" };
152
157
  this.notes.checkTransport({ operation: "attach-commit", plan });
153
158
  // A retry after a lost response reuses the same aliases and board identity.
@@ -159,7 +164,7 @@ export class AgentAttachment {
159
164
  { operation: "attach-commit", plan: route.plan },
160
165
  signal,
161
166
  );
162
- check();
167
+ await check();
163
168
  if (!isDeepStrictEqual(accepted, route.plan))
164
169
  throw new Error("Target did not accept the requested attachment");
165
170
  if (route.plan.board)
@@ -173,7 +178,7 @@ export class AgentAttachment {
173
178
  },
174
179
  route.plan.board.controller,
175
180
  );
176
- check();
181
+ await check();
177
182
  if (route.plan.context) this.target.retainIdentity(ctx);
178
183
  if (route.phase !== "ready")
179
184
  this.pi.appendEntry(ROUTE, { ...route, phase: "ready" });
@@ -220,24 +225,46 @@ export class AgentAttachment {
220
225
  const { plan } = route;
221
226
  if ((params.context && !plan.context) || (params.board && !plan.board))
222
227
  throw new Error("Cannot detach a choice that was not attached");
223
- const check = () => {
228
+ const controllerBoard = params.board ? binding(ctx) : undefined;
229
+ const check = async (checkRoute = true) => {
230
+ const currentContext =
231
+ params.context && plan.context
232
+ ? await this.target.context(ctx, false)
233
+ : undefined;
224
234
  signal.throwIfAborted();
225
235
  if (
226
236
  ctx.sessionManager.getSessionId() !== plan.controllerSessionId ||
237
+ (checkRoute &&
238
+ !isDeepStrictEqual(
239
+ attachmentRoutes(ctx).find(
240
+ (entry) =>
241
+ entry.machine === route.machine &&
242
+ entry.sessionFile === route.sessionFile,
243
+ ),
244
+ route,
245
+ )) ||
227
246
  (params.context &&
228
247
  plan.context &&
229
- !isDeepStrictEqual(
230
- this.target.context(ctx, false),
231
- plan.context.controller,
232
- ))
248
+ !isDeepStrictEqual(currentContext, plan.context.controller)) ||
249
+ (controllerBoard && !isDeepStrictEqual(binding(ctx), controllerBoard))
233
250
  )
234
251
  throw new Error(
235
252
  "Controller changed during detach; resume it and retry",
236
253
  );
237
254
  };
238
- check();
255
+ await check();
239
256
  try {
240
- const context = params.context ? this.notes.export(ctx) : undefined;
257
+ if (params.context && plan.context) {
258
+ await this.notes.verify(
259
+ ctx,
260
+ route.detached?.context ?? plan.context.targetNotes,
261
+ plan.context.target,
262
+ true,
263
+ );
264
+ await check();
265
+ }
266
+ const context = params.context ? await this.notes.export(ctx) : undefined;
267
+ await check();
241
268
  this.notes.checkTransport({
242
269
  operation: "detach-commit",
243
270
  plan,
@@ -254,7 +281,7 @@ export class AgentAttachment {
254
281
  },
255
282
  signal,
256
283
  );
257
- check();
284
+ await check();
258
285
  if (
259
286
  !result ||
260
287
  typeof result !== "object" ||
@@ -266,7 +293,8 @@ export class AgentAttachment {
266
293
  if (params.context && plan.context) {
267
294
  if (!("notes" in result))
268
295
  throw new Error("Target checkpoints were not retained");
269
- this.notes.validate(result.notes, plan.context.target);
296
+ await this.notes.verify(ctx, result.notes, plan.context.target, true);
297
+ await check();
270
298
  notes = result.notes;
271
299
  }
272
300
  this.pi.appendEntry(ROUTE, {
@@ -282,7 +310,7 @@ export class AgentAttachment {
282
310
  ...plan.board.desired,
283
311
  sessionId: plan.targetSessionId,
284
312
  });
285
- check();
313
+ await check(false);
286
314
  } catch (error) {
287
315
  throw new Error(
288
316
  `Detach incomplete; retry from the same controller and target with the same choices. ${String(error)}`,
@@ -0,0 +1,115 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import type {
3
+ ExtensionAPI,
4
+ ExtensionContext,
5
+ } from "@earendil-works/pi-coding-agent";
6
+ import {
7
+ contextBriefingWindow,
8
+ recordContextBriefing,
9
+ registerContextBriefing,
10
+ } from "../context-briefing.js";
11
+ import { boardBriefing } from "../messages.js";
12
+ import { binding } from "./identity.js";
13
+
14
+ const OWNER = "shepherdr-board";
15
+ const STATE = "shepherdr-board-awareness";
16
+ interface AwarenessState {
17
+ sessionId: string;
18
+ signature: string;
19
+ epoch: string;
20
+ }
21
+
22
+ /** Board state is sampled once per selected window/membership, never on a timer. */
23
+ export class BoardAwareness {
24
+ private readonly pi: ExtensionAPI;
25
+ private readonly read: (ctx: ExtensionContext) => Promise<unknown>;
26
+ constructor(
27
+ pi: ExtensionAPI,
28
+ read: (ctx: ExtensionContext) => Promise<unknown>,
29
+ ) {
30
+ this.pi = pi;
31
+ this.read = read;
32
+ registerContextBriefing(
33
+ pi,
34
+ "board",
35
+ (ctx) => binding(ctx).enabled,
36
+ (ctx, windowId) => this.record(ctx, windowId),
37
+ );
38
+ }
39
+
40
+ refresh(ctx: ExtensionContext): AwarenessState {
41
+ const own = binding(ctx);
42
+ const signature = JSON.stringify([
43
+ own.boardId,
44
+ own.rootSessionId,
45
+ own.agentName,
46
+ own.upstream,
47
+ own.enabled,
48
+ ]);
49
+ const saved = ctx.sessionManager
50
+ .getEntries()
51
+ .findLast(
52
+ (entry) =>
53
+ entry.type === "custom" &&
54
+ entry.customType === STATE &&
55
+ readState(entry.data).sessionId === own.sessionId,
56
+ );
57
+ if (saved?.type === "custom") {
58
+ const state = readState(saved.data);
59
+ if (state.signature === signature) return state;
60
+ }
61
+ const state = { sessionId: own.sessionId, signature, epoch: randomUUID() };
62
+ this.pi.appendEntry(STATE, state);
63
+ return state;
64
+ }
65
+
66
+ private async record(ctx: ExtensionContext, windowId?: string) {
67
+ const own = binding(ctx);
68
+ const state = this.refresh(ctx);
69
+ if (!own.enabled) return;
70
+ const window = contextBriefingWindow(ctx, windowId);
71
+ const key = JSON.stringify([own.sessionId, window, state.epoch]);
72
+ await recordContextBriefing(this.pi, ctx, OWNER, key, async () => {
73
+ let population: "empty" | "populated" | "unavailable";
74
+ try {
75
+ const value = await this.read(ctx);
76
+ if (!binding(ctx).enabled) return;
77
+ if (
78
+ !value ||
79
+ typeof value !== "object" ||
80
+ !("results" in value) ||
81
+ !Array.isArray(value.results)
82
+ )
83
+ throw new Error("Invalid board population response");
84
+ population = value.results.length ? "populated" : "empty";
85
+ } catch (error) {
86
+ ctx.signal?.throwIfAborted();
87
+ population = "unavailable";
88
+ ctx.ui.notify(`Board status unavailable: ${String(error)}`, "warning");
89
+ }
90
+ ctx.signal?.throwIfAborted();
91
+ if (!binding(ctx).enabled) return;
92
+ if (
93
+ binding(ctx).enabled !== own.enabled ||
94
+ this.refresh(ctx).epoch !== state.epoch
95
+ )
96
+ throw new Error("Board membership changed during its briefing");
97
+ return boardBriefing(Boolean(own.upstream), population);
98
+ });
99
+ }
100
+ }
101
+
102
+ function readState(value: unknown): AwarenessState {
103
+ if (
104
+ !value ||
105
+ typeof value !== "object" ||
106
+ !("sessionId" in value) ||
107
+ typeof value.sessionId !== "string" ||
108
+ !("signature" in value) ||
109
+ typeof value.signature !== "string" ||
110
+ !("epoch" in value) ||
111
+ typeof value.epoch !== "string"
112
+ )
113
+ throw new Error("Invalid saved board awareness");
114
+ return value as AwarenessState;
115
+ }
package/src/board/host.ts CHANGED
@@ -10,6 +10,7 @@ import {
10
10
  sessionContextPath,
11
11
  } from "../remote/shepherdr-context.mjs";
12
12
  import { executeArchive } from "./archive.js";
13
+ import { BoardAwareness } from "./awareness.js";
13
14
  import {
14
15
  type BoardScope,
15
16
  readBoardConfig,
@@ -51,12 +52,14 @@ export class AgentBoard {
51
52
  private readonly pi: ExtensionAPI;
52
53
  private readonly fleet: AgentFleet;
53
54
  private readonly turns: BoardTurns;
55
+ private readonly awareness: BoardAwareness;
54
56
  private refreshTools: (() => void) | undefined;
55
57
  private lastSetting: { sessionId: string; enabled: boolean } | undefined;
56
58
  private configError: string | undefined;
57
59
  constructor(pi: ExtensionAPI, fleet: AgentFleet) {
58
60
  this.pi = pi;
59
61
  this.fleet = fleet;
62
+ this.awareness = new BoardAwareness(pi, (ctx) => this.population(ctx));
60
63
  this.turns = new BoardTurns(pi, (ctx, request) =>
61
64
  this.toOwner(ctx, request),
62
65
  );
@@ -99,11 +102,44 @@ export class AgentBoard {
99
102
  setToolRefresh(refresh: () => void) {
100
103
  this.refreshTools = refresh;
101
104
  }
105
+ private async population(ctx: ExtensionContext) {
106
+ const own = binding(ctx);
107
+ if (own.upstream) {
108
+ const status = await this.toOwner(
109
+ ctx,
110
+ {
111
+ operation: "board-call",
112
+ caller: own,
113
+ params: { action: "help" },
114
+ requestId: "briefing-status",
115
+ },
116
+ ctx.signal,
117
+ );
118
+ if (
119
+ !status ||
120
+ typeof status !== "object" ||
121
+ !("enabled" in status) ||
122
+ typeof status.enabled !== "boolean"
123
+ )
124
+ throw new Error("Board status unavailable");
125
+ if (status.enabled !== own.enabled) {
126
+ saveBinding(this.pi, { ...own, enabled: status.enabled });
127
+ await this.refresh(ctx);
128
+ }
129
+ if (!status.enabled) return;
130
+ }
131
+ return this.execute(
132
+ ctx,
133
+ { action: "search_posts", limit: 1, max_chars_per_post: 1 },
134
+ "briefing",
135
+ );
136
+ }
102
137
  enabled(ctx: ExtensionContext | undefined) {
103
138
  return ctx ? binding(ctx).enabled : false;
104
139
  }
105
140
  async refresh(ctx: ExtensionContext) {
106
141
  const own = binding(ctx);
142
+ this.awareness.refresh(ctx);
107
143
  const setting = own.upstream ? undefined : rootBoardSetting(ctx);
108
144
  if (setting?.error && setting.error !== this.configError)
109
145
  ctx.ui.notify(`Board disabled: ${setting.error}`, "error");
@@ -159,12 +195,16 @@ export class AgentBoard {
159
195
  throw new Error(
160
196
  "Board is off; the user can enable it in /herdr → Settings",
161
197
  );
162
- return this.toOwner(ctx, {
163
- operation: "board-call",
164
- caller,
165
- params,
166
- requestId,
167
- });
198
+ return this.toOwner(
199
+ ctx,
200
+ {
201
+ operation: "board-call",
202
+ caller,
203
+ params,
204
+ requestId,
205
+ },
206
+ ctx.signal,
207
+ );
168
208
  }
169
209
  async prepare(
170
210
  ctx: ExtensionContext,
package/src/board/tool.ts CHANGED
@@ -9,9 +9,6 @@ export function createBoardTool(board: AgentBoard) {
9
9
  label: "Message board",
10
10
  description:
11
11
  "Shared discussions and saved board history; call help for actions",
12
- promptGuidelines: [
13
- "board is shared with your agent tree. Use it for plans, decisions and findings in substantial multi-agent work, not routine delegation. Use agents for task assignment and urgent messages",
14
- ],
15
12
  parameters: BoardParameters,
16
13
  executionMode: "sequential",
17
14
  async execute(id, params, signal, _onUpdate, ctx) {
@@ -0,0 +1,226 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import {
3
+ buildSessionContext,
4
+ type ExtensionAPI,
5
+ type ExtensionContext,
6
+ } from "@earendil-works/pi-coding-agent";
7
+ import type {
8
+ CODEX_CONTEXT_BRIEFING_TYPE,
9
+ CodexContextBriefing,
10
+ CodexContextBriefingHandler,
11
+ } from "@howaboua/pi-codex-conversion/developer-messages";
12
+ import { registerInferenceBriefing } from "./delivery.js";
13
+
14
+ // Conversion projects this durable protocol in inference, compaction and native replay.
15
+ const BRIEFING: typeof CODEX_CONTEXT_BRIEFING_TYPE = "codex-context-briefing";
16
+
17
+ export function registerContextBriefing(
18
+ pi: ExtensionAPI,
19
+ name: string,
20
+ relevant: (ctx: ExtensionContext) => boolean,
21
+ record: CodexContextBriefingHandler,
22
+ ) {
23
+ const hosted = registerInferenceBriefing(pi, record);
24
+ const warned = new Set<string>();
25
+ pi.on("context_with_system", async (event, ctx) => {
26
+ if (hosted.hosted()) return;
27
+ if (
28
+ hosted.outdated &&
29
+ relevant(ctx) &&
30
+ !warned.has(ctx.sessionManager.getSessionId())
31
+ ) {
32
+ warned.add(ctx.sessionManager.getSessionId());
33
+ ctx.ui.notify(
34
+ `Update Codex Conversion and reload to preserve ${name} briefings through its context rollover and native replay. Native Pi briefings and other agent tools remain available.`,
35
+ "warning",
36
+ );
37
+ }
38
+ try {
39
+ await record(ctx, undefined, event.messages);
40
+ return { messages: projectNative(ctx, event.messages) };
41
+ } catch (error) {
42
+ ctx.abort();
43
+ throw error;
44
+ }
45
+ });
46
+ }
47
+
48
+ export function contextBriefingWindow(
49
+ ctx: ExtensionContext,
50
+ windowId?: string,
51
+ ) {
52
+ const branch = ctx.sessionManager.getBranch();
53
+ const compaction = branch.findLastIndex(
54
+ (entry) =>
55
+ entry.type === "compaction" &&
56
+ !(
57
+ entry.details &&
58
+ typeof entry.details === "object" &&
59
+ "strategy" in entry.details &&
60
+ entry.details.strategy === "codex-context-window"
61
+ ),
62
+ );
63
+ const boundary = branch.findLastIndex(
64
+ (entry) =>
65
+ entry.type === "custom_message" &&
66
+ entry.customType === "codex-context-window" &&
67
+ entry.details &&
68
+ typeof entry.details === "object" &&
69
+ "contextManagement" in entry.details &&
70
+ entry.details.contextManagement &&
71
+ typeof entry.details.contextManagement === "object" &&
72
+ "kind" in entry.details.contextManagement &&
73
+ entry.details.contextManagement.kind === "window",
74
+ );
75
+ return compaction > boundary
76
+ ? branch[compaction]!.id
77
+ : (windowId ?? ctx.sessionManager.getSessionId());
78
+ }
79
+
80
+ export function hasContextRollover(ctx: ExtensionContext): boolean {
81
+ return ctx.sessionManager.getBranch().some((entry) => {
82
+ if (entry.type === "compaction") return true;
83
+ if (
84
+ entry.type !== "custom_message" ||
85
+ entry.customType !== "codex-context-window" ||
86
+ !entry.details ||
87
+ typeof entry.details !== "object" ||
88
+ !("contextManagement" in entry.details)
89
+ )
90
+ return false;
91
+ const window = entry.details.contextManagement;
92
+ return Boolean(
93
+ window &&
94
+ typeof window === "object" &&
95
+ "kind" in window &&
96
+ window.kind === "window" &&
97
+ "windowNumber" in window &&
98
+ typeof window.windowNumber === "number" &&
99
+ window.windowNumber > 0,
100
+ );
101
+ });
102
+ }
103
+
104
+ export async function recordContextBriefing(
105
+ pi: ExtensionAPI,
106
+ ctx: ExtensionContext,
107
+ owner: string,
108
+ key: string,
109
+ content: () => Promise<string | undefined>,
110
+ ) {
111
+ const saved = ctx.sessionManager
112
+ .getEntries()
113
+ .findLast(
114
+ (entry) =>
115
+ entry.type === "custom" &&
116
+ entry.customType === BRIEFING &&
117
+ readBriefing(entry.data).owner === owner &&
118
+ readBriefing(entry.data).key === key,
119
+ );
120
+ if (saved?.type === "custom") {
121
+ // Tree may select an ancestor before its metadata child. Reuse immutable bytes/ID.
122
+ if (
123
+ !ctx.sessionManager
124
+ .getBranch()
125
+ .some(
126
+ (entry) =>
127
+ entry.type === "custom" &&
128
+ entry.customType === BRIEFING &&
129
+ readBriefing(entry.data).owner === owner &&
130
+ readBriefing(entry.data).key === key,
131
+ )
132
+ )
133
+ pi.appendEntry(BRIEFING, readBriefing(saved.data));
134
+ return;
135
+ }
136
+ const value = await content();
137
+ if (value === undefined) return;
138
+ pi.appendEntry(BRIEFING, {
139
+ protocol: 1,
140
+ id: randomUUID(),
141
+ owner,
142
+ key,
143
+ content: value,
144
+ } satisfies CodexContextBriefing);
145
+ }
146
+
147
+ function projectNative(
148
+ ctx: ExtensionContext,
149
+ messages: NativeMessage[],
150
+ ): NativeMessage[] {
151
+ const entries = ctx.sessionManager.getBranch().map((entry) => {
152
+ if (entry.type !== "custom" || entry.customType !== BRIEFING) return entry;
153
+ const briefing = readBriefing(entry.data);
154
+ return {
155
+ ...entry,
156
+ type: "custom_message" as const,
157
+ content: briefing.content,
158
+ display: false,
159
+ details: briefing,
160
+ };
161
+ });
162
+ const reconstructed = buildSessionContext(entries).messages;
163
+ const positions = new Map<string, number[]>();
164
+ messages.forEach((message, index) => {
165
+ const key = messageKey(message);
166
+ const indices = positions.get(key) ?? [];
167
+ indices.push(index);
168
+ positions.set(key, indices);
169
+ });
170
+ const insertions = new Map<number, NativeMessage[]>();
171
+ let pending: NativeMessage[] = [];
172
+ let last = messages[0]?.role === "system" ? 0 : -1;
173
+ const insert = (index: number) => {
174
+ if (!pending.length) return;
175
+ const position =
176
+ messages[0]?.role === "system" ? Math.max(1, index) : index;
177
+ insertions.set(position, [...(insertions.get(position) ?? []), ...pending]);
178
+ pending = [];
179
+ };
180
+ for (const message of reconstructed) {
181
+ const index = positions.get(messageKey(message))?.shift();
182
+ if (index !== undefined) {
183
+ insert(index);
184
+ last = index;
185
+ } else if (message.role === "custom" && message.customType === BRIEFING) {
186
+ pending.push(message);
187
+ }
188
+ }
189
+ insert(last + 1);
190
+ return messages
191
+ .flatMap((message, index) => [...(insertions.get(index) ?? []), message])
192
+ .concat(insertions.get(messages.length) ?? []);
193
+ }
194
+
195
+ type NativeMessage = ReturnType<typeof buildSessionContext>["messages"][number];
196
+ function messageKey(message: NativeMessage) {
197
+ return JSON.stringify([
198
+ message.role,
199
+ message.timestamp,
200
+ message.role === "custom"
201
+ ? message.customType === BRIEFING
202
+ ? readBriefing(message.details).id
203
+ : message.customType
204
+ : message.role === "toolResult"
205
+ ? message.toolCallId
206
+ : undefined,
207
+ ]);
208
+ }
209
+ function readBriefing(value: unknown): CodexContextBriefing {
210
+ if (
211
+ !value ||
212
+ typeof value !== "object" ||
213
+ !("protocol" in value) ||
214
+ value.protocol !== 1 ||
215
+ !("id" in value) ||
216
+ typeof value.id !== "string" ||
217
+ !("owner" in value) ||
218
+ typeof value.owner !== "string" ||
219
+ !("key" in value) ||
220
+ typeof value.key !== "string" ||
221
+ !("content" in value) ||
222
+ typeof value.content !== "string"
223
+ )
224
+ throw new Error("Invalid saved context briefing");
225
+ return value as CodexContextBriefing;
226
+ }