@howaboua/pi-agent-board 0.0.4 → 0.0.6

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 (64) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +3 -1
  3. package/dist/viewer/archive.js +24 -17
  4. package/dist/viewer/web/posts.js +0 -1
  5. package/index.ts +5 -69
  6. package/package.json +15 -14
  7. package/runtime.ts +2 -0
  8. package/scripts/build-viewer.mjs +9 -0
  9. package/src/board/AGENTS.md +12 -0
  10. package/src/{archive.ts → board/archive.ts} +17 -7
  11. package/src/{awareness.ts → board/awareness.ts} +6 -11
  12. package/src/board/briefing.ts +25 -0
  13. package/src/{contract.ts → board/contract.ts} +39 -29
  14. package/src/board/feature.ts +91 -0
  15. package/src/{identity.ts → board/identity.ts} +121 -37
  16. package/src/{integration.ts → board/integration.ts} +1 -0
  17. package/src/board/protocol.ts +117 -0
  18. package/src/{queries.ts → board/queries.ts} +9 -11
  19. package/src/{response.ts → board/response.ts} +7 -1
  20. package/src/board/runtime/activation.ts +50 -0
  21. package/src/{runtime → board/runtime}/coordinator.ts +76 -43
  22. package/src/board/runtime/engine.ts +40 -0
  23. package/src/board/runtime/index.ts +63 -0
  24. package/src/{runtime → board/runtime}/owner.ts +44 -15
  25. package/src/{runtime → board/runtime}/routing.ts +19 -4
  26. package/src/{runtime → board/runtime}/turns.ts +9 -1
  27. package/src/{search.ts → board/search.ts} +11 -9
  28. package/src/board/settings/panel.ts +193 -0
  29. package/src/{store.ts → board/store.ts} +45 -9
  30. package/src/{summarizer.ts → board/summarizer.ts} +3 -2
  31. package/src/{tool.ts → board/tool.ts} +5 -0
  32. package/src/board/viewer/AGENTS.md +1 -0
  33. package/src/{viewer → board/viewer}/archive.ts +24 -17
  34. package/src/{viewer → board/viewer}/index.ts +5 -1
  35. package/src/{viewer → board/viewer}/web/posts.js +0 -1
  36. package/src/guidance.ts +121 -0
  37. package/src/settings-navigation.ts +11 -0
  38. package/src/timestamps.ts +3 -0
  39. package/tsconfig.json +6 -2
  40. package/tsconfig.viewer.json +11 -0
  41. package/changelog.ts +0 -337
  42. package/src/briefing.ts +0 -32
  43. package/src/protocol.ts +0 -78
  44. package/src/runtime/index.ts +0 -113
  45. package/src/settings/panel.ts +0 -87
  46. /package/src/{activity.ts → board/activity.ts} +0 -0
  47. /package/src/{config.ts → board/config.ts} +0 -0
  48. /package/src/{consolidation.ts → board/consolidation.ts} +0 -0
  49. /package/src/{context-briefing.ts → board/context-briefing.ts} +0 -0
  50. /package/src/{delivery.ts → board/delivery.ts} +0 -0
  51. /package/src/{paging.ts → board/paging.ts} +0 -0
  52. /package/src/{runtime → board/runtime}/catchup.ts +0 -0
  53. /package/src/{summaries.ts → board/summaries.ts} +0 -0
  54. /package/src/{viewer → board/viewer}/config.ts +0 -0
  55. /package/src/{viewer → board/viewer}/contracts.ts +0 -0
  56. /package/src/{viewer → board/viewer}/server.ts +0 -0
  57. /package/src/{viewer → board/viewer}/source.ts +0 -0
  58. /package/src/{viewer → board/viewer}/web/app.js +0 -0
  59. /package/src/{viewer → board/viewer}/web/index.html +0 -0
  60. /package/src/{viewer → board/viewer}/web/navigation.js +0 -0
  61. /package/src/{viewer → board/viewer}/web/render.js +0 -0
  62. /package/src/{viewer → board/viewer}/web/session.js +0 -0
  63. /package/src/{viewer → board/viewer}/web/style.css +0 -0
  64. /package/src/{viewer → board/viewer}/web/updates.js +0 -0
package/CHANGELOG.md CHANGED
@@ -1,5 +1,20 @@
1
1
  # @howaboua/pi-agent-board
2
2
 
3
+ ## 0.0.6
4
+
5
+ - Requires Node.js 22.19 or newer.
6
+ - Board now defers its engine while disabled, without losing saved membership or history.
7
+ - Board notifications now use compact previews with author and post/thread references.
8
+ - Board now uses minute precision in displayed dates, preserving existing archives and post ordering.
9
+ - Board guidance now uses shared references only when recipients have access.
10
+ - Replaced the TypeBox dependency with Pi's native schema validation.
11
+
12
+ ## 0.0.5
13
+
14
+ - Requires Pi 1.5 or newer.
15
+ - Board agents now use Pi session IDs without changing identity on attachment. Existing authors, subscriptions and archives remain accessible.
16
+ - Removed custom changelog suppression. Updates use Pi's native notices and `collapseChangelog`.
17
+
3
18
  ## 0.0.4
4
19
 
5
20
  - - Board and connected extension briefings now refresh after Notes context-window rollover.
package/README.md CHANGED
@@ -4,9 +4,11 @@ Shared discussions and saved board history for Pi, with a read-only browser view
4
4
 
5
5
  Works without Shepherdr or Pi Codex Conversion. Shepherdr adds agent-family membership, attachments and remote routing. Pi Codex Conversion exposes the same tool in Code Mode and Notebook.
6
6
 
7
+ This standalone package remains maintained alongside [Agent Comms](../pi-agent-comms), with the same Board improvements. It is not deprecated. Choose one or the other; do not load both in the same Pi session.
8
+
7
9
  ## Install
8
10
 
9
- Requires Pi 1.1.0 or newer and Node.js 22.18 or newer.
11
+ Requires Pi 1.5.0 or newer and Node.js 22.19 or newer.
10
12
 
11
13
  ```sh
12
14
  pi install npm:@howaboua/pi-agent-board
@@ -13,15 +13,18 @@ function count(row, key) {
13
13
  throw new Error(`Invalid board archive count: ${key}`);
14
14
  return value;
15
15
  }
16
- function nullableText(row, key) {
17
- return row[key] === null ? null : text(row, key);
16
+ function timestamp(row, key) {
17
+ return new Date(text(row, key)).toISOString().slice(0, 16) + "Z";
18
+ }
19
+ function nullableTimestamp(row, key) {
20
+ return row[key] === null ? null : timestamp(row, key);
18
21
  }
19
22
  function post(row) {
20
23
  return {
21
24
  id: text(row, "id"),
22
25
  channel: text(row, "channel"),
23
26
  author: text(row, "author"),
24
- createdAt: text(row, "created_at"),
27
+ createdAt: timestamp(row, "created_at"),
25
28
  text: text(row, "text"),
26
29
  };
27
30
  }
@@ -75,7 +78,7 @@ export class Archive {
75
78
  return row
76
79
  ? {
77
80
  text: text(row, "text"),
78
- createdAt: text(row, "created_at"),
81
+ createdAt: timestamp(row, "created_at"),
79
82
  throughMessageId: text(row, "through_message_id"),
80
83
  hasNewerPosts: count(row, "has_newer_posts") === 1,
81
84
  provider: text(row, "provider"),
@@ -87,15 +90,15 @@ export class Archive {
87
90
  index() {
88
91
  const { databasePath: _path, ...context } = this.source;
89
92
  const boards = this.all(`SELECT b.board_id,b.root_session_id,b.created_at,
90
- (SELECT MAX(created_at) FROM posts WHERE board_id=b.board_id) AS last_activity,
93
+ (SELECT created_at FROM posts WHERE board_id=b.board_id ORDER BY seq DESC LIMIT 1) AS last_activity,
91
94
  (SELECT COUNT(*) FROM channels WHERE board_id=b.board_id) AS channels,
92
95
  (SELECT COUNT(*) FROM posts WHERE board_id=b.board_id) AS posts,
93
96
  (SELECT COUNT(DISTINCT author) FROM posts WHERE board_id=b.board_id) AS agents
94
- FROM boards b WHERE owner_folder=? ORDER BY COALESCE(last_activity,b.created_at) DESC`, this.source.folder).map((row) => ({
97
+ FROM boards b WHERE owner_folder=? ORDER BY substr(COALESCE(last_activity,b.created_at),1,16) DESC,(SELECT MAX(seq) FROM posts WHERE board_id=b.board_id) DESC,b.board_id DESC`, this.source.folder).map((row) => ({
95
98
  id: text(row, "board_id"),
96
99
  rootSessionId: text(row, "root_session_id"),
97
- createdAt: text(row, "created_at"),
98
- lastActivity: nullableText(row, "last_activity"),
100
+ createdAt: timestamp(row, "created_at"),
101
+ lastActivity: nullableTimestamp(row, "last_activity"),
99
102
  channels: count(row, "channels"),
100
103
  posts: count(row, "posts"),
101
104
  agents: count(row, "agents"),
@@ -121,20 +124,23 @@ export class Archive {
121
124
  detail(id) {
122
125
  const board = this.board(id);
123
126
  const channels = this.all(`SELECT c.name,c.author,c.created_at,COUNT(p.id) AS posts,
124
- COUNT(CASE WHEN p.id=p.root THEN 1 END) AS threads,MAX(p.created_at) AS last_activity
127
+ COUNT(CASE WHEN p.id=p.root THEN 1 END) AS threads,
128
+ (SELECT created_at FROM posts latest WHERE latest.board_id=c.board_id AND latest.channel=c.name ORDER BY seq DESC LIMIT 1) AS last_activity
125
129
  FROM channels c LEFT JOIN posts p ON p.board_id=c.board_id AND p.channel=c.name
126
- WHERE c.board_id=? GROUP BY c.name ORDER BY COALESCE(last_activity,c.created_at) DESC,c.name`, id).map((row) => ({
130
+ WHERE c.board_id=? GROUP BY c.name ORDER BY substr(COALESCE(last_activity,c.created_at),1,16) DESC,MAX(p.seq) DESC,c.name`, id).map((row) => ({
127
131
  name: text(row, "name"),
128
132
  author: text(row, "author"),
129
- createdAt: text(row, "created_at"),
133
+ createdAt: timestamp(row, "created_at"),
130
134
  posts: count(row, "posts"),
131
135
  threads: count(row, "threads"),
132
- lastActivity: nullableText(row, "last_activity"),
136
+ lastActivity: nullableTimestamp(row, "last_activity"),
133
137
  }));
134
- const agents = this.all("SELECT author,COUNT(*) AS posts,MAX(created_at) AS last_activity FROM posts WHERE board_id=? GROUP BY author ORDER BY posts DESC,author", id).map((row) => ({
138
+ const agents = this.all(`SELECT author,COUNT(*) AS posts,
139
+ (SELECT created_at FROM posts latest WHERE latest.board_id=p.board_id AND latest.author=p.author ORDER BY seq DESC LIMIT 1) AS last_activity
140
+ FROM posts p WHERE board_id=? GROUP BY author ORDER BY posts DESC,author`, id).map((row) => ({
135
141
  name: text(row, "author"),
136
142
  posts: count(row, "posts"),
137
- lastActivity: text(row, "last_activity"),
143
+ lastActivity: timestamp(row, "last_activity"),
138
144
  }));
139
145
  const subscriptions = this.all("SELECT target,agent,enabled FROM subscriptions WHERE board_id=? ORDER BY target,agent", id).map((row) => ({
140
146
  target: text(row, "target"),
@@ -185,7 +191,8 @@ export class Archive {
185
191
  }
186
192
  const cursor = this.cursor(params);
187
193
  const rows = this.all(`SELECT r.id,r.channel,r.author,r.text,r.created_at,
188
- MAX(p.created_at) AS last_activity,MAX(p.seq) AS last_seq,COUNT(*)-1 AS replies
194
+ (SELECT created_at FROM posts latest WHERE latest.board_id=r.board_id AND latest.root=r.id ORDER BY seq DESC LIMIT 1) AS last_activity,
195
+ MAX(p.seq) AS last_seq,COUNT(*)-1 AS replies
189
196
  FROM posts r JOIN posts p ON p.board_id=r.board_id AND p.root=r.id
190
197
  WHERE ${where.join(" AND ")} GROUP BY r.id HAVING MAX(p.seq)<? ORDER BY last_seq DESC LIMIT 41`, ...args, cursor ?? Number.MAX_SAFE_INTEGER);
191
198
  const visible = rows.slice(0, 40);
@@ -203,8 +210,8 @@ export class Archive {
203
210
  preview: (params.get("full") === "true"
204
211
  ? text(row, "text")
205
212
  : (summary?.text ?? text(row, "text"))).slice(0, 600),
206
- createdAt: text(row, "created_at"),
207
- lastActivity: text(row, "last_activity"),
213
+ createdAt: timestamp(row, "created_at"),
214
+ lastActivity: timestamp(row, "last_activity"),
208
215
  replies: count(row, "replies"),
209
216
  };
210
217
  }),
@@ -51,7 +51,6 @@ export function renderPost(post, root, summary = false) {
51
51
  const header = node("header", "post-header");
52
52
  const time = node("time", "", date(post.createdAt));
53
53
  time.dateTime = post.createdAt;
54
- time.title = post.createdAt;
55
54
  header.append(
56
55
  summary ? node("strong", "", "Summary") : author(post.author),
57
56
  time,
package/index.ts CHANGED
@@ -1,72 +1,8 @@
1
1
  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
- import { binding } from "./src/identity.js";
3
- import { acquireBoard } from "./src/runtime/index.js";
4
- import { openBoardSettings } from "./src/settings/panel.js";
5
- import { openBoardViewer } from "./src/viewer/index.js";
2
+ import { createBoardFeature } from "./src/board/feature.js";
3
+ import { registerCommunicationGuidance } from "./src/guidance.js";
6
4
 
7
- export default async function agentBoardExtension(pi: ExtensionAPI) {
8
- const board = await acquireBoard(pi);
9
- pi.registerCommand("board", {
10
- description:
11
- "Board viewer; settings, status, on|off [session|folder|global]",
12
- getArgumentCompletions(prefix) {
13
- const commands = ["settings", "status", "on", "off"];
14
- const scopes = ["session", "folder", "global"];
15
- const options = prefix.includes(" ")
16
- ? ["on", "off"].flatMap((command) =>
17
- scopes.map((scope) => `${command} ${scope}`),
18
- )
19
- : commands;
20
- return options
21
- .filter((value) => value.startsWith(prefix))
22
- .map((value) => ({ label: value, value }));
23
- },
24
- async handler(args, ctx) {
25
- if (args.trim() === "settings") return openBoardSettings(pi, ctx, board);
26
- const [command = "", scope = "session", ...extra] = args
27
- .trim()
28
- .split(/\s+/);
29
- if (
30
- (command === "on" || command === "off") &&
31
- (scope === "session" || scope === "folder" || scope === "global") &&
32
- !extra.length
33
- ) {
34
- try {
35
- await board.setSetting(ctx, scope, command === "on");
36
- ctx.ui.notify(board.status(ctx), "info");
37
- } catch (error) {
38
- ctx.ui.notify(
39
- error instanceof Error ? error.message : String(error),
40
- "error",
41
- );
42
- }
43
- return;
44
- }
45
- if (args.trim() === "status") {
46
- ctx.ui.notify(board.status(ctx), "info");
47
- return;
48
- }
49
- if (command) {
50
- ctx.ui.notify(
51
- "Use /board, /board settings, /board status or /board on|off [session|folder|global]",
52
- "warning",
53
- );
54
- return;
55
- }
56
- await openBoardViewer(pi, ctx, (context, sessionName) => {
57
- const own = binding(context);
58
- if (own.upstream)
59
- throw new Error(
60
- "Open /board in the owning root session to view this shared board",
61
- );
62
- return {
63
- sessionId: own.sessionId,
64
- sessionName: sessionName ?? null,
65
- boardId: own.boardId,
66
- folder: own.ownerFolder,
67
- databasePath: own.databasePath,
68
- };
69
- });
70
- },
71
- });
5
+ export default async function agentBoard(pi: ExtensionAPI): Promise<void> {
6
+ const board = await createBoardFeature(pi);
7
+ registerCommunicationGuidance(pi, undefined, board);
72
8
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@howaboua/pi-agent-board",
3
- "version": "0.0.4",
3
+ "version": "0.0.6",
4
4
  "description": "Standalone agent message boards and a read-only browser viewer for Pi",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -12,28 +12,29 @@
12
12
  "files": [
13
13
  "index.ts",
14
14
  "src",
15
- "dist",
16
15
  "README.md",
17
- "INTEGRATION.md",
16
+ "CHANGELOG.md",
18
17
  "LICENSE",
19
18
  "tsconfig.json",
20
- "changelog.ts",
21
- "CHANGELOG.md"
19
+ "runtime.ts",
20
+ "dist",
21
+ "INTEGRATION.md",
22
+ "scripts",
23
+ "tsconfig.viewer.json"
22
24
  ],
23
25
  "main": "index.ts",
24
26
  "exports": {
25
27
  ".": "./index.ts",
26
- "./runtime": "./src/runtime/index.ts",
27
- "./integration": "./src/integration.ts"
28
+ "./runtime": "./runtime.ts",
29
+ "./integration": "./src/board/integration.ts"
28
30
  },
29
31
  "pi": {
30
32
  "extensions": [
31
- "./changelog.ts",
32
33
  "./index.ts"
33
34
  ]
34
35
  },
35
36
  "engines": {
36
- "node": ">=22.18.0"
37
+ "node": ">=22.19.0"
37
38
  },
38
39
  "scripts": {
39
40
  "build": "node scripts/build-viewer.mjs",
@@ -44,16 +45,16 @@
44
45
  "pack:dry": "npm pack --dry-run"
45
46
  },
46
47
  "dependencies": {
48
+ "@earendil-works/pi-schema": "1.5.2",
47
49
  "dompurify": "3.4.17",
48
- "marked": "18.1.2",
50
+ "marked": "18.2.0",
49
51
  "unicode-case-folding": "1.1.2"
50
52
  },
51
53
  "peerDependencies": {
52
54
  "@earendil-works/pi-ai": ">=1.1.0",
53
- "@earendil-works/pi-coding-agent": ">=1.1.0",
55
+ "@earendil-works/pi-coding-agent": ">=1.5.0",
54
56
  "@earendil-works/pi-tui": ">=1.1.0",
55
- "@howaboua/pi-codex-conversion": ">=4.0.5",
56
- "typebox": "*"
57
+ "@howaboua/pi-codex-conversion": ">=4.0.10"
57
58
  },
58
59
  "peerDependenciesMeta": {
59
60
  "@howaboua/pi-codex-conversion": {
@@ -64,6 +65,6 @@
64
65
  "access": "public"
65
66
  },
66
67
  "devDependencies": {
67
- "@howaboua/pi-codex-conversion": "4.0.5"
68
+ "@howaboua/pi-codex-conversion": "4.0.10"
68
69
  }
69
70
  }
package/runtime.ts ADDED
@@ -0,0 +1,2 @@
1
+ export { BoardRuntime } from "./src/board/runtime/coordinator.js";
2
+ export { acquireBoard, discoverBoard } from "./src/board/runtime/index.js";
@@ -0,0 +1,9 @@
1
+ import { spawnSync } from "node:child_process";
2
+ import { cpSync, rmSync } from "node:fs";
3
+
4
+ rmSync("dist", { recursive: true, force: true });
5
+ const result = spawnSync("tsc", ["-p", "tsconfig.viewer.json"], {
6
+ stdio: "inherit",
7
+ });
8
+ if (result.status !== 0) process.exit(result.status ?? 1);
9
+ cpSync("src/board/viewer/web", "dist/viewer/web", { recursive: true });
@@ -0,0 +1,12 @@
1
+ - Only an explicitly loaded Agent Comms or standalone Board extension activates Board. Discovery never imports the engine; disabled sessions keep binding/settings routes and reconcile inherited enablement before preparation. Preserve native replay of saved briefings without starting the engine. Settings and viewer reads must not activate it.
2
+ - Schema-v1 archives and `shepherdr-board-*` session records are compatibility contracts. Preserve their paths and identities across takeover; do not create a replacement archive.
3
+ - Post sequence owns chronology and continuation. Minute timestamps may tie or coexist with legacy precision; never order posts or advance cursors by timestamp text.
4
+ - Native session IDs own public agent references; saved legacy names are archive aliases, never membership grants. Keep parent-session associations when adopting members: flat references cannot authorize descendants or route notices by prefix.
5
+ - Status and its comment share the post transaction and invocation ID. New replies require open status, checked in that transaction after invocation replay. Replaying a status call must not reapply it over a later status; read-only legacy archives default to open without creating tables.
6
+ - Summaries are derived snapshots, not posts. Status changes discard them in the same transaction; a late save must match the closed status comment and covered latest post. Tool and viewer searches replace summarized posts by default; only `full` searches originals. Legacy reads never create summary tables.
7
+ - Start summarization only after a fresh committed status notice, never an invocation replay. Its system prompt owns instructions; source payload owns channel/status and chronological author/timestamp/text with the closing comment marked, not IDs or session context. Keep requests tool-free and cancel them with the owning session or board.
8
+ - Summaries default off. Validate the preference inside the caught background job so invalid summary settings cannot turn a committed status change into a tool failure.
9
+ - runtime/owner.ts validates owner requests and commits archives before summaries or best-effort notices. coordinator.ts owns settings, refresh and cancellation; routing.ts owns adapter/envelope routing, with binding changes awaiting coordinator refresh. turns.ts alone owns session-scoped turn capabilities. Do not copy their mutable state into the owner executor.
10
+ - Fleet discovery, spawning and SSH stay in host adapters. The viewer only receives a resolved source and opens it read-only; viewing must never initialize a board.
11
+ - Keep viewer startup lazy and packaged assets local. Do not modify a running user's viewer or listener configuration during validation.
12
+ - Viewer browser modules must remain in the server's explicit asset allowlist; the build copies web/ recursively. session.js owns shared selection/queue state; render, navigation and updates must not create parallel snapshots or bypass the queue.
@@ -8,22 +8,27 @@ import { boundedBoardRead, checkMutationBudget } from "./response.js";
8
8
  export async function readSubscribedUpdates(
9
9
  caller: BoardBinding,
10
10
  seen: string[],
11
+ aliases: [string, string][] = [],
11
12
  ) {
12
13
  if (!existsSync(caller.databasePath)) return [];
13
14
  const { BoardStore } = await import("./store.js");
14
- const store = new BoardStore(caller.databasePath, false);
15
+ const store = new BoardStore(caller.databasePath, false, aliases);
15
16
  try {
17
+ const identities = JSON.stringify(store.agentIdentities(caller.agentName));
16
18
  return store.all<{ message_id: string; thread_id: string }>(
17
19
  `SELECT p.id AS message_id,p.root AS thread_id FROM posts p
18
- WHERE p.board_id=? AND p.author<>? AND NOT EXISTS
20
+ WHERE p.board_id=? AND p.author NOT IN (SELECT value FROM json_each(?)) AND NOT EXISTS
19
21
  (SELECT 1 FROM json_each(?) WHERE value=p.id) AND EXISTS
20
22
  (SELECT 1 FROM subscriptions s WHERE s.board_id=p.board_id
21
- AND s.agent=? AND s.enabled=1 AND s.target=CASE WHEN p.id=p.root
22
- THEN 'channel:'||p.channel ELSE 'thread:'||p.root END)
23
+ AND s.agent IN (SELECT value FROM json_each(?)) AND s.enabled=1
24
+ AND (s.agent=? OR NOT EXISTS (SELECT 1 FROM subscriptions n WHERE n.board_id=s.board_id AND n.target=s.target AND n.agent=?))
25
+ AND s.target=CASE WHEN p.id=p.root THEN 'channel:'||p.channel ELSE 'thread:'||p.root END)
23
26
  ORDER BY p.seq ASC LIMIT 50`,
24
27
  caller.boardId,
25
- caller.agentName,
28
+ identities,
26
29
  JSON.stringify(seen),
30
+ identities,
31
+ caller.agentName,
27
32
  caller.agentName,
28
33
  );
29
34
  } finally {
@@ -36,6 +41,7 @@ export async function executeArchive(
36
41
  memberNames: readonly string[],
37
42
  params: BoardParams,
38
43
  requestId: string,
44
+ aliases: [string, string][] = [],
39
45
  ) {
40
46
  if (
41
47
  params.action === "set_status" &&
@@ -65,7 +71,8 @@ export async function executeArchive(
65
71
  ...(params.agents_to_notify ?? []),
66
72
  ...(params.target_agent === undefined ? [] : [params.target_agent]),
67
73
  ]) {
68
- const target = agentPath(value, caller.agentName);
74
+ const path = agentPath(value, caller.legacyAgentName ?? caller.agentName);
75
+ const target = new Map(aliases).get(path) ?? path;
69
76
  if (!memberNames.includes(target))
70
77
  throw new Error(`Agent not bound to this tree: ${target}`);
71
78
  }
@@ -87,7 +94,7 @@ export async function executeArchive(
87
94
  return { value: page([], params), recipients: [] };
88
95
  throw new Error("This board has no channels or posts yet");
89
96
  }
90
- const store = new storage.BoardStore(caller.databasePath, write);
97
+ const store = new storage.BoardStore(caller.databasePath, write, aliases);
91
98
  try {
92
99
  const scope = {
93
100
  boardId: caller.boardId,
@@ -95,6 +102,9 @@ export async function executeArchive(
95
102
  ownerFolder: caller.ownerFolder,
96
103
  callerSessionId: caller.sessionId,
97
104
  agentName: caller.agentName,
105
+ ...(caller.legacyAgentName
106
+ ? { legacyAgentName: caller.legacyAgentName }
107
+ : {}),
98
108
  members: memberNames,
99
109
  };
100
110
  return write
@@ -7,9 +7,9 @@ import { boardBriefing } from "./briefing.js";
7
7
  import {
8
8
  contextBriefingWindow,
9
9
  recordContextBriefing,
10
- registerContextBriefing,
11
10
  } from "./context-briefing.js";
12
11
  import { binding } from "./identity.js";
12
+ import type { BoardAdapter } from "./integration.js";
13
13
 
14
14
  const OWNER = "shepherdr-board";
15
15
  const STATE = "shepherdr-board-awareness";
@@ -28,11 +28,12 @@ export class BoardAwareness {
28
28
  error?: unknown,
29
29
  ) => void;
30
30
  private readonly gpt: () => boolean;
31
+ private readonly privateBriefing: () => BoardAdapter["briefing"];
31
32
  constructor(
32
33
  pi: ExtensionAPI,
33
34
  read: (ctx: ExtensionContext) => Promise<unknown>,
34
35
  availability: (ctx: ExtensionContext, error?: unknown) => void,
35
- privateBriefing: () => typeof boardBriefing | undefined,
36
+ privateBriefing: () => BoardAdapter["briefing"],
36
37
  gpt: () => boolean = () => false,
37
38
  ) {
38
39
  this.pi = pi;
@@ -40,14 +41,7 @@ export class BoardAwareness {
40
41
  this.availability = availability;
41
42
  this.gpt = gpt;
42
43
  this.privateBriefing = privateBriefing;
43
- registerContextBriefing(
44
- pi,
45
- "board",
46
- (ctx) => binding(ctx).enabled,
47
- (ctx, windowId) => this.record(ctx, windowId),
48
- );
49
44
  }
50
- private readonly privateBriefing: () => typeof boardBriefing | undefined;
51
45
 
52
46
  refresh(ctx: ExtensionContext): AwarenessState {
53
47
  const own = binding(ctx);
@@ -88,7 +82,8 @@ export class BoardAwareness {
88
82
  ids?: unknown;
89
83
  };
90
84
  return data?.boardId === own.boardId &&
91
- data.agentName === own.agentName &&
85
+ (data.agentName === own.agentName ||
86
+ data.agentName === own.legacyAgentName) &&
92
87
  Array.isArray(data.ids)
93
88
  ? data.ids.filter((id): id is string => typeof id === "string")
94
89
  : [];
@@ -128,7 +123,7 @@ export class BoardAwareness {
128
123
  );
129
124
  }
130
125
 
131
- private async record(ctx: ExtensionContext, windowId?: string) {
126
+ async record(ctx: ExtensionContext, windowId?: string) {
132
127
  const own = binding(ctx);
133
128
  const state = this.refresh(ctx);
134
129
  if (!own.enabled) return;
@@ -0,0 +1,25 @@
1
+ export function boardBriefing(
2
+ member: boolean,
3
+ population: "empty" | "populated" | "unavailable",
4
+ gpt = false,
5
+ ) {
6
+ const state =
7
+ population === "populated"
8
+ ? "Read relevant board threads."
9
+ : population === "empty"
10
+ ? gpt
11
+ ? "Shared board available; posts=none."
12
+ : "Shared board available; no posts yet."
13
+ : gpt
14
+ ? "Shared board status unavailable; board help→retry read when available."
15
+ : "Shared board status unavailable. Check board help and retry reading when available.";
16
+ return [
17
+ state,
18
+ member ? "Follow your assigned scope." : "",
19
+ gpt
20
+ ? "Channels=workstreams; threads=topics. Reuse relevant channels; new channel only for distinct coordination need≠task/result announcement. Read≠subscribe; subscribe to threads→replies, channels→new threads."
21
+ : "Channels group workstreams, threads group topics. Reuse a relevant channel. Create one only for a distinct coordination need, not task or result announcements. Reading does not subscribe: subscribe to relevant threads for replies, channels for new threads.",
22
+ ]
23
+ .filter(Boolean)
24
+ .join(" ");
25
+ }
@@ -1,6 +1,14 @@
1
- import { StringEnum, Type } from "@earendil-works/pi-ai";
2
- import type { Static } from "typebox";
3
- import { Check } from "typebox/value";
1
+ import {
2
+ arr,
3
+ bool,
4
+ compile,
5
+ int,
6
+ obj,
7
+ oneOf,
8
+ opt,
9
+ type Static,
10
+ str,
11
+ } from "@earendil-works/pi-schema";
4
12
 
5
13
  const BOARD_ACTIONS = [
6
14
  "help",
@@ -18,22 +26,23 @@ const BOARD_ACTIONS = [
18
26
  ] as const;
19
27
  const THREAD_STATUSES = ["open", "completed", "abandoned"] as const;
20
28
  export type ThreadStatus = (typeof THREAD_STATUSES)[number];
21
- export const BoardParameters = Type.Object({
22
- action: Type.Optional(StringEnum(BOARD_ACTIONS)),
23
- });
24
- const positive = Type.Optional(
25
- Type.Integer({ minimum: 1, maximum: 0xffffffff }),
29
+ export const BoardParameters = obj(
30
+ {
31
+ action: opt({ ...oneOf(BOARD_ACTIONS), type: "string" }),
32
+ },
33
+ { open: true },
26
34
  );
27
- const string = Type.Optional(Type.String());
28
- const Request = Type.Object(
35
+ const positive = opt(int({ minimum: 1, maximum: 0xffffffff }));
36
+ const string = opt(str());
37
+ const Request = obj(
29
38
  {
30
- action: StringEnum(BOARD_ACTIONS),
39
+ action: { ...oneOf(BOARD_ACTIONS), type: "string" },
31
40
  channel_name: string,
32
41
  new_channel_name: string,
33
42
  thread_id: string,
34
43
  message_id: string,
35
44
  text: string,
36
- status: Type.Optional(StringEnum(THREAD_STATUSES)),
45
+ status: opt({ ...oneOf(THREAD_STATUSES), type: "string" }),
37
46
  comment: string,
38
47
  query: string,
39
48
  author: string,
@@ -41,21 +50,17 @@ const Request = Type.Object(
41
50
  after_message_id: string,
42
51
  board_id: string,
43
52
  cursor: string,
44
- full: Type.Optional(Type.Boolean()),
45
- subscribe: Type.Optional(Type.Boolean()),
46
- recent_first: Type.Optional(Type.Boolean()),
47
- sort: Type.Optional(StringEnum(["created", "activity"])),
53
+ full: opt(bool()),
54
+ subscribe: opt(bool()),
55
+ recent_first: opt(bool()),
56
+ sort: opt({ ...oneOf(["created", "activity"]), type: "string" }),
48
57
  limit: positive,
49
58
  max_chars_per_post: positive,
50
59
  limit_chars: positive,
51
- offset_chars: Type.Optional(
52
- Type.Integer({ minimum: 0, maximum: 0xffffffff }),
53
- ),
54
- agents_to_notify: Type.Optional(
55
- Type.Array(Type.String(), { maxItems: 256 }),
56
- ),
60
+ offset_chars: opt(int({ minimum: 0, maximum: 0xffffffff })),
61
+ agents_to_notify: opt(arr(str(), { maxItems: 256 })),
57
62
  },
58
- { additionalProperties: false },
63
+ { open: false },
59
64
  );
60
65
  export type BoardParams = Static<typeof Request>;
61
66
  export type BoardAction = BoardParams["action"];
@@ -112,6 +117,8 @@ const requiredFields: Partial<Record<BoardAction, string[]>> = {
112
117
  read_thread: ["thread_id"],
113
118
  read_post: ["message_id"],
114
119
  };
120
+ const requestValidator = compile(Request);
121
+
115
122
  export function parseBoardRequest(value: unknown): BoardParams {
116
123
  if (
117
124
  value === undefined ||
@@ -121,7 +128,7 @@ export function parseBoardRequest(value: unknown): BoardParams {
121
128
  Object.keys(value).length === 0)
122
129
  )
123
130
  return { action: "help" };
124
- if (!Check(Request, value))
131
+ if (!requestValidator.check(value))
125
132
  throw new Error("Invalid board request; call board help");
126
133
  const request = { ...(value as BoardParams) };
127
134
  const allowed = new Set(["action", ...fields[request.action]]);
@@ -134,7 +141,6 @@ export function parseBoardRequest(value: unknown): BoardParams {
134
141
  "thread_id",
135
142
  "message_id",
136
143
  "after_message_id",
137
- "board_id",
138
144
  ] as const) {
139
145
  const id = request[field];
140
146
  if (
@@ -146,6 +152,11 @@ export function parseBoardRequest(value: unknown): BoardParams {
146
152
  throw new Error(`${field} must be a UUID`);
147
153
  if (id !== undefined) request[field] = id.toLowerCase();
148
154
  }
155
+ if (
156
+ request.board_id !== undefined &&
157
+ !/^[a-zA-Z0-9_.-]+$/.test(request.board_id)
158
+ )
159
+ throw new Error("Invalid board_id");
149
160
  if (request.action === "post")
150
161
  exactlyOne(request, ["channel_name", "new_channel_name", "thread_id"]);
151
162
  if (request.action === "subscribe" || request.action === "unsubscribe")
@@ -162,7 +173,7 @@ export function required(value: string | undefined, field: string): string {
162
173
  }
163
174
  export function agentPath(value: string, caller: string): string {
164
175
  const path = value.startsWith("/") ? value : `${caller}/${value}`;
165
- if (!/^\/root(?:\/[a-zA-Z0-9_-]+)*$/.test(path))
176
+ if (!/^\/[a-zA-Z0-9_.-]+(?:\/[a-zA-Z0-9_-]+)*$/.test(path))
166
177
  throw new Error("Invalid agent path");
167
178
  return path;
168
179
  }
@@ -189,7 +200,7 @@ export const boardHelp = {
189
200
  notify:
190
201
  "agents_to_notify is one-time, excludes author; only running turns, no waking or offline notices",
191
202
  agents:
192
- "Use spawn's boardAgent; absolute /root/... or child path relative to you, not a pane or contextAgent",
203
+ "Agent reference /<Pi session ID>; saved legacy references remain valid",
193
204
  paging:
194
205
  "limit default20, cap50; cursor opaque, keep query/sort/full unchanged. Concurrent changes may shift pages",
195
206
  summaries:
@@ -222,8 +233,7 @@ export function gptBoardHelp(value: unknown): unknown {
222
233
  "EXACTLY one: channel_name|thread_id; channel=first posts, thread=replies; target_agent=you by default; posting→subscribe author UNLESS explicitly unsubscribed",
223
234
  notify:
224
235
  "agents_to_notify=once, excludes author; running turns ONLY; NO waking/offline notices",
225
- agents:
226
- "spawn's boardAgent: absolute /root/... OR relative child path; NOT pane/contextAgent",
236
+ agents: "Agent=/<Pi session ID>; legacy references accepted",
227
237
  paging:
228
238
  "limit default20 cap50; opaque cursor→unchanged query/sort/full; concurrent changes MAY shift pages",
229
239
  summaries: