repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

rework forget prefix-cut API

ea8737d3b4f83e3699f7eb0487da6629be3c0733

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (7)

extensions/forget/CHANGELOG.md

Modified
3 3 # changelog
5 5 ## unreleased
7 7 - Add experimental `forget` tool.
8 -- Add short per-prompt task-switch reminder.
8 +- Replace inspect/id flow with `current_user` and `previous_user` prefix cuts.
9 +- Add short per-prompt context-hygiene reminder.
9 10 - Add unit, harness, and optional real MiniMax tests.

extensions/forget/PLAN.md

Modified
1 1 # forget plan
3 3 Experimental goal:
4 -expose a `forget` tool that removes selected transcript spans from the **active
5 -LLM context window**.
4 +let the model manage stale active context in long mixed-task sessions with one
5 +small prefix-cut API.
7 7 ## SDK constraints
22 22 ## Design
24 24 - Tool:
25 - `forget`
26 - - `mode="inspect"`:
27 - list active branch entries with id, role/type, rough token estimate, and no
28 - content preview by default.
29 - Preview is opt-in only because inspect output itself becomes newer context
30 - and can otherwise re-leak text the next `before` compaction is meant to
31 - hide.
32 - - `mode="before"`:
33 - append a compaction entry that replaces all active context before `entry_id`
34 - with a short tombstone summary.
25 + `forget(target?, reason?)`
26 + - `target="current_user"`:
27 + keep the latest user request onward; drop older active context.
28 + - `target="previous_user"`:
29 + keep the immediately previous user request onward; drop older active
30 + context.
31 + - omitted `target` defaults to `current_user`.
35 32 - Per-prompt system reminder:
36 - short turn-local line tells the agent to consider Forget when the user starts
37 - a new task/objective and skip same-task follow-ups.
33 + short turn-local line tells the agent to consider Forget in long mixed-task
34 + sessions and skip when prior context may still be needed.
38 35 - Guardrails:
39 - - target must exist on active branch.
40 - - target must be the latest user message, marked `current_user=yes` by
41 - inspect.
42 - - target must not be a `toolResult` or stale earlier user message.
43 - - dry-run preview available with `dry_run:
44 - true`.
36 + - no entry IDs exposed to the model.
37 + - no inspect/debug/status tool.
38 + - no ranges or holes.
39 + - target must resolve to a user message on the active branch.
45 40 - no physical deletion claim; JSONL keeps recoverable history.
46 41 - not a secret-redaction guarantee; newer/current messages and model thinking
47 42 can still contain sensitive strings.
44 +## Real-provider learnings
46 +- Long-session probes showed `previous_user` is useful for preserving immediate
47 + setup while dropping older task context.
48 +- Kimi and OpenAI used the API best in long mixed-task sessions.
49 +- Z.ai used it aggressively but still gained context cleanup.
50 +- MiniMax often ignored the tool; that is acceptable for weak-tool models.
51 +- `inspect`, raw entry IDs, `status`, and `user:<offset>` added complexity
52 + without reliable model gains.
49 54 ## Tests
51 56 - Unit:
52 - branch formatting, target validation, forget summary/details.
57 + target normalization, user-boundary resolution, terse errors, tombstone
58 + summary.
53 59 - Harness:
54 - extension loads, tool registers, injects short per-prompt reminder, `inspect`
55 - output works, `before` creates compaction with expected `firstKeptEntryId`,
56 - context drops old text, `range` refuses.
60 + extension loads, tool registers, reminder injects, `current_user` and
61 + `previous_user` create compactions with expected `firstKeptEntryId`, context
62 + drops old text, invalid targets fail tersely.
57 63 - Real MiniMax:
58 64 optional `FORGET_REAL=1`; runs isolated SDK session with only Forget loaded,
59 - calls real model, applies forget, verifies compaction is active.
60 -- Real task-switch probes:
61 - baseline prompt had 0 compactions; stronger `MUST` + `current_user=yes` prompt
62 - caused MiniMax to forget at task switches while still answering simple tasks.
65 + calls the tool directly, verifies compaction is active.
64 67 ## Manual test
67 70 cd extensions/forget
68 71 bun test
69 72 FORGET_REAL=1 bun run test:real
70 -pi -e ./index.ts --model minimax:MiniMax-M2.7-highspeed
73 +pi -e ./index.ts --model kimi-coding/kimi-for-coding

extensions/forget/README.md

Modified
5 5 ## Install / load
7 7 Loaded through the root `pi-ext` package.
8 -See [root README](../../README.md).
8 +See [root README](../../README.md).
10 10 ## Commands / tools / settings
15 15 Tools:
17 17 - `forget`:
18 - inspect active branch or forget all context before an entry.
18 + drops older active context before `current_user` or `previous_user`.
20 20 Settings:
21 21 none.
23 23 Hooks/events:
25 25 - `before_agent_start`:
26 - injects one short reminder so the agent considers Forget when a new user
27 - prompt changes task/objective.
26 + injects one short reminder so the agent considers Forget in long mixed-task
27 + sessions.
29 29 ## Behavior
31 -`forget mode="inspect"` lists active branch entries.
32 -Content previews are hidden by default so inspection does not copy
33 -soon-to-be-forgotten text into newer context.
34 -The latest user prompt is marked `current_user=yes` and repeated as
35 -`current_user_entry_id=...` near the top.
36 -Use `show_preview=true` only for debugging.
38 -`forget mode="before" entry_id="..."` appends a Pi compaction entry.
39 -Active LLM context becomes:
31 +`forget` appends a Pi compaction entry. Active LLM context becomes:
41 33 1. a short tombstone summary saying prior context was intentionally forgotten;
42 -2. branch messages from `entry_id` onward;
34 +2. branch messages from the chosen user boundary onward;
43 35 3. future messages.
37 +Targets:
39 +- `current_user`:
40 + keep the latest user request onward. Use for independent new tasks.
41 +- `previous_user`:
42 + keep the immediately previous user request onward. Use when the latest request
43 + depends on immediate setup but older context is stale.
45 +If `target` is omitted, `current_user` is used.
45 47 History is not physically deleted from the JSONL session file.
46 48 It is removed from the active context path by Pi compaction semantics and can be
47 49 recovered through tree/session history.
49 51 Forget is a context-budget tool, not a secrecy/redaction tool.
50 52 If sensitive text appears in the current request, assistant reasoning, tool
51 -results, or later messages, Forget cannot remove that middle/newer span without
52 -also dropping the newer branch.
53 +results, or later messages, Forget cannot remove that newer span without also
54 +dropping the newer branch.
54 56 Middle deletion is intentionally unsupported.
57 +Pi sessions are append-only, so Forget only performs prefix cuts.
56 -The injected reminder is intentionally turn-local system prompt text, not a
57 -stored reminder message.
59 +The injected reminder is turn-local system prompt text, not a stored reminder
60 +message.
58 61 It costs a short line each turn but does not accumulate inside the session
59 62 transcript.

extensions/forget/__tests__/harness.test.ts

Modified
36 36 describe("forget harness integration", () => {
37 - it("loads and registers tool plus command", async () => {
37 + it("loads and registers only the forget tool", async () => {
38 38 t = await createTestSession({ extensions: [forgetPath()] });
39 39 const [extension] = t.session.extensionRunner.extensions;
40 40 expect([...extension.tools.keys()]).toContain("forget");
41 41 expect([...extension.commands.keys()]).toEqual([]);
44 - it("inspect returns branch entries", async () => {
45 - t = await createTestSession({ extensions: [forgetPath()] });
46 - const user = t.session.sessionManager.appendMessage({
47 - role: "user",
48 - content: [{ type: "text", text: "alpha secret" }],
49 - });
50 - t.session.sessionManager.appendMessage({
51 - role: "assistant",
52 - content: [{ type: "text", text: "ok" }],
53 - });
55 - const result = await callForget({ mode: "inspect" });
56 - const text = textOf(result);
57 - expect(text).toContain(user);
58 - expect(text).not.toContain("alpha secret");
60 - const preview = await callForget({ mode: "inspect", show_preview: true });
61 - expect(textOf(preview)).toContain("alpha secret");
62 - });
64 - it("before dry-run does not append compaction", async () => {
65 - t = await createTestSession({ extensions: [forgetPath()] });
66 - const keep = t.session.sessionManager.appendMessage({
67 - role: "user",
68 - content: [{ type: "text", text: "keep this" }],
69 - });
71 - const result = await callForget({
72 - mode: "before",
73 - entry_id: keep,
74 - dry_run: true,
75 - });
76 - expect(textOf(result)).toContain("Dry run");
77 - expect(
78 - t.session.sessionManager
79 - .getEntries()
80 - .some((entry: any) => entry.type === "compaction"),
81 - ).toBe(false);
82 - });
84 - it("before appends forget compaction and active context excludes older message", async () => {
44 + it("current_user appends compaction and drops older active context", async () => {
85 45 t = await createTestSession({ extensions: [forgetPath()] });
86 46 t.session.sessionManager.appendMessage({
87 47 role: "user",
96 56 content: [{ type: "text", text: "safe answer" }],
99 - const result = await callForget({ mode: "before", entry_id: keep });
100 - expect(textOf(result)).toContain("Forget done");
59 + const result = await callForget({
60 + target: "current_user",
61 + reason: "new task",
62 + });
63 + expect(textOf(result)).toContain("done. kept=current_user");
102 65 const compaction = t.session.sessionManager
103 66 .getEntries()
107 70 expect(compaction.fromHook).toBe(true);
108 71 expect(compaction.details).toMatchObject({
109 72 kind: "forget",
110 - mode: "before",
73 + version: 2,
74 + target: "current_user",
75 + keptFromEntryId: keep,
76 + reason: "new task",
78 + expect(compaction.details.forgottenBefore).toBeGreaterThan(0);
113 80 const context = (t.session.sessionManager as any).buildSessionContext();
114 81 const serialized = JSON.stringify(context.messages);
118 85 expect(serialized).not.toContain("OLD_SECRET_DO_NOT_KEEP");
121 - it("rejects range tool mode", async () => {
88 + it("previous_user keeps immediate setup and drops older context", async () => {
122 89 t = await createTestSession({ extensions: [forgetPath()] });
123 - const range = await callForget({
124 - mode: "range",
125 - from_entry_id: "a",
126 - to_entry_id: "b",
90 + t.session.sessionManager.appendMessage({
91 + role: "user",
92 + content: [{ type: "text", text: "OLD_ARCHIVE" }],
128 - expect(range.isError).toBe(true);
129 - expect(textOf(range)).toContain("unsupported");
94 + t.session.sessionManager.appendMessage({
95 + role: "assistant",
96 + content: [{ type: "text", text: "ok" }],
97 + });
98 + const setup = t.session.sessionManager.appendMessage({
99 + role: "user",
100 + content: [{ type: "text", text: "SETUP_KEEP_ME" }],
101 + });
102 + t.session.sessionManager.appendMessage({
103 + role: "user",
104 + content: [{ type: "text", text: "continue setup" }],
105 + });
107 + const result = await callForget({ target: "previous_user" });
108 + expect(textOf(result)).toContain("done. kept=previous_user");
110 + const compaction = t.session.sessionManager
111 + .getEntries()
112 + .find((entry: any) => entry.type === "compaction") as any;
113 + expect(compaction.firstKeptEntryId).toBe(setup);
114 + expect(compaction.details.target).toBe("previous_user");
116 + const context = (t.session.sessionManager as any).buildSessionContext();
117 + const serialized = JSON.stringify(context.messages);
118 + expect(serialized).toContain("SETUP_KEEP_ME");
119 + expect(serialized).toContain("continue setup");
120 + expect(serialized).not.toContain("OLD_ARCHIVE");
121 + });
123 + it("returns terse errors and no-op when no safe cut exists", async () => {
124 + t = await createTestSession({ extensions: [forgetPath()] });
125 + const bad = await callForget({ target: "user:2" });
126 + expect(bad.isError).toBe(true);
127 + expect(textOf(bad)).toBe("bad_target. use current_user or previous_user");
129 + t.session.sessionManager.appendMessage({
130 + role: "user",
131 + content: [{ type: "text", text: "first" }],
132 + });
133 + const previous = await callForget({ target: "previous_user" });
134 + expect(previous.isError).toBe(true);
135 + expect(textOf(previous)).toBe(
136 + "no_boundary. no previous user; use current_user or skip",
137 + );
139 + const current = await callForget({ target: "current_user" });
140 + expect(textOf(current)).toBe("already_first. nothing to forget");
141 + expect(
142 + t.session.sessionManager
143 + .getEntries()
144 + .some((entry: any) => entry.type === "compaction"),
145 + ).toBe(false);

extensions/forget/__tests__/real/minimax.test.ts

Modified
80 80 const tool = session.extensionRunner.getToolDefinition("forget");
81 81 const result = await tool.execute(
82 82 "real-call-1",
83 - { mode: "before", entry_id: keep },
83 + { target: "current_user", reason: "new task" },
84 84 undefined,
85 85 undefined,
86 86 session.extensionRunner.createContext(),
88 - expect(textOf(result)).toContain("Forget done");
88 + expect(textOf(result)).toContain("done. kept=current_user");
90 + const compaction = session.sessionManager
91 + .getEntries()
92 + .find((entry: any) => entry.type === "compaction") as any;
93 + expect(compaction.firstKeptEntryId).toBe(keep);
94 + expect(compaction.details.target).toBe("current_user");
90 96 const context = (session.sessionManager as any).buildSessionContext();
91 97 const serialized = JSON.stringify(context.messages);

extensions/forget/__tests__/unit.test.ts

Modified
1 1 import { describe, expect, test } from "bun:test";
2 2 import forgetExtension, { __test } from "../index.ts";
4 -const { formatInspect, validateTarget, forgetSummary, preview, REMINDER } =
4 +const { forgetSummary, normalizeTarget, REMINDER, resolveTarget, userIndexes } =
5 5 __test;
7 7 function msg(id: string, role: string, text: string) {
25 25 const handler = handlers.get("before_agent_start");
26 26 const result = handler({ systemPrompt: "base" });
27 27 expect(result.systemPrompt).toContain(REMINDER);
28 - expect(REMINDER.length).toBeLessThan(100);
28 + expect(REMINDER).toContain("current_user");
29 + expect(REMINDER).toContain("previous_user");
31 - test("inspect formats active branch ids without previews by default", () => {
32 - const text = formatInspect([
33 - msg("u1", "user", "remember alpha secret"),
34 - msg("a1", "assistant", "ok"),
35 - ]);
36 - expect(text).toContain("Forget inspect: 2 active branch entries");
37 - expect(text).toContain("entry_id=u1 kind=user");
38 - expect(text).not.toContain("remember alpha secret");
39 - expect(text).toContain("entry_id=a1 kind=assistant");
32 + test("normalizes model-friendly target aliases", () => {
33 + expect(normalizeTarget(undefined)).toBe("current_user");
34 + expect(normalizeTarget("")).toBe("current_user");
35 + expect(normalizeTarget("current")).toBe("current_user");
36 + expect(normalizeTarget("user:0")).toBe("current_user");
37 + expect(normalizeTarget("prev")).toBe("previous_user");
38 + expect(normalizeTarget("user:1")).toBe("previous_user");
39 + expect(normalizeTarget("user:2")).toBeUndefined();
42 - test("inspect can show previews when explicitly requested", () => {
43 - const text = formatInspect(
44 - [msg("u1", "user", "remember alpha secret")],
45 - 80,
46 - true,
47 - );
48 - expect(text).toContain("remember alpha secret");
42 + test("finds user boundaries", () => {
43 + const branch = [
44 + msg("u1", "user", "one"),
45 + msg("a1", "assistant", "two"),
46 + msg("u2", "user", "three"),
47 + ];
48 + expect(userIndexes(branch)).toEqual([0, 2]);
51 - test("inspect limit omits older entries", () => {
52 - const text = formatInspect(
53 - [
54 - msg("u1", "user", "one"),
55 - msg("u2", "user", "two"),
56 - msg("u3", "user", "three"),
57 - ],
58 - 2,
59 - );
60 - expect(text).toContain("1 older omitted");
61 - expect(text).not.toContain("u1");
62 - expect(text).toContain("u2");
63 - expect(text).toContain("u3");
64 - });
66 - test("target validation accepts active user branch target", () => {
67 - const branch = [msg("u1", "user", "one"), msg("a1", "assistant", "two")];
68 - const result = validateTarget(branch, "u1");
69 - expect(result.ok).toBe(true);
70 - expect(result.before).toBe(0);
71 - expect(result.after).toBe(1);
72 - });
74 - test("target validation accepts numeric inspect row", () => {
75 - const branch = [msg("u1", "user", "one"), msg("a1", "assistant", "two")];
76 - const result = validateTarget(branch, "000");
77 - expect(result.ok).toBe(true);
78 - expect(result.entry?.id).toBe("u1");
79 - });
81 - test("target validation rejects stale user row", () => {
51 + test("resolves current and previous user prefix cuts", () => {
82 52 const branch = [
83 53 msg("u1", "user", "old"),
84 54 msg("a1", "assistant", "answer"),
85 55 msg("u2", "user", "new"),
56 + msg("a2", "assistant", "answer"),
87 - const result = validateTarget(branch, "u1");
88 - expect(result.ok).toBe(false);
89 - expect(result.error).toContain("current_user=yes");
58 + const current = resolveTarget(branch);
59 + expect(current).toMatchObject({
60 + ok: true,
61 + target: "current_user",
62 + offset: 0,
63 + index: 2,
64 + });
65 + expect(current.entry?.id).toBe("u2");
67 + const previous = resolveTarget(branch, "previous_user");
68 + expect(previous).toMatchObject({
69 + ok: true,
70 + target: "previous_user",
71 + offset: 1,
72 + index: 0,
73 + });
74 + expect(previous.entry?.id).toBe("u1");
92 - test("target validation rejects missing and toolResult targets", () => {
93 - const branch = [
94 - msg("u1", "user", "one"),
95 - msg("t1", "toolResult", "tool output"),
96 - ];
97 - expect(validateTarget(branch, "missing").ok).toBe(false);
98 - const tool = validateTarget(branch, "t1");
99 - expect(tool.ok).toBe(false);
100 - expect(tool.error).toContain("toolResult");
77 + test("returns terse errors for bad or missing boundaries", () => {
78 + expect(resolveTarget([], "wat")).toMatchObject({
79 + ok: false,
80 + code: "bad_target",
81 + hint: "use current_user or previous_user",
82 + });
83 + expect(
84 + resolveTarget([msg("u1", "user", "one")], "previous_user"),
85 + ).toMatchObject({
86 + ok: false,
87 + code: "no_boundary",
88 + hint: "no previous user; use current_user or skip",
89 + });
103 92 test("forget summary is explicit tombstone not hidden data", () => {
104 93 const branch = [msg("u1", "user", "secret")];
105 - const validation = validateTarget(branch, "u1");
106 - const summary = forgetSummary(validation);
94 + const resolution = resolveTarget(branch);
95 + const summary = forgetSummary(resolution, "new task");
107 96 expect(summary).toContain("intentionally removed");
97 + expect(summary).toContain("current_user");
108 98 expect(summary).toContain("u1");
99 + expect(summary).toContain("new task");
109 100 expect(summary).not.toContain("secret");
112 - test("preview compacts whitespace and truncates", () => {
113 - expect(preview("a\n\t b c", 20)).toBe("a b c");
114 - expect(preview("x".repeat(200), 10)).toBe(`${"x".repeat(9)}…`);
115 - });

extensions/forget/index.ts

Modified
5 5 const TOOL = "forget";
6 6 const DETAILS_KIND = "forget";
7 7 const REMINDER =
8 - "Before answer: if latest user asks different task, use forget inspect -> before current_user=yes.";
8 + "Context hygiene: use forget for safe prefix cuts in long mixed-task sessions. current_user=new task; previous_user=keep immediate setup. Skip if prior context may be needed.";
10 -type ForgetMode = "inspect" | "before" | "range";
10 +type ForgetTarget = "current_user" | "previous_user";
12 12 interface ForgetParams {
13 - mode: ForgetMode;
14 - entry_id?: string;
15 - from_entry_id?: string;
16 - to_entry_id?: string;
17 - dry_run?: boolean;
18 - show_preview?: boolean;
19 - limit?: number;
13 + target?: ForgetTarget | string;
14 + reason?: string;
22 17 interface BranchEntry {
23 18 type?: string;
24 19 id?: string;
25 - parentId?: string | null;
26 - timestamp?: string;
27 - message?: { role?: string; content?: unknown; toolName?: string };
28 - summary?: string;
29 - customType?: string;
30 - content?: unknown;
20 + message?: { role?: string };
31 21 [key: string]: unknown;
34 -interface TargetValidation {
24 +interface TargetResolution {
35 25 ok: boolean;
26 + target: ForgetTarget;
27 + offset: 0 | 1;
36 28 index: number;
29 + userCount: number;
37 30 entry?: BranchEntry;
38 - error?: string;
39 - before: number;
40 - after: number;
31 + code?: string;
32 + hint?: string;
43 35 function textResult(text: string, details?: Record<string, unknown>) {
44 36 return { content: [{ type: "text" as const, text }], details };
47 -function errorResult(text: string, details?: Record<string, unknown>) {
48 - return { content: [{ type: "text" as const, text }], isError: true, details };
51 -function contentText(content: unknown): string {
52 - if (typeof content === "string") return content;
53 - if (Array.isArray(content)) {
54 - return content
55 - .map((part) => {
56 - if (typeof part === "string") return part;
57 - if (part && typeof part === "object" && "text" in part) {
58 - return String((part as { text?: unknown }).text ?? "");
59 - }
60 - return "";
61 - })
62 - .join(" ");
63 - }
64 - if (content == null) return "";
65 - return JSON.stringify(content);
68 -function compactWhitespace(text: string): string {
69 - return text.replace(/\s+/g, " ").trim();
72 -function entryText(entry: BranchEntry): string {
73 - if (entry.type === "message") return contentText(entry.message?.content);
74 - if (entry.type === "custom_message") return contentText(entry.content);
75 - if (typeof entry.summary === "string") return entry.summary;
76 - return "";
79 -function entryKind(entry: BranchEntry): string {
80 - if (entry.type === "message") {
81 - const role = entry.message?.role ?? "message";
82 - const tool = entry.message?.toolName ? `:${entry.message.toolName}` : "";
83 - return `${role}${tool}`;
84 - }
85 - if (entry.type === "custom_message")
86 - return `custom:${entry.customType ?? "?"}`;
87 - return entry.type ?? "unknown";
90 -function estimateTokens(text: string): number {
91 - if (!text) return 0;
92 - return Math.max(1, Math.ceil(text.length / 4));
95 -function preview(text: string, max = 96): string {
96 - const cleaned = compactWhitespace(text);
97 - if (cleaned.length <= max) return cleaned;
98 - return `${cleaned.slice(0, max - 1)}…`;
101 -function validateTarget(
102 - branch: BranchEntry[],
103 - entryId?: string,
104 -): TargetValidation {
105 - if (!entryId) {
106 - return {
107 - ok: false,
108 - index: -1,
109 - before: 0,
110 - after: 0,
111 - error: "entry_id required. Run forget inspect first.",
112 - };
113 - }
115 - let index = branch.findIndex((entry) => entry.id === entryId);
116 - if (index === -1 && /^\d+$/.test(entryId)) {
117 - const numericIndex = Number.parseInt(entryId, 10);
118 - if (numericIndex >= 0 && numericIndex < branch.length) index = numericIndex;
119 - }
120 - if (index === -1) {
121 - return {
122 - ok: false,
123 - index,
124 - before: 0,
125 - after: 0,
126 - error: `entry_id not on active branch: ${entryId}`,
127 - };
128 - }
130 - const entry = branch[index];
131 - if (entry?.type === "message" && entry.message?.role === "toolResult") {
132 - return {
133 - ok: false,
134 - index,
135 - entry,
136 - before: index,
137 - after: branch.length - index - 1,
138 - error:
139 - "Refusing toolResult boundary. Choose preceding user/assistant message from inspect output.",
140 - };
141 - }
143 - if (entry?.type !== "message" || entry.message?.role !== "user") {
144 - return {
145 - ok: false,
146 - index,
147 - entry,
148 - before: index,
149 - after: branch.length - index - 1,
150 - error:
151 - "Choose a user row, preferably current_user=yes from inspect output.",
152 - };
153 - }
155 - const currentUserIndex = branch.findLastIndex(
156 - (candidate) =>
157 - candidate.type === "message" && candidate.message?.role === "user",
158 - );
159 - if (index !== currentUserIndex) {
160 - return {
161 - ok: false,
162 - index,
163 - entry,
164 - before: index,
165 - after: branch.length - index - 1,
166 - error: "Choose current_user=yes row from fresh inspect output.",
167 - };
168 - }
39 +function errorResult(
40 + code: string,
41 + hint: string,
42 + details?: Record<string, unknown>,
43 +) {
170 44 return {
171 - ok: true,
172 - index,
173 - entry,
174 - before: index,
175 - after: branch.length - index - 1,
45 + content: [{ type: "text" as const, text: `${code}. ${hint}` }],
46 + isError: true,
47 + details: { code, ...details },
179 -function formatInspect(
180 - branch: BranchEntry[],
181 - limit = 80,
182 - showPreview = false,
183 -): string {
184 - const capped = Math.max(1, Math.min(limit, 200));
185 - const visible = branch.slice(Math.max(0, branch.length - capped));
186 - const omitted = branch.length - visible.length;
187 - const currentUserIndex = branch.findLastIndex(
188 - (entry) => entry.type === "message" && entry.message?.role === "user",
189 - );
190 - const currentUser = branch[currentUserIndex];
191 - const lines = [
192 - `Forget inspect: ${branch.length} active branch entries${omitted > 0 ? ` (${omitted} older omitted)` : ""}.`,
193 - `current_user_entry_id=${currentUser?.id ?? "?"} current_user_row=${currentUserIndex}`,
194 - "Use mode=before with current_user=yes row. Numeric row index also accepted. `before` forgets older context.",
195 - showPreview
196 - ? "Previews shown. Do not keep inspect output if it contains content you plan to forget."
197 - : "Previews hidden by default so inspect output does not re-leak forgotten content. Use show_preview=true only for debugging.",
198 - "",
199 - ];
200 - for (let offset = 0; offset < visible.length; offset++) {
201 - const index = omitted + offset;
202 - const entry = visible[offset];
203 - const text = entryText(entry);
204 - const tokens = text ? estimateTokens(text) : 0;
205 - const previewText = showPreview ? ` ${preview(text)}` : "";
206 - const currentUser = index === currentUserIndex ? " current_user=yes" : "";
207 - lines.push(
208 - `row=${String(index).padStart(3, "0")} entry_id=${entry.id ?? "?"} kind=${entryKind(entry)}${currentUser} ~${tokens}t${previewText}`.trimEnd(),
209 - );
51 +function userIndexes(branch: BranchEntry[]): number[] {
52 + const indexes: number[] = [];
53 + for (let i = 0; i < branch.length; i++) {
54 + const entry = branch[i];
55 + if (entry?.type === "message" && entry.message?.role === "user")
56 + indexes.push(i);
212 - return lines.join("\n");
58 + return indexes;
215 -function forgetSummary(validation: TargetValidation): string {
61 +function normalizeTarget(target: unknown): ForgetTarget | undefined {
62 + if (target === undefined || target === null || target === "")
63 + return "current_user";
64 + if (target === "current_user" || target === "previous_user") return target;
65 + if (target === "current" || target === "latest" || target === "user:0")
66 + return "current_user";
67 + if (target === "previous" || target === "prev" || target === "user:1")
68 + return "previous_user";
69 + return undefined;
72 +function resolveTarget(
73 + branch: BranchEntry[],
74 + rawTarget?: unknown,
75 +): TargetResolution {
76 + const target = normalizeTarget(rawTarget);
77 + if (!target)
78 + return {
79 + ok: false,
80 + target: "current_user",
81 + offset: 0,
82 + index: -1,
83 + userCount: 0,
84 + code: "bad_target",
85 + hint: "use current_user or previous_user",
86 + };
87 + const offset = target === "current_user" ? 0 : 1;
88 + const users = userIndexes(branch);
89 + const position = users.length - 1 - offset;
90 + if (position < 0)
91 + return {
92 + ok: false,
93 + target,
94 + offset,
95 + index: -1,
96 + userCount: users.length,
97 + code: "no_boundary",
98 + hint:
99 + offset === 1
100 + ? "no previous user; use current_user or skip"
101 + : "no current user",
102 + };
103 + const index = users[position];
104 + return {
105 + ok: true,
106 + target,
107 + offset,
108 + index,
109 + userCount: users.length,
110 + entry: branch[index],
111 + };
114 +function forgetSummary(resolution: TargetResolution, reason?: string): string {
216 115 return [
217 116 "[Forget] Earlier conversation context intentionally removed from active LLM context.",
218 - `Kept from entry ${validation.entry?.id ?? "?"} (${entryKind(validation.entry ?? {})}).`,
219 - "Omitted content remains in append-only session history/tree, not in active prompt context.",
117 + `Kept from ${resolution.target} entry ${resolution.entry?.id ?? "?"}.`,
118 + `Reason: ${reason?.trim() || "context budget"}.`,
119 + "History remains append-only/recoverable; active prompt context changed only.",
220 120 ].join("\n");
230 130 function appendForgetCompaction(
231 131 ctx: unknown,
232 - validation: TargetValidation,
132 + resolution: TargetResolution,
133 + reason?: string,
233 134 ): string {
234 135 const sessionManager = (ctx as { sessionManager?: unknown })
235 136 .sessionManager as {
241 142 fromHook?: boolean,
242 143 ) => string;
245 - if (typeof sessionManager?.appendCompaction !== "function") {
145 + if (typeof sessionManager?.appendCompaction !== "function")
246 146 throw new Error(
247 147 "SessionManager appendCompaction unavailable in this Pi runtime",
249 - }
251 149 return sessionManager.appendCompaction(
252 - forgetSummary(validation),
253 - validation.entry?.id ?? "",
150 + forgetSummary(resolution, reason),
151 + resolution.entry?.id ?? "",
254 152 countTokensBefore(
255 153 ctx as { getContextUsage?: () => { tokens?: number | null } | undefined },
258 156 kind: DETAILS_KIND,
259 - version: 1,
260 - mode: "before",
261 - forgottenBefore: validation.before,
262 - keptFromEntryId: validation.entry?.id,
157 + version: 2,
158 + target: resolution.target,
159 + keptFromEntryId: resolution.entry?.id,
160 + forgottenBefore: resolution.index,
161 + reason,
268 167 export const __test = {
269 168 appendForgetCompaction,
270 - compactWhitespace,
271 - entryKind,
272 - entryText,
273 - estimateTokens,
274 169 forgetSummary,
275 - formatInspect,
276 - preview,
170 + normalizeTarget,
277 171 REMINDER,
278 - validateTarget,
172 + resolveTarget,
173 + userIndexes,
281 176 export default function (pi: ExtensionAPI) {
288 183 name: TOOL,
289 184 label: "Forget",
290 185 description:
291 - "Context-budget tool. Inspect active branch or forget older context before an entry. Not privacy, recall, or middle deletion.",
186 + "Context-budget tool. Drops older active context before current_user or previous_user. Not privacy deletion.",
292 187 promptSnippet:
293 - "At task switches, free context by forgetting older transcript before current_user=yes.",
188 + "forget(target?, reason?) — prefix-cut active context before current_user or previous_user",
294 189 promptGuidelines: [
295 - "MUST use forget before answering when the latest user prompt asks a different task than the previous user prompt.",
296 - "Forget flow: forget inspect -> forget before current_user=yes. Skip same-task follow-ups.",
297 - "Forget is context-budget only: not privacy, not recall, not middle deletion.",
190 + "target=current_user: latest user starts an independent new task; drop older context.",
191 + "target=previous_user: latest request depends on immediate prior setup; keep that setup and drop older context.",
192 + "Skip forget if prior discussion may be needed or no safe prefix cut exists.",
299 194 parameters: Type.Object({
300 - mode: StringEnum(["inspect", "before", "range"] as const, {
301 - description:
302 - "inspect lists active branch entries; before forgets older context; range is unsupported.",
303 - }),
304 - entry_id: Type.Optional(
305 - Type.String({
306 - description: "Target active-branch entry id from inspect output",
195 + target: Type.Optional(
196 + StringEnum(["current_user", "previous_user"] as const, {
197 + description: "Prefix-cut boundary. Defaults to current_user.",
309 - from_entry_id: Type.Optional(
310 - Type.String({
311 - description:
312 - "Unsupported range start; accepted only to explain refusal",
313 - }),
314 - ),
315 - to_entry_id: Type.Optional(
316 - Type.String({
317 - description:
318 - "Unsupported range end; accepted only to explain refusal",
319 - }),
320 - ),
321 - dry_run: Type.Optional(
322 - Type.Boolean({
323 - description: "Preview mutation without changing active context",
324 - }),
325 - ),
326 - show_preview: Type.Optional(
327 - Type.Boolean({
328 - description:
329 - "Show content previews in inspect output. Default false to avoid re-leaking content you plan to forget.",
330 - }),
331 - ),
332 - limit: Type.Optional(
333 - Type.Number({
334 - description: "Max inspect entries, default 80, cap 200",
335 - }),
200 + reason: Type.Optional(
201 + Type.String({ description: "Short reason for context compaction" }),
338 204 async execute(_toolCallId, params: ForgetParams, _signal, _onUpdate, ctx) {
339 205 const branch = ctx.sessionManager.getBranch() as BranchEntry[];
341 - if (params.mode === "inspect") {
342 - return textResult(
343 - formatInspect(branch, params.limit, params.show_preview),
344 - {
345 - branchEntries: branch.length,
346 - showPreview: params.show_preview === true,
347 - },
348 - );
349 - }
351 - if (params.mode === "range") {
206 + const resolution = resolveTarget(branch, params.target);
207 + if (!resolution.ok)
352 208 return errorResult(
353 - "Forget range unsupported. Pi sessions are append-only; middle deletion would require replay or fragile per-turn filtering. Use mode=before.",
354 - { mode: "range", from: params.from_entry_id, to: params.to_entry_id },
209 + resolution.code ?? "invalid",
210 + resolution.hint ?? "skip forget",
211 + { target: params.target },
356 - }
358 - const validation = validateTarget(branch, params.entry_id);
359 - if (!validation.ok)
360 - return errorResult(validation.error ?? "Invalid entry_id");
362 - if (params.dry_run) {
363 - return textResult(
364 - `Dry run: would forget ${validation.before} entries before ${params.entry_id}; keep ${validation.after + 1} entries from target through leaf.`,
365 - { mode: "before", dryRun: true, ...validation },
366 - );
367 - }
369 - const compactionId = appendForgetCompaction(ctx, validation);
213 + if (resolution.target === "current_user" && resolution.userCount <= 1)
214 + return textResult("already_first. nothing to forget", {
215 + skipped: true,
216 + target: resolution.target,
217 + forgottenBefore: 0,
218 + });
219 + const compactionId = appendForgetCompaction(
220 + ctx,
221 + resolution,
222 + params.reason,
223 + );
370 224 return textResult(
371 - `Forget done. Active context keeps current user task onward. Forgotten older entries: ${validation.before}.`,
225 + `done. kept=${resolution.target} dropped_entries=${resolution.index}`,
373 - mode: "before",
374 227 compactionId,
375 - forgottenBefore: validation.before,
376 - keptFromEntryId: params.entry_id,
228 + target: resolution.target,
229 + offset: resolution.offset,
230 + keptFromEntryId: resolution.entry?.id,
231 + forgottenBefore: resolution.index,