@astrosheep/pi-context 0.25.1 → 0.26.0

package/dist/src/context/boot.d.ts

@@ -0,0 +1,24 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type NotesSnapshot } from "../pi/notes/snapshot.js";
+export type IncompleteNotesNotifier = (ctx: ExtensionContext, windowId: string, snapshot: NotesSnapshot) => void;
+/** The boot custom message: identity, notes snapshot, and static protocol; never reset prose. */
+export type BootMessage = {
+    readonly customType: string;
+    readonly content: string;
+    readonly display: false;
+    readonly details: {
+        windowId: string;
+    };
+};
+/**
+ * Acquire one notes snapshot and build the boot custom message for a window. All identity
+ * fields are captured synchronously before the first filesystem await.
+ */
+export declare function buildBootMessage(ctx: ExtensionContext, windowId: string, previousId: string | undefined, notifyIncompleteNotes?: IncompleteNotesNotifier, isCurrent?: () => boolean): Promise<BootMessage>;
+/** Persist one hidden boot message without triggering a model turn. */
+export declare function sendBoot(pi: ExtensionAPI, boot: BootMessage): void;
+/**
+ * Boot entry point for `session_start` / `session_tree`. Ordinary startup ensures one root
+ * boot; a reset marker instead asks reset-artifact repair to complete its persisted tail.
+ */
+export declare function ensureBoot(pi: ExtensionAPI, ctx: ExtensionContext, notifyIncompleteNotes?: IncompleteNotesNotifier, isCurrent?: () => boolean): Promise<void>;

package/dist/src/context/boot.js

@@ -1,28 +1,28 @@
-import { loadNotesSnapshot } from "../notes/notes-snapshot.js";
-import { agentSlug, modelSlug } from "../notes/paths.js";
+import { notesContextFromPi } from "../pi/notes/adapter.js";
+import { loadNotesSnapshot } from "../pi/notes/snapshot.js";
 import { BOOT_TYPE } from "../protocol.js";
 import { renderBootBlock } from "./prompts.js";
-import { currentReset, isWindowBoot, rootWindowId } from "./context-window.js";
+import { currentReset, currentWindowId, isWindowBoot, rootWindowId } from "./context-window.js";
 import { repairResetTail } from "./reset-artifacts.js";
-/** Render the boot block from the live context; acquisition stays with loadNotesSnapshot. */
-function bootContent(ctx, currentId, previousId, notes) {
-    return renderBootBlock({
-        agentName: agentSlug(ctx),
-        modelName: modelSlug(ctx),
-        firstWindowId: rootWindowId(ctx.sessionManager.getSessionId()),
-        currentWindowId: currentId,
-        previousWindowId: previousId,
-        notes,
-    });
+/** Render the boot block from one pre-await identity and acquired notes snapshot. */
+function bootContent(agentName, modelName, firstWindowId, currentId, previousId, notes) {
+    return renderBootBlock({ agentName, modelName, firstWindowId, currentWindowId: currentId, previousWindowId: previousId, notes });
 }
 /**
- * Acquire one notes snapshot and build the boot custom message for a window. The caller
- * supplies `previousId` only when a reset boundary needs the prior window identity.
+ * Acquire one notes snapshot and build the boot custom message for a window. All identity
+ * fields are captured synchronously before the first filesystem await.
  */
-export function buildBootMessage(ctx, windowId, previousId, notifyIncompleteNotes) {
-    const notes = loadNotesSnapshot(ctx);
-    notifyIncompleteNotes?.(ctx, windowId, notes);
-    return { customType: BOOT_TYPE, content: bootContent(ctx, windowId, previousId, notes), display: false, details: { windowId } };
+export async function buildBootMessage(ctx, windowId, previousId, notifyIncompleteNotes, isCurrent = () => true) {
+    const identity = notesContextFromPi(ctx);
+    const notes = await loadNotesSnapshot(ctx, undefined, identity);
+    if (isCurrent())
+        notifyIncompleteNotes?.(ctx, windowId, notes);
+    return {
+        customType: BOOT_TYPE,
+        content: bootContent(identity.agent, identity.model, rootWindowId(identity.sessionId), windowId, previousId, notes),
+        display: false,
+        details: { windowId },
+    };
 }
 /** Persist one hidden boot message without triggering a model turn. */
 export function sendBoot(pi, boot) {
@@ -31,16 +31,25 @@ export function sendBoot(pi, boot) {
 /**
  * Boot entry point for `session_start` / `session_tree`. Ordinary startup ensures one root
  * boot; a reset marker instead asks reset-artifact repair to complete its persisted tail.
- * Boot idempotence lives here: an already-projected root boot or a complete reset tail emits nothing.
  */
-export function ensureBoot(pi, ctx, notifyIncompleteNotes) {
+export async function ensureBoot(pi, ctx, notifyIncompleteNotes, isCurrent = () => true) {
+    const sessionId = ctx.sessionManager.getSessionId();
     const reset = currentReset(ctx);
+    const windowId = reset?.data.windowId ?? rootWindowId(sessionId);
+    const stillCurrent = () => isCurrent() &&
+        ctx.signal?.aborted !== true &&
+        ctx.sessionManager.getSessionId() === sessionId &&
+        currentWindowId(ctx) === windowId;
     if (reset) {
-        repairResetTail(pi, ctx, reset, notifyIncompleteNotes);
+        await repairResetTail(pi, ctx, reset, notifyIncompleteNotes, stillCurrent);
         return;
     }
-    const windowId = rootWindowId(ctx.sessionManager.getSessionId());
     if (ctx.sessionManager.buildSessionProjection().messages.some((message) => isWindowBoot(message, windowId)))
         return;
-    sendBoot(pi, buildBootMessage(ctx, windowId, undefined, notifyIncompleteNotes));
+    const boot = await buildBootMessage(ctx, windowId, undefined, notifyIncompleteNotes, stillCurrent);
+    if (!stillCurrent())
+        return;
+    if (ctx.sessionManager.buildSessionProjection().messages.some((message) => isWindowBoot(message, windowId)))
+        return;
+    sendBoot(pi, boot);
 }

package/dist/src/context/budget.d.ts

@@ -0,0 +1,9 @@
+import { type ExtensionAPI, type ExtensionContext, type SessionBoundaryDraft, type SettingsManager } from "@earendil-works/pi-coding-agent";
+/** Remaining tokens in the provider's active window, or null without a usable estimate. */
+export declare function remainingTokens(ctx: Pick<ExtensionContext, "sessionManager" | "getContextUsage" | "model">): number | null;
+export declare function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean, settingsManager?: SettingsManager, onCloseOut?: (windowId: string) => void): {
+    automaticResetEnabled: (ctx: ExtensionContext) => boolean;
+    hardReserveDue: (ctx: ExtensionContext) => boolean;
+    consumeTurnEnd: (ctx: ExtensionContext) => SessionBoundaryDraft[];
+    clear: () => void;
+};

package/dist/src/context/budget.js

@@ -1,6 +1,6 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-coding-agent";
-import { GUIDANCE_CLOSE_TAG, GUIDANCE_OPEN_TAG, GUIDANCE_TYPE, WARNING_PROMPT, WARNING_TYPE } from "../protocol.js";
+import { GUIDANCE_TYPE, WARNING_CONTENT, WARNING_TYPE } from "../protocol.js";
 import { readThresholdSettings } from "./thresholds.js";
 import { currentWindowId, hasWindowMessage, windowUsage } from "./context-window.js";
 import { tokenBudgetGuidance } from "./prompts.js";
@@ -10,7 +10,7 @@ export function remainingTokens(ctx) {
     const usage = windowUsage(ctx);
     return !usage || usage.tokens === null ? null : Math.max(0, usage.contextWindow - usage.tokens);
 }
-export function registerBudget(pi, isEnabled, settingsManager) {
+export function registerBudget(pi, isEnabled, settingsManager, onCloseOut = () => { }) {
     let cachedPolicy;
     const notifiedWarnings = new Set();
     const resolvePolicy = (ctx) => {
@@ -33,7 +33,7 @@ export function registerBudget(pi, isEnabled, settingsManager) {
     const automaticResetEnabled = (ctx) => {
         return resolvePolicy(ctx).automatic;
     };
-    const resetDue = (ctx) => {
+    const hardReserveDue = (ctx) => {
         if (!automaticResetEnabled(ctx))
             return false;
         const usage = windowUsage(ctx);
@@ -49,8 +49,8 @@ export function registerBudget(pi, isEnabled, settingsManager) {
             if (notice.windowId !== windowId || !hasWindowMessage(ctx, notice.customType))
                 continue;
             ctx.ui.notify(notice.customType === WARNING_TYPE
-                ? "pi-context: context budget critical — final checkpoint warning recorded for the model."
-                : "pi-context: context budget low — checkpoint reminder recorded for the model, kept out of the chat view.", "warning");
+                ? "pi-context: Context almost full; close out the current memory window."
+                : "pi-context: Context running low; checkpoint your notes soon.", "warning");
         }
         pendingNotices = [];
     };
@@ -72,7 +72,7 @@ export function registerBudget(pi, isEnabled, settingsManager) {
         clearStaged();
         const windowId = currentWindowId(ctx);
         const drafts = staged.filter((draft) => draft !== undefined && draft.windowId === windowId);
-        pendingNotices = drafts.map(({ windowId, customType }) => ({ windowId, customType }));
+        pendingNotices = drafts.map(({ windowId, customType, remaining }) => ({ windowId, customType, remaining }));
         return drafts.map((draft) => ({
             type: "custom_message",
             customType: draft.customType,
@@ -88,7 +88,6 @@ export function registerBudget(pi, isEnabled, settingsManager) {
     // lifecycle point that must discard an uncommitted draft before the next prompt.
     // UI notices follow committed reminders. Aborted requests can retry their drafts
     // without showing the same low-budget notification twice.
-    pi.on("turn_start", (_event, ctx) => notifyCommittedReminders(ctx));
     pi.on("agent_settled", (_event, ctx) => {
         notifyCommittedReminders(ctx);
         clearStaged();
@@ -103,13 +102,16 @@ export function registerBudget(pi, isEnabled, settingsManager) {
             return undefined;
         const windowId = currentWindowId(ctx);
         const { reminder, warning } = thresholdsFor(ctx);
-        if (hasWindowMessage(ctx, WARNING_TYPE) || pendingWarning?.windowId === windowId)
-            return undefined;
-        if (remaining <= warning) {
-            // A not-yet-committed shallow reminder is superseded by the final warning.
+        if (remaining <= warning && automaticResetEnabled(ctx)) {
+            // Re-arm close-out on each eligible request. A prior request may have aborted
+            // after persisting the warning, so warning deduplication must not own this state.
+            onCloseOut(windowId);
+            if (hasWindowMessage(ctx, WARNING_TYPE) || pendingWarning?.windowId === windowId)
+                return undefined;
+            // The critical close-out starts at reserve + runway, not at the hard reserve.
             pendingGuidance = undefined;
-            const content = `${GUIDANCE_OPEN_TAG}\n${WARNING_PROMPT}\n${GUIDANCE_CLOSE_TAG}`;
-            pendingWarning = { windowId, content };
+            const content = WARNING_CONTENT;
+            pendingWarning = { windowId, content, remaining };
             const warningMessage = {
                 role: "custom",
                 customType: WARNING_TYPE,
@@ -119,13 +121,15 @@ export function registerBudget(pi, isEnabled, settingsManager) {
             };
             return { messages: [..._event.messages, warningMessage] };
         }
+        if (hasWindowMessage(ctx, WARNING_TYPE) || pendingWarning?.windowId === windowId)
+            return undefined;
         if (hasWindowMessage(ctx, GUIDANCE_TYPE) || pendingGuidance?.windowId === windowId)
             return undefined;
         if (remaining <= reminder) {
             // Persist at turn_end, before any reset drafts. A queued sendMessage could
             // otherwise cross the marker and leak the old window's reminder forward.
             const left = Math.max(0, remaining - warning);
-            pendingGuidance = { windowId, content: tokenBudgetGuidance(left) };
+            pendingGuidance = { windowId, content: tokenBudgetGuidance(left), remaining };
         }
         return undefined;
     });
@@ -143,7 +147,7 @@ export function registerBudget(pi, isEnabled, settingsManager) {
     }));
     return {
         automaticResetEnabled,
-        resetDue,
+        hardReserveDue,
         consumeTurnEnd,
         clear: () => { clearStaged(); pendingNotices = []; },
     };

package/dist/src/context/context-window.d.ts

@@ -0,0 +1,41 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { type CustomEntry, type ExtensionContext, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { SessionReader } from "../session-reader.js";
+export type WindowMarker = CustomEntry<{
+    windowId: string;
+}> & {
+    data: {
+        windowId: string;
+    };
+};
+export declare function isWindowMarker(entry: SessionEntry): entry is WindowMarker;
+/** Only the active branch can supply a window boundary. */
+export declare function currentReset(ctx: SessionReader): WindowMarker | undefined;
+/** A reset is checkpoint-backed only when its marker directly follows a native compaction. */
+export declare function isCheckpointBackedReset(ctx: SessionReader, marker?: WindowMarker | undefined): boolean;
+/** Mint the durable identity of a session's root history window. */
+export declare function rootWindowId(sessionId: string): string;
+/** Persisted messages in the active window, excluding earlier windows on this branch. */
+export declare function hasWindowMessage(ctx: SessionReader, customType: string): boolean;
+/** The root or latest durable marker on the active branch. */
+export declare function currentWindowId(ctx: SessionReader): string;
+/** The durable window active just before the marker: the last earlier marker, else the root window. */
+export declare function previousWindowId(ctx: SessionReader, markerId: string): string;
+/** Match a provider-facing boot message, optionally by window identity. */
+export declare function isWindowBoot(message: AgentMessage, windowId?: string): boolean;
+/** Match a persisted boot entry by raw identity, even when a later edit hides it from projection. */
+export declare function isWindowBootEntry(entry: SessionEntry, windowId: string): boolean;
+/**
+ * The durable marker selects a boot message by identity, never by wall-clock time.
+ * The boot is the first conversation message of the window. Folding only its prefix
+ * preserves later prompt/tool patches in place, including their cacheable ordering.
+ */
+export declare function projectWindow(messages: AgentMessage[], windowId: string): AgentMessage[];
+/**
+ * Root windows are not reset boundaries. A forked session can copy a root boot whose
+ * details name the source session; refresh that boot in-place in the provider projection
+ * while retaining every user/assistant/tool message from the copied root transcript.
+ */
+export declare function projectRootWindow(messages: AgentMessage[], windowId: string): AgentMessage[];
+/** Usage for the selected window, excluding provider usage recorded before its marker. */
+export declare function windowUsage(ctx: Pick<ExtensionContext, "sessionManager" | "getContextUsage" | "model">): import("@earendil-works/pi-coding-agent").ContextUsage | undefined;

package/dist/src/context/context-window.js

@@ -18,6 +18,16 @@ export function currentReset(ctx) {
     }
     return undefined;
 }
+/** A reset is checkpoint-backed only when its marker directly follows a native compaction. */
+export function isCheckpointBackedReset(ctx, marker = currentReset(ctx)) {
+    if (!marker?.parentId)
+        return false;
+    const branch = ctx.sessionManager.getBranch();
+    const markerIndex = branch.findIndex((entry) => entry.id === marker.id);
+    const checkpoint = branch[markerIndex - 1];
+    return markerIndex > 0 && checkpoint?.id === marker.parentId && checkpoint.type === "compaction" &&
+        checkpoint.summary === "" && checkpoint.firstKeptEntryId === checkpoint.id;
+}
 /** Mint the durable identity of a session's root history window. */
 export function rootWindowId(sessionId) {
     return `pcw:${sessionId.slice(0, 8)}:root`;
@@ -99,7 +109,12 @@ export function windowUsage(ctx) {
         return undefined;
     const windowId = reset.data.windowId;
     try {
-        const messages = projectWindow(ctx.sessionManager.buildSessionProjection().messages, windowId);
+        const canonicalMessages = ctx.sessionManager.buildSessionProjection().messages;
+        // New resets already cut the durable Pi projection. Marker slicing is retained only
+        // for sessions written before native reset checkpoints existed.
+        const messages = isCheckpointBackedReset(ctx, reset)
+            ? canonicalMessages
+            : projectWindow(canonicalMessages, windowId);
         const { tokens } = estimateContextTokens(convertToLlm(messages));
         return { tokens, contextWindow, percent: tokens / contextWindow * 100 };
     }

package/dist/src/context/prompts.d.ts

@@ -0,0 +1,20 @@
+import type { NotesSnapshot } from "../pi/notes/snapshot.js";
+/**
+ * Render a static, once-per-window boot block from explicit data. This function does not read
+ * notes or call runtime UI APIs; acquisition belongs to loadNotesSnapshot and its caller.
+ */
+export type BootRenderData = {
+    readonly agentName: string;
+    readonly modelName: string;
+    readonly firstWindowId: string;
+    readonly currentWindowId: string;
+    readonly previousWindowId?: string;
+    readonly notes: NotesSnapshot;
+};
+export declare function renderBootBlock(data: BootRenderData): string;
+/**
+ * Codex-equivalent low-budget reminder. The measured remaining count is frozen into
+ * the text at the crossing that fires it, so each persisted copy is a snapshot true
+ * at write time; get_context_remaining remains the live source for the current figure.
+ */
+export declare function tokenBudgetGuidance(remaining: number): string;

package/dist/src/context/prompts.js

@@ -59,7 +59,7 @@ function notesIndex(snapshot) {
     if (recentNotes.length > 0) {
         const lines = [`You find ${recentNotes.length} crumpled note${recentNotes.length === 1 ? "" : "s"} in your pocket (by prefix, most recent first within each: up to ${POCKET_SESSION_LIMIT} from this session, ${POCKET_PROJECT_LIMIT} from @project, ${POCKET_HUMAN_LIMIT} from @human, ${POCKET_AGENT_LIMIT} from @self, ${POCKET_MODEL_LIMIT} from @model). A note's content never appears here, so its name has to say what the note is about:`];
         for (const row of recentNotes) {
-            lines.push(`- ${row.address} (${row.body.split("\n").length} lines, ${row.sizeBytes} UTF-8 bytes, updated ${relativeTime(row.meta.updated_at, snapshot.openedAt)})`);
+            lines.push(`- ${row.address} (${row.body.split("\n").length} lines, ${row.sizeBytes} UTF-8 bytes, updated ${relativeTime(row.meta.updatedAt, snapshot.openedAt)})`);
         }
         sections.push(lines.join("\n"));
     }

package/dist/src/context/reset-artifacts.d.ts

@@ -0,0 +1,26 @@
+import type { ExtensionAPI, ExtensionContext, SessionBoundaryDraft, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { type WindowMarker } from "./context-window.js";
+import { type IncompleteNotesNotifier } from "./boot.js";
+export type ResetTailState = {
+    readonly boot: boolean;
+    readonly continuation: boolean;
+};
+/** Match the hidden continuation entry that carries the one reset message. */
+export declare function isWindowContinuationEntry(entry: SessionEntry): boolean;
+/** The single continuation sender: the only reset prose persisted for a window. */
+export declare function sendContinuation(pi: ExtensionAPI): void;
+/**
+ * The closed, ordered reset shape: retain-none native checkpoint, marker, matching boot,
+ * continuation. The boot snapshot is acquired asynchronously after capturing this identity.
+ */
+export declare function buildResetDrafts(ctx: ExtensionContext, notifyIncompleteNotes?: IncompleteNotesNotifier, isCurrent?: () => boolean): Promise<[SessionBoundaryDraft, SessionBoundaryDraft, SessionBoundaryDraft, SessionBoundaryDraft]>;
+/**
+ * Inspect the persisted tail of a reset marker. It reports which reset messages are present
+ * only while the tail stays repairable: metadata may follow the marker, but real conversation,
+ * a foreign message, a later marker, or a misordered/duplicate reset artifact refuses repair.
+ */
+export declare function inspectResetTail(ctx: ExtensionContext, markerId: string, windowId: string): ResetTailState | undefined;
+/** True once the marker's tail already carries its boot and continuation in a valid order. */
+export declare function resetTailCommitted(ctx: ExtensionContext, markerId: string, windowId: string): boolean;
+/** Emit only the reset artifacts an incomplete tail is missing, in the closed order. */
+export declare function repairResetTail(pi: ExtensionAPI, ctx: ExtensionContext, marker: WindowMarker, notifyIncompleteNotes?: IncompleteNotesNotifier, isCurrent?: () => boolean): Promise<void>;

package/dist/src/context/reset-artifacts.js

@@ -11,31 +11,26 @@ export function sendContinuation(pi) {
     pi.sendMessage({ customType: CONTINUATION_TYPE, content: CONTINUATION, display: false }, { triggerTurn: false });
 }
 /**
- * The closed, ordered reset shape: marker, matching boot, continuation. This is the one
- * source of the reset message and the one place that mints the new window identity.
+ * The closed, ordered reset shape: retain-none native checkpoint, marker, matching boot,
+ * continuation. The boot snapshot is acquired asynchronously after capturing this identity.
  */
-export function buildResetDrafts(ctx, notifyIncompleteNotes) {
-    const sessionPrefix = ctx.sessionManager.getSessionId().slice(0, 8);
+export async function buildResetDrafts(ctx, notifyIncompleteNotes, isCurrent = () => true) {
+    const sessionId = ctx.sessionManager.getSessionId();
+    const previousId = currentWindowId(ctx);
+    const sessionPrefix = sessionId.slice(0, 8);
     const usedWindowIds = new Set(ctx.sessionManager.getBranch().filter(isWindowMarker).map((entry) => entry.data.windowId));
     let windowId;
     do {
         windowId = `pcw:${sessionPrefix}:${randomUUID().slice(0, 8)}`;
     } while (usedWindowIds.has(windowId));
-    const boot = buildBootMessage(ctx, windowId, currentWindowId(ctx), notifyIncompleteNotes);
+    const boot = await buildBootMessage(ctx, windowId, previousId, notifyIncompleteNotes, isCurrent);
     return [
+        { type: "compaction", summary: "", firstKeptEntryId: null },
         { type: "custom", customType: RESET_MARKER_TYPE, data: { windowId } },
         { type: "custom_message", customType: BOOT_TYPE, content: boot.content, display: false, details: { windowId } },
         { type: "custom_message", customType: CONTINUATION_TYPE, content: CONTINUATION, display: false },
     ];
 }
-/** Persist the marker and send both hidden reset messages; returns the new window id. */
-export function persistManualReset(pi, ctx, notifyIncompleteNotes) {
-    const [marker, boot, continuation] = buildResetDrafts(ctx, notifyIncompleteNotes);
-    pi.appendEntry(marker.customType, marker.data);
-    pi.sendMessage({ customType: boot.customType, content: boot.content, display: boot.display, details: boot.details }, { triggerTurn: false });
-    pi.sendMessage({ customType: continuation.customType, content: continuation.content, display: continuation.display }, { triggerTurn: false });
-    return boot.details.windowId;
-}
 /**
  * Inspect the persisted tail of a reset marker. It reports which reset messages are present
  * only while the tail stays repairable: metadata may follow the marker, but real conversation,
@@ -75,12 +70,18 @@ export function resetTailCommitted(ctx, markerId, windowId) {
     return tail?.boot === true && tail.continuation === true;
 }
 /** Emit only the reset artifacts an incomplete tail is missing, in the closed order. */
-export function repairResetTail(pi, ctx, marker, notifyIncompleteNotes) {
+export async function repairResetTail(pi, ctx, marker, notifyIncompleteNotes, isCurrent = () => true) {
     const tail = inspectResetTail(ctx, marker.id, marker.data.windowId);
     if (!tail || (tail.boot && tail.continuation))
         return;
-    if (!tail.boot)
-        sendBoot(pi, buildBootMessage(ctx, marker.data.windowId, previousWindowId(ctx, marker.id), notifyIncompleteNotes));
-    if (!tail.continuation)
+    const boot = tail.boot ? undefined : await buildBootMessage(ctx, marker.data.windowId, previousWindowId(ctx, marker.id), notifyIncompleteNotes, isCurrent);
+    if (!isCurrent())
+        return;
+    const latest = inspectResetTail(ctx, marker.id, marker.data.windowId);
+    if (!latest)
+        return;
+    if (!latest.boot && boot)
+        sendBoot(pi, boot);
+    if (!latest.continuation && (latest.boot || boot))
         sendContinuation(pi);
 }

package/dist/src/context/reset-lifecycle.d.ts

@@ -0,0 +1,89 @@
+import type { ExtensionAPI, ExtensionContext, SessionBoundaryDraft } from "@earendil-works/pi-coding-agent";
+type BudgetOwner = {
+    automaticResetEnabled: (ctx: ExtensionContext) => boolean;
+    hardReserveDue: (ctx: ExtensionContext) => boolean;
+    consumeTurnEnd: (ctx: ExtensionContext) => SessionBoundaryDraft[];
+    clear: () => void;
+};
+type ResetOptions = {
+    isEnabled: () => boolean;
+    budget: BudgetOwner;
+    buildReset: (ctx: ExtensionContext, isCurrent: () => boolean) => SessionBoundaryDraft[] | Promise<SessionBoundaryDraft[]>;
+    getLifecycleGeneration?: () => number;
+    onResetReady?: (ctx: ExtensionContext, drafts: readonly SessionBoundaryDraft[]) => void;
+};
+export type ResetRequestSource = "manual" | "automatic";
+export type ResetRequest = {
+    readonly phase: "none";
+} | {
+    readonly phase: "close-out";
+    readonly windowId: string;
+    readonly source: ResetRequestSource;
+} | {
+    readonly phase: "tool-requested";
+    readonly windowId: string;
+};
+export type ResetOverflowPhase = "idle" | "pending" | "pending-spent" | "spent";
+export interface ResetControlState {
+    readonly request: ResetRequest;
+    readonly overflow: ResetOverflowPhase;
+}
+export declare function initialResetControl(): ResetControlState;
+/** Facts for a completed turn. Guard values stay lazy to preserve policy resolution order. */
+export interface ResetTurnEndFacts {
+    readonly windowId: string;
+    readonly aborted: boolean;
+    readonly overflow: boolean;
+    readonly failed: boolean;
+    readonly enabled: boolean;
+    readonly queued: boolean;
+    readonly automaticResetEnabled: boolean;
+    readonly hardReserveDue: boolean;
+}
+/** Facts for the pre-settlement boundary; policy guards stay lazy for the same reason. */
+export interface ResetBeforeSettleFacts {
+    readonly windowId: string;
+    readonly queued: boolean;
+    readonly enabled: boolean;
+    readonly automaticResetEnabled: boolean;
+    readonly aborted: boolean;
+    readonly failed: boolean;
+}
+export type ResetControlEvent = {
+    readonly type: "close_out";
+    readonly windowId: string;
+    readonly source: ResetRequestSource;
+} | {
+    readonly type: "tool_request";
+    readonly windowId: string;
+} | {
+    readonly type: "turn_end";
+    readonly facts: ResetTurnEndFacts;
+} | {
+    readonly type: "before_settle";
+    readonly facts: ResetBeforeSettleFacts;
+} | {
+    readonly type: "settled";
+} | {
+    readonly type: "abort";
+} | {
+    readonly type: "clear";
+};
+export type ResetControlEffect = "none" | "close-out-armed" | "already-pending" | "commit-boundary" | "recover-overflow";
+export interface ResetControlResult {
+    readonly state: ResetControlState;
+    readonly effect: ResetControlEffect;
+}
+/** Pure reset-control transitions: request phases own close-out, tool commit, and fallback. */
+export declare function reduceResetControl(state: ResetControlState, event: ResetControlEvent): ResetControlResult;
+/**
+ * Own close-out requests at Pi's public turn and pre-settlement boundaries. Tool-requested
+ * resets commit at turn_end; manual and budget close-outs remain armed across note/tool turns
+ * and fall back at a successful agent_before_settle. Overflow recovery remains bounded.
+ */
+export declare function registerResetLifecycle(pi: ExtensionAPI, options: ResetOptions): {
+    closeOut(windowId: string, source: ResetRequestSource): ResetControlEffect;
+    request(windowId: string): "rollover_already_pending" | "rollover_requested";
+    clear: () => void;
+};
+export {};