@astrosheep/pi-context 0.19.0 → 0.21.0

package/dist/src/reset-lifecycle.js

@@ -0,0 +1,101 @@
+/** A reset request is session-local. Only this module schedules compaction/continuation. */
+export function registerResetLifecycle(pi, options) {
+    let state = { phase: "idle" };
+    let handledEntry;
+    let active = true;
+    const clear = () => {
+        state = { phase: "idle" };
+        handledEntry = undefined;
+    };
+    const valid = (request, ctx) => active && options.isEnabled() && state.phase === "compacting" && state.attempt === request && ctx.sessionManager.getSessionId() === request.sessionId;
+    // State is intentionally not resumed from a pending request: a loaded session must
+    // not execute work from a tool that belonged to a previous runtime or tree branch.
+    pi.on("session_start", () => { clear(); active = true; });
+    pi.on("session_shutdown", () => { clear(); active = false; });
+    pi.on("session_tree", clear);
+    pi.on("agent_end", (_event, ctx) => {
+        if (!active || !options.isEnabled())
+            return;
+        if (ctx.signal?.aborted) {
+            // Esc cancels the user's run. Do not reset or resurrect it at settled.
+            state = { phase: "idle" };
+            return;
+        }
+    });
+    pi.on("agent_settled", (_event, ctx) => {
+        if (!active || !options.isEnabled() || state.phase === "compacting" || !ctx.isIdle())
+            return;
+        if (state.phase !== "requested")
+            return;
+        // One owner for requested resets. Consume the request before any external call;
+        // repeated settled events and reentrant callbacks are harmless.
+        const request = { completed: false, sessionId: ctx.sessionManager.getSessionId(), explicit: true };
+        state = { phase: "compacting", attempt: request };
+        const onError = (error) => {
+            if (!valid(request, ctx))
+                return;
+            state = { phase: "idle" };
+            // Do not retry from settled in a tight loop. A later prompt may trigger a
+            // native reset or explicitly request one.
+            ctx.ui.notify(`pi-context: reset did not complete (${error.message}). The conversation is retained; resume with another prompt.`, "warning");
+        };
+        try {
+            ctx.compact({
+                onComplete: () => {
+                    if (!valid(request, ctx))
+                        return;
+                    state = { phase: "idle" };
+                    // session_compact only confirms the boundary. onComplete runs after
+                    // Pi clears compaction state; sending inside the hook starts too early.
+                    // A queued user prompt may already have started at compaction_end.
+                    if (request.completed && ctx.isIdle() && !ctx.hasPendingMessages()) {
+                        pi.sendMessage(options.continuation, { triggerTurn: true });
+                    }
+                },
+                onError,
+            });
+        }
+        catch (error) {
+            onError(error instanceof Error ? error : new Error(String(error)));
+        }
+    });
+    pi.on("session_before_compact", (event, ctx) => {
+        if (!active || !options.isEnabled())
+            return undefined;
+        if (event.signal.aborted)
+            return { cancel: true };
+        // Automatic threshold/overflow compactions reset on the spot — no model turn.
+        // The warning steer fired earlier (see warning.ts); what crosses the reserve
+        // line now is the wipe itself.
+        try {
+            return options.buildReset(event, ctx, state.phase === "requested");
+        }
+        catch (error) {
+            ctx.ui.notify(`pi-context: could not build reset (${String(error)}).`, "warning");
+            return { cancel: true }; // Never fall through to a generated default summary.
+        }
+    });
+    pi.on("session_compact", (event, ctx) => {
+        if (!active || !options.isEnabled() || handledEntry === event.compactionEntry.id)
+            return;
+        if (!options.isCurrentReset(event.compactionEntry.id, ctx))
+            return;
+        handledEntry = event.compactionEntry.id;
+        if (state.phase === "compacting")
+            state.attempt.completed = !event.willRetry;
+        else
+            state = { phase: "idle" };
+        // A native compaction (including overflow retry) owns its own scheduling.
+        // Only a reset we requested gets a continuation from our onComplete callback.
+        options.onReset(event.compactionEntry.id);
+    });
+    return {
+        request() {
+            const pending = state.phase !== "idle";
+            if (!pending)
+                state = { phase: "requested" };
+            return pending ? "rollover_already_pending" : "rollover_requested";
+        },
+        clear,
+    };
+}

package/dist/src/session-reader.js

@@ -0,0 +1 @@
+export {};

package/dist/src/thresholds.js

@@ -0,0 +1,75 @@
+import { SettingsManager } from "@earendil-works/pi-coding-agent";
+import { PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS } from "./protocol.js";
+function isSettingsObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Read the raw "pi-context" object from one parsed settings scope. */
+function piContextSettings(settings) {
+    if (!isSettingsObject(settings))
+        return {};
+    const value = settings[PI_CONTEXT_SETTINGS_KEY];
+    return isSettingsObject(value) ? value : {};
+}
+/** Merge the global and project "pi-context" objects per key; project wins, mirroring Pi's deep merge. */
+export function mergePiContextSettings(globalSettings, projectSettings) {
+    const merged = { ...piContextSettings(globalSettings), ...piContextSettings(projectSettings) };
+    return { reminderMarginTokens: merged.reminderMarginTokens };
+}
+/** A margin is usable only as a positive integer; anything else is ignored. */
+function validMargin(raw) {
+    if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw <= 0)
+        return undefined;
+    return raw;
+}
+/**
+ * Pure derivation of the thresholds from Pi's reserve: the reminder fires at reserve
+ * plus the pi-context margin, the warning steer at reserve plus WARNING_RUNWAY_TOKENS.
+ * An invalid margin degrades to the default and reports one warning. Pi's automatic
+ * threshold/overflow compaction itself resets immediately, with no model turn.
+ */
+export function deriveThresholds(reserveTokens, margins) {
+    const warnings = [];
+    const reminderKey = `${PI_CONTEXT_SETTINGS_KEY}.reminderMarginTokens`;
+    let reminderMargin;
+    if (margins.reminderMarginTokens === undefined)
+        reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
+    else {
+        const parsed = validMargin(margins.reminderMarginTokens);
+        if (parsed === undefined) {
+            warnings.push(`pi-context: ${reminderKey} must be a positive integer; using default ${DEFAULT_REMINDER_MARGIN_TOKENS}.`);
+            reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
+        }
+        else
+            reminderMargin = parsed;
+    }
+    return { thresholds: { reminder: reserveTokens + reminderMargin, reserve: reserveTokens, warning: reserveTokens + WARNING_RUNWAY_TOKENS }, warnings };
+}
+let cached;
+/**
+ * Session-level threshold resolution: Pi's compaction reserve plus the settings.json
+ * "pi-context" margins. The file-backed read is cached until resetThresholds (called
+ * on session_start/session_tree); invalid configuration degrades per offending key
+ * with one warning and never throws during session operation.
+ */
+export function thresholdsFor(ctx) {
+    if (cached)
+        return cached;
+    try {
+        const settingsManager = SettingsManager.create(ctx.cwd, undefined, { projectTrusted: ctx.isProjectTrusted() });
+        // Pass the active model so per-model compaction.modelOverrides resolve (SDK 0.86);
+        // on older runtimes the extra argument is ignored and the ordinary setting wins.
+        const model = ctx.model;
+        const derived = deriveThresholds(settingsManager.getCompactionSettings(model ? { provider: model.provider, id: model.id } : undefined).reserveTokens, mergePiContextSettings(settingsManager.getGlobalSettings(), settingsManager.getProjectSettings()));
+        for (const warning of derived.warnings)
+            ctx.ui.notify(warning, "warning");
+        cached = derived.thresholds;
+    }
+    catch (error) {
+        ctx.ui.notify(`pi-context: could not read settings; using defaults (${String(error)}).`, "warning");
+        cached = { reminder: DEFAULT_RESERVE_TOKENS + DEFAULT_REMINDER_MARGIN_TOKENS, reserve: DEFAULT_RESERVE_TOKENS, warning: DEFAULT_RESERVE_TOKENS + WARNING_RUNWAY_TOKENS };
+    }
+    return cached;
+}
+export function resetThresholds() {
+    cached = undefined;
+}

package/dist/src/tool-output.js

@@ -0,0 +1,175 @@
+export const TOOL_OUTPUT_MAX_BYTES = 32 * 1024;
+export const DEFAULT_READ_WINDOW_CHARS = 12000;
+export const MAX_READ_WINDOW_CHARS = 50000;
+export const HISTORY_PREVIEW_CHARS = 1200;
+function json(value) {
+    return JSON.stringify(value, null, 2);
+}
+/** True when `value` serializes within the same wire budget `output()` enforces. */
+export function withinBudget(value, budget = TOOL_OUTPUT_MAX_BYTES) {
+    return Buffer.byteLength(json(value), "utf8") <= budget;
+}
+/** True when `text` fits the wire budget verbatim, for raw payloads with no JSON encoding. */
+export function withinTextBudget(text, budget = TOOL_OUTPUT_MAX_BYTES) {
+    return Buffer.byteLength(text, "utf8") <= budget;
+}
+/** Marker standing in for characters elided from the middle of an oversized single unit. */
+export function truncationMarker(removedChars) {
+    return `…[truncated ${removedChars} chars]…`;
+}
+/**
+ * Middle-truncate `text` until `fits` accepts it, keeping a head and a tail joined by
+ * `truncationMarker`. Codex's `truncate_middle` semantics: when one indivisible unit
+ * (a note line, a single match, a history item) exceeds the wire budget on its own, it is
+ * still returned — visibly truncated — so cursors advance and no page comes back empty.
+ * Returns `text` unchanged when it already fits.
+ */
+export function middleTruncate(text, fits) {
+    if (fits(text))
+        return text;
+    const chars = Array.from(text);
+    const build = (kept) => {
+        const head = Math.ceil(kept / 2);
+        return chars.slice(0, head).join("") + truncationMarker(chars.length - kept) + chars.slice(chars.length - (kept - head)).join("");
+    };
+    // The serialized size is non-decreasing in `kept` (each kept character adds at least one
+    // byte while the marker loses at most one digit), so a binary search finds the largest
+    // keep count that still fits.
+    let low = 0;
+    let high = chars.length;
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        if (fits(build(mid)))
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    return build(low);
+}
+/**
+ * Longest contiguous prefix of `text` (counted in code points) accepted by `fits`.
+ *
+ * This is the truncation used by every cursor-bearing payload: the delivered text is
+ * always a plain prefix of the original, so a cursor computed from its code-point length
+ * addresses exactly the first undelivered character. No marker character is ever appended;
+ * the companion `truncated`/`total_chars` fields name what was left out.
+ */
+export function prefixFit(text, fits) {
+    if (fits(text))
+        return text;
+    const chars = Array.from(text);
+    // Serialized size is non-decreasing in the kept count, so the largest fitting prefix is
+    // found by a monotone binary search instead of a quadratic shrink loop.
+    let low = 0;
+    let high = chars.length;
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        if (fits(chars.slice(0, mid).join("")))
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    // A candidate's serialized size can dip by a byte or two at the very end (a numeric cursor
+    // becoming null), so the predicate is not perfectly monotone at the tail. Back off until the
+    // returned prefix provably fits; in the monotone case this loop never runs.
+    while (low > 0 && !fits(chars.slice(0, low).join("")))
+        low -= 1;
+    return chars.slice(0, low).join("");
+}
+/**
+ * Read one character window of `text`: the longest contiguous prefix of
+ * `chars[resolved, resolved + limit)` that fits the wire budget.
+ *
+ * `offsetChars` is a code-point offset. A negative value counts back from the end and
+ * resolves to `max(0, total_chars + offsetChars)`, so `-N` reaches the tail and any
+ * `N >= total_chars` reads from the start; the resolved absolute offset is always echoed.
+ * Following `next_offset_chars` reconstructs `text` by plain concatenation, because the
+ * payload is always a plain prefix with no marker. `render` builds the exact response for
+ * a candidate window, and `measure` decides whether that response fits the wire budget (JSON
+ * serialization by default; raw-text renders pass a verbatim byte measure), so the budget is
+ * always measured on the bytes that go on the wire.
+ */
+export function readCharacterWindow(text, offsetChars, limitChars, render, measure = withinBudget) {
+    const chars = Array.from(text);
+    const requested = offsetChars ?? 0;
+    const resolved = requested < 0 ? Math.max(0, chars.length + requested) : Math.max(0, requested);
+    const windowChars = chars.slice(resolved, resolved + Math.min(limitChars ?? DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS));
+    const build = (content) => {
+        const next = resolved + Array.from(content).length;
+        return { offset_chars: resolved, content, total_chars: chars.length, next_offset_chars: next < chars.length ? next : null };
+    };
+    const content = prefixFit(windowChars.join(""), (candidate) => measure(render(build(candidate))));
+    return render(build(content));
+}
+/**
+ * One-line bracketed header preceding a raw character-window payload: the identity, the
+ * delivered char range, and either the resume cursor or `end`. `tail` appends extra
+ * metadata (notes add their timestamps) inside the same brackets.
+ */
+export function characterWindowHeader(identity, window, tail = "") {
+    // The range end is offset + delivered count, never `total_chars`: a read resolved past the
+    // end delivers zero characters there, and the header must not render an inverted range.
+    const end = window.offset_chars + Array.from(window.content).length;
+    const resume = window.next_offset_chars === null ? "end" : `continue at offset_chars=${window.next_offset_chars}`;
+    return `[${identity} · chars ${window.offset_chars}-${end} of ${window.total_chars} · ${resume}${tail}]`;
+}
+/**
+ * Code-point offset of the earliest occurrence of any of `queries` in `text`, or 0 when
+ * none occurs. Shared by the two search tools so a match address is computed identically.
+ */
+export function earliestMatchOffsetChars(text, queries) {
+    let earliest = -1;
+    for (const query of queries) {
+        const index = text.indexOf(query);
+        if (index < 0)
+            continue;
+        if (earliest < 0 || index < earliest)
+            earliest = index;
+    }
+    return earliest <= 0 ? 0 : Array.from(text.slice(0, earliest)).length;
+}
+/**
+ * Build a page without ever adding an item that would exceed the wire budget.
+ *
+ * A single item that cannot fit is middle-truncated through the optional `truncate`
+ * callback and still included, with `next_cursor` advanced past it. Without that treatment
+ * an oversized item would yield an empty page forever: the cursor would keep pointing back
+ * at the same index.
+ */
+export function page(items, cursor, key, limit, truncate) {
+    const end = Math.min(items.length, cursor + (limit ?? items.length));
+    const selected = [];
+    let next = end < items.length ? end : null;
+    for (let index = cursor; index < end; index++) {
+        const candidateNext = index + 1 < end || end < items.length ? index + 1 : null;
+        const fits = (list) => withinBudget({ [key]: list, next_cursor: candidateNext });
+        if (!fits([...selected, items[index]])) {
+            if (selected.length === 0 && truncate) {
+                selected.push(truncate(items[index], (candidate) => fits([candidate])));
+                next = candidateNext;
+            }
+            else {
+                next = index;
+            }
+            break;
+        }
+        selected.push(items[index]);
+    }
+    return { [key]: selected, next_cursor: next };
+}
+/**
+ * Encode a structured result through the common tool result boundary. `details` is slim
+ * metadata for logs/UI (pi convention: never a second copy of the payload) and stays
+ * undefined unless the tool has metadata worth persisting.
+ */
+export function output(value, details, terminate = false) {
+    return { content: [{ type: "text", text: json(value) }], details, terminate };
+}
+/**
+ * Encode a prose payload as raw text: a one-line bracketed metadata header, then the payload
+ * verbatim. The model reads the note or history item itself instead of a JSON envelope;
+ * `details` carries the slim metadata object and never duplicates the payload.
+ */
+export function outputRaw(header, content, details, terminate = false) {
+    return { content: [{ type: "text", text: `${header}\n${content}` }], details, terminate };
+}

package/dist/src/tool-schema.js

@@ -0,0 +1,26 @@
+import { Type } from "@earendil-works/pi-ai";
+export const nullableString = () => Type.Optional(Type.Union([Type.String(), Type.Null()]));
+export const positiveInteger = () => Type.Optional(Type.Integer({ minimum: 1 }));
+export const cursor = () => Type.Optional(Type.Integer({ minimum: 0, description: "Continuation cursor: pass the previous next_cursor back unchanged, with the same filters and ordering. Omit to start. next_cursor is null only when the set is exhausted." }));
+export const recentFirst = () => Type.Optional(Type.Boolean({ description: "Return newest-first. Only an explicit false returns oldest-first. Defaults to true." }));
+/** Role filter. `developer` is the known author for this extension's own custom entries. */
+export const role = Type.Union([Type.Literal("user"), Type.Literal("assistant"), Type.Literal("tool_call"), Type.Literal("tool"), Type.Literal("system"), Type.Literal("developer"), Type.Null()], { description: "Filter by the item's role. Exactly six: \"user\" and \"assistant\" are a message's visible text (assistant text never contains tool calls); \"tool_call\" is one tool invocation (tool_name set, content = the call's JSON arguments); \"tool\" is one tool run's output (tool_name set); \"system\" is a native Pi compaction summary; \"developer\" is an entry this extension authored (boot, guidance, warning, continuation messages, reset-window compaction summaries, any pi-context/* entry)." });
+/** Search query parameter: one literal, or several literals combined with OR. */
+export const searchQuery = () => Type.Union([Type.String(), Type.Array(Type.String(), { minItems: 1 })]);
+/**
+ * Normalize a search `query` parameter into the literal needles to match.
+ * A bare string is a one-element list, so single-query behavior is unchanged.
+ * An empty list, a non-string element, or an empty string is refused rather than silently
+ * searching for nothing: those are argument errors, not empty result sets. An empty string
+ * matches every line and every item, so it can never be what the caller meant.
+ */
+export function searchQueries(query) {
+    const candidates = typeof query === "string" ? [query] : query;
+    if (!Array.isArray(candidates) || candidates.length === 0)
+        throw new Error("query must be a string or a non-empty array of strings");
+    if (!candidates.every((candidate) => typeof candidate === "string"))
+        throw new Error("query array elements must be strings");
+    if (candidates.some((candidate) => candidate === ""))
+        throw new Error("query strings must be non-empty: an empty query matches everything");
+    return candidates;
+}

package/dist/src/warning.js

@@ -0,0 +1,44 @@
+import { WARNING_TYPE, GUIDANCE_OPEN_TAG, GUIDANCE_CLOSE_TAG, WARNING_PROMPT } from "./protocol.js";
+import { thresholdsFor, resetThresholds } from "./thresholds.js";
+import { hasWindowMessage, currentWindowId } from "./history.js";
+import { remainingTokens } from "./budget.js";
+/**
+ * The final checkpoint warning, steered to the model once per window. Like the early
+ * reminder, the steer text is model-facing only (display: false); the human learns
+ * about it from the warning-level notify, not from a chat-visible message.
+ */
+/** Trigger: does the steer fire at this remaining-token count? Pure. */
+export function warningDue(remaining, thresholds) {
+    return remaining <= thresholds.warning;
+}
+/** Delivery: what happens when it fires. */
+export function steerWarning(pi, ctx, thresholds, remaining) {
+    pi.sendMessage({ customType: WARNING_TYPE, content: `${GUIDANCE_OPEN_TAG}\n${WARNING_PROMPT}\n${GUIDANCE_CLOSE_TAG}`, display: false }, { triggerTurn: true });
+    ctx.ui.notify(`pi-context: context budget critical (${Math.max(0, remaining - thresholds.reserve)} tokens before reserve) — final checkpoint warning steered to the model.`, "warning");
+}
+/** Registration: once-per-window guard plus trigger+delivery on the context hook. */
+export function registerWarning(pi, isEnabled) {
+    let firedInWindow;
+    // Threshold resolution is owned by budget.ts; this module only consumes the shared
+    // cache (lazily on the context hook) so session_start never warns twice.
+    pi.on("session_start", () => { firedInWindow = undefined; });
+    pi.on("session_tree", () => { firedInWindow = undefined; resetThresholds(); });
+    pi.on("context", (_event, ctx) => {
+        const windowId = currentWindowId(ctx);
+        if (!isEnabled() || firedInWindow === windowId || hasWindowMessage(ctx, WARNING_TYPE))
+            return undefined;
+        const remaining = remainingTokens(ctx);
+        if (remaining === null)
+            return undefined;
+        const thresholds = thresholdsFor(ctx);
+        if (!warningDue(remaining, thresholds))
+            return undefined;
+        firedInWindow = windowId;
+        // The steer reaches the model at the next sampling step with at most the runway
+        // of invisible budget left. After it, the model decides for itself: end the
+        // window, or ride it into Pi's automatic compaction, which resets on the spot
+        // with no turn (see reset-lifecycle).
+        steerWarning(pi, ctx, thresholds, remaining);
+        return undefined;
+    });
+}

package/dist/test/agent-loop.test.js

@@ -0,0 +1,214 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
+import { createAgentSession, DefaultResourceLoader, ModelRuntime, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import piContext from "../src/index.js";
+import { WARNING_TYPE, GUIDANCE_TYPE } from "../src/protocol.js";
+for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "uncompactable", "followup", "steering", "repeat", "abort"]) {
+    test(`real Pi loop: ${mode} reset preserves history and handles completion`, { timeout: 15000 }, async () => {
+        const dir = mkdtempSync(join(tmpdir(), "pi-context-loop-"));
+        const previousDir = process.env.PI_CODING_AGENT_DIR;
+        const previousNotesRoot = process.env.PI_NOTES_HOME;
+        process.env.PI_CODING_AGENT_DIR = dir;
+        const notesRoot = mkdtempSync(join(tmpdir(), "pi-context-loop-notes-"));
+        process.env.PI_NOTES_HOME = notesRoot;
+        let session;
+        try {
+            const runtime = await ModelRuntime.create({ authPath: join(dir, "auth.json"), modelsPath: null, modelsStorePath: join(dir, "models"), refreshOnCreate: false });
+            await runtime.setRuntimeApiKey("openai", "scripted-test-key");
+            const base = runtime.getModels("openai")[0];
+            assert.ok(base);
+            const model = { ...base, contextWindow: 100000, maxTokens: 4096 };
+            const usageMode = mode === "golden" || mode === "write-error" || mode === "ignored-warning";
+            const expectedResets = mode === "abort" || mode === "uncompactable" ? 0 : 1;
+            // 0.86 split-turn cut can still summarize a turn prefix, so keepRecentTokens: 1 no longer
+            // makes a reset uncompactable; a keep larger than the whole session keeps everything and does.
+            const settings = { compaction: { enabled: usageMode, reserveTokens: 32768, keepRecentTokens: mode === "uncompactable" ? 1_000_000 : 200 }, retry: { enabled: false } };
+            writeFileSync(join(dir, "settings.json"), JSON.stringify(settings));
+            const settingsManager = SettingsManager.create(dir, dir);
+            let resets = 0;
+            let settled = 0;
+            let targetResets = expectedResets;
+            let activeSentinel = "OLD_CONTEXT_SENTINEL";
+            let finish;
+            let failFinish;
+            const finished = new Promise((resolve, reject) => { finish = resolve; failFinish = reject; });
+            const finishTimeout = setTimeout(() => failFinish(new Error(`timed out waiting for ${mode} agent settlement`)), 5000);
+            const loader = new DefaultResourceLoader({ cwd: dir, agentDir: dir, settingsManager,
+                noExtensions: true, noSkills: true, noThemes: true, noPromptTemplates: true,
+                systemPromptOverride: () => "Use the tools as requested.", agentsFilesOverride: () => ({ agentsFiles: [] }),
+                extensionFactories: [piContext, (pi) => {
+                        pi.on("session_compact", () => { resets++; });
+                        pi.on("agent_settled", () => {
+                            settled++;
+                            if (mode === "abort") {
+                                if (settled === 1)
+                                    finish();
+                                return;
+                            }
+                            if (resets >= targetResets && requests.length > 0 && !requests.at(-1).includes(activeSentinel))
+                                finish();
+                        });
+                        pi.on("tool_result", () => {
+                            if (mode === "abort")
+                                void session.abort();
+                        });
+                        pi.on("tool_call", async () => {
+                            if (mode === "followup")
+                                await session.followUp("QUEUED_INPUT_SENTINEL");
+                            if (mode === "steering")
+                                await session.steer("QUEUED_INPUT_SENTINEL");
+                        });
+                    }],
+            });
+            await loader.reload();
+            const sm = SessionManager.inMemory(dir);
+            sm.appendMessage({ role: "user", content: "Earlier work to retain in durable history.", timestamp: Date.now() });
+            sm.appendMessage({ role: "assistant", api: model.api, provider: model.provider, model: model.id,
+                content: [{ type: "text", text: "Earlier result. ".repeat(100) }], stopReason: "stop", timestamp: Date.now(),
+                usage: { input: 100, output: 100, cacheRead: 0, cacheWrite: 0, totalTokens: 200, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } } });
+            ({ session } = await createAgentSession({ cwd: dir, agentDir: dir, modelRuntime: runtime, model, settingsManager, sessionManager: sm, resourceLoader: loader, tools: ["new_context", "notes_write", "get_context_remaining"] }));
+            const requests = [];
+            let checkpointed = false;
+            let freshTurns = 0;
+            session.agent.streamFunction = (_model, context) => {
+                requests.push(JSON.stringify(context.messages));
+                const n = requests.length;
+                const request = requests[n - 1];
+                const fresh = !request.includes("OLD_CONTEXT_SENTINEL");
+                if (fresh)
+                    freshTurns++;
+                const sawWarning = request.includes("Your memory is about to be erased");
+                const sawGuidance = request.includes("Your brain is almost out of room");
+                const explicitReset = (n === 1 && !usageMode && mode !== "uncompactable") || (mode === "repeat" && (n === 1 || n === 3));
+                const checkpoint = usageMode && sawWarning && !checkpointed && mode !== "ignored-warning";
+                if (checkpoint)
+                    checkpointed = true;
+                // The warning is chosen from the previous turn's usage, so a scripted run has to
+                // keep taking turns until it sees the warning (first window) or the next
+                // window's reminder. "ignored-warning" keeps working instead of checkpointing.
+                const probe = usageMode && !checkpoint && ((!fresh && !sawWarning) || (mode === "ignored-warning" && sawWarning) || (fresh && freshTurns === 2 && !sawGuidance));
+                const tokens = usageMode ? (fresh ? (freshTurns === 1 ? 100 : 50000) : sawWarning ? 70000 : n === 1 ? 50000 : 60000) : 100;
+                const tool = explicitReset || (mode === "uncompactable" && n === 1);
+                const call = probe ? "get_context_remaining" : checkpoint ? "notes_write" : tool ? "new_context" : undefined;
+                const message = { role: "assistant", api: model.api, provider: model.provider, model: model.id,
+                    content: probe ? [{ type: "toolCall", id: "probe-call", name: "get_context_remaining", arguments: {} }]
+                        : checkpoint ? [{ type: "toolCall", id: "checkpoint-call", name: "notes_write", arguments: { address: mode === "write-error" ? "../invalid.md" : "checkpoint.md", content: "CHECKPOINT_SENTINEL" } }]
+                            : tool ? [{ type: "toolCall", id: "reset-call", name: "new_context", arguments: {} }]
+                                : [{ type: "text", text: fresh ? "Resumed." : "Working." }],
+                    stopReason: call ? "toolUse" : "stop", timestamp: Date.now(),
+                    usage: { input: tokens, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: tokens + 1, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+                };
+                const stream = createAssistantMessageEventStream();
+                stream.push({ type: "done", reason: message.stopReason, message });
+                stream.end();
+                return stream;
+            };
+            await session.bindExtensions({});
+            let failure;
+            session.subscribe((event) => {
+                if (mode === "uncompactable" && event.type === "compaction_end" && event.errorMessage) {
+                    failure = event.errorMessage;
+                    finish();
+                }
+            });
+            await session.prompt("OLD_CONTEXT_SENTINEL: save progress and continue the task.");
+            await finished;
+            clearTimeout(finishTimeout);
+            await session.waitForIdle();
+            if (mode === "abort") {
+                assert.equal(resets, 0, "user cancellation clears pending rollover");
+                assert.equal(requests.length, 1, "no continuation resurrects the cancelled run");
+                await session.prompt("Resume explicitly after cancellation.");
+                assert.equal(requests.length, 2);
+                assert.ok(requests[1].includes("Resume explicitly after cancellation."));
+                assert.ok(requests[1].includes("OLD_CONTEXT_SENTINEL"), "no reset happened: history is intact");
+                return;
+            }
+            if (mode === "uncompactable") {
+                assert.match(failure ?? "", /Nothing to compact/);
+                assert.equal(resets, 0);
+                assert.equal(requests.length, 1, "failed reset does not loop or resume automatically");
+                await session.prompt("Continue after the failed reset.");
+                assert.equal(requests.length, 2);
+                assert.ok(requests[1].includes("OLD_CONTEXT_SENTINEL"));
+                return;
+            }
+            assert.equal(resets, expectedResets);
+            if (mode === "golden" || mode === "write-error" || mode === "ignored-warning") {
+                const branch = sm.getBranch();
+                const guidanceIndices = branch.flatMap((entry, i) => entry.type === "custom_message" && entry.customType === GUIDANCE_TYPE ? [i] : []);
+                const warningIndices = branch.flatMap((entry, i) => entry.type === "custom_message" && entry.customType === WARNING_TYPE ? [i] : []);
+                const noteFile = join(notesRoot, "pi", "session", sm.getSessionId(), "checkpoint.md");
+                const resetIndex = branch.findIndex((entry) => entry.type === "compaction");
+                assert.equal(guidanceIndices.length, 1, "one early reminder");
+                assert.equal(warningIndices.length, 1, "one final warning steer");
+                assert.ok(warningIndices[0] > guidanceIndices[0], "the reminder precedes the warning");
+                if (mode === "ignored-warning") {
+                    assert.equal(existsSync(noteFile), false, "an ignored warning leaves no checkpoint");
+                }
+                else if (mode === "write-error") {
+                    assert.equal(existsSync(noteFile), false, "failed write creates no checkpoint");
+                    assert.ok(branch.some((entry) => entry.type === "message" && entry.message.role === "toolResult" && entry.message.toolName === "notes_write" && entry.message.isError));
+                    assert.ok(!requests.at(-1).includes("checkpoint.md"), "fresh context must not invent a saved note");
+                }
+                else {
+                    assert.ok(existsSync(noteFile), "the checkpoint is a real file on disk");
+                    assert.ok(resetIndex > warningIndices[0], "the warning precedes the wipe");
+                    assert.ok(requests.at(-1).includes("checkpoint.md"), "fresh boot carries the saved checkpoint as a metadata line");
+                }
+                assert.ok(!requests.at(-1).includes("Your brain is almost out of room"), "new window excludes old guidance");
+            }
+            if (mode === "followup" || mode === "steering") {
+                assert.ok(requests[1].includes("QUEUED_INPUT_SENTINEL"), "queued user work is delivered before rollover");
+                assert.ok(requests[1].includes("OLD_CONTEXT_SENTINEL"), "queue drains in the existing window");
+                assert.ok(!requests[2].includes("QUEUED_INPUT_SENTINEL"), "queue is not replayed after rollover");
+                const queuedEntries = sm.getBranch().filter((entry) => entry.type === "message" && JSON.stringify(entry.message).includes("QUEUED_INPUT_SENTINEL"));
+                assert.equal(queuedEntries.length, 1, "one durable user input");
+            }
+            if (mode === "repeat") {
+                const nextFinished = new Promise((resolve) => { finish = resolve; });
+                targetResets = 2;
+                activeSentinel = "SECOND_WINDOW_SENTINEL";
+                await session.prompt("SECOND_WINDOW_SENTINEL: " + "Additional work. ".repeat(100));
+                await nextFinished;
+                await session.waitForIdle();
+                assert.equal(resets, 2);
+                assert.ok(!requests.at(-1).includes("SECOND_WINDOW_SENTINEL"));
+                const boundaries = sm.getBranch().filter((entry) => entry.type === "compaction");
+                assert.equal(new Set(boundaries.map((entry) => JSON.stringify(entry.details))).size, 2);
+            }
+            assert.ok(requests[0].includes("OLD_CONTEXT_SENTINEL"));
+            assert.ok(!requests.at(-1).includes("OLD_CONTEXT_SENTINEL"));
+            assert.ok(requests.at(-1).includes("context_window"));
+            assert.ok(JSON.stringify(session.sessionManager.getBranch()).includes("OLD_CONTEXT_SENTINEL"));
+            if (mode === "golden") {
+                await session.prompt("Keep working in the new window until its reminder threshold.");
+                assert.equal(resets, 1);
+                const branch = sm.getBranch();
+                const boundary = branch.findIndex((entry) => entry.type === "compaction");
+                const reminders = branch.flatMap((entry, i) => entry.type === "custom_message" && entry.customType === GUIDANCE_TYPE ? [i] : []);
+                assert.equal(reminders.length, 2, "the next window gets its own reminder");
+                assert.ok(reminders[1] > boundary, "old messages cannot suppress a new window's reminder");
+                const warnings = branch.flatMap((entry, i) => entry.type === "custom_message" && entry.customType === WARNING_TYPE ? [i] : []);
+                assert.equal(warnings.length, 1, "the next window has no warning yet");
+            }
+        }
+        finally {
+            session?.dispose();
+            if (previousDir === undefined)
+                delete process.env.PI_CODING_AGENT_DIR;
+            else
+                process.env.PI_CODING_AGENT_DIR = previousDir;
+            if (previousNotesRoot === undefined)
+                delete process.env.PI_NOTES_HOME;
+            else
+                process.env.PI_NOTES_HOME = previousNotesRoot;
+            rmSync(dir, { recursive: true, force: true });
+            rmSync(notesRoot, { recursive: true, force: true });
+        }
+    });
+}