@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.
- package/LICENSE +21 -0
- package/README.md +148 -0
- package/docs/context-management.md +257 -0
- package/package.json +57 -0
- package/src/context-management.ts +895 -0
- package/src/context-tools.ts +203 -0
- package/src/context-window.ts +393 -0
- package/src/fingerprint.ts +104 -0
- package/src/index.ts +1 -0
- package/src/notes-state.ts +144 -0
- package/src/pi-context-management.ts +105 -0
- package/src/recall-context.ts +524 -0
- package/src/settings-menu.ts +186 -0
- package/src/settings.ts +175 -0
- package/src/terminal.ts +6 -0
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
import { StringEnum } from "@earendil-works/pi-ai";
|
|
2
|
+
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
3
|
+
import { Type } from "typebox";
|
|
4
|
+
import { CONTEXT_DETAILS_KIND, CONTEXT_VERSION, loadContextLineage } from "./context-window.js";
|
|
5
|
+
import { createNoteMutation, NOTES_ENTRY_TYPE } from "./notes-state.js";
|
|
6
|
+
import { recallContext } from "./recall-context.js";
|
|
7
|
+
import { terminalText } from "./terminal.js";
|
|
8
|
+
|
|
9
|
+
export const CONTEXT_MANAGEMENT_TOOL_NAMES = [
|
|
10
|
+
"context_management_start_new_context",
|
|
11
|
+
"context_management_get_context_remaining",
|
|
12
|
+
"context_management_recall_context",
|
|
13
|
+
"context_management_update_notes",
|
|
14
|
+
] as const;
|
|
15
|
+
|
|
16
|
+
export const CONTEXT_MANAGEMENT_TOOL_DESCRIPTIONS = {
|
|
17
|
+
context_management_start_new_context:
|
|
18
|
+
"Request a fresh summary-free context window after the current agent run settles. Save important durable information with context_management_update_notes first. This tool changes context state but does not read or write memory itself.",
|
|
19
|
+
context_management_get_context_remaining:
|
|
20
|
+
"Inspect the active model context window and estimated remaining tokens without changing context state.",
|
|
21
|
+
context_management_recall_context:
|
|
22
|
+
"Read-only access to branch-local conversation history or context notes. List items, read one stable item ID, or search text. Use the returned cursor to continue bounded results.",
|
|
23
|
+
context_management_update_notes:
|
|
24
|
+
"Write or append one branch-local context note. This tool changes notes only; use context_management_recall_context with source notes to read them.",
|
|
25
|
+
} as const satisfies Record<(typeof CONTEXT_MANAGEMENT_TOOL_NAMES)[number], string>;
|
|
26
|
+
|
|
27
|
+
const RECALL_SOURCES = ["history", "notes"] as const;
|
|
28
|
+
const RECALL_ACTIONS = ["list", "read", "search"] as const;
|
|
29
|
+
const NOTE_ACTIONS = ["write", "append"] as const;
|
|
30
|
+
|
|
31
|
+
export interface ContextToolRuntime {
|
|
32
|
+
isEnabled(ctx: ExtensionContext): boolean;
|
|
33
|
+
firstWindowId(ctx: ExtensionContext): string | undefined;
|
|
34
|
+
requestNewContext(
|
|
35
|
+
ctx: ExtensionContext,
|
|
36
|
+
input: { toolCallId: string; reason?: string },
|
|
37
|
+
): { requestId: string; currentWindowId: string; nextWindowId: string; reason?: string };
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function requireEnabled(runtime: ContextToolRuntime, ctx: ExtensionContext): void {
|
|
41
|
+
if (!runtime.isEnabled(ctx)) {
|
|
42
|
+
throw new Error("Experimental context management is disabled; enable it in pi-context-management settings first");
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function throwIfAborted(signal?: AbortSignal): void {
|
|
47
|
+
if (signal?.aborted) throw new DOMException("Context tool operation aborted", "AbortError");
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function result(value: unknown, details?: unknown) {
|
|
51
|
+
return {
|
|
52
|
+
content: [{ type: "text" as const, text: terminalText(JSON.stringify(value, null, 2)) }],
|
|
53
|
+
details,
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export function registerContextManagementTools(pi: ExtensionAPI, runtime: ContextToolRuntime): void {
|
|
58
|
+
pi.registerTool({
|
|
59
|
+
name: "context_management_start_new_context",
|
|
60
|
+
label: "Start New Context",
|
|
61
|
+
description: CONTEXT_MANAGEMENT_TOOL_DESCRIPTIONS.context_management_start_new_context,
|
|
62
|
+
parameters: Type.Object(
|
|
63
|
+
{
|
|
64
|
+
reason: Type.Optional(
|
|
65
|
+
Type.String({
|
|
66
|
+
description: "Short reason for starting a fresh context window",
|
|
67
|
+
maxLength: 512,
|
|
68
|
+
}),
|
|
69
|
+
),
|
|
70
|
+
},
|
|
71
|
+
{ additionalProperties: false },
|
|
72
|
+
),
|
|
73
|
+
executionMode: "sequential",
|
|
74
|
+
async execute(toolCallId, params, signal, _onUpdate, ctx) {
|
|
75
|
+
requireEnabled(runtime, ctx);
|
|
76
|
+
throwIfAborted(signal);
|
|
77
|
+
const requested = runtime.requestNewContext(ctx, {
|
|
78
|
+
toolCallId,
|
|
79
|
+
...(params.reason ? { reason: params.reason } : {}),
|
|
80
|
+
});
|
|
81
|
+
throwIfAborted(signal);
|
|
82
|
+
return {
|
|
83
|
+
...result(
|
|
84
|
+
{
|
|
85
|
+
status: "scheduled",
|
|
86
|
+
requestId: requested.requestId,
|
|
87
|
+
currentWindowId: requested.currentWindowId,
|
|
88
|
+
message:
|
|
89
|
+
"The current run will end before rollover. A hidden continuation follows the compaction attempt unless a later successful turn already continued the work.",
|
|
90
|
+
},
|
|
91
|
+
{
|
|
92
|
+
kind: CONTEXT_DETAILS_KIND,
|
|
93
|
+
version: CONTEXT_VERSION,
|
|
94
|
+
...requested,
|
|
95
|
+
status: "scheduled",
|
|
96
|
+
},
|
|
97
|
+
),
|
|
98
|
+
terminate: true,
|
|
99
|
+
};
|
|
100
|
+
},
|
|
101
|
+
});
|
|
102
|
+
|
|
103
|
+
pi.registerTool({
|
|
104
|
+
name: "context_management_get_context_remaining",
|
|
105
|
+
label: "Get Context Remaining",
|
|
106
|
+
description: CONTEXT_MANAGEMENT_TOOL_DESCRIPTIONS.context_management_get_context_remaining,
|
|
107
|
+
parameters: Type.Object({}, { additionalProperties: false }),
|
|
108
|
+
async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
|
|
109
|
+
requireEnabled(runtime, ctx);
|
|
110
|
+
throwIfAborted(signal);
|
|
111
|
+
const usage = ctx.getContextUsage();
|
|
112
|
+
const lineage = loadContextLineage(ctx.sessionManager.getBranch());
|
|
113
|
+
if (!usage) {
|
|
114
|
+
return result({
|
|
115
|
+
available: false,
|
|
116
|
+
...(lineage ? { currentWindowId: lineage.currentWindowId } : {}),
|
|
117
|
+
});
|
|
118
|
+
}
|
|
119
|
+
const remainingTokens = usage.tokens === null ? null : Math.max(0, usage.contextWindow - usage.tokens);
|
|
120
|
+
return result({
|
|
121
|
+
available: usage.tokens !== null,
|
|
122
|
+
...(lineage ? { currentWindowId: lineage.currentWindowId } : {}),
|
|
123
|
+
contextWindow: usage.contextWindow,
|
|
124
|
+
usedTokens: usage.tokens,
|
|
125
|
+
remainingTokens,
|
|
126
|
+
remainingPercent: usage.percent === null ? null : Math.max(0, 100 - usage.percent),
|
|
127
|
+
});
|
|
128
|
+
},
|
|
129
|
+
});
|
|
130
|
+
|
|
131
|
+
pi.registerTool({
|
|
132
|
+
name: "context_management_recall_context",
|
|
133
|
+
label: "Recall Context",
|
|
134
|
+
description: CONTEXT_MANAGEMENT_TOOL_DESCRIPTIONS.context_management_recall_context,
|
|
135
|
+
parameters: Type.Object(
|
|
136
|
+
{
|
|
137
|
+
source: StringEnum(RECALL_SOURCES, {
|
|
138
|
+
description: "Read conversation history or context notes",
|
|
139
|
+
}),
|
|
140
|
+
action: StringEnum(RECALL_ACTIONS, {
|
|
141
|
+
description: "List items, read one ID, or search text",
|
|
142
|
+
}),
|
|
143
|
+
id: Type.Optional(Type.String({ description: "Stable history item ID or note name", maxLength: 256 })),
|
|
144
|
+
query: Type.Optional(Type.String({ description: "Case-insensitive search text", maxLength: 512 })),
|
|
145
|
+
cursor: Type.Optional(Type.String({ description: "Cursor returned by an earlier result", maxLength: 12 })),
|
|
146
|
+
},
|
|
147
|
+
{ additionalProperties: false },
|
|
148
|
+
),
|
|
149
|
+
async execute(toolCallId, params, signal, _onUpdate, ctx) {
|
|
150
|
+
requireEnabled(runtime, ctx);
|
|
151
|
+
throwIfAborted(signal);
|
|
152
|
+
const recalled = recallContext(ctx.sessionManager.getBranch(), params, toolCallId, {
|
|
153
|
+
firstWindowId: runtime.firstWindowId(ctx),
|
|
154
|
+
});
|
|
155
|
+
throwIfAborted(signal);
|
|
156
|
+
return {
|
|
157
|
+
content: [{ type: "text", text: recalled.text }],
|
|
158
|
+
details: recalled.details,
|
|
159
|
+
};
|
|
160
|
+
},
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
pi.registerTool({
|
|
164
|
+
name: "context_management_update_notes",
|
|
165
|
+
label: "Update Context Notes",
|
|
166
|
+
description: CONTEXT_MANAGEMENT_TOOL_DESCRIPTIONS.context_management_update_notes,
|
|
167
|
+
parameters: Type.Object(
|
|
168
|
+
{
|
|
169
|
+
action: StringEnum(NOTE_ACTIONS, {
|
|
170
|
+
description: "Replace a note or append content exactly as supplied",
|
|
171
|
+
}),
|
|
172
|
+
note: Type.String({ description: "Note name", minLength: 1, maxLength: 128 }),
|
|
173
|
+
content: Type.String({
|
|
174
|
+
description: "Note content written or appended exactly as supplied",
|
|
175
|
+
minLength: 1,
|
|
176
|
+
maxLength: 16_384,
|
|
177
|
+
}),
|
|
178
|
+
},
|
|
179
|
+
{ additionalProperties: false },
|
|
180
|
+
),
|
|
181
|
+
executionMode: "sequential",
|
|
182
|
+
async execute(_toolCallId, params, signal, _onUpdate, ctx) {
|
|
183
|
+
requireEnabled(runtime, ctx);
|
|
184
|
+
throwIfAborted(signal);
|
|
185
|
+
const updated = createNoteMutation(ctx.sessionManager.getBranch(), params);
|
|
186
|
+
throwIfAborted(signal);
|
|
187
|
+
pi.appendEntry(NOTES_ENTRY_TYPE, updated.mutation);
|
|
188
|
+
return result(
|
|
189
|
+
{
|
|
190
|
+
status: "updated",
|
|
191
|
+
action: updated.mutation.action,
|
|
192
|
+
note: updated.mutation.note,
|
|
193
|
+
bytes: Buffer.byteLength(updated.notes.get(updated.mutation.note) ?? "", "utf8"),
|
|
194
|
+
},
|
|
195
|
+
{
|
|
196
|
+
version: updated.mutation.version,
|
|
197
|
+
action: updated.mutation.action,
|
|
198
|
+
note: updated.mutation.note,
|
|
199
|
+
},
|
|
200
|
+
);
|
|
201
|
+
},
|
|
202
|
+
});
|
|
203
|
+
}
|
|
@@ -0,0 +1,393 @@
|
|
|
1
|
+
import { randomUUID } from "node:crypto";
|
|
2
|
+
import type { AgentMessage } from "@earendil-works/pi-agent-core";
|
|
3
|
+
import type { CompactionEntry, SessionBeforeCompactEvent, SessionEntry } from "@earendil-works/pi-coding-agent";
|
|
4
|
+
import { buildContextEntries, sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
|
|
5
|
+
import { createFingerprintBudget, type FingerprintBudget, fingerprintMessage } from "./fingerprint.js";
|
|
6
|
+
|
|
7
|
+
export const CONTEXT_STATE_ENTRY_TYPE = "pi-context-management-state";
|
|
8
|
+
export const CONTEXT_CONTRACT_MESSAGE_TYPE = "pi-context-management-contract";
|
|
9
|
+
export const CONTEXT_DEACTIVATION_MESSAGE_TYPE = "pi-context-management-deactivation";
|
|
10
|
+
export const CONTEXT_DETAILS_KIND = "pi-context-management-window";
|
|
11
|
+
export const CONTEXT_VERSION = 1;
|
|
12
|
+
const MAX_DETAILS_BYTES = 8 * 1024 * 1024;
|
|
13
|
+
const MAX_FINGERPRINTS = 100_000;
|
|
14
|
+
export const MAX_CONTEXT_BRANCH_ENTRY_VISITS = 100_000;
|
|
15
|
+
export const MAX_CONTEXT_BRANCH_SCAN_UNITS = 8 * 1024 * 1024;
|
|
16
|
+
|
|
17
|
+
export interface ContextBranchScanBudget {
|
|
18
|
+
remainingVisits: number;
|
|
19
|
+
remainingScanUnits: number;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export function createContextBranchScanBudget(): ContextBranchScanBudget {
|
|
23
|
+
return {
|
|
24
|
+
remainingVisits: MAX_CONTEXT_BRANCH_ENTRY_VISITS,
|
|
25
|
+
remainingScanUnits: MAX_CONTEXT_BRANCH_SCAN_UNITS,
|
|
26
|
+
};
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export function visitContextBranchEntry(budget: ContextBranchScanBudget): void {
|
|
30
|
+
if (budget.remainingVisits <= 0) {
|
|
31
|
+
throw new Error("context_management context branch traversal exceeded its entry limit");
|
|
32
|
+
}
|
|
33
|
+
budget.remainingVisits -= 1;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
function consumeContextBranchScan(budget: ContextBranchScanBudget, units: number): void {
|
|
37
|
+
if (!Number.isSafeInteger(units) || units < 0 || units > budget.remainingScanUnits) {
|
|
38
|
+
throw new Error("context_management context branch traversal exceeded its scan limit");
|
|
39
|
+
}
|
|
40
|
+
budget.remainingScanUnits -= units;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export interface ContextLineage {
|
|
44
|
+
firstWindowId: string;
|
|
45
|
+
previousWindowId?: string;
|
|
46
|
+
currentWindowId: string;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export interface ContextStateEntryData extends ContextLineage {
|
|
50
|
+
kind: typeof CONTEXT_DETAILS_KIND;
|
|
51
|
+
version: typeof CONTEXT_VERSION;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
export interface ContextManagementDetails extends ContextLineage {
|
|
55
|
+
kind: typeof CONTEXT_DETAILS_KIND;
|
|
56
|
+
version: typeof CONTEXT_VERSION;
|
|
57
|
+
reason: SessionBeforeCompactEvent["reason"];
|
|
58
|
+
requestId?: string;
|
|
59
|
+
keptMessageFingerprints: string[];
|
|
60
|
+
retryResponseFingerprint?: string;
|
|
61
|
+
createdAt: string;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
65
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
function isIdentifier(value: unknown): value is string {
|
|
69
|
+
return typeof value === "string" && value.length >= 8 && value.length <= 128;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
function parseLineage(value: Record<string, unknown>): ContextLineage | undefined {
|
|
73
|
+
if (!isIdentifier(value.firstWindowId) || !isIdentifier(value.currentWindowId)) return undefined;
|
|
74
|
+
if (value.previousWindowId !== undefined && !isIdentifier(value.previousWindowId)) return undefined;
|
|
75
|
+
return {
|
|
76
|
+
firstWindowId: value.firstWindowId,
|
|
77
|
+
...(typeof value.previousWindowId === "string" ? { previousWindowId: value.previousWindowId } : {}),
|
|
78
|
+
currentWindowId: value.currentWindowId,
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
export function parseContextState(value: unknown): ContextStateEntryData | undefined {
|
|
83
|
+
if (!isRecord(value)) return undefined;
|
|
84
|
+
const lineage = parseLineage(value);
|
|
85
|
+
if (
|
|
86
|
+
!lineage ||
|
|
87
|
+
value.kind !== CONTEXT_DETAILS_KIND ||
|
|
88
|
+
value.version !== CONTEXT_VERSION ||
|
|
89
|
+
value.previousWindowId !== undefined ||
|
|
90
|
+
lineage.firstWindowId !== lineage.currentWindowId
|
|
91
|
+
) {
|
|
92
|
+
return undefined;
|
|
93
|
+
}
|
|
94
|
+
return { kind: CONTEXT_DETAILS_KIND, version: CONTEXT_VERSION, ...lineage };
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
export function parseContextManagementDetails(
|
|
98
|
+
value: unknown,
|
|
99
|
+
budget?: ContextBranchScanBudget,
|
|
100
|
+
): ContextManagementDetails | undefined {
|
|
101
|
+
if (!isRecord(value) || value.kind !== CONTEXT_DETAILS_KIND || value.version !== CONTEXT_VERSION) return undefined;
|
|
102
|
+
const lineage = parseLineage(value);
|
|
103
|
+
if (
|
|
104
|
+
!lineage?.previousWindowId ||
|
|
105
|
+
lineage.currentWindowId === lineage.previousWindowId ||
|
|
106
|
+
(value.reason !== "manual" && value.reason !== "threshold" && value.reason !== "overflow") ||
|
|
107
|
+
(value.requestId !== undefined && !isIdentifier(value.requestId)) ||
|
|
108
|
+
!Array.isArray(value.keptMessageFingerprints) ||
|
|
109
|
+
value.keptMessageFingerprints.length > MAX_FINGERPRINTS ||
|
|
110
|
+
(value.retryResponseFingerprint !== undefined &&
|
|
111
|
+
(typeof value.retryResponseFingerprint !== "string" || value.retryResponseFingerprint.length !== 64)) ||
|
|
112
|
+
typeof value.createdAt !== "string" ||
|
|
113
|
+
value.createdAt.length > 64
|
|
114
|
+
) {
|
|
115
|
+
return undefined;
|
|
116
|
+
}
|
|
117
|
+
const scanUnits =
|
|
118
|
+
1 +
|
|
119
|
+
lineage.firstWindowId.length +
|
|
120
|
+
lineage.previousWindowId.length +
|
|
121
|
+
lineage.currentWindowId.length +
|
|
122
|
+
value.createdAt.length +
|
|
123
|
+
(typeof value.requestId === "string" ? value.requestId.length : 0) +
|
|
124
|
+
(typeof value.retryResponseFingerprint === "string" ? value.retryResponseFingerprint.length : 0) +
|
|
125
|
+
value.keptMessageFingerprints.length +
|
|
126
|
+
value.keptMessageFingerprints.reduce(
|
|
127
|
+
(total, fingerprint) => total + (typeof fingerprint === "string" ? fingerprint.length : 1),
|
|
128
|
+
0,
|
|
129
|
+
);
|
|
130
|
+
const scanBudget = budget ?? createContextBranchScanBudget();
|
|
131
|
+
try {
|
|
132
|
+
consumeContextBranchScan(scanBudget, scanUnits);
|
|
133
|
+
} catch (error) {
|
|
134
|
+
if (budget) throw error;
|
|
135
|
+
return undefined;
|
|
136
|
+
}
|
|
137
|
+
if (
|
|
138
|
+
!value.keptMessageFingerprints.every(
|
|
139
|
+
(fingerprint) => typeof fingerprint === "string" && /^[a-f0-9]{64}$/.test(fingerprint),
|
|
140
|
+
) ||
|
|
141
|
+
(typeof value.retryResponseFingerprint === "string" && !/^[a-f0-9]{64}$/.test(value.retryResponseFingerprint))
|
|
142
|
+
) {
|
|
143
|
+
return undefined;
|
|
144
|
+
}
|
|
145
|
+
const details: ContextManagementDetails = {
|
|
146
|
+
kind: CONTEXT_DETAILS_KIND,
|
|
147
|
+
version: CONTEXT_VERSION,
|
|
148
|
+
...lineage,
|
|
149
|
+
reason: value.reason,
|
|
150
|
+
...(typeof value.requestId === "string" ? { requestId: value.requestId } : {}),
|
|
151
|
+
keptMessageFingerprints: [...value.keptMessageFingerprints],
|
|
152
|
+
...(typeof value.retryResponseFingerprint === "string"
|
|
153
|
+
? { retryResponseFingerprint: value.retryResponseFingerprint }
|
|
154
|
+
: {}),
|
|
155
|
+
createdAt: value.createdAt,
|
|
156
|
+
};
|
|
157
|
+
return Buffer.byteLength(JSON.stringify(details), "utf8") <= MAX_DETAILS_BYTES ? details : undefined;
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
export function parseContextManagementCompaction(
|
|
161
|
+
entry: Pick<CompactionEntry, "summary" | "details">,
|
|
162
|
+
budget?: ContextBranchScanBudget,
|
|
163
|
+
): ContextManagementDetails | undefined {
|
|
164
|
+
const details = parseContextManagementDetails(entry.details, budget);
|
|
165
|
+
return details && entry.summary === contextContract(details) ? details : undefined;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
export function createInitialContextState(windowId = randomUUID()): ContextStateEntryData {
|
|
169
|
+
return {
|
|
170
|
+
kind: CONTEXT_DETAILS_KIND,
|
|
171
|
+
version: CONTEXT_VERSION,
|
|
172
|
+
firstWindowId: windowId,
|
|
173
|
+
currentWindowId: windowId,
|
|
174
|
+
};
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
export function loadContextLineage(
|
|
178
|
+
entries: readonly SessionEntry[],
|
|
179
|
+
budget: ContextBranchScanBudget = createContextBranchScanBudget(),
|
|
180
|
+
): ContextLineage | undefined {
|
|
181
|
+
for (let index = entries.length - 1; index >= 0; index -= 1) {
|
|
182
|
+
visitContextBranchEntry(budget);
|
|
183
|
+
const entry = entries[index];
|
|
184
|
+
if (entry.type === "compaction") {
|
|
185
|
+
const details = parseContextManagementCompaction(entry, budget);
|
|
186
|
+
if (details) return details;
|
|
187
|
+
continue;
|
|
188
|
+
}
|
|
189
|
+
if (entry.type === "custom" && entry.customType === CONTEXT_STATE_ENTRY_TYPE) {
|
|
190
|
+
const state = parseContextState(entry.data);
|
|
191
|
+
if (state) return state;
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
return undefined;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
export function activeContextManagementCompaction(
|
|
198
|
+
entries: readonly SessionEntry[],
|
|
199
|
+
budget: ContextBranchScanBudget = createContextBranchScanBudget(),
|
|
200
|
+
):
|
|
201
|
+
| {
|
|
202
|
+
entry: CompactionEntry<ContextManagementDetails>;
|
|
203
|
+
details: ContextManagementDetails;
|
|
204
|
+
}
|
|
205
|
+
| undefined {
|
|
206
|
+
for (let index = entries.length - 1; index >= 0; index -= 1) {
|
|
207
|
+
visitContextBranchEntry(budget);
|
|
208
|
+
const entry = entries[index];
|
|
209
|
+
if (entry.type !== "compaction") continue;
|
|
210
|
+
const details = parseContextManagementCompaction(entry, budget);
|
|
211
|
+
return details ? { entry: entry as CompactionEntry<ContextManagementDetails>, details } : undefined;
|
|
212
|
+
}
|
|
213
|
+
return undefined;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
export function contextContract(lineage: ContextLineage): string {
|
|
217
|
+
return [
|
|
218
|
+
`[PI_CONTEXT_MANAGEMENT_WINDOW:${lineage.currentWindowId}]`,
|
|
219
|
+
"Experimental Pi-native context management is active.",
|
|
220
|
+
lineage.previousWindowId
|
|
221
|
+
? `The previous context window was ${lineage.previousWindowId}.`
|
|
222
|
+
: "This is the first context window in this session.",
|
|
223
|
+
"Use context_management_get_context_remaining to inspect capacity, context_management_recall_context to retrieve older history or notes, and context_management_update_notes to preserve durable working memory.",
|
|
224
|
+
"Call context_management_start_new_context when a fresh context is needed. Important information is not summarized automatically.",
|
|
225
|
+
].join("\n");
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
export function contextDeactivation(): string {
|
|
229
|
+
return [
|
|
230
|
+
"Experimental Pi-native context management is no longer active.",
|
|
231
|
+
"Its context tools are unavailable. Continue with Pi's active compaction strategy and do not call context_management_start_new_context, context_management_get_context_remaining, context_management_recall_context, or context_management_update_notes.",
|
|
232
|
+
].join("\n");
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
export function latestContextMode(
|
|
236
|
+
entries: readonly SessionEntry[],
|
|
237
|
+
budget: ContextBranchScanBudget = createContextBranchScanBudget(),
|
|
238
|
+
): "active" | "inactive" | undefined {
|
|
239
|
+
let mode: "active" | "inactive" | undefined;
|
|
240
|
+
for (const _entry of entries) visitContextBranchEntry(budget);
|
|
241
|
+
const leafId = entries.at(-1)?.id ?? null;
|
|
242
|
+
for (const entry of buildContextEntries([...entries], leafId)) {
|
|
243
|
+
if (entry.type === "compaction" && parseContextManagementCompaction(entry, budget)) mode = "active";
|
|
244
|
+
for (const message of sessionEntryToContextMessages(entry)) {
|
|
245
|
+
if (message.role !== "custom") continue;
|
|
246
|
+
if (message.customType === CONTEXT_CONTRACT_MESSAGE_TYPE) mode = "active";
|
|
247
|
+
if (message.customType === CONTEXT_DEACTIVATION_MESSAGE_TYPE && message.content === contextDeactivation()) {
|
|
248
|
+
mode = "inactive";
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
return mode;
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
export function createContextContractMessage(lineage: ContextLineage): AgentMessage {
|
|
256
|
+
return {
|
|
257
|
+
role: "custom",
|
|
258
|
+
customType: CONTEXT_CONTRACT_MESSAGE_TYPE,
|
|
259
|
+
content: contextContract(lineage),
|
|
260
|
+
display: false,
|
|
261
|
+
details: {
|
|
262
|
+
kind: CONTEXT_DETAILS_KIND,
|
|
263
|
+
version: CONTEXT_VERSION,
|
|
264
|
+
currentWindowId: lineage.currentWindowId,
|
|
265
|
+
},
|
|
266
|
+
timestamp: 0,
|
|
267
|
+
};
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
export function hasContextContract(messages: readonly AgentMessage[], lineage: ContextLineage): boolean {
|
|
271
|
+
const expected = contextContract(lineage);
|
|
272
|
+
return messages.some(
|
|
273
|
+
(message) =>
|
|
274
|
+
(message.role === "custom" &&
|
|
275
|
+
message.customType === CONTEXT_CONTRACT_MESSAGE_TYPE &&
|
|
276
|
+
message.content === expected) ||
|
|
277
|
+
(message.role === "compactionSummary" && message.summary === expected),
|
|
278
|
+
);
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
export function reconcileContextContract(messages: readonly AgentMessage[], lineage: ContextLineage): AgentMessage[] {
|
|
282
|
+
if (hasContextContract(messages, lineage)) return [...messages];
|
|
283
|
+
return [...messages, createContextContractMessage(lineage)];
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
export function compactionRetainedContext(
|
|
287
|
+
event: SessionBeforeCompactEvent,
|
|
288
|
+
fingerprintBudget: FingerprintBudget = createFingerprintBudget(),
|
|
289
|
+
): {
|
|
290
|
+
keptMessages: AgentMessage[];
|
|
291
|
+
retryResponseFingerprint?: string;
|
|
292
|
+
} {
|
|
293
|
+
const leafId = event.branchEntries.at(-1)?.id ?? null;
|
|
294
|
+
const contextEntries = buildContextEntries(event.branchEntries, leafId);
|
|
295
|
+
const keptIndex = contextEntries.findIndex((entry) => entry.id === event.preparation.firstKeptEntryId);
|
|
296
|
+
if (keptIndex < 0) {
|
|
297
|
+
throw new Error("Pi compaction cut point is not present in the active context");
|
|
298
|
+
}
|
|
299
|
+
const keptMessages = contextEntries.slice(keptIndex).flatMap(sessionEntryToContextMessages);
|
|
300
|
+
const lastMessage = keptMessages.at(-1);
|
|
301
|
+
if (
|
|
302
|
+
event.willRetry &&
|
|
303
|
+
lastMessage?.role === "assistant" &&
|
|
304
|
+
(lastMessage.stopReason === "error" || lastMessage.stopReason === "length")
|
|
305
|
+
) {
|
|
306
|
+
return {
|
|
307
|
+
keptMessages: keptMessages.slice(0, -1),
|
|
308
|
+
retryResponseFingerprint: fingerprintMessage(lastMessage, fingerprintBudget),
|
|
309
|
+
};
|
|
310
|
+
}
|
|
311
|
+
return { keptMessages };
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
export function createContextManagementDetails(
|
|
315
|
+
input: {
|
|
316
|
+
lineage: ContextLineage;
|
|
317
|
+
keptMessages: readonly AgentMessage[];
|
|
318
|
+
retryResponseFingerprint?: string;
|
|
319
|
+
reason: SessionBeforeCompactEvent["reason"];
|
|
320
|
+
requestId?: string;
|
|
321
|
+
windowId?: string;
|
|
322
|
+
createdAt?: string;
|
|
323
|
+
},
|
|
324
|
+
fingerprintBudget: FingerprintBudget = createFingerprintBudget(),
|
|
325
|
+
): ContextManagementDetails {
|
|
326
|
+
const currentWindowId = input.windowId ?? randomUUID();
|
|
327
|
+
const details: ContextManagementDetails = {
|
|
328
|
+
kind: CONTEXT_DETAILS_KIND,
|
|
329
|
+
version: CONTEXT_VERSION,
|
|
330
|
+
firstWindowId: input.lineage.firstWindowId,
|
|
331
|
+
previousWindowId: input.lineage.currentWindowId,
|
|
332
|
+
currentWindowId,
|
|
333
|
+
reason: input.reason,
|
|
334
|
+
...(input.requestId ? { requestId: input.requestId } : {}),
|
|
335
|
+
keptMessageFingerprints: input.keptMessages.map((message) => fingerprintMessage(message, fingerprintBudget)),
|
|
336
|
+
...(input.retryResponseFingerprint ? { retryResponseFingerprint: input.retryResponseFingerprint } : {}),
|
|
337
|
+
createdAt: input.createdAt ?? new Date().toISOString(),
|
|
338
|
+
};
|
|
339
|
+
const parsed = parseContextManagementDetails(details);
|
|
340
|
+
if (!parsed) throw new Error("Created invalid context-management details");
|
|
341
|
+
return parsed;
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
function isOlderCompactionSummary(message: AgentMessage, timestamp: number): boolean {
|
|
345
|
+
return (
|
|
346
|
+
message.role === "compactionSummary" &&
|
|
347
|
+
Number.isFinite(message.timestamp) &&
|
|
348
|
+
Number.isFinite(timestamp) &&
|
|
349
|
+
message.timestamp < timestamp
|
|
350
|
+
);
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
export function projectContextManagementContext(
|
|
354
|
+
messages: readonly AgentMessage[],
|
|
355
|
+
entry: CompactionEntry<ContextManagementDetails>,
|
|
356
|
+
details: ContextManagementDetails,
|
|
357
|
+
): AgentMessage[] | undefined {
|
|
358
|
+
const fingerprintBudget = createFingerprintBudget();
|
|
359
|
+
const expectedSummary = contextContract(details);
|
|
360
|
+
if (entry.summary !== expectedSummary) return undefined;
|
|
361
|
+
const summaryIndex = messages.findIndex(
|
|
362
|
+
(message) => message.role === "compactionSummary" && message.summary === expectedSummary,
|
|
363
|
+
);
|
|
364
|
+
if (summaryIndex < 0) return undefined;
|
|
365
|
+
const timestamp = messages[summaryIndex].timestamp;
|
|
366
|
+
let messageIndex = summaryIndex + 1;
|
|
367
|
+
let fingerprintIndex = 0;
|
|
368
|
+
while (fingerprintIndex < details.keptMessageFingerprints.length) {
|
|
369
|
+
if (messageIndex >= messages.length) return undefined;
|
|
370
|
+
const message = messages[messageIndex];
|
|
371
|
+
if (fingerprintMessage(message, fingerprintBudget) === details.keptMessageFingerprints[fingerprintIndex]) {
|
|
372
|
+
messageIndex += 1;
|
|
373
|
+
fingerprintIndex += 1;
|
|
374
|
+
continue;
|
|
375
|
+
}
|
|
376
|
+
if (isOlderCompactionSummary(message, timestamp)) {
|
|
377
|
+
messageIndex += 1;
|
|
378
|
+
continue;
|
|
379
|
+
}
|
|
380
|
+
return undefined;
|
|
381
|
+
}
|
|
382
|
+
while (messageIndex < messages.length && isOlderCompactionSummary(messages[messageIndex], timestamp)) {
|
|
383
|
+
messageIndex += 1;
|
|
384
|
+
}
|
|
385
|
+
if (
|
|
386
|
+
details.retryResponseFingerprint &&
|
|
387
|
+
messageIndex < messages.length &&
|
|
388
|
+
fingerprintMessage(messages[messageIndex], fingerprintBudget) === details.retryResponseFingerprint
|
|
389
|
+
) {
|
|
390
|
+
messageIndex += 1;
|
|
391
|
+
}
|
|
392
|
+
return [...messages.slice(0, summaryIndex + 1), ...messages.slice(messageIndex)];
|
|
393
|
+
}
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import type { AgentMessage } from "@earendil-works/pi-agent-core";
|
|
3
|
+
|
|
4
|
+
const MAX_FINGERPRINT_DEPTH = 512;
|
|
5
|
+
export const MAX_FINGERPRINT_OPERATION_UNITS = 4 * 1024 * 1024;
|
|
6
|
+
export const MAX_FINGERPRINT_OPERATION_BYTES = 8 * 1024 * 1024;
|
|
7
|
+
|
|
8
|
+
export interface FingerprintBudget {
|
|
9
|
+
remainingUnits: number;
|
|
10
|
+
remainingBytes: number;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
export function createFingerprintBudget(): FingerprintBudget {
|
|
14
|
+
return {
|
|
15
|
+
remainingUnits: MAX_FINGERPRINT_OPERATION_UNITS,
|
|
16
|
+
remainingBytes: MAX_FINGERPRINT_OPERATION_BYTES,
|
|
17
|
+
};
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
type JsonContainer = unknown[] | Record<string, unknown>;
|
|
21
|
+
|
|
22
|
+
interface CloneTask {
|
|
23
|
+
source: unknown;
|
|
24
|
+
parent: JsonContainer;
|
|
25
|
+
key: string | number;
|
|
26
|
+
depth: number;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function failLimit(): never {
|
|
30
|
+
throw new Error("Context message fingerprint exceeded its traversal limit");
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
function assign(parent: JsonContainer, key: string | number, value: unknown): void {
|
|
34
|
+
if (Array.isArray(parent)) parent[key as number] = value;
|
|
35
|
+
else parent[String(key)] = value;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function stableValue(value: unknown, operationBudget: FingerprintBudget): unknown {
|
|
39
|
+
const root: Record<string, unknown> = {};
|
|
40
|
+
const tasks: CloneTask[] = [{ source: value, parent: root, key: "value", depth: 0 }];
|
|
41
|
+
let remainingUnits = MAX_FINGERPRINT_OPERATION_UNITS;
|
|
42
|
+
const consume = (units: number) => {
|
|
43
|
+
if (!Number.isSafeInteger(units) || units < 0 || units > remainingUnits || units > operationBudget.remainingUnits) {
|
|
44
|
+
failLimit();
|
|
45
|
+
}
|
|
46
|
+
remainingUnits -= units;
|
|
47
|
+
operationBudget.remainingUnits -= units;
|
|
48
|
+
};
|
|
49
|
+
|
|
50
|
+
while (tasks.length > 0) {
|
|
51
|
+
const task = tasks.pop();
|
|
52
|
+
if (!task) break;
|
|
53
|
+
consume(1);
|
|
54
|
+
const source = task.source;
|
|
55
|
+
if (typeof source === "string") consume(source.length);
|
|
56
|
+
if (typeof source !== "object" || source === null) {
|
|
57
|
+
if (typeof source === "bigint") throw new Error("Context message fingerprint cannot serialize bigint values");
|
|
58
|
+
assign(task.parent, task.key, source);
|
|
59
|
+
continue;
|
|
60
|
+
}
|
|
61
|
+
if (task.depth >= MAX_FINGERPRINT_DEPTH) failLimit();
|
|
62
|
+
if (Array.isArray(source)) {
|
|
63
|
+
consume(source.length);
|
|
64
|
+
const target = new Array<unknown>(source.length);
|
|
65
|
+
assign(task.parent, task.key, target);
|
|
66
|
+
for (let index = source.length - 1; index >= 0; index -= 1) {
|
|
67
|
+
tasks.push({ source: source[index], parent: target, key: index, depth: task.depth + 1 });
|
|
68
|
+
}
|
|
69
|
+
continue;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
const keys: string[] = [];
|
|
73
|
+
for (const key in source) {
|
|
74
|
+
if (!Object.hasOwn(source, key)) continue;
|
|
75
|
+
consume(1 + key.length);
|
|
76
|
+
keys.push(key);
|
|
77
|
+
}
|
|
78
|
+
keys.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
|
|
79
|
+
const target: Record<string, unknown> = {};
|
|
80
|
+
assign(task.parent, task.key, target);
|
|
81
|
+
for (let index = keys.length - 1; index >= 0; index -= 1) {
|
|
82
|
+
const key = keys[index];
|
|
83
|
+
tasks.push({
|
|
84
|
+
source: (source as Record<string, unknown>)[key],
|
|
85
|
+
parent: target,
|
|
86
|
+
key,
|
|
87
|
+
depth: task.depth + 1,
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
return root.value;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
export function fingerprintMessage(
|
|
95
|
+
message: AgentMessage,
|
|
96
|
+
operationBudget: FingerprintBudget = createFingerprintBudget(),
|
|
97
|
+
): string {
|
|
98
|
+
const serialized = JSON.stringify(stableValue(message, operationBudget));
|
|
99
|
+
if (serialized === undefined) failLimit();
|
|
100
|
+
const bytes = Buffer.byteLength(serialized, "utf8");
|
|
101
|
+
if (bytes > MAX_FINGERPRINT_OPERATION_BYTES || bytes > operationBudget.remainingBytes) failLimit();
|
|
102
|
+
operationBudget.remainingBytes -= bytes;
|
|
103
|
+
return createHash("sha256").update(serialized).digest("hex");
|
|
104
|
+
}
|