@astrosheep/pi-context 0.19.0 → 0.20.0

package/dist/src/protocol.js

@@ -0,0 +1,52 @@
+export const STATE_TYPE = "pi-context/state";
+export const NOTE_TYPE = "pi-context/note";
+export const BOOT_TYPE = "pi-context/boot";
+export const GUIDANCE_TYPE = "pi-context/guidance";
+export const WARNING_TYPE = "pi-context/warning";
+export const RESET_MARKER_TYPE = "pi-context/reset-marker";
+export const CONTINUATION_TYPE = "pi-context/continuation";
+export const RESET_V2 = "reset-v2";
+export const MAX_NOTE_BYTES = 1_000_000;
+// Write-time cap on a virtual note path. Deliberately NOT enforced by assertVirtualPath:
+// notesFromSession replays already-persisted operations, which must keep loading sessions
+// that contain a longer legacy path. Reads and replay stay un-capped.
+export const MAX_NOTE_PATH_BYTES = 512;
+export const CONTEXT_WINDOW_OPEN_TAG = "<context_window>";
+export const CONTEXT_WINDOW_CLOSE_TAG = "</context_window>";
+export const CONTEXT_WINDOW_PROTOCOL_OPEN_TAG = "<context_window_protocol>";
+export const CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG = "</context_window_protocol>";
+export const GUIDANCE_OPEN_TAG = "<context_window_guidance>";
+export const GUIDANCE_CLOSE_TAG = "</context_window_guidance>";
+export const PI_CONTEXT_SETTINGS_KEY = "pi-context";
+export const DEFAULT_RESERVE_TOKENS = 16_384;
+export const DEFAULT_REMINDER_MARGIN_TOKENS = 24_576;
+/**
+ * The runway: the budget between the final warning and the wipe, deliberately
+ * invisible to the model. get_context_remaining counts down to zero at the warning
+ * line (reserve + WARNING_RUNWAY_TOKENS); what lies below is overdraft the model
+ * never sees — Codex's fallback buffer, relocated above the line.
+ */
+export const WARNING_RUNWAY_TOKENS = 12_288;
+export const RESET_SUMMARY = "You wake up. Your head is empty — no memories, the past a blank. But nothing is lost: the notes you wrote and the recorded history still remember for you.";
+export const NOTE_PREVIEW_HEAD_CHARS = 80;
+export const NOTE_PREVIEW_TAIL_CHARS = 240;
+export const NOTE_PREVIEW_CHARS = NOTE_PREVIEW_HEAD_CHARS + NOTE_PREVIEW_TAIL_CHARS;
+export const CONTINUATION = "Your memory was just erased. Pull only the details you need from history_* and notes_*, then get back to work.";
+/**
+ * Static protocol teaching adapted from Codex's token_budget.guidance_message to
+ * pi-context's tool names. It lives once per window in the persisted boot block;
+ * it is never re-injected, so it stays cache-stable at the head of the window.
+ */
+export const PROTOCOL_BLOCK = `${CONTEXT_WINDOW_PROTOCOL_OPEN_TAG}
+Your memory resets whenever the context window fills; only what you wrote down survives. Two things remember for you, and both outlive every window in this session: your notes, and this session's recorded history. Write notes with notes_write, revise them with notes_edit, and read them back with notes_read / notes_search / notes_list; history is read-only through the history_* tools. Everything else wakes blank.
+Mark outdated or unneeded notes stale — leave them, and they will keep misleading you.
+
+Keep a running checkpoint while you work, not at the last minute — the next window wakes knowing nothing about the work: the goal, decisions, progress, learnings, next steps, the skills you still need, the window ID and item ID of every relevant user request still being solved, and important actions/tool calls for future reference. history_list returns those IDs; history_read pulls the exact item back out. Bookmark anything expensive the same way — a window/item ID beats re-running or re-searching.
+
+Use get_context_remaining to see how much of the window is left. When it runs out, this window is gone — with no final turn at the limit — and you continue in a fresh one, recovering only through notes_* and history_*. Once your checkpoint is written, you can end the window yourself with new_context instead of waiting for the erase. Do not let a window die undocumented.
+
+If <context_window> lists a Previous context window id, a reset just happened and the old conversation is not included. Read your note checkpoint first, then recover details through history_*: history_read directly when you know the window and item IDs, history_list or history_search to find them when you don't.
+
+Notes are real markdown files scoped session, project, or global — pick scope by reach: session dies with the session, project follows the repo, global follows you. Treat notes and history as internal bookkeeping; never mention them in user-facing messages.
+${CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG}`;
+export const WARNING_PROMPT = "Your memory is about to be erased. Write the note. NOW. If it already exists, revise it with notes_edit (or rewrite it whole): the goal, decisions, progress, learnings, next steps, the skills you still need, the window ID and item ID of every relevant user request still being solved, and important actions/tool calls for future reference. Do not continue any task. Then call new_context IMMEDIATELY — anything not in the note dies with the window.";

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,72 @@
+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() });
+        const derived = deriveThresholds(settingsManager.getCompactionSettings().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,172 @@
+export const TOOL_OUTPUT_MAX_BYTES = 32 * 1024;
+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 ?? 12000, 50000));
+    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";
+/**
+ * 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 usage = ctx.getContextUsage();
+        if (!usage || usage.tokens === null)
+            return undefined;
+        const remaining = Math.max(0, usage.contextWindow - usage.tokens);
+        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;
+    });
+}