@astrosheep/pi-context 0.24.0 → 0.25.0

package/dist/src/reset-lifecycle.js

@@ -1,155 +0,0 @@
-/** 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 release = (attempt) => {
-        if (attempt.settled)
-            return;
-        attempt.settled = true;
-        if (state.phase === "compacting" && state.attempt === attempt) {
-            state = { phase: "idle" };
-            handledEntry = undefined;
-        }
-        attempt.release();
-    };
-    const clear = () => {
-        if (state.phase === "compacting")
-            release(state.attempt);
-        state = { phase: "idle" };
-        handledEntry = undefined;
-    };
-    const valid = (request, ctx) => active && options.isEnabled() && state.phase === "compacting" && state.attempt === request && ctx.sessionManager.getSessionId() === request.sessionId;
-    const begin = (ctx) => {
-        let releaseWait;
-        const request = {
-            completed: false,
-            explicit: true,
-            nextRequested: false,
-            continuationStarted: false,
-            sessionId: ctx.sessionManager.getSessionId(),
-            settled: false,
-            wait: new Promise((resolve) => { releaseWait = resolve; }),
-            release: () => releaseWait(),
-        };
-        state = { phase: "compacting", attempt: request };
-        const onError = (error) => {
-            if (!valid(request, ctx))
-                return;
-            release(request);
-            // 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;
-                    // 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()) {
-                        // The SDK detaches sendMessage, so own the next settled event before
-                        // starting it. The originating agent_settled handler awaits wait.
-                        if (request.continuationStarted)
-                            return;
-                        request.continuationStarted = true;
-                        try {
-                            pi.sendMessage(options.continuation, { triggerTurn: true });
-                        }
-                        catch (error) {
-                            onError(error instanceof Error ? error : new Error(String(error)));
-                        }
-                        return;
-                    }
-                    release(request);
-                },
-                onError,
-            });
-        }
-        catch (error) {
-            onError(error instanceof Error ? error : new Error(String(error)));
-        }
-        return request;
-    };
-    // 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.
-            clear();
-        }
-    });
-    pi.on("agent_settled", (_event, ctx) => {
-        if (!active || !options.isEnabled() || !ctx.isIdle())
-            return;
-        if (state.phase === "compacting" && state.attempt.continuationStarted) {
-            const preceding = state.attempt;
-            if (!preceding.nextRequested) {
-                release(preceding);
-                return;
-            }
-            // This settled event belongs to the continuation started by preceding.
-            // If it requested another reset, retain preceding until that reset's own
-            // continuation settles. Its eventual nested handler only releases its own
-            // waiter, so it never awaits itself.
-            const next = begin(ctx);
-            return next.wait.then(() => release(preceding));
-        }
-        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.
-        return begin(ctx).wait;
-    });
-    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() {
-            if (state.phase === "idle") {
-                state = { phase: "requested" };
-                return "rollover_requested";
-            }
-            if (state.phase === "compacting" && state.attempt.continuationStarted && !state.attempt.nextRequested) {
-                state.attempt.nextRequested = true;
-                return "rollover_requested";
-            }
-            return "rollover_already_pending";
-        },
-        clear,
-    };
-}

package/dist/src/thresholds.js

@@ -1,102 +0,0 @@
-import { SettingsManager } from "@earendil-works/pi-coding-agent";
-import { PI_CONTEXT_SETTINGS_KEY, PI_CONTEXT_DREAMER_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, dreamer: merged.dreamer };
-}
-/** 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 };
-}
-/**
- * `pi-context.dreamer` is a non-empty model pattern. Anything else present is ignored
- * with one warning; absent means no configured pattern, so the automatic model applies.
- */
-export function deriveDreamer(settings) {
-    const raw = settings.dreamer;
-    if (raw === undefined)
-        return { warnings: [] };
-    if (typeof raw !== "string" || raw.trim().length === 0) {
-        return { warnings: [`pi-context: ${PI_CONTEXT_SETTINGS_KEY}.${PI_CONTEXT_DREAMER_KEY} must be a non-empty string; ignoring it.`] };
-    }
-    return { pattern: raw.trim(), warnings: [] };
-}
-/**
- * Resolve the configurable dreamer model from Pi settings for a CLI invocation: global
- * `~/.pi/agent/settings.json` merged with the project's `.pi/settings.json`, project
- * values winning per key. A settings read failure degrades to no pattern with one warning.
- */
-export function readDreamerSettings(cwd = process.cwd()) {
-    try {
-        const settingsManager = SettingsManager.create(cwd, undefined, { projectTrusted: true });
-        return deriveDreamer(mergePiContextSettings(settingsManager.getGlobalSettings(), settingsManager.getProjectSettings()));
-    }
-    catch (error) {
-        return { warnings: [`pi-context: could not read settings; using the automatic dreamer model (${String(error)}).`] };
-    }
-}
-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/warning.js

@@ -1,44 +0,0 @@
-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;
-    });
-}