@howaboua/pi-agent-board 0.0.3 → 0.0.5

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/briefing.ts CHANGED
@@ -5,28 +5,26 @@ export function boardBriefing(
5
5
  ) {
6
6
  const state =
7
7
  population === "populated"
8
- ? gpt
9
- ? "Read relevantboardthreads."
10
- : "Read relevant board threads."
8
+ ? "Read relevant board threads."
11
9
  : population === "empty"
12
10
  ? gpt
13
- ? "Sharedboard available; posts=none."
11
+ ? "Shared board available; posts=none."
14
12
  : "Shared board available; no posts yet."
15
13
  : gpt
16
- ? "Sharedboard status unavailable; board help→retry read when available."
14
+ ? "Shared board status unavailable; board help→retry read when available."
17
15
  : "Shared board status unavailable. Check board help and retry reading when available.";
18
16
  return [
19
17
  state,
20
18
  member
21
19
  ? gpt
22
- ? "Root owns setup; follow assignedtask."
20
+ ? "Root owns setup; follow assigned task."
23
21
  : "The root agent owns setup; follow your assigned task."
24
22
  : "",
25
23
  gpt
26
- ? "Posts=work-changing ownership/decisions/findings/blockers only. Existingthread replies; link≠repeat. Personalcheckpoints→notes. No ack/statusspam/duplicate completionreports."
24
+ ? "Posts=work-changing ownership/decisions/findings/blockers only. Existing thread replies; link≠repeat. Personal checkpoints→notes. No ack/status spam/duplicate completion reports."
27
25
  : "Post only new information that changes another agent's work: ownership, decisions, findings or blockers. Reply in existing threads; link rather than repeat. Keep personal checkpoints in notes. Skip acknowledgements, routine status and duplicated completion reports.",
28
26
  gpt
29
- ? "Channels=workstreams; threads=topics. Reuse relevantchannels≠catchalls. Newchannel requires distinctcoordinationpurpose; never task/result announcement only."
27
+ ? "Channels=workstreams; threads=topics. Reuse relevant channels≠catchalls. New channel requires distinct coordination purpose; never task/result announcement only."
30
28
  : "Channels group shared workstreams; threads group topics. Reuse a relevant channel, not a catch-all. Create a channel only for a distinct coordination need, never just to announce a task or result.",
31
29
  ]
32
30
  .filter(Boolean)
@@ -3,6 +3,7 @@ import {
3
3
  buildSessionContext,
4
4
  type ExtensionAPI,
5
5
  type ExtensionContext,
6
+ type SessionEntry,
6
7
  } from "@earendil-works/pi-coding-agent";
7
8
  import type {
8
9
  CODEX_CONTEXT_BRIEFING_TYPE,
@@ -61,47 +62,64 @@ export function contextBriefingWindow(
61
62
  entry.details.strategy === "codex-context-window"
62
63
  ),
63
64
  );
64
- const boundary = branch.findLastIndex(
65
- (entry) =>
66
- entry.type === "custom_message" &&
67
- entry.customType === "codex-context-window" &&
68
- entry.details &&
69
- typeof entry.details === "object" &&
70
- "contextManagement" in entry.details &&
71
- entry.details.contextManagement &&
72
- typeof entry.details.contextManagement === "object" &&
73
- "kind" in entry.details.contextManagement &&
74
- entry.details.contextManagement.kind === "window",
75
- );
65
+ const boundary = branch.findLastIndex((entry) => briefingIdentity(entry));
76
66
  return compaction > boundary
77
67
  ? branch[compaction]!.id
78
- : (windowId ?? ctx.sessionManager.getSessionId());
68
+ : (windowId ??
69
+ (boundary >= 0
70
+ ? briefingIdentity(branch[boundary]!)?.currentWindowId
71
+ : undefined) ??
72
+ ctx.sessionManager.getSessionId());
79
73
  }
80
74
 
81
75
  export function hasContextRollover(ctx: ExtensionContext): boolean {
82
76
  return ctx.sessionManager.getBranch().some((entry) => {
83
77
  if (entry.type === "compaction") return true;
84
- if (
85
- entry.type !== "custom_message" ||
86
- entry.customType !== "codex-context-window" ||
87
- !entry.details ||
88
- typeof entry.details !== "object" ||
89
- !("contextManagement" in entry.details)
90
- )
91
- return false;
92
- const window = entry.details.contextManagement;
93
- return Boolean(
94
- window &&
95
- typeof window === "object" &&
96
- "kind" in window &&
97
- window.kind === "window" &&
98
- "windowNumber" in window &&
99
- typeof window.windowNumber === "number" &&
100
- window.windowNumber > 0,
101
- );
78
+ return (briefingIdentity(entry)?.windowNumber ?? 0) > 0;
102
79
  });
103
80
  }
104
81
 
82
+ /** Consume owner-authored identities without depending on an optional runtime. */
83
+ function briefingIdentity(entry: SessionEntry) {
84
+ if (entry.type !== "custom_message") return;
85
+ const details = entry.details;
86
+ if (!details || typeof details !== "object") return;
87
+ let identity: unknown;
88
+ if (
89
+ entry.customType === "notes-compaction:window:v1" &&
90
+ "protocol" in details &&
91
+ details.protocol === 1 &&
92
+ "kind" in details &&
93
+ details.kind === "window" &&
94
+ "identity" in details
95
+ )
96
+ identity = details.identity;
97
+ else if (
98
+ entry.customType === "codex-context-window" &&
99
+ "contextManagement" in details &&
100
+ details.contextManagement &&
101
+ typeof details.contextManagement === "object" &&
102
+ "kind" in details.contextManagement &&
103
+ details.contextManagement.kind === "window"
104
+ )
105
+ identity = details.contextManagement;
106
+ if (
107
+ identity &&
108
+ typeof identity === "object" &&
109
+ "currentWindowId" in identity &&
110
+ typeof identity.currentWindowId === "string" &&
111
+ identity.currentWindowId &&
112
+ "windowNumber" in identity &&
113
+ typeof identity.windowNumber === "number" &&
114
+ Number.isInteger(identity.windowNumber) &&
115
+ identity.windowNumber >= 0
116
+ )
117
+ return {
118
+ currentWindowId: identity.currentWindowId,
119
+ windowNumber: identity.windowNumber,
120
+ };
121
+ }
122
+
105
123
  export async function recordContextBriefing(
106
124
  pi: ExtensionAPI,
107
125
  ctx: ExtensionContext,
package/src/contract.ts CHANGED
@@ -1,7 +1,10 @@
1
- import { StringEnum, Type } from "@earendil-works/pi-ai";
2
- import type { Static } from "typebox";
1
+ import { type Static, Type } from "typebox";
3
2
  import { Check } from "typebox/value";
4
3
 
4
+ function StringEnum<T extends readonly string[]>(values: T) {
5
+ return Type.Unsafe<T[number]>({ type: "string", enum: values });
6
+ }
7
+
5
8
  const BOARD_ACTIONS = [
6
9
  "help",
7
10
  "list_boards",
@@ -134,7 +137,6 @@ export function parseBoardRequest(value: unknown): BoardParams {
134
137
  "thread_id",
135
138
  "message_id",
136
139
  "after_message_id",
137
- "board_id",
138
140
  ] as const) {
139
141
  const id = request[field];
140
142
  if (
@@ -146,6 +148,11 @@ export function parseBoardRequest(value: unknown): BoardParams {
146
148
  throw new Error(`${field} must be a UUID`);
147
149
  if (id !== undefined) request[field] = id.toLowerCase();
148
150
  }
151
+ if (
152
+ request.board_id !== undefined &&
153
+ !/^[a-zA-Z0-9_.-]+$/.test(request.board_id)
154
+ )
155
+ throw new Error("Invalid board_id");
149
156
  if (request.action === "post")
150
157
  exactlyOne(request, ["channel_name", "new_channel_name", "thread_id"]);
151
158
  if (request.action === "subscribe" || request.action === "unsubscribe")
@@ -162,7 +169,7 @@ export function required(value: string | undefined, field: string): string {
162
169
  }
163
170
  export function agentPath(value: string, caller: string): string {
164
171
  const path = value.startsWith("/") ? value : `${caller}/${value}`;
165
- if (!/^\/root(?:\/[a-zA-Z0-9_-]+)*$/.test(path))
172
+ if (!/^\/[a-zA-Z0-9_.-]+(?:\/[a-zA-Z0-9_-]+)*$/.test(path))
166
173
  throw new Error("Invalid agent path");
167
174
  return path;
168
175
  }
@@ -189,7 +196,7 @@ export const boardHelp = {
189
196
  notify:
190
197
  "agents_to_notify is one-time, excludes author; only running turns, no waking or offline notices",
191
198
  agents:
192
- "Use spawn's boardAgent; absolute /root/... or child path relative to you, not a pane or contextAgent",
199
+ "Agent reference /<Pi session ID>; saved legacy references remain valid",
193
200
  paging:
194
201
  "limit default20, cap50; cursor opaque, keep query/sort/full unchanged. Concurrent changes may shift pages",
195
202
  summaries:
@@ -214,23 +221,24 @@ export function gptBoardHelp(value: unknown): unknown {
214
221
  return value;
215
222
  const compact: typeof boardHelp.rules = {
216
223
  scope:
217
- "Default: your tree. board_id browses saved history only, never writes. Discover via list_boards",
218
- post: "text required. Exactly one: channel_name, new_channel_name, thread_id. Thread ID=first post ID. New channel subscribes author to first posts",
219
- set_status: boardHelp.rules.set_status,
224
+ "Default=your tree; board_id→saved history READONLY; discover→list_boards",
225
+ post: "text required; EXACTLY one: channel_name|new_channel_name|thread_id. thread_id=first post ID; new channel→author subscribed to first posts",
226
+ set_status:
227
+ "Parent session ONLY; completed=user confirms done; abandoned=user drops it; NOT agents finish. Closed→reopen BEFORE reply",
220
228
  subscriptions:
221
- "Exactly one: channel_name/thread_id. Channel=first posts, thread=replies. target_agent defaults to you. Posting subscribes author to thread unless explicitly unsubscribed",
229
+ "EXACTLY one: channel_name|thread_id; channel=first posts, thread=replies; target_agent=you by default; posting→subscribe author UNLESS explicitly unsubscribed",
222
230
  notify:
223
- "agents_to_notify: one-time, excludes author. Running turns only, no waking/offline notices",
224
- agents:
225
- "Use spawn's boardAgent, absolute /root/... or relative child path. Never pane/contextAgent",
231
+ "agents_to_notify=once, excludes author; running turns ONLY; NO waking/offline notices",
232
+ agents: "Agent=/<Pi session ID>; legacy references accepted",
226
233
  paging:
227
- "limit default20 cap50. Opaque cursor, unchanged query/sort/full. Concurrent changes may shift pages",
228
- summaries: boardHelp.rules.summaries,
234
+ "limit default20 cap50; opaque cursor→unchanged query/sort/full; concurrent changes MAY shift pages",
235
+ summaries:
236
+ "Closing MAY summarise IF enabled; summarised threads return/search summaries ONLY; full=true reads/searches originals; summary author filters=participants; read_post=originals ALWAYS",
229
237
  order:
230
- "Newest first. get_channels: activity. list_threads sort=created|activity. read_thread: newest replies, root repeated each page",
231
- text: "Case-insensitive substring search. max_chars_per_post default1000. read_post: Unicode-character offsets, limit_chars default20000. Continue at next_offset_chars<n_chars",
238
+ "Newest first; get_channels→activity; list_threads sort=created|activity; read_thread→newest replies+root EVERY page",
239
+ text: "Case-insensitive substring; max_chars_per_post default1000; read_post→Unicode-char offsets, limit_chars default20000; next_offset_chars<n_chars→continue",
232
240
  budget:
233
- "Post cap64KiB. Channel: 1-128 UTF-8 bytes, no edge whitespace/control characters. Results cap8000 serialized UTF-8 bytes. Reads may reduce limits; continue returned cursor/offset",
241
+ "Post≤64KiB; channel=1-128 UTF-8 bytes, NO edge whitespace/control chars; results≤8000 serialized UTF-8 bytes; reads MAY lower limits; continue returned cursor/offset",
234
242
  };
235
243
  return {
236
244
  ...value,
package/src/identity.ts CHANGED
@@ -1,21 +1,26 @@
1
1
  import { resolve } from "node:path";
2
- import { Type } from "@earendil-works/pi-ai";
3
2
  import type {
4
3
  ExtensionAPI,
5
4
  ExtensionContext,
6
5
  } from "@earendil-works/pi-coding-agent";
7
- import type { Static } from "typebox";
6
+ import { type Static, Type } from "typebox";
8
7
  import { Check } from "typebox/value";
9
8
  import { readBoardConfig } from "./config.js";
10
9
 
11
- const uuid = Type.String({ pattern: "^[a-f0-9-]{36}$" });
10
+ const nativeId = Type.String({ pattern: "^[a-zA-Z0-9_.-]+$" });
12
11
  export const BindingSchema = Type.Object(
13
12
  {
14
13
  protocol: Type.Literal(1),
15
- boardId: uuid,
16
- rootSessionId: uuid,
17
- sessionId: uuid,
18
- agentName: Type.String({ pattern: "^/root(?:/[a-zA-Z0-9_-]+)*$" }),
14
+ boardId: nativeId,
15
+ rootSessionId: nativeId,
16
+ sessionId: nativeId,
17
+ agentName: Type.String({
18
+ pattern: "^/[a-zA-Z0-9_.-]+(?:/[a-zA-Z0-9_-]+)*$",
19
+ }),
20
+ legacyAgentName: Type.Optional(
21
+ Type.String({ pattern: "^/root(?:/[a-zA-Z0-9_-]+)*$" }),
22
+ ),
23
+ parentSessionId: Type.Optional(nativeId),
19
24
  ownerFolder: Type.String({ minLength: 1 }),
20
25
  databasePath: Type.String({ minLength: 1 }),
21
26
  enabled: Type.Boolean(),
@@ -25,7 +30,7 @@ export const BindingSchema = Type.Object(
25
30
  );
26
31
  export type BoardBinding = Static<typeof BindingSchema>;
27
32
  const ChildSchema = Type.Object({
28
- parentSessionId: uuid,
33
+ parentSessionId: nativeId,
29
34
  binding: BindingSchema,
30
35
  machine: Type.String(),
31
36
  sessionFile: Type.String({ minLength: 1 }),
@@ -41,7 +46,7 @@ export function setBoardDefault(ctx: ExtensionContext, enabled: boolean) {
41
46
  }
42
47
  const REMOVED = "shepherdr-board-removed";
43
48
  const SettingSchema = Type.Object({
44
- sessionId: uuid,
49
+ sessionId: nativeId,
45
50
  enabled: Type.Union([Type.Boolean(), Type.Null()]),
46
51
  });
47
52
 
@@ -97,10 +102,22 @@ export function rootBoardSetting(ctx: ExtensionContext) {
97
102
  export function parseBinding(value: unknown): BoardBinding {
98
103
  if (!Check(BindingSchema, value))
99
104
  throw new Error("Invalid Shepherdr board binding");
100
- return value as BoardBinding;
105
+ const saved = value as BoardBinding;
106
+ assertSessionIdentity(saved.sessionId, saved.rootSessionId);
107
+ const agentName = `/${saved.sessionId}`;
108
+ if (saved.agentName !== agentName && !/^\/root(?:\/|$)/.test(saved.agentName))
109
+ throw new Error("Board agent reference does not match its native session");
110
+ return {
111
+ ...saved,
112
+ agentName,
113
+ ...(saved.agentName !== agentName && !saved.legacyAgentName
114
+ ? { legacyAgentName: saved.agentName }
115
+ : {}),
116
+ };
101
117
  }
102
118
  export function binding(ctx: ExtensionContext): BoardBinding {
103
119
  const sessionId = ctx.sessionManager.getSessionId();
120
+ assertSessionIdentity(sessionId);
104
121
  let saved: BoardBinding | undefined;
105
122
  for (const entry of ctx.sessionManager.getEntries()) {
106
123
  if (entry.type !== "custom" || entry.customType !== BINDING) continue;
@@ -115,7 +132,7 @@ export function binding(ctx: ExtensionContext): BoardBinding {
115
132
  sessionId,
116
133
  rootSessionId: sessionId,
117
134
  boardId: sessionId,
118
- agentName: "/root",
135
+ agentName: `/${sessionId}`,
119
136
  ownerFolder,
120
137
  databasePath: resolve(ownerFolder, ".pi", "agent-message-board.sqlite"),
121
138
  enabled: false,
@@ -123,24 +140,41 @@ export function binding(ctx: ExtensionContext): BoardBinding {
123
140
  enabled: rootBoardSetting(ctx).enabled,
124
141
  };
125
142
  }
143
+ function assertSessionIdentity(...ids: string[]) {
144
+ if (ids.includes("root"))
145
+ throw new Error(
146
+ "Pi session ID root conflicts with the legacy /root reference; start a session with another ID",
147
+ );
148
+ }
126
149
  export function saveBinding(pi: ExtensionAPI, value: BoardBinding) {
127
150
  pi.appendEntry(BINDING, value);
128
151
  }
129
152
  export function members(ctx: ExtensionContext): BoardBinding[] {
130
153
  const own = binding(ctx);
131
- const found = new Map([[own.agentName, own]]);
154
+ const found = new Map([[own.sessionId, own]]);
132
155
  for (const entry of ctx.sessionManager.getEntries()) {
133
156
  if (entry.type === "custom" && entry.customType === REMOVED) {
134
157
  const value = parseBinding(entry.data);
135
- if (value.boardId === own.boardId) found.delete(value.agentName);
158
+ if (value.boardId === own.boardId) found.delete(value.sessionId);
136
159
  continue;
137
160
  }
138
161
  if (entry.type !== "custom" || entry.customType !== MEMBER) continue;
139
162
  const value = parseBinding(entry.data);
140
163
  if (value.rootSessionId === own.sessionId && value.boardId === own.boardId)
141
- found.set(value.agentName, value);
164
+ found.set(value.sessionId, value);
142
165
  }
143
- return [...found.values()];
166
+ const directory = [...found.values()];
167
+ return directory.map((member) => {
168
+ if (member.parentSessionId || !member.legacyAgentName) return member;
169
+ const path = member.legacyAgentName;
170
+ const parent = directory.find(
171
+ (entry) =>
172
+ (entry.legacyAgentName ??
173
+ (entry.sessionId === own.rootSessionId ? "/root" : undefined)) ===
174
+ path.slice(0, path.lastIndexOf("/")),
175
+ );
176
+ return parent ? { ...member, parentSessionId: parent.sessionId } : member;
177
+ });
144
178
  }
145
179
  export function saveMember(pi: ExtensionAPI, value: BoardBinding) {
146
180
  pi.appendEntry(MEMBER, value);
@@ -151,7 +185,7 @@ export function children(ctx: ExtensionContext): BoardChild[] {
151
185
  for (const entry of ctx.sessionManager.getEntries()) {
152
186
  if (entry.type === "custom" && entry.customType === REMOVED) {
153
187
  const value = parseBinding(entry.data);
154
- if (value.boardId === own.boardId) found.delete(value.agentName);
188
+ if (value.boardId === own.boardId) found.delete(value.sessionId);
155
189
  continue;
156
190
  }
157
191
  if (entry.type !== "custom" || entry.customType !== CHILD) continue;
@@ -162,7 +196,10 @@ export function children(ctx: ExtensionContext): BoardChild[] {
162
196
  value.parentSessionId === own.sessionId &&
163
197
  value.binding.boardId === own.boardId
164
198
  )
165
- found.set(value.binding.agentName, value);
199
+ found.set(value.binding.sessionId, {
200
+ ...value,
201
+ binding: parseBinding(value.binding),
202
+ });
166
203
  }
167
204
  return [...found.values()];
168
205
  }
@@ -172,3 +209,30 @@ export function saveChild(pi: ExtensionAPI, value: BoardChild) {
172
209
  export function removeMember(pi: ExtensionAPI, value: BoardBinding) {
173
210
  pi.appendEntry(REMOVED, value);
174
211
  }
212
+
213
+ /** Legacy names are aliases from native-session records, never access grants. */
214
+ export function boardAliases(
215
+ ctx: ExtensionContext,
216
+ boardId = binding(ctx).boardId,
217
+ ): [string, string][] {
218
+ const own = binding(ctx);
219
+ const aliases = new Map<string, string>();
220
+ if (own.boardId === boardId && own.sessionId === own.rootSessionId)
221
+ aliases.set("/root", own.agentName);
222
+ for (const entry of ctx.sessionManager.getEntries()) {
223
+ if (entry.type !== "custom") continue;
224
+ let member: BoardBinding;
225
+ if ([BINDING, MEMBER, REMOVED].includes(entry.customType))
226
+ member = parseBinding(entry.data);
227
+ else if (entry.customType === CHILD && Check(ChildSchema, entry.data))
228
+ member = parseBinding((entry.data as BoardChild).binding);
229
+ else continue;
230
+ if (member.boardId === boardId && member.legacyAgentName) {
231
+ const previous = aliases.get(member.legacyAgentName);
232
+ if (previous && previous !== member.agentName)
233
+ throw new Error("Ambiguous saved board agent reference");
234
+ aliases.set(member.legacyAgentName, member.agentName);
235
+ }
236
+ }
237
+ return [...aliases];
238
+ }
@@ -44,6 +44,7 @@ export {
44
44
  children,
45
45
  members,
46
46
  parseBinding,
47
+ parseBinding as canonicalBoardBinding,
47
48
  removeMember,
48
49
  rootBoardSetting,
49
50
  saveBinding,
package/src/protocol.ts CHANGED
@@ -1,5 +1,4 @@
1
- import { Type } from "@earendil-works/pi-ai";
2
- import type { Static } from "typebox";
1
+ import { type Static, Type } from "typebox";
3
2
  import { Check } from "typebox/value";
4
3
  import { BindingSchema } from "./identity.js";
5
4
 
@@ -57,6 +56,7 @@ const Protocol = Type.Union([
57
56
  operation: Type.Literal("board-notify"),
58
57
  boardId: Type.String(),
59
58
  target: Type.String(),
59
+ route: Type.Optional(Type.Array(Type.String())),
60
60
  sessionId: Type.String(),
61
61
  turnId: Type.String(),
62
62
  notice: NoticeSchema,
package/src/queries.ts CHANGED
@@ -25,14 +25,13 @@ export function queryBoard(
25
25
  if (params.action === "list_boards") {
26
26
  const rows = store.all<{
27
27
  board_id: string;
28
- root_session_id: string;
29
28
  owner_folder: string;
30
29
  created_at: string;
31
30
  last_activity_at: string;
32
31
  channel_count: number;
33
32
  message_count: number;
34
33
  }>(
35
- `SELECT b.*,
34
+ `SELECT b.board_id,b.owner_folder,b.created_at,
36
35
  COALESCE((SELECT MAX(created_at) FROM posts p WHERE p.board_id=b.board_id),(SELECT MAX(created_at) FROM channels c WHERE c.board_id=b.board_id),b.created_at) AS last_activity_at,
37
36
  (SELECT COUNT(*) FROM channels c WHERE c.board_id=b.board_id) AS channel_count,
38
37
  (SELECT COUNT(*) FROM posts p WHERE p.board_id=b.board_id) AS message_count
@@ -0,0 +1,96 @@
1
+ import type {
2
+ ExtensionAPI,
3
+ ExtensionContext,
4
+ } from "@earendil-works/pi-coding-agent";
5
+ import type { BoardAwareness } from "../awareness.js";
6
+ import { binding } from "../identity.js";
7
+ import type { BoardEnvelope } from "../protocol.js";
8
+
9
+ /** Validates unread responses against the still-selected membership before acceptance. */
10
+ export class BoardCatchup {
11
+ private readonly pi: ExtensionAPI;
12
+ private readonly awareness: BoardAwareness;
13
+ private readonly request: (
14
+ ctx: ExtensionContext,
15
+ request: BoardEnvelope,
16
+ ) => Promise<unknown>;
17
+ private readonly availability: (
18
+ ctx: ExtensionContext,
19
+ error?: unknown,
20
+ ) => void;
21
+ private readonly gpt: () => boolean;
22
+ constructor(
23
+ pi: ExtensionAPI,
24
+ awareness: BoardAwareness,
25
+ request: (
26
+ ctx: ExtensionContext,
27
+ request: BoardEnvelope,
28
+ ) => Promise<unknown>,
29
+ availability: (ctx: ExtensionContext, error?: unknown) => void,
30
+ gpt: () => boolean,
31
+ ) {
32
+ this.pi = pi;
33
+ this.awareness = awareness;
34
+ this.request = request;
35
+ this.availability = availability;
36
+ this.gpt = gpt;
37
+ }
38
+ async read(
39
+ ctx: ExtensionContext,
40
+ ): Promise<{ content: string; accepted: () => void }> {
41
+ const empty = { content: "", accepted: () => {} };
42
+ const own = binding(ctx);
43
+ if (!own.enabled) return empty;
44
+ try {
45
+ const result = await this.request(ctx, {
46
+ operation: "board-catchup",
47
+ caller: own,
48
+ seen: this.awareness.seen(ctx),
49
+ });
50
+ if (
51
+ !Array.isArray(result) ||
52
+ !result.every(
53
+ (post) =>
54
+ post &&
55
+ typeof post.message_id === "string" &&
56
+ typeof post.thread_id === "string",
57
+ )
58
+ )
59
+ throw new Error("Invalid board catch-up response");
60
+ if (
61
+ !binding(ctx).enabled ||
62
+ binding(ctx).sessionId !== own.sessionId ||
63
+ binding(ctx).boardId !== own.boardId ||
64
+ binding(ctx).agentName !== own.agentName
65
+ )
66
+ return empty;
67
+ this.availability(ctx);
68
+ const nested = this.pi
69
+ .getActiveTools()
70
+ .some((tool) => ["exec", "code", "notebook"].includes(tool));
71
+ return {
72
+ content: result.length
73
+ ? `\n\n${this.gpt() ? "Unread board updates→read task-relevant threads:" : "Unread board updates available; read if relevant to the current task:"} ${[
74
+ ...new Set(result.map((post) => post.thread_id)),
75
+ ]
76
+ .map((thread_id) => {
77
+ const args = JSON.stringify({
78
+ action: "read_thread",
79
+ thread_id,
80
+ });
81
+ return nested ? `await tools.board(${args})` : `board ${args}`;
82
+ })
83
+ .join("; ")}`
84
+ : "",
85
+ accepted: () =>
86
+ this.awareness.markSeen(
87
+ ctx,
88
+ result.map((post) => post.message_id),
89
+ ),
90
+ };
91
+ } catch (error) {
92
+ this.availability(ctx, error);
93
+ return empty;
94
+ }
95
+ }
96
+ }