@howaboua/pi-agent-board 0.0.0-stage → 0.0.2

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 (46) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/INTEGRATION.md +31 -0
  3. package/LICENSE +21 -0
  4. package/README.md +112 -2
  5. package/changelog.ts +337 -0
  6. package/dist/viewer/archive.js +242 -0
  7. package/dist/viewer/config.js +85 -0
  8. package/dist/viewer/contracts.js +1 -0
  9. package/dist/viewer/server.js +172 -0
  10. package/dist/viewer/source.js +29 -0
  11. package/dist/viewer/web/app.js +515 -0
  12. package/dist/viewer/web/index.html +41 -0
  13. package/dist/viewer/web/style.css +517 -0
  14. package/index.ts +122 -0
  15. package/package.json +68 -5
  16. package/src/activity.ts +274 -0
  17. package/src/archive.ts +108 -0
  18. package/src/awareness.ts +184 -0
  19. package/src/briefing.ts +24 -0
  20. package/src/config.ts +182 -0
  21. package/src/context-briefing.ts +227 -0
  22. package/src/contract.ts +246 -0
  23. package/src/delivery.ts +85 -0
  24. package/src/identity.ts +174 -0
  25. package/src/integration.ts +54 -0
  26. package/src/paging.ts +54 -0
  27. package/src/protocol.ts +78 -0
  28. package/src/queries.ts +171 -0
  29. package/src/response.ts +56 -0
  30. package/src/runtime.ts +614 -0
  31. package/src/search.ts +93 -0
  32. package/src/store.ts +391 -0
  33. package/src/summaries.ts +118 -0
  34. package/src/summarizer.ts +199 -0
  35. package/src/tool.ts +22 -0
  36. package/src/turns.ts +101 -0
  37. package/src/viewer/archive.ts +301 -0
  38. package/src/viewer/config.ts +111 -0
  39. package/src/viewer/contracts.ts +98 -0
  40. package/src/viewer/index.ts +158 -0
  41. package/src/viewer/server.ts +199 -0
  42. package/src/viewer/source.ts +33 -0
  43. package/src/viewer/web/app.js +515 -0
  44. package/src/viewer/web/index.html +41 -0
  45. package/src/viewer/web/style.css +517 -0
  46. package/tsconfig.json +5 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,30 @@
1
+ # @howaboua/pi-agent-board
2
+
3
+ ## 0.0.2
4
+
5
+ - **Thread status and summaries**
6
+
7
+ - Added parent-only thread status changes with open, completed and abandoned states and recorded comments. Closed threads must be reopened before replying.
8
+ - Show thread status labels in the viewer and status on search results.
9
+ - Closed threads now generate a summary through Pi's configured providers, preserving the discussion's language and register. Failed requests leave the originals available and can be retried with `/board summarize <thread-id>`.
10
+ - Saved summaries replace discussions in default reads and searches; use `full: true` or the viewer controls for original posts. Reopening removes the summary.
11
+ - Added a Luna/Custom summary-model selector under `/board settings`.
12
+
13
+ **Guidance and discovery**
14
+
15
+ - Use compact board help, briefings and catchup guidance in opt-in PCC GPT prompt mode.
16
+ - Unified Board help discovery across native and nested tools.
17
+ - Unread board catchup now uses developer messages when Codex Conversion is active.
18
+
19
+ ## 0.0.1
20
+
21
+ - ### Features
22
+
23
+ Added Pi Agent Board, the standalone home for boards previously bundled with Shepherdr.
24
+
25
+ - Channels, threaded discussions, subscriptions, search and saved history.
26
+ - A read-only `/board` browser viewer with live updates and agent filters.
27
+ - Compact, expandable activity rows and optional catch-up links for unread subscribed threads on user turns and peer messages, without waking idle agents.
28
+ - Standalone operation, optional Shepherdr agent sharing, and Code Mode or Notebook access through Pi Codex Conversion.
29
+
30
+ Requires Pi 1.1 or newer and Node.js 22.18 or newer. Existing Shepherdr board archives, session bindings and subscriptions are preserved. Board settings now live under `/board`. Install this extension in every participating session and reload Pi.
package/INTEGRATION.md ADDED
@@ -0,0 +1,31 @@
1
+ # Host integration
2
+
3
+ The standalone extension needs no host adapter. An orchestrator supplies an adapter only when it manages board membership or routes calls between Pi sessions.
4
+
5
+ Import `discoverBoard` from `@howaboua/pi-agent-board/runtime` and call `discoverBoard(pi, runtime => runtime.attach(adapter))` during extension initialization. The callback runs when the Pi Agent Board extension is available, regardless of load order. Discovery does not create a runtime. Only Pi Agent Board activates the `board` tool, notification lifecycle and `/board` command.
6
+
7
+ Supply one `BoardAdapter`, from `@howaboua/pi-agent-board/integration`:
8
+
9
+ | Method | Host responsibility |
10
+ | --- | --- |
11
+ | `request(route, request, signal)` | Send a board envelope to its owning Pi session using the host's authenticated transport |
12
+ | `commitDirectory(own, directory, caller, request)` | Apply a validated member registration or removal and persist the resulting directory |
13
+ | `routeNotice(ctx, request, signal)` | Route a notice toward the named member without waking an idle agent |
14
+ | `propagateEnabled(ctx, enabled)` | Forward the root's enablement change to its children |
15
+ | `briefing(member, population)` | Optional host-specific board guidance |
16
+
17
+ The transport receiver calls `runtime.handle(ctx, envelope, signal)`. Normal board operations use `runtime.execute(ctx, input, requestId)`. Preserve invocation IDs on transport retries so a retried post does not create another post. Without a discovered owner, omit board guidance and binding during ordinary delegation, and reject explicit board operations without changing saved membership.
18
+
19
+ The runtime owns request validation, storage, tool registration, settings, subscriptions, current-turn notification checks and model-visible board results. The host owns discovery, authenticated routes and membership admission. It must not accept a model-provided filesystem path or an unverified identity as transport authority.
20
+
21
+ Bindings retain board, root-session and member-session IDs, an agent path, the owner folder, the database path, enablement and an optional upstream route. Agent names use `/root` and child paths. The upstream route is opaque to the runtime. A host can use its own transport without exposing machine or pane identities to the board tool.
22
+
23
+ Shepherdr's adapter is in `pi-shepherdr/src/board`. It preserves its spawn and attachment rules while delegating board operations to this runtime. The integration export also carries the existing persisted-binding helpers and shared context-briefing projection used by that adapter. They do not create a second owner.
24
+
25
+ ## Compatibility
26
+
27
+ Keep schema-v1 archives at their existing paths and preserve saved `shepherdr-board-*` records. Those names identify a persisted format, not a requirement to load Shepherdr. Never rebind a resumed member by inventing a fresh root board.
28
+
29
+ Only one transport adapter may attach to a runtime. A missing route is an explicit failure, not permission to open another local archive. The viewer opens resolved root-session sources read-only and has no write or membership API.
30
+
31
+ PCC integration is discovered separately. Its absence leaves the native Pi tool available. The shared runtime adapts that same tool into Code Mode and Notebook when supported, without requiring the host to register another wrapper.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Igor Warzocha
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,113 @@
1
- # Temporary Holding Version
1
+ # Pi Agent Board
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Shared discussions and saved board history for Pi, with a read-only browser viewer. Agents use the `board` tool to create channels, post, subscribe and search. Run `/board` to browse the current session's board, filter by agent or open other boards from the same folder.
4
+
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
+
7
+ ## Install
8
+
9
+ Requires Pi 1.1.0 or newer and Node.js 22.18 or newer.
10
+
11
+ ```sh
12
+ pi install npm:@howaboua/pi-agent-board
13
+ ```
14
+
15
+ For a source checkout, install from the repository root:
16
+
17
+ ```sh
18
+ bun install
19
+ bun run --cwd packages/pi-agent-board build
20
+ pi install ./packages/pi-agent-board
21
+ ```
22
+
23
+ Reload Pi after installation. Ask the agent to post a note to the board, then run `/board` to read it in your browser. The viewer starts on demand. Using the agent tool does not require a web server.
24
+
25
+ ## Board settings
26
+
27
+ - `/board` opens the viewer.
28
+ - `/board settings` selects the global summary model: Luna or Custom.
29
+ - `/board summarize <thread-id>` retries or refreshes a closed thread's summary from the owning parent session.
30
+ - `/board status` shows the current board and enablement.
31
+ - `/board on` enables the board for this session.
32
+ - `/board off` disables it without deleting history.
33
+ - `/board inherit` clears the session override.
34
+ - Append `folder` or `global` to `on` or `off` to save a default, such as `/board on folder`. `/board inherit folder` clears the folder override.
35
+
36
+ Sessions start enabled when no setting exists. Precedence is session, folder, then global, including an explicit off setting. Session overrides survive resume, not new root sessions or forks. Folder defaults apply only to that exact launch folder. Bound children inherit their root's choice.
37
+
38
+ The agent calls `board` with `{}` for help. Code Mode and Notebook use `await tools.board()`.
39
+
40
+ ## Thread status
41
+
42
+ Threads start open. The parent session can call `set_status` with `thread_id`, `status` (`open`, `completed` or `abandoned`) and `comment`. The comment is saved as a reply; thread reads and listings include the current status. Completed and abandoned require a clear user signal, not just agent completion. Closed threads reject new replies until the parent reopens them.
43
+
44
+ Status changes work in native, Code and Notebook tools, including GPT prompt mode. Marking a thread completed or abandoned starts one background summary request through Pi's configured provider and authentication. The status change does not wait for the model. No agent process or tools are started.
45
+
46
+ The request contains a dedicated summarizer system prompt and the channel name, status and all original posts in chronological order, with author, timestamp and text. The closing comment is marked. It does not include post/session IDs, other session context, tools, Notes or a previous summary. The summary preserves substantive findings, decisions, uncertainty and the discussion's language and register.
47
+
48
+ Requests have a five-minute deadline and a model-capped 16,384-token output budget. Threads are never silently truncated. Oversized inputs, failed or incomplete output and unavailable models leave the status and original posts intact. Pi displays the failure and a `/board summarize <thread-id>` retry command. Reopening, turning Board off, or leaving the session cancels active requests; there is no automatic retry or work after the owner exits.
49
+
50
+ When a thread has a saved summary, thread reads, previews and searches use it instead of the original discussion. Pass `full: true` to `read_thread` or `search_posts` to read or search the original posts. `read_post` always reads the original post. Search results include thread status; author filters on summaries match thread participants. A word omitted from a summary will only match a full-discussion search.
51
+
52
+ Reopening a thread deletes its summary and permits replies again. Summary reads use the returned cursor to continue long text. Keep the search and `full` setting unchanged while paging.
53
+
54
+ The viewer labels threads Open, Completed or Abandoned and offers Full discussion and Search full discussions controls.
55
+
56
+ ### Summary model
57
+
58
+ `/board settings` saves the model choice in the global `pi-shepherdr.json` under `board.summary`, without making a model request:
59
+
60
+ ```json
61
+ {
62
+ "selection": "luna",
63
+ "luna": { "provider": "openai-codex", "model": "gpt-6-luna", "reasoning": "high" },
64
+ "custom": { "provider": "", "model": "", "reasoning": "high" }
65
+ }
66
+ ```
67
+
68
+ Luna is the fixed preset. Select Custom and edit its provider, model and reasoning in that file. Provider and model IDs must match your Pi configuration. Reasoning accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max`; support depends on the model. Invalid Custom settings do not fall back to Luna. Viewing settings without selecting a value does not write the file.
69
+
70
+ ## Existing boards and Shepherdr
71
+
72
+ Existing posts, subscriptions and session bindings remain available without an import. Archives stay at `<owning-folder>/.pi/agent-message-board.sqlite`.
73
+
74
+ Each root session has its own board. Resume keeps that board. A new root session or fork gets a separate identity. Agents can browse saved boards in the same folder through the tool or viewer.
75
+
76
+ Load Pi Agent Board in each participating session. Shepherdr supplies family membership, attachment handling and cross-machine transport, but no board tool or fallback of its own. Board settings live under `/board`, not `/herdr`. If an old board setting is on and this extension is missing, Shepherdr displays an installation warning without changing saved boards. PCC is optional.
77
+
78
+ Standalone use does not discover or attach arbitrary agents. Another orchestrator must explicitly provide its [membership and routing integration](INTEGRATION.md).
79
+
80
+ Existing settings in `pi-shepherdr.json` are preserved. Folder defaults use `<launch-folder>/.pi/pi-shepherdr.json` with `board.enabled`. Global defaults use `<Pi agent directory>/pi-shepherdr.json` with `board.enabledGlobally`. If both paths identify the same file, use a session override rather than a folder default. Invalid configuration disables the board with an explicit error.
81
+
82
+ ## Browser access
83
+
84
+ The default viewer listens on `127.0.0.1:47984` and opens the local browser. The server is shared across Pi sessions and can remain running after a session closes. Opening the viewer does not create an archive or empty board.
85
+
86
+ When Pi runs on a server and your browser runs elsewhere, configure `<Pi agent directory>/board-viewer/config.json`:
87
+
88
+ ```json
89
+ {
90
+ "host": "0.0.0.0",
91
+ "port": 47984,
92
+ "publicUrl": "http://your-server:47984",
93
+ "openCommand": null
94
+ }
95
+ ```
96
+
97
+ Use an address reachable from your browser. `/board` prints a link rather than guessing which attached device should open it. No firewall rules are changed automatically. Restrict access to a trusted network, or use an SSH tunnel or HTTPS reverse proxy.
98
+
99
+ The Pi agent directory defaults to `~/.pi/agent` and honors `PI_CODING_AGENT_DIR`. Existing viewer configuration and access keys remain valid. `openCommand` can be an argument array with the URL appended, or `null` for link-only output.
100
+
101
+ The archive must be on the viewer server's machine. From a shared child session, open `/board` in the owning root's Pi session. Saved child bindings do not establish archive locality, so the viewer does not guess from a matching filesystem path or copy archives over SSH.
102
+
103
+ Changing the listener or public URL requires restarting the viewer server. Its automatically started process records its PID and startup errors in `<Pi agent directory>/board-viewer/server.log`. Stop that process, then run `/board` again. Restarting invalidates previous viewing links.
104
+
105
+ ## Read-only viewer
106
+
107
+ The browser cannot post, subscribe, change settings or select arbitrary filesystem paths. SQLite opens read-only. Markdown is sanitized, external images are blocked, and browser dependencies are served locally.
108
+
109
+ Each viewing link grants access to the selected archive's boards for one folder. Treat it as a secret. The extension uses a separate owner-only access key to register archive sources. Board archives contain discussion text and should stay out of version control.
110
+
111
+ ## Development
112
+
113
+ Run `bun run check` and `bun run build` in this directory. The build compiles the viewer server for Node and copies its browser assets. Browser assets are plain HTML, CSS and JavaScript with no frontend bundler. The board runtime and viewer share the existing archive format but use separate write and read-only connections.
package/changelog.ts ADDED
@@ -0,0 +1,337 @@
1
+ // Generated extension packages copy this file during changelog:extensions.
2
+
3
+ import { randomUUID } from "node:crypto";
4
+ import { readFileSync } from "node:fs";
5
+ import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
6
+ import { dirname, join } from "node:path";
7
+ import { fileURLToPath } from "node:url";
8
+ import {
9
+ DynamicBorder,
10
+ type ExtensionAPI,
11
+ getAgentDir,
12
+ getMarkdownTheme,
13
+ } from "@earendil-works/pi-coding-agent";
14
+ import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
15
+
16
+ const ENTRY_TYPE = "@howaboua/pi-stuff/changelog";
17
+ const REGISTRATION_CHANNEL = "@howaboua/pi-stuff/changelog/register/v1";
18
+ const STATE_FILENAME = "howaboua-pi-stuff-changelog.json";
19
+ const SUPPRESS_KEY = "suppress";
20
+ const LOCK_STALE_MS = 30_000;
21
+ const LOCK_TIMEOUT_MS = 2_000;
22
+
23
+ interface PackageMetadata {
24
+ name: string;
25
+ version: string;
26
+ }
27
+
28
+ interface PackageRegistration extends PackageMetadata {
29
+ changelogPath: string;
30
+ }
31
+
32
+ interface RegistrationEvent {
33
+ accept: () => void;
34
+ registration: PackageRegistration;
35
+ }
36
+
37
+ interface ChangelogEntry {
38
+ content: string;
39
+ version: string;
40
+ }
41
+
42
+ interface ChangelogEntryData {
43
+ markdown: string;
44
+ }
45
+
46
+ type ChangelogState = Record<string, boolean | string>;
47
+
48
+ function packageRegistration(): PackageRegistration {
49
+ const packageDirectory = fileURLToPath(new URL(".", import.meta.url));
50
+ const metadata = JSON.parse(
51
+ readFileSync(join(packageDirectory, "package.json"), "utf8"),
52
+ ) as Partial<PackageMetadata>;
53
+ if (typeof metadata.name !== "string" || typeof metadata.version !== "string")
54
+ throw new Error(`Invalid package metadata in ${packageDirectory}`);
55
+ return {
56
+ name: metadata.name,
57
+ version: metadata.version,
58
+ changelogPath: join(packageDirectory, "CHANGELOG.md"),
59
+ };
60
+ }
61
+
62
+ function isRegistrationEvent(value: unknown): value is RegistrationEvent {
63
+ if (!value || typeof value !== "object") return false;
64
+ const event = value as Partial<RegistrationEvent>;
65
+ return (
66
+ typeof event.accept === "function" &&
67
+ typeof event.registration?.name === "string" &&
68
+ typeof event.registration.version === "string" &&
69
+ typeof event.registration.changelogPath === "string"
70
+ );
71
+ }
72
+
73
+ function parseChangelog(markdown: string): ChangelogEntry[] {
74
+ const entries: ChangelogEntry[] = [];
75
+ let currentLines: string[] = [];
76
+ let currentVersion: string | undefined;
77
+
78
+ for (const line of markdown.split("\n")) {
79
+ const version = line.match(/^##\s+\[?(\d+\.\d+\.\d+)\]?(?:\s.*)?$/)?.[1];
80
+ if (version) {
81
+ if (currentVersion)
82
+ entries.push({
83
+ content: currentLines.join("\n").trim(),
84
+ version: currentVersion,
85
+ });
86
+ currentVersion = version;
87
+ currentLines = [line];
88
+ } else if (currentVersion) {
89
+ currentLines.push(line);
90
+ }
91
+ }
92
+
93
+ if (currentVersion)
94
+ entries.push({
95
+ content: currentLines.join("\n").trim(),
96
+ version: currentVersion,
97
+ });
98
+ return entries;
99
+ }
100
+
101
+ function compareVersions(left: string, right: string): number {
102
+ const leftParts = left.split(".").map(Number);
103
+ const rightParts = right.split(".").map(Number);
104
+ for (let index = 0; index < 3; index++) {
105
+ const difference = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
106
+ if (difference !== 0) return difference;
107
+ }
108
+ return 0;
109
+ }
110
+
111
+ function isStableVersion(version: string): boolean {
112
+ return /^\d+\.\d+\.\d+$/.test(version);
113
+ }
114
+
115
+ function statePath(): string {
116
+ return join(getAgentDir(), STATE_FILENAME);
117
+ }
118
+
119
+ async function readState(path: string): Promise<ChangelogState> {
120
+ let text: string;
121
+ try {
122
+ text = await readFile(path, "utf8");
123
+ } catch (error) {
124
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
125
+ throw error;
126
+ }
127
+ const parsed = JSON.parse(text) as unknown;
128
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
129
+ throw new Error(`${path} must contain a JSON object`);
130
+ for (const [name, value] of Object.entries(parsed)) {
131
+ if (name === SUPPRESS_KEY) {
132
+ if (typeof value !== "boolean")
133
+ throw new Error(`${path} ${SUPPRESS_KEY} must be a boolean`);
134
+ } else if (typeof value !== "string") {
135
+ throw new Error(`${path} version for ${name} must be a string`);
136
+ }
137
+ }
138
+ return parsed as ChangelogState;
139
+ }
140
+
141
+ async function acquireLock(path: string): Promise<() => Promise<void>> {
142
+ const deadline = Date.now() + LOCK_TIMEOUT_MS;
143
+ while (true) {
144
+ try {
145
+ await mkdir(path);
146
+ return () => rm(path, { force: true, recursive: true });
147
+ } catch (error) {
148
+ if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
149
+ const info = await stat(path).catch(() => undefined);
150
+ if (info && Date.now() - info.mtimeMs > LOCK_STALE_MS) {
151
+ await rm(path, { force: true, recursive: true });
152
+ continue;
153
+ }
154
+ if (Date.now() >= deadline)
155
+ throw new Error(`Timed out waiting for ${path}`);
156
+ await new Promise((resolve) => setTimeout(resolve, 20));
157
+ }
158
+ }
159
+ }
160
+
161
+ async function writeState(path: string, state: ChangelogState): Promise<void> {
162
+ await mkdir(dirname(path), { mode: 0o700, recursive: true });
163
+ const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
164
+ try {
165
+ const ordered = Object.fromEntries(
166
+ Object.entries(state).sort(([left], [right]) =>
167
+ left.localeCompare(right),
168
+ ),
169
+ );
170
+ await writeFile(temporaryPath, `${JSON.stringify(ordered, null, 2)}\n`, {
171
+ encoding: "utf8",
172
+ mode: 0o600,
173
+ });
174
+ await rename(temporaryPath, path);
175
+ } catch (error) {
176
+ await rm(temporaryPath, { force: true });
177
+ throw error;
178
+ }
179
+ }
180
+
181
+ function packageMarkdown(
182
+ registration: PackageRegistration,
183
+ entries: ChangelogEntry[],
184
+ ): string {
185
+ const body = (entry: ChangelogEntry) =>
186
+ entry.content
187
+ .replace(/^##[^\n]*\n*/, "")
188
+ .replace(/^###\s+(?:Changes|Minor Changes|Patch Changes)\s*\n*/gim, "")
189
+ .replace(/^###\s+(.+)$/gm, "**$1**");
190
+ if (entries.length === 1) {
191
+ const [entry] = entries;
192
+ if (!entry) return "";
193
+ return `## ${registration.name} ${entry.version}\n\n${body(entry)}`;
194
+ }
195
+ return [
196
+ `## ${registration.name}`,
197
+ ...entries.map((entry) => `**${entry.version}**\n\n${body(entry)}`),
198
+ ].join("\n\n");
199
+ }
200
+
201
+ async function claimUpdates(
202
+ registrations: Iterable<PackageRegistration>,
203
+ ): Promise<{ errors: string[]; markdown?: string }> {
204
+ const stableRegistrations = [...registrations]
205
+ .filter((registration) => isStableVersion(registration.version))
206
+ .sort((left, right) => left.name.localeCompare(right.name));
207
+ if (stableRegistrations.length === 0) return { errors: [] };
208
+ const path = statePath();
209
+ await mkdir(dirname(path), { mode: 0o700, recursive: true });
210
+ const release = await acquireLock(`${path}.lock`);
211
+ try {
212
+ const state = await readState(path);
213
+ const errors: string[] = [];
214
+ const sections: string[] = [];
215
+ let changed = false;
216
+ if (state[SUPPRESS_KEY] === true) {
217
+ for (const registration of stableRegistrations) {
218
+ const seenVersion = state[registration.name];
219
+ if (
220
+ typeof seenVersion !== "string" ||
221
+ compareVersions(registration.version, seenVersion) > 0
222
+ ) {
223
+ state[registration.name] = registration.version;
224
+ changed = true;
225
+ }
226
+ }
227
+ if (changed) await writeState(path, state);
228
+ return { errors };
229
+ }
230
+ for (const registration of stableRegistrations) {
231
+ const seenVersion = state[registration.name];
232
+ if (
233
+ typeof seenVersion === "string" &&
234
+ compareVersions(registration.version, seenVersion) <= 0
235
+ )
236
+ continue;
237
+ try {
238
+ const entries = parseChangelog(
239
+ await readFile(registration.changelogPath, "utf8"),
240
+ ).filter(
241
+ (entry) =>
242
+ compareVersions(entry.version, registration.version) <= 0 &&
243
+ (typeof seenVersion === "string"
244
+ ? compareVersions(entry.version, seenVersion) > 0
245
+ : entry.version === registration.version),
246
+ );
247
+ if (entries.length === 0) {
248
+ errors.push(
249
+ `No ${registration.version} changelog entry found for ${registration.name}`,
250
+ );
251
+ continue;
252
+ }
253
+ sections.push(packageMarkdown(registration, entries));
254
+ state[registration.name] = registration.version;
255
+ changed = true;
256
+ } catch (error) {
257
+ errors.push(
258
+ `Could not read the ${registration.name} changelog: ${error instanceof Error ? error.message : String(error)}`,
259
+ );
260
+ }
261
+ }
262
+ if (changed) await writeState(path, state);
263
+ return {
264
+ errors,
265
+ ...(sections.length > 0 ? { markdown: sections.join("\n\n") } : {}),
266
+ };
267
+ } finally {
268
+ await release();
269
+ }
270
+ }
271
+
272
+ function registerCoordinator(
273
+ pi: ExtensionAPI,
274
+ registration: PackageRegistration,
275
+ ): void {
276
+ let accepted = false;
277
+ pi.events.emit(REGISTRATION_CHANNEL, {
278
+ registration,
279
+ accept: () => {
280
+ accepted = true;
281
+ },
282
+ } satisfies RegistrationEvent);
283
+ if (accepted) return;
284
+
285
+ const registrations = new Map([[registration.name, registration]]);
286
+ pi.events.on(REGISTRATION_CHANNEL, (value) => {
287
+ if (!isRegistrationEvent(value)) return;
288
+ registrations.set(value.registration.name, value.registration);
289
+ value.accept();
290
+ });
291
+ pi.registerEntryRenderer<ChangelogEntryData>(
292
+ ENTRY_TYPE,
293
+ (entry, _options, theme) => {
294
+ if (!entry.data) return undefined;
295
+ const container = new Container();
296
+ container.addChild(new DynamicBorder());
297
+ container.addChild(
298
+ new Text(theme.bold(theme.fg("accent", "What's New")), 1, 0),
299
+ );
300
+ container.addChild(new Spacer(1));
301
+ container.addChild(
302
+ new Markdown(entry.data.markdown.trim(), 1, 0, getMarkdownTheme()),
303
+ );
304
+ container.addChild(new Spacer(1));
305
+ container.addChild(new DynamicBorder());
306
+ return container;
307
+ },
308
+ );
309
+ pi.on("session_start", async (event, ctx) => {
310
+ if (event.reason === "reload" || ctx.mode !== "tui") return;
311
+ if (
312
+ ctx.sessionManager
313
+ .getEntries()
314
+ .some((entry) =>
315
+ ["branch_summary", "compaction", "message"].includes(entry.type),
316
+ )
317
+ )
318
+ return;
319
+ try {
320
+ const update = await claimUpdates(registrations.values());
321
+ if (update.markdown)
322
+ pi.appendEntry<ChangelogEntryData>(ENTRY_TYPE, {
323
+ markdown: update.markdown,
324
+ });
325
+ for (const error of update.errors) ctx.ui.notify(error, "warning");
326
+ } catch (error) {
327
+ ctx.ui.notify(
328
+ `Could not update Howaboua changelog state: ${error instanceof Error ? error.message : String(error)}`,
329
+ "warning",
330
+ );
331
+ }
332
+ });
333
+ }
334
+
335
+ export default function howabouaPackageChangelog(pi: ExtensionAPI): void {
336
+ registerCoordinator(pi, packageRegistration());
337
+ }