@howaboua/pi-agent-comms 0.0.0-stage → 0.0.1-dev.14.1.g7d1d3da173aa

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,221 @@
1
+ import { setImmediate } from "node:timers/promises";
2
+ import type { SessionEntry } from "@earendil-works/pi-coding-agent";
3
+ import { buildTreeArchiveIndex } from "./tree-archive.js";
4
+ import { windowDetails } from "./window-message.js";
5
+
6
+ interface HistoryItem {
7
+ window_id: string;
8
+ item_id: string;
9
+ role: string;
10
+ tool_name?: string;
11
+ tool_namespace?: string;
12
+ content: string;
13
+ }
14
+
15
+ // Cache lazy metadata, not rendered content: Pi retains persisted entries, so
16
+ // caching serialized tool arguments would duplicate them for the session lifetime.
17
+ const cachedItems = new WeakMap<SessionEntry, HistoryItem>();
18
+ const indexItems = new WeakMap<
19
+ HistoryItem,
20
+ Pick<HistoryItem, "item_id" | "content">
21
+ >();
22
+ function customHistoryRole(
23
+ entry: Extract<SessionEntry, { type: "custom_message" }>,
24
+ ): string {
25
+ // Persisted developer metadata is a wire contract, not a package dependency.
26
+ const details = entry.details;
27
+ const metadata =
28
+ details &&
29
+ typeof details === "object" &&
30
+ "@howaboua/pi-codex-conversion/developer-message" in details
31
+ ? details["@howaboua/pi-codex-conversion/developer-message"]
32
+ : [
33
+ "codex-developer-message",
34
+ "codex-context-window",
35
+ "codex-current-time-reminder",
36
+ "codex-toolkit-update",
37
+ "codex-notebook-status",
38
+ "codex-context-briefing",
39
+ ].includes(entry.customType)
40
+ ? details
41
+ : undefined;
42
+ return metadata &&
43
+ typeof metadata === "object" &&
44
+ "protocol" in metadata &&
45
+ metadata.protocol === 1 &&
46
+ "id" in metadata &&
47
+ typeof metadata.id === "string" &&
48
+ metadata.id.trim() !== ""
49
+ ? "developer"
50
+ : "user";
51
+ }
52
+
53
+ /** Pi's selected JSONL branch is the archive. */
54
+ export async function historyWindows(
55
+ entries: readonly SessionEntry[],
56
+ sessionId: string,
57
+ allEntries: readonly SessionEntry[],
58
+ signal?: AbortSignal,
59
+ ): Promise<{
60
+ windows: Map<string, HistoryItem[]>;
61
+ retired: Set<string>;
62
+ indexItems: Pick<typeof indexItems, "get" | "has">;
63
+ }> {
64
+ const archive = buildTreeArchiveIndex(allEntries, entries);
65
+ if (archive.invalidManifest)
66
+ throw new Error(
67
+ "Saved history could not be read. Open an intact copy of the source session.",
68
+ );
69
+ if (archive.archives.some((item) => !item.entries))
70
+ throw new Error(
71
+ "Archived history is unavailable in this session copy. Resume the source session.",
72
+ );
73
+ const seen = new Set<string>();
74
+ entries = [
75
+ ...archive.archives.flatMap((item) => item.entries ?? []),
76
+ ...entries,
77
+ ].filter((entry) => {
78
+ if (seen.has(entry.id)) return false;
79
+ seen.add(entry.id);
80
+ return true;
81
+ });
82
+ let windowId = `session:${sessionId}`;
83
+ let activeStart = 0;
84
+ let hasWindowBoundary = false;
85
+ const positions = new Map(
86
+ entries.map((entry, position) => [entry.id, position]),
87
+ );
88
+ for (const [position, entry] of entries.entries()) {
89
+ const boundary = windowDetails(entry);
90
+ if (boundary?.kind === "window") {
91
+ // Pi persists the initial kickoff before the returned window message.
92
+ if (
93
+ !hasWindowBoundary &&
94
+ !boundary.trim &&
95
+ boundary.identity.windowNumber === 0
96
+ )
97
+ windowId = boundary.identity.currentWindowId;
98
+ hasWindowBoundary = true;
99
+ if (boundary.trim) activeStart = position + 1;
100
+ }
101
+ if (entry.type === "compaction") {
102
+ const kept = positions.get(entry.firstKeptEntryId);
103
+ if (kept !== undefined && kept <= position)
104
+ activeStart = Math.max(activeStart, kept);
105
+ }
106
+ }
107
+ const retired = new Set(
108
+ entries.slice(0, activeStart).map((entry) => entry.id),
109
+ );
110
+ const windows = new Map<string, HistoryItem[]>();
111
+ windows.set(windowId, []);
112
+ for (const [position, entry] of entries.entries()) {
113
+ if (position % 512 === 0) {
114
+ await setImmediate();
115
+ signal?.throwIfAborted();
116
+ }
117
+ const boundary = windowDetails(entry);
118
+ if (boundary?.kind === "window") {
119
+ windowId = boundary.identity.currentWindowId;
120
+ if (!windows.has(windowId)) windows.set(windowId, []);
121
+ continue;
122
+ }
123
+ const cached = cachedItems.get(entry);
124
+ if (cached?.window_id === windowId) {
125
+ windows.get(windowId)!.push(cached);
126
+ continue;
127
+ }
128
+ let item: HistoryItem | undefined;
129
+ if (entry.type === "message") {
130
+ const message = entry.message;
131
+ const call =
132
+ message.role === "assistant"
133
+ ? message.content.find((block) => block.type === "toolCall")
134
+ : undefined;
135
+ const toolName =
136
+ message.role === "toolResult"
137
+ ? message.toolName
138
+ : call?.type === "toolCall"
139
+ ? call.name
140
+ : undefined;
141
+ const render = () =>
142
+ !("content" in message)
143
+ ? JSON.stringify(message)
144
+ : typeof message.content === "string"
145
+ ? message.content
146
+ : message.content
147
+ .map((block) => {
148
+ if (block.type === "text") return block.text;
149
+ if (block.type === "thinking") return block.thinking;
150
+ if (block.type === "toolCall")
151
+ return JSON.stringify({
152
+ tool: block.name,
153
+ arguments: block.arguments,
154
+ });
155
+ if (block.type === "image")
156
+ return `[image ${block.mimeType}]`;
157
+ return JSON.stringify(block);
158
+ })
159
+ .join("\n");
160
+ item = {
161
+ window_id: windowId,
162
+ item_id: entry.id,
163
+ role: message.role === "toolResult" ? "tool" : message.role,
164
+ ...(toolName
165
+ ? {
166
+ tool_name: toolName,
167
+ ...(["notes", "history"].includes(toolName)
168
+ ? { tool_namespace: toolName }
169
+ : {}),
170
+ }
171
+ : {}),
172
+ get content() {
173
+ return render();
174
+ },
175
+ };
176
+ if (message.role === "user" || message.role === "assistant") {
177
+ const body = message.content;
178
+ const hasText =
179
+ typeof body === "string"
180
+ ? body.length > 0
181
+ : body.some(
182
+ (block) => block.type === "text" && block.text.length > 0,
183
+ );
184
+ let indexedContent: string | undefined;
185
+ if (hasText)
186
+ indexItems.set(item, {
187
+ item_id: item.item_id,
188
+ get content() {
189
+ return (indexedContent ??=
190
+ typeof body === "string"
191
+ ? body
192
+ : body
193
+ .filter((block) => block.type === "text")
194
+ .map((block) => block.text)
195
+ .join("\n"));
196
+ },
197
+ });
198
+ }
199
+ } else if (entry.type === "custom_message" && !boundary) {
200
+ item = {
201
+ window_id: windowId,
202
+ item_id: entry.id,
203
+ role: customHistoryRole(entry),
204
+ get content() {
205
+ return typeof entry.content === "string"
206
+ ? entry.content
207
+ : entry.content
208
+ .map((block) =>
209
+ block.type === "text" ? block.text : "[image]",
210
+ )
211
+ .join("\n");
212
+ },
213
+ };
214
+ }
215
+ if (item) {
216
+ cachedItems.set(entry, item);
217
+ windows.get(windowId)!.push(item);
218
+ }
219
+ }
220
+ return { windows, retired, indexItems };
221
+ }
@@ -0,0 +1,158 @@
1
+ import type { SessionEntry } from "@earendil-works/pi-coding-agent";
2
+ import type { HistorySearch } from "./history-search.js";
3
+ import { historyWindows } from "./history-windows.js";
4
+
5
+ export async function indexHistory(
6
+ entries: readonly SessionEntry[],
7
+ sessionId: string,
8
+ search: HistorySearch,
9
+ allEntries: readonly SessionEntry[] = entries,
10
+ ): Promise<void> {
11
+ if (!search.isEnabled(sessionId)) return;
12
+ const { windows, retired, indexItems } = await historyWindows(
13
+ entries,
14
+ sessionId,
15
+ allEntries,
16
+ );
17
+ const items = [...windows.values()].flat();
18
+ await search.index(
19
+ sessionId,
20
+ items
21
+ .filter((item) => retired.has(item.item_id))
22
+ .flatMap((item) => indexItems.get(item) ?? []),
23
+ undefined,
24
+ items
25
+ .filter((item) => !retired.has(item.item_id) || !indexItems.has(item))
26
+ .map((item) => item.item_id),
27
+ );
28
+ }
29
+
30
+ export async function useHistory(
31
+ entries: readonly SessionEntry[],
32
+ params: Record<string, unknown>,
33
+ sessionId: string,
34
+ search: HistorySearch,
35
+ allEntries: readonly SessionEntry[] = entries,
36
+ signal?: AbortSignal,
37
+ liveAccess = false,
38
+ ): Promise<Record<string, unknown>> {
39
+ signal?.throwIfAborted();
40
+ const { windows, retired, indexItems } = await historyWindows(
41
+ entries,
42
+ sessionId,
43
+ allEntries,
44
+ signal,
45
+ );
46
+ const action = params["action"];
47
+ if (action === "list_windows") {
48
+ let values = [...windows].filter(([, items]) => items.length);
49
+ if (params["recent_first"] === true) values = values.reverse();
50
+ const limit = integer(params["limit"], 20, 100);
51
+ return {
52
+ windows: values
53
+ .slice(0, limit)
54
+ .map(([id, items]) => ({ window_id: id, item_count: items.length })),
55
+ truncated: values.length > limit,
56
+ };
57
+ }
58
+ if (action === "read_item") {
59
+ const windowId = params["window_id"];
60
+ const itemId = params["item_id"];
61
+ if (typeof windowId !== "string" || typeof itemId !== "string")
62
+ throw new Error(
63
+ `history read requires ${typeof windowId !== "string" ? "window_id" : "item_id"} as a string. Copy window_id and item_id from the same search or list result`,
64
+ );
65
+ // Keep exact pre-initialisation references saved by earlier releases readable.
66
+ const items =
67
+ windows.get(windowId) ??
68
+ (windowId === `session:${sessionId}`
69
+ ? windows.values().next().value
70
+ : undefined);
71
+ const item = items?.find((item) => item.item_id === itemId);
72
+ if (!item) return { item: null };
73
+ const { content: fullContent, ...metadata } = item;
74
+ const offset = integer(params["offset_chars"], 0, fullContent.length);
75
+ const limit = integer(params["limit_chars"], 8000, 8000);
76
+ const content = fullContent.slice(offset, offset + limit);
77
+ return {
78
+ item: {
79
+ ...metadata,
80
+ content,
81
+ total_chars: fullContent.length,
82
+ ...(offset + content.length < fullContent.length
83
+ ? { next_offset_chars: offset + content.length }
84
+ : {}),
85
+ },
86
+ };
87
+ }
88
+ if (action !== "list_items" && action !== "search_contents")
89
+ throw new Error("Unknown history action");
90
+ if (
91
+ action === "search_contents" &&
92
+ (typeof params["query"] !== "string" || !params["query"])
93
+ )
94
+ throw new Error("Supply a nonempty search query");
95
+ const limit = integer(params["limit"], 10, 25);
96
+ let items = [...windows.values()]
97
+ .flat()
98
+ .filter(
99
+ (item) =>
100
+ (!params["window_id"] || item.window_id === params["window_id"]) &&
101
+ (!params["role"] || item.role === params["role"]) &&
102
+ (!params["tool_name"] || item.tool_name === params["tool_name"]) &&
103
+ (!params["tool_namespace"] ||
104
+ item.tool_namespace === params["tool_namespace"]),
105
+ );
106
+ const ranked =
107
+ search.isEnabled(sessionId) &&
108
+ !liveAccess &&
109
+ !params["agent_name"] &&
110
+ (!params["role"] ||
111
+ params["role"] === "user" ||
112
+ params["role"] === "assistant") &&
113
+ !params["tool_name"] &&
114
+ !params["tool_namespace"] &&
115
+ (!params["window_id"] || items.every((item) => retired.has(item.item_id)));
116
+ if (action === "search_contents" && ranked) {
117
+ const canonical = new Map(items.map((item) => [item.item_id, item]));
118
+ const matches = await search.search(
119
+ sessionId,
120
+ items
121
+ .filter((item) => retired.has(item.item_id))
122
+ .flatMap((item) => indexItems.get(item) ?? []),
123
+ params["query"] as string,
124
+ limit,
125
+ params["recent_first"] === true,
126
+ signal,
127
+ );
128
+ items = matches.map((item) => canonical.get(item.item_id)!);
129
+ } else {
130
+ if (action === "search_contents")
131
+ items = items.filter((item) =>
132
+ item.content.includes(params["query"] as string),
133
+ );
134
+ if (params["recent_first"] === true) items = items.reverse();
135
+ }
136
+ const previewChars = integer(params["max_chars_per_item"], 1000, 1000);
137
+ const previews = [];
138
+ let size = 0;
139
+ for (const item of items) {
140
+ const { content, ...metadata } = item;
141
+ const preview = {
142
+ ...metadata,
143
+ truncated_content: content.slice(0, previewChars),
144
+ content_chars: content.length,
145
+ };
146
+ const chars = JSON.stringify(preview).length;
147
+ if (previews.length >= limit || size + chars > 8000) break;
148
+ previews.push(preview);
149
+ size += chars;
150
+ }
151
+ return { items: previews, truncated: previews.length < items.length };
152
+ }
153
+
154
+ function integer(value: unknown, fallback: number, max: number): number {
155
+ return typeof value === "number" && Number.isInteger(value)
156
+ ? Math.max(0, Math.min(value, max))
157
+ : fallback;
158
+ }
@@ -0,0 +1,201 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import type {
3
+ ExtensionAPI,
4
+ ExtensionContext,
5
+ InputEvent,
6
+ InputEventResult,
7
+ } from "@earendil-works/pi-coding-agent";
8
+ import type { NotesLifecycle } from "./lifecycle.js";
9
+ import { SETTLEMENT_ENTRY } from "./windows.js";
10
+
11
+ interface HeldInput {
12
+ sessionId: string;
13
+ phase: "failed" | "rolling" | "releasing" | "draining";
14
+ releasePrompt: string;
15
+ admissions: ((result: InputEventResult) => void)[];
16
+ }
17
+
18
+ // Owns suspended input calls and custom-kickoff admission; reset settles held callers.
19
+ export class IdleAdmission {
20
+ private held: HeldInput | undefined;
21
+ private customAdmission: Promise<void> | undefined;
22
+ private readonly host: Pick<
23
+ NotesLifecycle,
24
+ "active" | "fresh" | "windows" | "idleMinutes"
25
+ >;
26
+ private readonly pi: ExtensionAPI;
27
+ private readonly roll: (
28
+ ctx: ExtensionContext,
29
+ triggerTurn: boolean,
30
+ ) => Promise<void>;
31
+ private readonly rolloverPending: () => boolean;
32
+ private readonly checkpointPending: () => boolean;
33
+ constructor(
34
+ host: IdleAdmission["host"],
35
+ pi: ExtensionAPI,
36
+ roll: IdleAdmission["roll"],
37
+ rolloverPending: () => boolean,
38
+ checkpointPending: () => boolean,
39
+ ) {
40
+ this.host = host;
41
+ this.pi = pi;
42
+ this.roll = roll;
43
+ this.rolloverPending = rolloverPending;
44
+ this.checkpointPending = checkpointPending;
45
+ }
46
+ get pending(): boolean {
47
+ return Boolean(this.held);
48
+ }
49
+ reset(): void {
50
+ this.customAdmission = undefined;
51
+ for (const admit of this.held?.admissions ?? [])
52
+ admit({ action: "handled" });
53
+ this.held = undefined;
54
+ }
55
+ fail(ctx: ExtensionContext, error: unknown): void {
56
+ if (this.held) this.failHeld(ctx, this.held, error);
57
+ }
58
+ drain(): boolean {
59
+ if (this.held?.phase !== "draining") return false;
60
+ // Retry admissions are original SDK calls too. Releasing all at once races Agent.prompt.
61
+ this.held.phase = "releasing";
62
+ this.pi.sendUserMessage(this.held.releasePrompt);
63
+ return true;
64
+ }
65
+
66
+ prepareCustomTurn(ctx: ExtensionContext): Promise<void> | undefined {
67
+ if (this.customAdmission) return this.customAdmission;
68
+ if (!this.host.active || !this.idleDue(ctx) || !this.host.fresh(ctx))
69
+ return;
70
+ const sessionId = ctx.sessionManager.getSessionId();
71
+ const preparation = this.roll(ctx, false)
72
+ .then(() => {
73
+ if (
74
+ !this.host.active ||
75
+ sessionId !== ctx.sessionManager.getSessionId()
76
+ )
77
+ throw new Error("Session changed during custom kickoff admission");
78
+ })
79
+ .finally(() => {
80
+ if (this.customAdmission === preparation)
81
+ this.customAdmission = undefined;
82
+ });
83
+ this.customAdmission = preparation;
84
+ return preparation;
85
+ }
86
+ private idleDue(ctx: ExtensionContext): boolean {
87
+ if (
88
+ this.host.idleMinutes === 0 ||
89
+ !ctx.isIdle() ||
90
+ !this.host.windows.current ||
91
+ this.rolloverPending() ||
92
+ this.checkpointPending()
93
+ )
94
+ return false;
95
+ const branch = ctx.sessionManager.getBranch();
96
+ const terminal = branch.findLast(
97
+ (entry) => entry.type === "message" && entry.message.role !== "system",
98
+ );
99
+ if (!terminal) return false;
100
+ const settlement = ctx.sessionManager
101
+ .getEntries()
102
+ .findLast(
103
+ (entry) =>
104
+ entry.type === "custom" &&
105
+ entry.customType === SETTLEMENT_ENTRY &&
106
+ entry.data &&
107
+ typeof entry.data === "object" &&
108
+ "completedEntryId" in entry.data &&
109
+ entry.data.completedEntryId === terminal.id,
110
+ );
111
+ if (
112
+ settlement?.type !== "custom" ||
113
+ !settlement.data ||
114
+ typeof settlement.data !== "object"
115
+ )
116
+ return false;
117
+ const data = settlement.data;
118
+ return (
119
+ !("aborted" in data && data.aborted === true) &&
120
+ "windowId" in data &&
121
+ data.windowId === this.host.windows.current.currentWindowId &&
122
+ "settledAt" in data &&
123
+ typeof data.settledAt === "number" &&
124
+ Number.isFinite(data.settledAt) &&
125
+ Date.now() - data.settledAt >= this.host.idleMinutes * 60_000
126
+ );
127
+ }
128
+ async input(
129
+ event: InputEvent,
130
+ ctx: ExtensionContext,
131
+ ): Promise<InputEventResult | undefined> {
132
+ const releasing = this.held;
133
+ if (
134
+ releasing?.phase === "releasing" &&
135
+ event.source === "extension" &&
136
+ event.text === releasing.releasePrompt
137
+ ) {
138
+ const admit = releasing.admissions.shift();
139
+ if (releasing.admissions.length) releasing.phase = "draining";
140
+ else this.held = undefined;
141
+ admit?.({ action: "continue" });
142
+ return { action: "handled" };
143
+ }
144
+ if (!this.held && (!this.idleDue(ctx) || !this.host.fresh(ctx))) return;
145
+ const held =
146
+ this.held ??
147
+ ({
148
+ sessionId: ctx.sessionManager.getSessionId(),
149
+ phase: "failed",
150
+ releasePrompt: `Admit saved input: ${randomUUID()}`,
151
+ admissions: [],
152
+ } satisfies HeldInput);
153
+ this.held = held;
154
+ const admission = new Promise<InputEventResult>((resolve) =>
155
+ held.admissions.push(resolve),
156
+ );
157
+ if (held.phase !== "failed") return admission;
158
+ held.phase = "rolling";
159
+ void Promise.resolve().then(async () => {
160
+ try {
161
+ if (
162
+ this.held !== held ||
163
+ held.sessionId !== ctx.sessionManager.getSessionId()
164
+ )
165
+ return;
166
+ await this.finishHeld(ctx, held);
167
+ } catch (error) {
168
+ this.failHeld(ctx, held, error);
169
+ }
170
+ });
171
+ return admission;
172
+ }
173
+ private failHeld(
174
+ ctx: ExtensionContext,
175
+ held: HeldInput,
176
+ error: unknown,
177
+ ): void {
178
+ if (this.held !== held) return;
179
+ held.phase = "failed";
180
+ ctx.ui.notify(
181
+ `Idle rollover failed: ${error instanceof Error ? error.message : String(error)}. Input and attachments remain pending. Submit another prompt to retry, or reload to cancel.`,
182
+ "error",
183
+ );
184
+ }
185
+ private async finishHeld(
186
+ ctx: ExtensionContext,
187
+ held: HeldInput,
188
+ ): Promise<void> {
189
+ held.phase = "rolling";
190
+ await this.roll(ctx, false);
191
+ if (
192
+ this.held !== held ||
193
+ held.sessionId !== ctx.sessionManager.getSessionId()
194
+ )
195
+ return;
196
+ held.phase = "releasing";
197
+ // Pi defers this user kickoff until EVERY agent_settled handler returns.
198
+ // Its input-only admission releases the original SDK calls, preserving images/options.
199
+ this.pi.sendUserMessage(held.releasePrompt);
200
+ }
201
+ }
@@ -0,0 +1,125 @@
1
+ import { join } from "node:path";
2
+ import {
3
+ type ExtensionAPI,
4
+ type ExtensionContext,
5
+ getAgentDir,
6
+ } from "@earendil-works/pi-coding-agent";
7
+ import { createNotesActivation } from "./activation.js";
8
+ import { createNotesContextOwner } from "./context-owner.js";
9
+ import { registerNotesHooks } from "./extension-hooks.js";
10
+ import { registerNotesSharing } from "./extension-sharing.js";
11
+ import { registerCheckpointRenderer } from "./fresh-checkpoint.js";
12
+ import { HistorySearch } from "./history-search.js";
13
+ import { registerNotesToolIntegrations } from "./integrations.js";
14
+ import { NotesLifecycle } from "./lifecycle.js";
15
+ import { createModelRoles } from "./model-roles.js";
16
+ import { registerNoteSaveMarkers } from "./note-save-marker.js";
17
+ import { SessionPruning } from "./session-pruning.js";
18
+ import type { NotesSettings } from "./settings.js";
19
+ import type { NotesStore } from "./store.js";
20
+ import { createTools } from "./tools.js";
21
+ import { WindowCheckpoints } from "./window-checkpoint.js";
22
+ import { registerWindowRenderer } from "./windows.js";
23
+
24
+ export async function createNotesRuntime(pi: ExtensionAPI, store: NotesStore) {
25
+ registerWindowRenderer(pi);
26
+ registerCheckpointRenderer(pi);
27
+ const dir = join(getAgentDir(), "notes-compaction");
28
+ const settingsPath = join(dir, "settings.json");
29
+ const search = new HistorySearch(join(dir, "history-search.sqlite"));
30
+ const lifecycle = new NotesLifecycle(pi, store);
31
+ const checkpoints = new WindowCheckpoints((entries) =>
32
+ lifecycle.windows.projectBranch(entries),
33
+ );
34
+ let refreshNested = () => {};
35
+ const activation = createNotesActivation(
36
+ pi,
37
+ store,
38
+ search,
39
+ lifecycle,
40
+ settingsPath,
41
+ () => refreshNested(),
42
+ );
43
+ const stopAdmission = pi.events.on(
44
+ "pi-notes-compaction:custom-turn-admission:v1",
45
+ (value) => {
46
+ const request = value as {
47
+ protocol?: number;
48
+ ctx: Parameters<NotesLifecycle["prepareCustomTurn"]>[0];
49
+ preparation?: Promise<void>;
50
+ };
51
+ if (request?.protocol === 1 && !request.preparation) {
52
+ activation.refreshActivation(request.ctx);
53
+ request.preparation = (async () => {
54
+ if (activation.available && request.ctx.isIdle())
55
+ await checkpoints.restore(request.ctx);
56
+ await lifecycle.prepareCustomTurn(request.ctx);
57
+ })();
58
+ }
59
+ },
60
+ );
61
+ const roles = createModelRoles(pi, activation, lifecycle);
62
+ const tools = createTools(pi, store, lifecycle, search, roles);
63
+ refreshNested = await registerNotesToolIntegrations(
64
+ pi,
65
+ lifecycle,
66
+ activation,
67
+ tools,
68
+ );
69
+ for (const tool of tools) pi.registerTool(tool);
70
+ const owner = createNotesContextOwner(pi, store, lifecycle, search);
71
+ const { family, stopOwner } = await registerNotesSharing(
72
+ pi,
73
+ owner,
74
+ activation,
75
+ lifecycle,
76
+ );
77
+ const markers = registerNoteSaveMarkers(
78
+ pi,
79
+ () => lifecycle.active && activation.settings.noteSaveMarkers,
80
+ () => lifecycle.windows.current?.currentWindowId,
81
+ );
82
+ await registerNotesHooks(
83
+ pi,
84
+ activation,
85
+ lifecycle,
86
+ owner,
87
+ checkpoints,
88
+ markers,
89
+ );
90
+ const sessionPruning = new SessionPruning(
91
+ pi,
92
+ store,
93
+ search,
94
+ () => lifecycle.windows.current?.currentWindowId,
95
+ );
96
+ sessionPruning.register();
97
+ pi.on("session_shutdown", () => {
98
+ lifecycle.reset();
99
+ lifecycle.active = false;
100
+ search.close();
101
+ stopOwner();
102
+ stopAdmission();
103
+ });
104
+ return {
105
+ activation,
106
+ lifecycle,
107
+ search,
108
+ sessionPruning,
109
+ roles,
110
+ async start(ctx: ExtensionContext, settings?: NotesSettings) {
111
+ markers.start(ctx);
112
+ activation.start(ctx, family, settings);
113
+ if (activation.available) {
114
+ try {
115
+ await checkpoints.restore(ctx);
116
+ } catch (error) {
117
+ ctx.ui.notify(`Context checkpoint failed: ${String(error)}`, "error");
118
+ }
119
+ }
120
+ sessionPruning.start(ctx);
121
+ },
122
+ };
123
+ }
124
+
125
+ export type NotesRuntime = Awaited<ReturnType<typeof createNotesRuntime>>;