@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
package/src/index.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { default } from "./pi-context-management.js";
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
import { stripVTControlCharacters } from "node:util";
|
|
2
|
+
import type { SessionEntry } from "@earendil-works/pi-coding-agent";
|
|
3
|
+
|
|
4
|
+
export const NOTES_ENTRY_TYPE = "pi-context-management-note";
|
|
5
|
+
export const NOTES_VERSION = 1;
|
|
6
|
+
export const MAX_NOTE_NAME_LENGTH = 128;
|
|
7
|
+
export const MAX_NOTE_MUTATION_BYTES = 16 * 1024;
|
|
8
|
+
export const MAX_NOTE_COUNT = 64;
|
|
9
|
+
export const MAX_NOTES_BYTES = 256 * 1024;
|
|
10
|
+
export const MAX_NOTE_BRANCH_ENTRY_VISITS = 100_000;
|
|
11
|
+
export const MAX_NOTE_REPLAY_SCAN_UNITS = 4 * 1024 * 1024;
|
|
12
|
+
|
|
13
|
+
export type NoteAction = "write" | "append";
|
|
14
|
+
|
|
15
|
+
export interface NoteMutation {
|
|
16
|
+
version: typeof NOTES_VERSION;
|
|
17
|
+
action: NoteAction;
|
|
18
|
+
note: string;
|
|
19
|
+
content: string;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export interface ContextNote {
|
|
23
|
+
name: string;
|
|
24
|
+
content: string;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
28
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function bytes(value: string): number {
|
|
32
|
+
return Buffer.byteLength(value, "utf8");
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
function validNoteName(value: unknown): value is string {
|
|
36
|
+
return (
|
|
37
|
+
typeof value === "string" &&
|
|
38
|
+
value.length > 0 &&
|
|
39
|
+
value.length <= MAX_NOTE_NAME_LENGTH &&
|
|
40
|
+
value.trim() === value &&
|
|
41
|
+
stripVTControlCharacters(value) === value &&
|
|
42
|
+
!Array.from(value).some((character) => {
|
|
43
|
+
const codePoint = character.codePointAt(0) ?? 0;
|
|
44
|
+
return codePoint < 32 || (codePoint >= 127 && codePoint <= 159);
|
|
45
|
+
})
|
|
46
|
+
);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export function parseNoteMutation(value: unknown): NoteMutation | undefined {
|
|
50
|
+
if (!isRecord(value)) return undefined;
|
|
51
|
+
if (
|
|
52
|
+
value.version !== NOTES_VERSION ||
|
|
53
|
+
(value.action !== "write" && value.action !== "append") ||
|
|
54
|
+
!validNoteName(value.note) ||
|
|
55
|
+
typeof value.content !== "string" ||
|
|
56
|
+
value.content.length === 0 ||
|
|
57
|
+
value.content.length > MAX_NOTE_MUTATION_BYTES ||
|
|
58
|
+
bytes(value.content) > MAX_NOTE_MUTATION_BYTES
|
|
59
|
+
) {
|
|
60
|
+
return undefined;
|
|
61
|
+
}
|
|
62
|
+
return {
|
|
63
|
+
version: NOTES_VERSION,
|
|
64
|
+
action: value.action,
|
|
65
|
+
note: value.note,
|
|
66
|
+
content: value.content,
|
|
67
|
+
};
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export function loadNotes(entries: readonly SessionEntry[]): Map<string, string> {
|
|
71
|
+
const notes = new Map<string, string>();
|
|
72
|
+
const noteContentBytes = new Map<string, number>();
|
|
73
|
+
let totalBytes = 0;
|
|
74
|
+
let remainingEntries = MAX_NOTE_BRANCH_ENTRY_VISITS;
|
|
75
|
+
let remainingScanUnits = MAX_NOTE_REPLAY_SCAN_UNITS;
|
|
76
|
+
for (const entry of entries) {
|
|
77
|
+
if (remainingEntries <= 0) {
|
|
78
|
+
throw new Error("context_management notes branch traversal exceeded its entry limit");
|
|
79
|
+
}
|
|
80
|
+
remainingEntries -= 1;
|
|
81
|
+
if (entry.type !== "custom" || entry.customType !== NOTES_ENTRY_TYPE) continue;
|
|
82
|
+
const data = entry.data;
|
|
83
|
+
const scanUnits =
|
|
84
|
+
1 +
|
|
85
|
+
(isRecord(data) && typeof data.note === "string" ? data.note.length : 0) +
|
|
86
|
+
(isRecord(data) && typeof data.content === "string" ? data.content.length : 0);
|
|
87
|
+
if (scanUnits > remainingScanUnits) {
|
|
88
|
+
throw new Error("context_management notes replay exceeded its scan limit");
|
|
89
|
+
}
|
|
90
|
+
remainingScanUnits -= scanUnits;
|
|
91
|
+
const mutation = parseNoteMutation(data);
|
|
92
|
+
if (!mutation) continue;
|
|
93
|
+
|
|
94
|
+
const previous = notes.get(mutation.note);
|
|
95
|
+
const previousContentBytes = noteContentBytes.get(mutation.note) ?? 0;
|
|
96
|
+
const nameBytes = bytes(mutation.note);
|
|
97
|
+
const mutationContentBytes = bytes(mutation.content);
|
|
98
|
+
const nextContentBytes =
|
|
99
|
+
mutation.action === "append" ? previousContentBytes + mutationContentBytes : mutationContentBytes;
|
|
100
|
+
const nextTotalBytes =
|
|
101
|
+
totalBytes - (previous === undefined ? 0 : nameBytes + previousContentBytes) + nameBytes + nextContentBytes;
|
|
102
|
+
if ((previous === undefined && notes.size >= MAX_NOTE_COUNT) || nextTotalBytes > MAX_NOTES_BYTES) continue;
|
|
103
|
+
|
|
104
|
+
notes.set(mutation.note, mutation.action === "append" ? `${previous ?? ""}${mutation.content}` : mutation.content);
|
|
105
|
+
noteContentBytes.set(mutation.note, nextContentBytes);
|
|
106
|
+
totalBytes = nextTotalBytes;
|
|
107
|
+
}
|
|
108
|
+
return notes;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
function totalNotesBytes(notes: ReadonlyMap<string, string>): number {
|
|
112
|
+
let total = 0;
|
|
113
|
+
for (const [name, content] of notes) total += bytes(name) + bytes(content);
|
|
114
|
+
return total;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
export function createNoteMutation(
|
|
118
|
+
entries: readonly SessionEntry[],
|
|
119
|
+
input: { action: NoteAction; note: string; content: string },
|
|
120
|
+
): { mutation: NoteMutation; notes: Map<string, string> } {
|
|
121
|
+
const mutation = parseNoteMutation({ version: NOTES_VERSION, ...input });
|
|
122
|
+
if (!mutation) {
|
|
123
|
+
throw new Error(
|
|
124
|
+
`Invalid note mutation; names must be 1-${MAX_NOTE_NAME_LENGTH} characters without terminal controls and content must be 1-${MAX_NOTE_MUTATION_BYTES} UTF-8 bytes`,
|
|
125
|
+
);
|
|
126
|
+
}
|
|
127
|
+
const notes = loadNotes(entries);
|
|
128
|
+
const exists = notes.has(mutation.note);
|
|
129
|
+
const next = mutation.action === "append" ? `${notes.get(mutation.note) ?? ""}${mutation.content}` : mutation.content;
|
|
130
|
+
if (!exists && notes.size >= MAX_NOTE_COUNT) {
|
|
131
|
+
throw new Error(`Context notes are limited to ${MAX_NOTE_COUNT} names`);
|
|
132
|
+
}
|
|
133
|
+
notes.set(mutation.note, next);
|
|
134
|
+
if (totalNotesBytes(notes) > MAX_NOTES_BYTES) {
|
|
135
|
+
throw new Error(`Context notes exceed the ${MAX_NOTES_BYTES}-byte active-state limit`);
|
|
136
|
+
}
|
|
137
|
+
return { mutation, notes };
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
export function sortedNotes(entries: readonly SessionEntry[]): ContextNote[] {
|
|
141
|
+
return [...loadNotes(entries)]
|
|
142
|
+
.map(([name, content]) => ({ name, content }))
|
|
143
|
+
.sort((left, right) => left.name.localeCompare(right.name));
|
|
144
|
+
}
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import { createContextManager } from "./context-management.js";
|
|
3
|
+
import {
|
|
4
|
+
type ContextManagementSettingsRuntime,
|
|
5
|
+
type ContextManagementSettingsState,
|
|
6
|
+
createContextManagementSettingsRuntime,
|
|
7
|
+
} from "./settings.js";
|
|
8
|
+
import { terminalText } from "./terminal.js";
|
|
9
|
+
|
|
10
|
+
interface SessionRuntime {
|
|
11
|
+
controller: AbortController;
|
|
12
|
+
generation: number;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
export function createContextManagementExtension(
|
|
16
|
+
options: { settingsRuntime?: ContextManagementSettingsRuntime } = {},
|
|
17
|
+
): (pi: ExtensionAPI) => void {
|
|
18
|
+
return (pi) => {
|
|
19
|
+
const settingsRuntime = options.settingsRuntime ?? createContextManagementSettingsRuntime();
|
|
20
|
+
const manager = createContextManager(pi, settingsRuntime);
|
|
21
|
+
const sessions = new Map<ExtensionContext["sessionManager"], SessionRuntime>();
|
|
22
|
+
let nextGeneration = 0;
|
|
23
|
+
|
|
24
|
+
pi.registerCommand("context-management", {
|
|
25
|
+
description: "Configure experimental summary-free context management",
|
|
26
|
+
handler: async (args, ctx) => {
|
|
27
|
+
if (args.trim()) throw new Error("Usage: /context-management");
|
|
28
|
+
const owner = sessions.get(ctx.sessionManager);
|
|
29
|
+
const controller = owner?.controller ?? new AbortController();
|
|
30
|
+
const { showContextManagementMenu } = await import("./settings-menu.js");
|
|
31
|
+
if (owner && (sessions.get(ctx.sessionManager) !== owner || controller.signal.aborted)) return;
|
|
32
|
+
await showContextManagementMenu(settingsRuntime, ctx, {
|
|
33
|
+
signal: controller.signal,
|
|
34
|
+
isCurrent: () =>
|
|
35
|
+
owner
|
|
36
|
+
? sessions.get(ctx.sessionManager) === owner && !controller.signal.aborted
|
|
37
|
+
: !controller.signal.aborted,
|
|
38
|
+
isActive: () => manager.isEnabled(ctx),
|
|
39
|
+
onSettingsChanged: () => manager.applySettings(ctx),
|
|
40
|
+
});
|
|
41
|
+
},
|
|
42
|
+
});
|
|
43
|
+
|
|
44
|
+
pi.on("session_start", async (_event, ctx) => {
|
|
45
|
+
sessions.get(ctx.sessionManager)?.controller.abort();
|
|
46
|
+
const owner: SessionRuntime = {
|
|
47
|
+
controller: new AbortController(),
|
|
48
|
+
generation: ++nextGeneration,
|
|
49
|
+
};
|
|
50
|
+
sessions.set(ctx.sessionManager, owner);
|
|
51
|
+
const sessionId = ctx.sessionManager.getSessionId();
|
|
52
|
+
let state: Readonly<ContextManagementSettingsState>;
|
|
53
|
+
try {
|
|
54
|
+
state = await settingsRuntime.reload(owner.controller.signal);
|
|
55
|
+
} catch (error) {
|
|
56
|
+
if (owner.controller.signal.aborted || sessions.get(ctx.sessionManager) !== owner) return;
|
|
57
|
+
state = settingsRuntime.get();
|
|
58
|
+
if (ctx.hasUI) {
|
|
59
|
+
ctx.ui.notify(
|
|
60
|
+
`Could not load pi-context-management.json; using defaults. ${terminalText(error instanceof Error ? error.message : String(error))}`,
|
|
61
|
+
"warning",
|
|
62
|
+
);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
if (
|
|
66
|
+
owner.controller.signal.aborted ||
|
|
67
|
+
sessions.get(ctx.sessionManager) !== owner ||
|
|
68
|
+
ctx.sessionManager.getSessionId() !== sessionId
|
|
69
|
+
) {
|
|
70
|
+
return;
|
|
71
|
+
}
|
|
72
|
+
if (ctx.hasUI && state.kind === "invalid") {
|
|
73
|
+
ctx.ui.notify(
|
|
74
|
+
`Invalid pi-context-management.json; using defaults without overwriting it. ${terminalText(state.issue ?? "unknown validation error")}`,
|
|
75
|
+
"warning",
|
|
76
|
+
);
|
|
77
|
+
}
|
|
78
|
+
manager.startSession(ctx);
|
|
79
|
+
});
|
|
80
|
+
|
|
81
|
+
pi.on("input", (_event, ctx) => manager.onInput(ctx));
|
|
82
|
+
pi.on("session_before_compact", (event, ctx) => manager.beforeCompact(event, ctx));
|
|
83
|
+
pi.on("context", (event, ctx) => {
|
|
84
|
+
const messages = manager.projectContext(event.messages, ctx);
|
|
85
|
+
return messages ? { messages } : undefined;
|
|
86
|
+
});
|
|
87
|
+
pi.on("session_tree", (_event, ctx) => manager.onSessionTree(ctx));
|
|
88
|
+
pi.on("session_compact", (event, ctx) => manager.onCompact(event, ctx));
|
|
89
|
+
pi.on("session_compact_failed", (event, ctx) => manager.onCompactFailed(event, ctx));
|
|
90
|
+
pi.on("agent_start", (_event, ctx) => manager.onAgentStart(ctx));
|
|
91
|
+
pi.on("agent_end", (event, ctx) => manager.onAgentEnd(event, ctx));
|
|
92
|
+
pi.on("turn_start", (_event, ctx) => manager.onTurnStart(ctx));
|
|
93
|
+
pi.on("agent_settled", (_event, ctx) => manager.onAgentSettled(ctx));
|
|
94
|
+
|
|
95
|
+
pi.on("session_shutdown", async (_event, ctx) => {
|
|
96
|
+
const owner = sessions.get(ctx.sessionManager);
|
|
97
|
+
owner?.controller.abort();
|
|
98
|
+
if (sessions.get(ctx.sessionManager) === owner) sessions.delete(ctx.sessionManager);
|
|
99
|
+
manager.shutdown(ctx);
|
|
100
|
+
await settingsRuntime.flush();
|
|
101
|
+
});
|
|
102
|
+
};
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
export default createContextManagementExtension();
|