@narumitw/pi-context-management 0.0.0

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.
@@ -0,0 +1,895 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { realpathSync } from "node:fs";
3
+ import { join } from "node:path";
4
+ import { fileURLToPath } from "node:url";
5
+ import type { AgentMessage } from "@earendil-works/pi-agent-core";
6
+ import {
7
+ type AgentEndEvent,
8
+ type ExtensionAPI,
9
+ type ExtensionContext,
10
+ type SessionBeforeCompactEvent,
11
+ type SessionCompactEvent,
12
+ type SessionEntry,
13
+ sessionEntryToContextMessages,
14
+ } from "@earendil-works/pi-coding-agent";
15
+ import {
16
+ CONTEXT_MANAGEMENT_TOOL_NAMES,
17
+ type ContextToolRuntime,
18
+ registerContextManagementTools,
19
+ } from "./context-tools.js";
20
+ import {
21
+ activeContextManagementCompaction,
22
+ CONTEXT_CONTRACT_MESSAGE_TYPE,
23
+ CONTEXT_DEACTIVATION_MESSAGE_TYPE,
24
+ CONTEXT_DETAILS_KIND,
25
+ CONTEXT_STATE_ENTRY_TYPE,
26
+ CONTEXT_VERSION,
27
+ type ContextBranchScanBudget,
28
+ type ContextLineage,
29
+ compactionRetainedContext,
30
+ contextContract,
31
+ contextDeactivation,
32
+ createContextBranchScanBudget,
33
+ createContextContractMessage,
34
+ createContextManagementDetails,
35
+ createInitialContextState,
36
+ hasContextContract,
37
+ latestContextMode,
38
+ loadContextLineage,
39
+ parseContextManagementCompaction,
40
+ projectContextManagementContext,
41
+ reconcileContextContract,
42
+ visitContextBranchEntry,
43
+ } from "./context-window.js";
44
+ import { createFingerprintBudget } from "./fingerprint.js";
45
+ import type { ContextManagementSettingsRuntime } from "./settings.js";
46
+ import { terminalText } from "./terminal.js";
47
+
48
+ const CONTINUATION_MESSAGE_TYPE = "pi-context-management-continuation";
49
+ const ROLLOVER_STATE_ENTRY_TYPE = "pi-context-management-rollover";
50
+ const START_NEW_CONTEXT_TOOL_NAME = "context_management_start_new_context";
51
+ const EXTENSION_ENTRY_PATH = realpathSync(join(fileURLToPath(new URL(".", import.meta.url)), "index.ts"));
52
+
53
+ type PendingRollover = {
54
+ requestId: string;
55
+ nextWindowId: string;
56
+ sessionId: string;
57
+ generation: number;
58
+ status: "requested" | "compacting" | "completed" | "failed";
59
+ turnStartedAfterRequest: boolean;
60
+ successfulTurnAfterRequest: boolean;
61
+ reason?: string;
62
+ errorMessage?: string;
63
+ };
64
+
65
+ type SessionKey = ExtensionContext["sessionManager"];
66
+
67
+ interface SessionState {
68
+ key: SessionKey;
69
+ generation: number;
70
+ sessionId: string;
71
+ lineage?: ContextLineage;
72
+ lineageFailed: boolean;
73
+ pending?: PendingRollover;
74
+ warned: boolean;
75
+ warnedUnavailableTools: boolean;
76
+ warnedProjectionFailure: boolean;
77
+ toolsAvailable: boolean;
78
+ removeToolsAtSettlement: boolean;
79
+ fallbackDeactivationPending: boolean;
80
+ fallbackActivationPending: boolean;
81
+ agentRunActive: boolean;
82
+ controller: AbortController;
83
+ }
84
+
85
+ function sameNames(left: readonly string[], right: readonly string[]): boolean {
86
+ return left.length === right.length && left.every((name, index) => name === right[index]);
87
+ }
88
+
89
+ function isOwnedToolSource(tool: { sourceInfo: { path: string } } | undefined): boolean {
90
+ if (!tool || tool.sourceInfo.path.startsWith("<")) return false;
91
+ try {
92
+ return realpathSync(tool.sourceInfo.path) === EXTENSION_ENTRY_PATH;
93
+ } catch {
94
+ return false;
95
+ }
96
+ }
97
+
98
+ function isRecord(value: unknown): value is Record<string, unknown> {
99
+ return typeof value === "object" && value !== null && !Array.isArray(value);
100
+ }
101
+
102
+ function isIdentifier(value: unknown): value is string {
103
+ return typeof value === "string" && value.length >= 8 && value.length <= 128;
104
+ }
105
+
106
+ function contractMessage(lineage: ContextLineage) {
107
+ return {
108
+ customType: CONTEXT_CONTRACT_MESSAGE_TYPE,
109
+ content: contextContract(lineage),
110
+ display: false,
111
+ details: {
112
+ kind: CONTEXT_DETAILS_KIND,
113
+ version: CONTEXT_VERSION,
114
+ currentWindowId: lineage.currentWindowId,
115
+ },
116
+ };
117
+ }
118
+
119
+ function deactivationMessage() {
120
+ return {
121
+ customType: CONTEXT_DEACTIVATION_MESSAGE_TYPE,
122
+ content: contextDeactivation(),
123
+ display: false,
124
+ details: { kind: CONTEXT_DETAILS_KIND, version: CONTEXT_VERSION },
125
+ };
126
+ }
127
+
128
+ function deactivationAgentMessage(): AgentMessage {
129
+ return {
130
+ role: "custom",
131
+ ...deactivationMessage(),
132
+ timestamp: 0,
133
+ };
134
+ }
135
+
136
+ interface CompactFailedEvent {
137
+ errorMessage?: string;
138
+ aborted: boolean;
139
+ }
140
+
141
+ function latestAssistantStopReason(messages: readonly AgentMessage[]): string | undefined {
142
+ for (let index = messages.length - 1; index >= 0; index -= 1) {
143
+ const message = messages[index];
144
+ if (message.role === "assistant") return message.stopReason;
145
+ }
146
+ return undefined;
147
+ }
148
+
149
+ function terminalRolloverRequestId(entry: SessionEntry): string | undefined {
150
+ if (entry.type === "custom" && entry.customType === ROLLOVER_STATE_ENTRY_TYPE) {
151
+ const data = entry.data;
152
+ return isRecord(data) &&
153
+ data.kind === CONTEXT_DETAILS_KIND &&
154
+ data.version === CONTEXT_VERSION &&
155
+ (data.status === "cancelled" || data.status === "suppressed") &&
156
+ isIdentifier(data.requestId)
157
+ ? data.requestId
158
+ : undefined;
159
+ }
160
+ const message = entry.type === "message" && entry.message.role === "custom" ? entry.message : undefined;
161
+ const customMessage = entry.type === "custom_message" ? entry : message;
162
+ if (
163
+ customMessage?.customType === CONTINUATION_MESSAGE_TYPE &&
164
+ isRecord(customMessage.details) &&
165
+ customMessage.details.kind === CONTEXT_DETAILS_KIND &&
166
+ customMessage.details.version === CONTEXT_VERSION &&
167
+ isIdentifier(customMessage.details.requestId)
168
+ ) {
169
+ return customMessage.details.requestId;
170
+ }
171
+ return undefined;
172
+ }
173
+
174
+ function restoredRollover(
175
+ entries: readonly SessionEntry[],
176
+ sessionId: string,
177
+ generation: number,
178
+ budget: ContextBranchScanBudget = createContextBranchScanBudget(),
179
+ ): PendingRollover | undefined {
180
+ const terminalRequests = new Set<string>();
181
+ const completedRequests = new Map<string, string>();
182
+ for (let index = entries.length - 1; index >= 0; index -= 1) {
183
+ visitContextBranchEntry(budget);
184
+ const entry = entries[index];
185
+ const terminalRequestId = terminalRolloverRequestId(entry);
186
+ if (terminalRequestId) terminalRequests.add(terminalRequestId);
187
+ if (entry.type === "compaction") {
188
+ const details = parseContextManagementCompaction(entry, budget);
189
+ if (details?.requestId) completedRequests.set(details.requestId, details.currentWindowId);
190
+ continue;
191
+ }
192
+ if (entry.type !== "message") continue;
193
+ const message = entry.message;
194
+ if (message.role !== "toolResult" || message.toolName !== START_NEW_CONTEXT_TOOL_NAME) continue;
195
+ const details = message.details;
196
+ if (
197
+ !isRecord(details) ||
198
+ details.kind !== CONTEXT_DETAILS_KIND ||
199
+ details.version !== CONTEXT_VERSION ||
200
+ details.status !== "scheduled" ||
201
+ !isIdentifier(details.requestId) ||
202
+ !isIdentifier(details.currentWindowId) ||
203
+ !isIdentifier(details.nextWindowId) ||
204
+ (details.reason !== undefined && (typeof details.reason !== "string" || details.reason.length > 512))
205
+ ) {
206
+ continue;
207
+ }
208
+ if (terminalRequests.has(details.requestId)) return undefined;
209
+ const completedWindowId = completedRequests.get(details.requestId);
210
+ return {
211
+ requestId: details.requestId,
212
+ nextWindowId: completedWindowId ?? details.nextWindowId,
213
+ sessionId,
214
+ generation,
215
+ status: completedWindowId ? "completed" : "requested",
216
+ turnStartedAfterRequest: false,
217
+ successfulTurnAfterRequest: false,
218
+ ...(typeof details.reason === "string" ? { reason: details.reason } : {}),
219
+ };
220
+ }
221
+ return undefined;
222
+ }
223
+
224
+ function boundedContextMessages(entries: readonly SessionEntry[]): AgentMessage[] {
225
+ const budget = createContextBranchScanBudget();
226
+ const messages: AgentMessage[] = [];
227
+ for (const entry of entries) {
228
+ visitContextBranchEntry(budget);
229
+ messages.push(...sessionEntryToContextMessages(entry));
230
+ }
231
+ return messages;
232
+ }
233
+
234
+ function branchContainsEntry(entries: readonly SessionEntry[], entryId: string): boolean {
235
+ const budget = createContextBranchScanBudget();
236
+ for (let index = entries.length - 1; index >= 0; index -= 1) {
237
+ visitContextBranchEntry(budget);
238
+ if (entries[index].id === entryId) return true;
239
+ }
240
+ return false;
241
+ }
242
+
243
+ type BeforeCompactResult =
244
+ | { cancel: true }
245
+ | {
246
+ compaction: {
247
+ summary: string;
248
+ firstKeptEntryId: string;
249
+ tokensBefore: number;
250
+ details: unknown;
251
+ };
252
+ };
253
+
254
+ export interface ContextManager {
255
+ isEnabled(ctx: ExtensionContext): boolean;
256
+ startSession(ctx: ExtensionContext): void;
257
+ onSessionTree(ctx: ExtensionContext): void;
258
+ applySettings(ctx: ExtensionContext): void;
259
+ onInput(ctx: ExtensionContext): void;
260
+ beforeCompact(event: SessionBeforeCompactEvent, ctx: ExtensionContext): BeforeCompactResult | undefined;
261
+ projectContext(messages: readonly AgentMessage[], ctx: ExtensionContext): AgentMessage[] | undefined;
262
+ onCompact(event: SessionCompactEvent, ctx: ExtensionContext): void;
263
+ onCompactFailed(event: CompactFailedEvent, ctx: ExtensionContext): void;
264
+ onAgentStart(ctx: ExtensionContext): void;
265
+ onAgentEnd(event: AgentEndEvent, ctx: ExtensionContext): void;
266
+ onTurnStart(ctx: ExtensionContext): void;
267
+ onAgentSettled(ctx: ExtensionContext): void;
268
+ shutdown(ctx: ExtensionContext): void;
269
+ }
270
+
271
+ export function createContextManager(
272
+ pi: ExtensionAPI,
273
+ settingsRuntime: ContextManagementSettingsRuntime,
274
+ ): ContextManager {
275
+ const states = new Map<SessionKey, SessionState>();
276
+ let nextGeneration = 0;
277
+ const isConfigured = () => settingsRuntime.get().settings.enabled;
278
+
279
+ const stateFor = (ctx: ExtensionContext): SessionState | undefined => {
280
+ const state = states.get(ctx.sessionManager);
281
+ return state && !state.controller.signal.aborted && state.sessionId === ctx.sessionManager.getSessionId()
282
+ ? state
283
+ : undefined;
284
+ };
285
+
286
+ const inspectToolUnit = () => {
287
+ const available = new Map(pi.getAllTools().map((tool) => [tool.name, tool]));
288
+ const ownedNames = new Set<string>(
289
+ CONTEXT_MANAGEMENT_TOOL_NAMES.filter((name) => isOwnedToolSource(available.get(name))),
290
+ );
291
+ const activeNames = new Set(pi.getActiveTools());
292
+ const unavailableNames = CONTEXT_MANAGEMENT_TOOL_NAMES.filter((name) => !ownedNames.has(name));
293
+ const inactiveNames = CONTEXT_MANAGEMENT_TOOL_NAMES.filter(
294
+ (name) => ownedNames.has(name) && !activeNames.has(name),
295
+ );
296
+ return {
297
+ ownedNames,
298
+ unavailableNames,
299
+ inactiveNames,
300
+ complete: unavailableNames.length === 0 && inactiveNames.length === 0,
301
+ };
302
+ };
303
+
304
+ const enabledFor = (state: SessionState) =>
305
+ (isConfigured() || state.removeToolsAtSettlement) && state.toolsAvailable && inspectToolUnit().complete;
306
+
307
+ const isOwned = (state: SessionState, ctx: ExtensionContext, request?: PendingRollover) =>
308
+ stateFor(ctx) === state &&
309
+ (!request ||
310
+ (request.sessionId === state.sessionId &&
311
+ request.generation === state.generation &&
312
+ state.pending?.requestId === request.requestId));
313
+
314
+ const removeOwnedTools = (ownedNames: ReadonlySet<string>) => {
315
+ const current = pi.getActiveTools();
316
+ const next = current.filter((name) => !ownedNames.has(name));
317
+ if (!sameNames(current, next)) pi.setActiveTools(next);
318
+ for (const state of states.values()) state.toolsAvailable = false;
319
+ };
320
+
321
+ const warnToolUnitUnavailable = (
322
+ state: SessionState,
323
+ ctx: ExtensionContext,
324
+ unavailableNames: readonly string[],
325
+ inactiveNames: readonly string[],
326
+ ) => {
327
+ if (state.warnedUnavailableTools || !ctx.hasUI) return;
328
+ state.warnedUnavailableTools = true;
329
+ const names = [...unavailableNames, ...inactiveNames];
330
+ ctx.ui.notify(
331
+ `Experimental context management could not activate because these tool names are unavailable, inactive, or owned by another extension: ${names.join(", ")}. Pi-native compaction remains active.`,
332
+ "warning",
333
+ );
334
+ };
335
+
336
+ const hasDeferredToolRemoval = () => [...states.values()].some((state) => state.removeToolsAtSettlement);
337
+
338
+ const reconcileTools = (state: SessionState, activate: boolean, ctx: ExtensionContext): boolean => {
339
+ const inspection = inspectToolUnit();
340
+ const available = activate && inspection.unavailableNames.length === 0;
341
+ const current = pi.getActiveTools();
342
+ const next = available
343
+ ? [...current, ...inspection.inactiveNames]
344
+ : current.filter((name) => !inspection.ownedNames.has(name));
345
+ if (!sameNames(current, next)) pi.setActiveTools(next);
346
+ for (const candidate of states.values()) {
347
+ candidate.toolsAvailable =
348
+ available && !candidate.lineageFailed && (candidate === state || candidate.lineage !== undefined);
349
+ }
350
+ if (activate && !available) {
351
+ warnToolUnitUnavailable(state, ctx, inspection.unavailableNames, inspection.inactiveNames);
352
+ }
353
+ return available;
354
+ };
355
+
356
+ const deactivateIncompleteToolUnit = (
357
+ state: SessionState,
358
+ ctx: ExtensionContext,
359
+ publishCurrentDeactivation = true,
360
+ ): boolean => {
361
+ const inspection = inspectToolUnit();
362
+ if (inspection.complete) return false;
363
+ let branchIsActive = false;
364
+ for (const candidate of states.values()) {
365
+ if (candidate.controller.signal.aborted || candidate.sessionId !== candidate.key.getSessionId()) continue;
366
+ const candidateBranchIsActive = latestContextMode(candidate.key.getBranch()) === "active";
367
+ if (candidate === state) branchIsActive = candidateBranchIsActive;
368
+ candidate.fallbackDeactivationPending = candidateBranchIsActive;
369
+ candidate.fallbackActivationPending = false;
370
+ candidate.removeToolsAtSettlement = false;
371
+ if (candidate.pending?.status === "requested" || candidate.pending?.status === "compacting") {
372
+ candidate.pending.status = "failed";
373
+ candidate.pending.errorMessage = "Experimental context management tool unit became incomplete during rollover.";
374
+ }
375
+ }
376
+ if (branchIsActive && publishCurrentDeactivation) {
377
+ pi.sendMessage(deactivationMessage(), { triggerTurn: false });
378
+ }
379
+ removeOwnedTools(inspection.ownedNames);
380
+ warnToolUnitUnavailable(state, ctx, inspection.unavailableNames, inspection.inactiveNames);
381
+ return branchIsActive;
382
+ };
383
+
384
+ const ensureLineage = (state: SessionState, ctx: ExtensionContext): ContextLineage => {
385
+ let lineage: ContextLineage;
386
+ try {
387
+ const persisted = state.lineage ?? loadContextLineage(ctx.sessionManager.getBranch());
388
+ if (persisted) {
389
+ lineage = persisted;
390
+ } else {
391
+ const initial = createInitialContextState();
392
+ pi.appendEntry(CONTEXT_STATE_ENTRY_TYPE, initial);
393
+ lineage = initial;
394
+ }
395
+ } catch (error) {
396
+ state.lineageFailed = true;
397
+ state.toolsAvailable = false;
398
+ throw error;
399
+ }
400
+ state.lineage = lineage;
401
+ state.lineageFailed = false;
402
+ state.toolsAvailable = (isConfigured() || state.removeToolsAtSettlement) && inspectToolUnit().complete;
403
+ return lineage;
404
+ };
405
+
406
+ const warnEnabled = (state: SessionState, ctx: ExtensionContext) => {
407
+ if (state.warned || !ctx.hasUI) return;
408
+ state.warned = true;
409
+ ctx.ui.notify(
410
+ "Experimental context management is active. Context rollover does not create a summary; preserve important information with context_management_update_notes.",
411
+ "warning",
412
+ );
413
+ };
414
+
415
+ const applySettings = (ctx: ExtensionContext) => {
416
+ const state = stateFor(ctx);
417
+ if (!state) return;
418
+ const branch = ctx.sessionManager.getBranch();
419
+ const runIsActive = state.agentRunActive || ctx.signal !== undefined;
420
+ state.agentRunActive = runIsActive;
421
+ if (!isConfigured()) {
422
+ const inspection = inspectToolUnit();
423
+ for (const candidate of states.values()) {
424
+ candidate.fallbackActivationPending = false;
425
+ const candidateRunIsActive = candidate === state ? runIsActive : candidate.agentRunActive;
426
+ if (candidateRunIsActive && candidate.toolsAvailable && inspection.complete) {
427
+ candidate.removeToolsAtSettlement = true;
428
+ candidate.fallbackDeactivationPending = false;
429
+ continue;
430
+ }
431
+ candidate.removeToolsAtSettlement = false;
432
+ const branchIsActive =
433
+ !candidate.controller.signal.aborted &&
434
+ candidate.sessionId === candidate.key.getSessionId() &&
435
+ latestContextMode(candidate.key.getBranch()) === "active";
436
+ candidate.fallbackDeactivationPending = branchIsActive && (candidate !== state || candidateRunIsActive);
437
+ if (branchIsActive && candidate === state && !candidateRunIsActive) {
438
+ pi.sendMessage(deactivationMessage(), { triggerTurn: false });
439
+ }
440
+ }
441
+ reconcileTools(state, hasDeferredToolRemoval(), ctx);
442
+ return;
443
+ }
444
+ const contractAlreadyActiveOrQueued = state.removeToolsAtSettlement && !state.fallbackDeactivationPending;
445
+ const deactivationAlreadyPending = state.fallbackDeactivationPending;
446
+ const toolsWereAvailable = state.toolsAvailable;
447
+ for (const candidate of states.values()) {
448
+ candidate.removeToolsAtSettlement = false;
449
+ candidate.fallbackDeactivationPending = false;
450
+ candidate.fallbackActivationPending = false;
451
+ }
452
+ if (!reconcileTools(state, true, ctx)) {
453
+ deactivateIncompleteToolUnit(state, ctx);
454
+ if (runIsActive && (toolsWereAvailable || contractAlreadyActiveOrQueued || deactivationAlreadyPending)) {
455
+ state.fallbackDeactivationPending = true;
456
+ }
457
+ return;
458
+ }
459
+ let activeLineage: ContextLineage;
460
+ try {
461
+ activeLineage = ensureLineage(state, ctx);
462
+ } catch (error) {
463
+ state.toolsAvailable = false;
464
+ const healthySessionRemains = [...states.values()].some(
465
+ (candidate) =>
466
+ candidate !== state &&
467
+ candidate.toolsAvailable &&
468
+ !candidate.controller.signal.aborted &&
469
+ candidate.sessionId === candidate.key.getSessionId(),
470
+ );
471
+ if (!healthySessionRemains) reconcileTools(state, false, ctx);
472
+ throw error;
473
+ }
474
+ for (const candidate of states.values()) {
475
+ if (
476
+ candidate !== state &&
477
+ candidate.lineage !== undefined &&
478
+ !candidate.controller.signal.aborted &&
479
+ candidate.sessionId === candidate.key.getSessionId() &&
480
+ latestContextMode(candidate.key.getBranch()) !== "active"
481
+ ) {
482
+ candidate.fallbackActivationPending = true;
483
+ }
484
+ }
485
+ const messages = boundedContextMessages(branch);
486
+ if (
487
+ deactivationAlreadyPending ||
488
+ (!contractAlreadyActiveOrQueued &&
489
+ (latestContextMode(branch) !== "active" || !hasContextContract(messages, activeLineage)))
490
+ ) {
491
+ pi.sendMessage(contractMessage(activeLineage), { triggerTurn: false });
492
+ }
493
+ state.fallbackActivationPending = false;
494
+ warnEnabled(state, ctx);
495
+ };
496
+
497
+ const requestNewContext: ContextToolRuntime["requestNewContext"] = (ctx, input) => {
498
+ const state = stateFor(ctx);
499
+ if (!state) throw new Error("The context session was replaced; retry in the active session");
500
+ if (!isConfigured()) {
501
+ throw new Error("Experimental context management is deactivating; retry after enabling it");
502
+ }
503
+ if (state.pending) throw new Error("A context rollover is already pending");
504
+ const activeLineage = ensureLineage(state, ctx);
505
+ state.pending = {
506
+ requestId: randomUUID(),
507
+ nextWindowId: randomUUID(),
508
+ sessionId: state.sessionId,
509
+ generation: state.generation,
510
+ status: "requested",
511
+ turnStartedAfterRequest: false,
512
+ successfulTurnAfterRequest: false,
513
+ ...(input.reason ? { reason: input.reason } : {}),
514
+ };
515
+ return {
516
+ requestId: state.pending.requestId,
517
+ currentWindowId: activeLineage.currentWindowId,
518
+ nextWindowId: state.pending.nextWindowId,
519
+ ...(state.pending.reason ? { reason: state.pending.reason } : {}),
520
+ };
521
+ };
522
+
523
+ registerContextManagementTools(pi, {
524
+ isEnabled(ctx) {
525
+ const state = stateFor(ctx);
526
+ return state ? enabledFor(state) : false;
527
+ },
528
+ firstWindowId(ctx) {
529
+ return stateFor(ctx)?.lineage?.firstWindowId;
530
+ },
531
+ requestNewContext,
532
+ });
533
+
534
+ const continueAfterRollover = (state: SessionState, ctx: ExtensionContext, request: PendingRollover) => {
535
+ if (!isOwned(state, ctx, request) || request.status !== "completed") return;
536
+ const current = state.lineage;
537
+ const contextToolsAvailable = enabledFor(state);
538
+ state.pending = undefined;
539
+ if (!current) return;
540
+ pi.sendMessage(
541
+ {
542
+ customType: CONTINUATION_MESSAGE_TYPE,
543
+ content: [
544
+ `Context window ${current.currentWindowId} is now active.`,
545
+ request.reason ? `Rollover reason: ${request.reason}` : undefined,
546
+ contextToolsAvailable
547
+ ? "Continue the interrupted task. Use context_management_recall_context for older details and do not assume an automatic summary exists."
548
+ : "Continue the interrupted task. The experimental context tools became unavailable; do not assume an automatic summary or local recall is available.",
549
+ ]
550
+ .filter((line): line is string => Boolean(line))
551
+ .join("\n"),
552
+ display: false,
553
+ details: {
554
+ kind: CONTEXT_DETAILS_KIND,
555
+ version: CONTEXT_VERSION,
556
+ requestId: request.requestId,
557
+ currentWindowId: current.currentWindowId,
558
+ },
559
+ },
560
+ { triggerTurn: true },
561
+ );
562
+ };
563
+
564
+ const failRollover = (state: SessionState, ctx: ExtensionContext, request: PendingRollover, message: string) => {
565
+ if (!isOwned(state, ctx, request)) return;
566
+ state.pending = undefined;
567
+ const safeMessage = terminalText(message).slice(0, 2_000);
568
+ if (ctx.hasUI) ctx.ui.notify(safeMessage, "warning");
569
+ pi.sendMessage(
570
+ {
571
+ customType: CONTINUATION_MESSAGE_TYPE,
572
+ content: `The requested experimental context rollover failed. Continue with Pi's active fallback context. ${safeMessage}`,
573
+ display: false,
574
+ details: {
575
+ kind: CONTEXT_DETAILS_KIND,
576
+ version: CONTEXT_VERSION,
577
+ requestId: request.requestId,
578
+ failed: true,
579
+ },
580
+ },
581
+ request.successfulTurnAfterRequest
582
+ ? { triggerTurn: false }
583
+ : ctx.isIdle()
584
+ ? { triggerTurn: true }
585
+ : { triggerTurn: true, deliverAs: "followUp" },
586
+ );
587
+ };
588
+
589
+ const finishRolloverWithoutContinuation = (
590
+ state: SessionState,
591
+ ctx: ExtensionContext,
592
+ request: PendingRollover,
593
+ status: "cancelled" | "suppressed",
594
+ ) => {
595
+ if (!isOwned(state, ctx, request)) return;
596
+ pi.appendEntry(ROLLOVER_STATE_ENTRY_TYPE, {
597
+ kind: CONTEXT_DETAILS_KIND,
598
+ version: CONTEXT_VERSION,
599
+ requestId: request.requestId,
600
+ status,
601
+ });
602
+ if (isOwned(state, ctx, request)) state.pending = undefined;
603
+ };
604
+
605
+ const settle = (state: SessionState, ctx: ExtensionContext) => {
606
+ if (!isOwned(state, ctx)) return;
607
+ state.agentRunActive = ctx.signal !== undefined;
608
+ if (state.agentRunActive) return;
609
+ if (state.removeToolsAtSettlement || state.fallbackDeactivationPending) {
610
+ state.removeToolsAtSettlement = false;
611
+ state.fallbackDeactivationPending = false;
612
+ if (!isConfigured()) {
613
+ if (latestContextMode(ctx.sessionManager.getBranch()) !== "inactive") {
614
+ pi.sendMessage(deactivationMessage(), { triggerTurn: false });
615
+ }
616
+ reconcileTools(state, hasDeferredToolRemoval(), ctx);
617
+ }
618
+ }
619
+ const request = state.pending;
620
+ if (!request || !isOwned(state, ctx, request)) return;
621
+ if (!isConfigured() && (request.status === "requested" || request.status === "compacting")) {
622
+ request.status = "failed";
623
+ request.errorMessage = "Experimental context management was disabled before rollover completed.";
624
+ }
625
+ if (request.status === "completed") {
626
+ if (request.successfulTurnAfterRequest) {
627
+ finishRolloverWithoutContinuation(state, ctx, request, "suppressed");
628
+ } else {
629
+ continueAfterRollover(state, ctx, request);
630
+ }
631
+ return;
632
+ }
633
+ if (request.status === "failed") {
634
+ failRollover(state, ctx, request, request.errorMessage ?? "Compaction failed.");
635
+ return;
636
+ }
637
+ if (request.status !== "requested") return;
638
+ request.status = "compacting";
639
+ ctx.compact({
640
+ onComplete: (result) => {
641
+ if (!isOwned(state, ctx, request)) return;
642
+ if (request.status === "failed") {
643
+ failRollover(
644
+ state,
645
+ ctx,
646
+ request,
647
+ request.errorMessage ?? "Compaction completed without the requested context marker.",
648
+ );
649
+ return;
650
+ }
651
+ const details = parseContextManagementCompaction(result);
652
+ if (request.status !== "completed" || !details || details.requestId !== request.requestId) {
653
+ failRollover(state, ctx, request, "Compaction completed without the requested context marker.");
654
+ return;
655
+ }
656
+ state.lineage = details;
657
+ if (request.successfulTurnAfterRequest) {
658
+ finishRolloverWithoutContinuation(state, ctx, request, "suppressed");
659
+ } else {
660
+ continueAfterRollover(state, ctx, request);
661
+ }
662
+ },
663
+ onError: (error) => failRollover(state, ctx, request, error.message),
664
+ });
665
+ };
666
+
667
+ return {
668
+ isEnabled(ctx) {
669
+ const state = stateFor(ctx);
670
+ return state ? enabledFor(state) : false;
671
+ },
672
+ startSession(ctx) {
673
+ const previous = states.get(ctx.sessionManager);
674
+ previous?.controller.abort();
675
+ const generation = ++nextGeneration;
676
+ const branch = ctx.sessionManager.getBranch();
677
+ const sessionId = ctx.sessionManager.getSessionId();
678
+ const recoveryBudget = createContextBranchScanBudget();
679
+ const state: SessionState = {
680
+ key: ctx.sessionManager,
681
+ generation,
682
+ sessionId,
683
+ lineage: loadContextLineage(branch, recoveryBudget),
684
+ lineageFailed: false,
685
+ pending: restoredRollover(branch, sessionId, generation, recoveryBudget),
686
+ warned: false,
687
+ warnedUnavailableTools: false,
688
+ warnedProjectionFailure: false,
689
+ toolsAvailable: false,
690
+ removeToolsAtSettlement: false,
691
+ fallbackDeactivationPending: false,
692
+ fallbackActivationPending: false,
693
+ agentRunActive: false,
694
+ controller: new AbortController(),
695
+ };
696
+ states.set(ctx.sessionManager, state);
697
+ applySettings(ctx);
698
+ if (state.pending && ctx.isIdle()) settle(state, ctx);
699
+ },
700
+ onSessionTree(ctx) {
701
+ const previous = stateFor(ctx);
702
+ if (!previous) return;
703
+ previous.controller.abort();
704
+ const generation = ++nextGeneration;
705
+ const branch = ctx.sessionManager.getBranch();
706
+ const recoveryBudget = createContextBranchScanBudget();
707
+ const state: SessionState = {
708
+ ...previous,
709
+ generation,
710
+ lineage: loadContextLineage(branch, recoveryBudget),
711
+ lineageFailed: false,
712
+ pending: restoredRollover(branch, previous.sessionId, generation, recoveryBudget),
713
+ removeToolsAtSettlement: false,
714
+ fallbackDeactivationPending: false,
715
+ fallbackActivationPending: false,
716
+ agentRunActive: false,
717
+ controller: new AbortController(),
718
+ };
719
+ states.set(ctx.sessionManager, state);
720
+ applySettings(ctx);
721
+ if (state.pending && ctx.isIdle()) settle(state, ctx);
722
+ },
723
+ applySettings,
724
+ onInput(ctx) {
725
+ const state = stateFor(ctx);
726
+ if (!state || !ctx.isIdle()) return;
727
+ if (isConfigured() && state.fallbackActivationPending && enabledFor(state)) {
728
+ const activeLineage = ensureLineage(state, ctx);
729
+ if (latestContextMode(ctx.sessionManager.getBranch()) !== "active") {
730
+ pi.sendMessage(contractMessage(activeLineage), { triggerTurn: false });
731
+ }
732
+ state.fallbackActivationPending = false;
733
+ return;
734
+ }
735
+ if (isConfigured() || !state.fallbackDeactivationPending) return;
736
+ if (latestContextMode(ctx.sessionManager.getBranch()) !== "inactive") {
737
+ pi.sendMessage(deactivationMessage(), { triggerTurn: false });
738
+ }
739
+ state.fallbackDeactivationPending = false;
740
+ },
741
+ beforeCompact(event, ctx) {
742
+ const state = stateFor(ctx);
743
+ if (!state || event.signal.aborted) return undefined;
744
+ if (state.toolsAvailable && !inspectToolUnit().complete) deactivateIncompleteToolUnit(state, ctx);
745
+ if (!enabledFor(state)) return undefined;
746
+ const request =
747
+ state.pending?.status === "requested" || state.pending?.status === "compacting" ? state.pending : undefined;
748
+ try {
749
+ const activeLineage = ensureLineage(state, ctx);
750
+ const fingerprintBudget = createFingerprintBudget();
751
+ const details = createContextManagementDetails(
752
+ {
753
+ lineage: activeLineage,
754
+ ...compactionRetainedContext(event, fingerprintBudget),
755
+ reason: event.reason,
756
+ ...(request ? { requestId: request.requestId, windowId: request.nextWindowId } : {}),
757
+ },
758
+ fingerprintBudget,
759
+ );
760
+ if (request) request.status = "compacting";
761
+ return {
762
+ compaction: {
763
+ summary: contextContract(details),
764
+ firstKeptEntryId: event.preparation.firstKeptEntryId,
765
+ tokensBefore: event.preparation.tokensBefore,
766
+ details,
767
+ },
768
+ };
769
+ } catch (error) {
770
+ const message = terminalText(error instanceof Error ? error.message : String(error)).slice(0, 2_000);
771
+ if (request && isOwned(state, ctx, request)) {
772
+ request.status = "failed";
773
+ request.errorMessage = message;
774
+ }
775
+ if (ctx.hasUI) ctx.ui.notify(`Experimental context compaction was cancelled. ${message}`, "warning");
776
+ return { cancel: true };
777
+ }
778
+ },
779
+ projectContext(messages, ctx) {
780
+ const state = stateFor(ctx);
781
+ if (!state) return undefined;
782
+ if (state.toolsAvailable && !inspectToolUnit().complete) {
783
+ deactivateIncompleteToolUnit(state, ctx, false);
784
+ }
785
+ if (!enabledFor(state)) {
786
+ if (state.fallbackDeactivationPending) {
787
+ if (latestContextMode(ctx.sessionManager.getBranch()) !== "inactive") {
788
+ pi.sendMessage(deactivationMessage(), { triggerTurn: false });
789
+ state.fallbackDeactivationPending = false;
790
+ return [...messages, deactivationAgentMessage()];
791
+ }
792
+ state.fallbackDeactivationPending = false;
793
+ }
794
+ return undefined;
795
+ }
796
+ const branch = ctx.sessionManager.getBranch();
797
+ try {
798
+ const activationPending = state.fallbackActivationPending && latestContextMode(branch) !== "active";
799
+ const activeLineage = state.lineage ?? loadContextLineage(branch);
800
+ if (!activeLineage) return undefined;
801
+ const compaction = activeContextManagementCompaction(branch);
802
+ if (compaction) {
803
+ const projected = projectContextManagementContext(messages, compaction.entry, compaction.details);
804
+ if (!projected) return undefined;
805
+ state.fallbackActivationPending = false;
806
+ if (activationPending) {
807
+ pi.sendMessage(contractMessage(compaction.details), { triggerTurn: false });
808
+ return [...projected, createContextContractMessage(compaction.details)];
809
+ }
810
+ return reconcileContextContract(projected, compaction.details);
811
+ }
812
+ state.fallbackActivationPending = false;
813
+ if (activationPending) {
814
+ pi.sendMessage(contractMessage(activeLineage), { triggerTurn: false });
815
+ return [...messages, createContextContractMessage(activeLineage)];
816
+ }
817
+ return hasContextContract(messages, activeLineage)
818
+ ? undefined
819
+ : reconcileContextContract(messages, activeLineage);
820
+ } catch (error) {
821
+ if (!state.warnedProjectionFailure && ctx.hasUI) {
822
+ state.warnedProjectionFailure = true;
823
+ ctx.ui.notify(
824
+ `Experimental context projection kept Pi's persisted context unchanged. ${terminalText(error instanceof Error ? error.message : String(error))}`,
825
+ "warning",
826
+ );
827
+ }
828
+ return undefined;
829
+ }
830
+ },
831
+ onCompact(event, ctx) {
832
+ const state = stateFor(ctx);
833
+ if (!state || !branchContainsEntry(ctx.sessionManager.getBranch(), event.compactionEntry.id)) {
834
+ return;
835
+ }
836
+ const details = parseContextManagementCompaction(event.compactionEntry);
837
+ const request = state.pending;
838
+ if (request?.status !== "compacting" || !isOwned(state, ctx, request)) {
839
+ if (details) state.lineage = details;
840
+ return;
841
+ }
842
+ if (!details || details.requestId !== request.requestId) {
843
+ request.status = "failed";
844
+ request.errorMessage = "Compaction completed without the requested context marker.";
845
+ return;
846
+ }
847
+ state.lineage = details;
848
+ request.status = "completed";
849
+ },
850
+ onCompactFailed(event, ctx) {
851
+ const state = stateFor(ctx);
852
+ const request = state?.pending;
853
+ if (!state || request?.status !== "compacting" || !isOwned(state, ctx, request)) return;
854
+ if (event.aborted) {
855
+ finishRolloverWithoutContinuation(state, ctx, request, "cancelled");
856
+ return;
857
+ }
858
+ request.status = "failed";
859
+ request.errorMessage = event.errorMessage ?? "Compaction failed.";
860
+ },
861
+ onAgentStart(ctx) {
862
+ const state = stateFor(ctx);
863
+ if (state) state.agentRunActive = true;
864
+ },
865
+ onAgentEnd(event, ctx) {
866
+ const state = stateFor(ctx);
867
+ const request = state?.pending;
868
+ if (!state || !request || !isOwned(state, ctx, request)) return;
869
+ const stopReason = latestAssistantStopReason(event.messages);
870
+ if (ctx.signal?.aborted || stopReason === "aborted") {
871
+ finishRolloverWithoutContinuation(state, ctx, request, "cancelled");
872
+ return;
873
+ }
874
+ if (request.turnStartedAfterRequest && (stopReason === "stop" || stopReason === "toolUse")) {
875
+ request.successfulTurnAfterRequest = true;
876
+ }
877
+ },
878
+ onTurnStart(ctx) {
879
+ const state = stateFor(ctx);
880
+ const request = state?.pending;
881
+ if (state && request && isOwned(state, ctx, request)) request.turnStartedAfterRequest = true;
882
+ },
883
+ onAgentSettled(ctx) {
884
+ const state = stateFor(ctx);
885
+ if (state) settle(state, ctx);
886
+ },
887
+ shutdown(ctx) {
888
+ const state = states.get(ctx.sessionManager);
889
+ if (!state) return;
890
+ state.controller.abort();
891
+ states.delete(ctx.sessionManager);
892
+ if (!isConfigured()) reconcileTools(state, hasDeferredToolRemoval(), ctx);
893
+ },
894
+ };
895
+ }