@howaboua/pi-agent-comms 0.0.0-stage → 0.0.1-dev.13.1.gef1ce49691d6

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 (141) hide show
  1. package/INTEGRATION.md +31 -0
  2. package/LICENSE +21 -0
  3. package/PCC-INTEGRATION.md +17 -0
  4. package/README.md +53 -2
  5. package/dist/viewer/archive.js +249 -0
  6. package/dist/viewer/config.js +85 -0
  7. package/dist/viewer/contracts.js +1 -0
  8. package/dist/viewer/server.js +177 -0
  9. package/dist/viewer/source.js +29 -0
  10. package/dist/viewer/web/app.js +88 -0
  11. package/dist/viewer/web/index.html +41 -0
  12. package/dist/viewer/web/navigation.js +72 -0
  13. package/dist/viewer/web/posts.js +105 -0
  14. package/dist/viewer/web/render.js +147 -0
  15. package/dist/viewer/web/session.js +86 -0
  16. package/dist/viewer/web/style.css +517 -0
  17. package/dist/viewer/web/updates.js +106 -0
  18. package/docs/BOARD-CHANGELOG.md +49 -0
  19. package/docs/BOARD.md +124 -0
  20. package/docs/NOTES-CHANGELOG.md +127 -0
  21. package/docs/NOTES.md +122 -0
  22. package/index.ts +21 -0
  23. package/package.json +75 -5
  24. package/src/board/AGENTS.md +12 -0
  25. package/src/board/activity.ts +274 -0
  26. package/src/board/archive.ts +118 -0
  27. package/src/board/awareness.ts +179 -0
  28. package/src/board/briefing.ts +25 -0
  29. package/src/board/config.ts +192 -0
  30. package/src/board/consolidation.ts +32 -0
  31. package/src/board/context-briefing.ts +245 -0
  32. package/src/board/contract.ts +254 -0
  33. package/src/board/delivery.ts +85 -0
  34. package/src/board/feature.ts +91 -0
  35. package/src/board/identity.ts +238 -0
  36. package/src/board/integration.ts +55 -0
  37. package/src/board/paging.ts +54 -0
  38. package/src/board/protocol.ts +78 -0
  39. package/src/board/queries.ts +168 -0
  40. package/src/board/response.ts +82 -0
  41. package/src/board/runtime/activation.ts +50 -0
  42. package/src/board/runtime/catchup.ts +96 -0
  43. package/src/board/runtime/coordinator.ts +311 -0
  44. package/src/board/runtime/engine.ts +40 -0
  45. package/src/board/runtime/index.ts +63 -0
  46. package/src/board/runtime/owner.ts +168 -0
  47. package/src/board/runtime/routing.ts +152 -0
  48. package/src/board/runtime/turns.ts +109 -0
  49. package/src/board/search.ts +95 -0
  50. package/src/board/settings/panel.ts +193 -0
  51. package/src/board/store.ts +427 -0
  52. package/src/board/summaries.ts +124 -0
  53. package/src/board/summarizer.ts +201 -0
  54. package/src/board/tool.ts +27 -0
  55. package/src/board/viewer/AGENTS.md +1 -0
  56. package/src/board/viewer/archive.ts +308 -0
  57. package/src/board/viewer/config.ts +111 -0
  58. package/src/board/viewer/contracts.ts +98 -0
  59. package/src/board/viewer/index.ts +162 -0
  60. package/src/board/viewer/server.ts +204 -0
  61. package/src/board/viewer/source.ts +33 -0
  62. package/src/board/viewer/web/app.js +88 -0
  63. package/src/board/viewer/web/index.html +41 -0
  64. package/src/board/viewer/web/navigation.js +72 -0
  65. package/src/board/viewer/web/posts.js +105 -0
  66. package/src/board/viewer/web/render.js +147 -0
  67. package/src/board/viewer/web/session.js +86 -0
  68. package/src/board/viewer/web/style.css +517 -0
  69. package/src/board/viewer/web/updates.js +106 -0
  70. package/src/guidance.ts +121 -0
  71. package/src/notes/AGENTS.md +27 -0
  72. package/src/notes/activation.ts +150 -0
  73. package/src/notes/agent-identity.ts +221 -0
  74. package/src/notes/attachment-sharing.ts +165 -0
  75. package/src/notes/attachment-snapshot.ts +113 -0
  76. package/src/notes/binding-startup.ts +30 -0
  77. package/src/notes/bridge.ts +130 -0
  78. package/src/notes/compaction-projection.ts +88 -0
  79. package/src/notes/context-owner.ts +99 -0
  80. package/src/notes/context-sharing.ts +178 -0
  81. package/src/notes/extension-hooks.ts +200 -0
  82. package/src/notes/extension-sharing.ts +133 -0
  83. package/src/notes/feature.ts +168 -0
  84. package/src/notes/fresh-checkpoint.ts +143 -0
  85. package/src/notes/fresh-notes.ts +323 -0
  86. package/src/notes/history-search-protocol.ts +39 -0
  87. package/src/notes/history-search-pruning.mjs +120 -0
  88. package/src/notes/history-search-worker.mjs +258 -0
  89. package/src/notes/history-search.ts +269 -0
  90. package/src/notes/history-windows.ts +221 -0
  91. package/src/notes/history.ts +158 -0
  92. package/src/notes/idle-admission.ts +201 -0
  93. package/src/notes/index.ts +125 -0
  94. package/src/notes/integrations.ts +174 -0
  95. package/src/notes/lifecycle.ts +308 -0
  96. package/src/notes/model-role-config.ts +79 -0
  97. package/src/notes/model-role-screen.ts +74 -0
  98. package/src/notes/model-roles.ts +225 -0
  99. package/src/notes/note-query.ts +148 -0
  100. package/src/notes/note-result.ts +88 -0
  101. package/src/notes/note-save-marker.ts +128 -0
  102. package/src/notes/notes-lookup.ts +115 -0
  103. package/src/notes/notes.ts +302 -0
  104. package/src/notes/query-executor.ts +242 -0
  105. package/src/notes/query-input.ts +126 -0
  106. package/src/notes/remote.ts +376 -0
  107. package/src/notes/rollover.ts +224 -0
  108. package/src/notes/saved-session-access.ts +117 -0
  109. package/src/notes/saved-session-index.mjs +83 -0
  110. package/src/notes/saved-session.mjs +241 -0
  111. package/src/notes/saved-session.ts +51 -0
  112. package/src/notes/saved-sharing-records.ts +135 -0
  113. package/src/notes/session-pruning-content.ts +237 -0
  114. package/src/notes/session-pruning-plan.ts +243 -0
  115. package/src/notes/session-pruning-policy.ts +20 -0
  116. package/src/notes/session-pruning-screen.ts +204 -0
  117. package/src/notes/session-pruning-source.ts +44 -0
  118. package/src/notes/session-pruning-transaction.ts +141 -0
  119. package/src/notes/session-pruning.ts +155 -0
  120. package/src/notes/settings-command.ts +95 -0
  121. package/src/notes/settings-controls.ts +199 -0
  122. package/src/notes/settings-screen.ts +113 -0
  123. package/src/notes/settings.ts +287 -0
  124. package/src/notes/shared-notes.ts +411 -0
  125. package/src/notes/shared-session-reader.ts +143 -0
  126. package/src/notes/sharing-service.ts +282 -0
  127. package/src/notes/sqlite.mjs +33 -0
  128. package/src/notes/store.ts +283 -0
  129. package/src/notes/task-boundary.ts +37 -0
  130. package/src/notes/tool-contracts.ts +312 -0
  131. package/src/notes/tools.ts +148 -0
  132. package/src/notes/tree-archive-manifest.mjs +27 -0
  133. package/src/notes/tree-archive.ts +129 -0
  134. package/src/notes/tree-checkpoint.ts +170 -0
  135. package/src/notes/tree-handoff-read.ts +192 -0
  136. package/src/notes/window-checkpoint.ts +105 -0
  137. package/src/notes/window-message.ts +185 -0
  138. package/src/notes/windows.ts +272 -0
  139. package/src/settings-navigation.ts +11 -0
  140. package/src/timestamps.ts +3 -0
  141. package/tsconfig.json +9 -0
@@ -0,0 +1,272 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import type { AgentMessage } from "@earendil-works/pi-agent-core";
3
+ import { getCurrentSystemMessage } from "@earendil-works/pi-ai";
4
+ import type {
5
+ CustomMessageEntryDraft,
6
+ ExtensionContext,
7
+ SessionEntry,
8
+ } from "@earendil-works/pi-coding-agent";
9
+ import type { NotesBridge, WindowIdentity } from "./bridge.js";
10
+ import {
11
+ renderTaskBoundaryReminder,
12
+ taskBoundaryEligible,
13
+ } from "./task-boundary.js";
14
+ import { isWindowCheckpoint } from "./window-checkpoint.js";
15
+
16
+ import {
17
+ messageWindowDetails,
18
+ WINDOW_MESSAGE,
19
+ type WindowDetails,
20
+ windowDetails,
21
+ } from "./window-message.js";
22
+
23
+ export {
24
+ registerWindowRenderer,
25
+ SETTLEMENT_ENTRY,
26
+ WINDOW_MESSAGE,
27
+ windowDetails,
28
+ windowMessage,
29
+ } from "./window-message.js";
30
+
31
+ export class Windows {
32
+ current: WindowIdentity | undefined;
33
+ private identityEntry:
34
+ | Extract<SessionEntry, { type: "custom_message" }>
35
+ | undefined;
36
+ private restoredIdentity:
37
+ | {
38
+ entryId: string;
39
+ timestamp: number;
40
+ prepare: NotesBridge["prepareReminder"];
41
+ message: AgentMessage;
42
+ }
43
+ | undefined;
44
+ private compactedSinceBoundary = false;
45
+ private reminders = new Set<string>();
46
+ restore(entries: readonly SessionEntry[]): void {
47
+ this.current = undefined;
48
+ this.identityEntry = undefined;
49
+ this.compactedSinceBoundary = false;
50
+ this.reminders.clear();
51
+ for (const entry of entries) {
52
+ const details = windowDetails(entry);
53
+ if (
54
+ entry.type === "custom_message" &&
55
+ (details?.kind === "window" || details?.kind === "identity")
56
+ )
57
+ this.identityEntry = entry;
58
+ if (details?.kind === "window") {
59
+ this.current = details.identity;
60
+ if (details.trim) this.compactedSinceBoundary = false;
61
+ } else if (
62
+ details &&
63
+ (details.kind === "reminder" ||
64
+ details.kind === "urgent" ||
65
+ details.kind === "task-boundary")
66
+ )
67
+ this.reminders.add(
68
+ `${details.identity.currentWindowId}:${details.kind}`,
69
+ );
70
+ if (entry.type === "compaction" && !isWindowCheckpoint(entry)) {
71
+ // Compaction frees capacity, but does not create a new window identity.
72
+ this.reminders = new Set(
73
+ [...this.reminders].filter((key) => key.endsWith(":task-boundary")),
74
+ );
75
+ this.compactedSinceBoundary = true;
76
+ }
77
+ }
78
+ }
79
+ next(): WindowIdentity {
80
+ const id = randomUUID();
81
+ return this.current
82
+ ? {
83
+ firstWindowId: this.current.firstWindowId,
84
+ currentWindowId: id,
85
+ previousWindowId: this.current.currentWindowId,
86
+ windowNumber: this.current.windowNumber + 1,
87
+ }
88
+ : { firstWindowId: id, currentWindowId: id, windowNumber: 0 };
89
+ }
90
+ remaining(ctx: ExtensionContext) {
91
+ const usage = ctx.getContextUsage();
92
+ const contextWindow = usage?.contextWindow ?? ctx.model?.contextWindow ?? 0;
93
+ const tokens = usage?.tokens;
94
+ const remainingTokens =
95
+ tokens === undefined ||
96
+ tokens === null ||
97
+ !Number.isFinite(tokens) ||
98
+ !Number.isFinite(contextWindow) ||
99
+ contextWindow <= 0
100
+ ? undefined
101
+ : Math.max(0, contextWindow - Math.max(0, tokens));
102
+ return {
103
+ contextWindow,
104
+ windowId: this.current?.currentWindowId,
105
+ remainingTokens,
106
+ remainingPercent:
107
+ remainingTokens === undefined
108
+ ? undefined
109
+ : Math.round((remainingTokens / contextWindow) * 1000) / 10,
110
+ };
111
+ }
112
+ reminder(
113
+ ctx: ExtensionContext,
114
+ taskBoundaryReminder = 0,
115
+ checkpointReminder = true,
116
+ gpt = false,
117
+ ): CustomMessageEntryDraft | undefined {
118
+ const { remainingTokens, contextWindow, remainingPercent } =
119
+ this.remaining(ctx);
120
+ if (
121
+ !this.current ||
122
+ remainingTokens === undefined ||
123
+ remainingPercent === undefined
124
+ )
125
+ return;
126
+ const used = 100 * (1 - remainingTokens / contextWindow);
127
+ let kind: WindowDetails["kind"] | undefined = checkpointReminder
128
+ ? used >= 90
129
+ ? "urgent"
130
+ : used >= 85
131
+ ? "reminder"
132
+ : undefined
133
+ : undefined;
134
+ if (kind && this.reminders.has(`${this.current.currentWindowId}:${kind}`))
135
+ kind = undefined;
136
+ if (
137
+ !kind &&
138
+ taskBoundaryReminder &&
139
+ !this.reminders.has(`${this.current.currentWindowId}:task-boundary`) &&
140
+ taskBoundaryEligible(ctx, taskBoundaryReminder)
141
+ )
142
+ kind = "task-boundary";
143
+ if (!kind) return;
144
+ this.reminders.add(`${this.current.currentWindowId}:${kind}`);
145
+ if (kind === "urgent")
146
+ this.reminders.add(`${this.current.currentWindowId}:reminder`);
147
+ return {
148
+ type: "custom_message",
149
+ customType: WINDOW_MESSAGE,
150
+ content:
151
+ kind === "task-boundary"
152
+ ? renderTaskBoundaryReminder(remainingPercent, gpt)
153
+ : gpt
154
+ ? `<context_window_reminder>\n${kind === "urgent" ? "Urgent: " : ""}${remainingPercent}% context left; save checkpoint via notes→new_context ${kind === "urgent" ? "now, before other work" : "before continuing work"}.\n</context_window_reminder>`
155
+ : `<context_window_reminder>\n${kind === "urgent" ? "Urgent: " : ""}${remainingPercent}% context remaining. Save checkpoint with notes, then call new_context ${kind === "urgent" ? "now, before other work" : "before continuing work"}.\n</context_window_reminder>`,
156
+ display: true,
157
+ details: {
158
+ protocol: 1,
159
+ kind,
160
+ identity: this.current,
161
+ trim: false,
162
+ } satisfies WindowDetails,
163
+ };
164
+ }
165
+ projectMessages(
166
+ messages: readonly AgentMessage[],
167
+ prepareIdentity?: NotesBridge["prepareReminder"],
168
+ ): AgentMessage[] {
169
+ if (this.compactedSinceBoundary) {
170
+ const summary = messages.findIndex(
171
+ (message) => message.role === "compactionSummary",
172
+ );
173
+ const entry = this.identityEntry;
174
+ const details = entry && windowDetails(entry);
175
+ const hasIdentity = messages.some((message) => {
176
+ const current =
177
+ message.role === "custom" &&
178
+ messageWindowDetails(message.customType, message.details);
179
+ return (
180
+ current &&
181
+ (current.kind === "window" || current.kind === "identity") &&
182
+ current.identity.currentWindowId === this.current?.currentWindowId
183
+ );
184
+ });
185
+ if (
186
+ summary < 0 ||
187
+ messages[0]?.role !== "system" ||
188
+ !entry ||
189
+ !details ||
190
+ typeof entry.content !== "string" ||
191
+ hasIdentity
192
+ )
193
+ return [...messages];
194
+ const timestamp = messages[summary]!.timestamp;
195
+ if (
196
+ this.restoredIdentity?.entryId !== entry.id ||
197
+ this.restoredIdentity.timestamp !== timestamp ||
198
+ this.restoredIdentity.prepare !== prepareIdentity
199
+ ) {
200
+ const draft: CustomMessageEntryDraft = {
201
+ type: "custom_message",
202
+ customType: WINDOW_MESSAGE,
203
+ content: `${entry.content}\n\nIf no checkpoint is available, use history to recover missing context.`,
204
+ display: false,
205
+ details: {
206
+ ...details,
207
+ kind: "identity",
208
+ trim: false,
209
+ } satisfies WindowDetails,
210
+ };
211
+ const prepared = prepareIdentity?.(draft) ?? draft;
212
+ this.restoredIdentity = {
213
+ entryId: entry.id,
214
+ timestamp,
215
+ prepare: prepareIdentity,
216
+ message: {
217
+ role: "custom",
218
+ customType: prepared.customType,
219
+ content: prepared.content,
220
+ display: prepared.display,
221
+ details: prepared.details,
222
+ timestamp,
223
+ },
224
+ };
225
+ }
226
+ // Carry the older identity ahead of its summary, outside opaque native replay.
227
+ return [
228
+ ...messages.slice(0, summary),
229
+ this.restoredIdentity.message,
230
+ ...messages.slice(summary),
231
+ ];
232
+ }
233
+ let boundary = -1;
234
+ for (let i = 0; i < messages.length; i++) {
235
+ const message = messages[i]!;
236
+ if (message.role !== "custom") continue;
237
+ const details = messageWindowDetails(message.customType, message.details);
238
+ if (!details && message.customType === WINDOW_MESSAGE)
239
+ throw new Error(
240
+ "Invalid saved context window. Open an intact session branch to continue.",
241
+ );
242
+ if (details?.kind === "window" && details.trim) boundary = i;
243
+ }
244
+ if (boundary < 0) return [...messages];
245
+ const system = getCurrentSystemMessage(messages.slice(0, boundary));
246
+ return system
247
+ ? [system, ...messages.slice(boundary)]
248
+ : messages.slice(boundary);
249
+ }
250
+ projectBranch(entries: readonly SessionEntry[]): SessionEntry[] {
251
+ let boundary = -1;
252
+ for (let i = 0; i < entries.length; i++) {
253
+ const details = windowDetails(entries[i]!);
254
+ if (details?.kind === "window" && details.trim) boundary = i;
255
+ // Normal Pi/PCC compaction has already chosen its own checkpoint.
256
+ if (entries[i]!.type === "compaction" && !isWindowCheckpoint(entries[i]!))
257
+ boundary = -1;
258
+ }
259
+ return entries.slice(Math.max(0, boundary)).map(
260
+ (entry): SessionEntry =>
261
+ isWindowCheckpoint(entry)
262
+ ? {
263
+ type: "custom",
264
+ id: entry.id,
265
+ parentId: entry.parentId,
266
+ timestamp: entry.timestamp,
267
+ customType: "notes-compaction:window-checkpoint",
268
+ }
269
+ : entry,
270
+ );
271
+ }
272
+ }
@@ -0,0 +1,11 @@
1
+ import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
2
+
3
+ export type SettingsTab = "notes" | "board";
4
+ export type OpenSettings = (
5
+ ctx: ExtensionCommandContext,
6
+ tab: SettingsTab,
7
+ ) => Promise<void>;
8
+
9
+ export interface FeatureSettings {
10
+ openSettings(ctx: ExtensionCommandContext): Promise<SettingsTab | undefined>;
11
+ }
@@ -0,0 +1,3 @@
1
+ export function minuteTimestamp(value: string | number = Date.now()): string {
2
+ return new Date(value).toISOString().slice(0, 16) + "Z";
3
+ }
package/tsconfig.json ADDED
@@ -0,0 +1,9 @@
1
+ {
2
+ "extends": "../../tsconfig.base.json",
3
+ "compilerOptions": {
4
+ "allowJs": true,
5
+ "checkJs": true,
6
+ "allowImportingTsExtensions": true
7
+ },
8
+ "include": ["index.ts", "src/**/*.ts", "src/**/*.mjs"]
9
+ }