@astrosheep/pi-context 0.24.0 → 0.25.0

package/src/prompts.ts

@@ -1,91 +0,0 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { historyFromSession } from "./history.js";
-import { listNotes } from "./notes/store.js";
-import { CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, POCKET_PERSONAL_LIMIT, POCKET_PROJECT_LIMIT, POCKET_SESSION_LIMIT, RESET_SUMMARY, PROTOCOL_BLOCK, GUIDANCE_OPEN_TAG, GUIDANCE_CLOSE_TAG } from "./protocol.js";
-
-/** Codex-style <context_window> identity block: agent name and first/current/previous window ids only. */
-function identityBlock(agentName: string, firstWindowId: string, currentWindowId: string, previousWindowId?: string): string {
-	const lines = [
-		`Agent name: ${agentName}`,
-		`First context window id: ${firstWindowId}`,
-		`Current context window id: ${currentWindowId}`,
-	];
-	if (previousWindowId) lines.push(`Previous context window id: ${previousWindowId}`);
-	return `${CONTEXT_WINDOW_OPEN_TAG}\n${lines.join("\n")}\n${CONTEXT_WINDOW_CLOSE_TAG}`;
-}
-
-function relativeTime(timestamp: number, now: number): string {
-	const seconds = Math.trunc((timestamp - now) / 1000);
-	const [unit, size] = ([["d", 86400], ["h", 3600], ["m", 60], ["s", 1]] as const)
-		.find(([unit, size]) => Math.abs(seconds) >= size || unit === "s")!;
-	const amount = `${Math.abs(Math.trunc(seconds / size))}${unit}`;
-	return seconds > 0 ? `in ${amount}` : `${amount} ago`;
-}
-
-/**
- * Boot notes index. Map residency ("地图在场"): fresh MAP.md bodies from the personal and
- * project homes are both injected, broadest first; stale maps are skipped per home, and the
- * session home is never peeked — a session MAP.md is an ordinary note. The pocket then lists
- * recent fresh notes under per-home quotas (POCKET_SESSION_LIMIT / POCKET_PROJECT_LIMIT /
- * POCKET_PERSONAL_LIMIT), most-recently-updated first within each home, one metadata line
- * each: address, line count, UTF-8 byte count, relative update time at window open. Bodies never render
- * in the pocket; stale notes are excluded; MAP.md itself never takes a pocket seat.
- */
-function notesIndex(ctx: ExtensionContext): string {
-	const sections: string[] = [];
-	// Map residency ("地图在场"): scope-native maps, both fresh ones injected broadest-first.
-	// A session MAP.md is an ordinary note, never resident; stale maps skip independently.
-	for (const scope of ["personal", "project"] as const) {
-		const toc = listNotes(ctx, { scope }).find((row) => row.path === "MAP.md");
-		if (toc && !toc.meta.stale) {
-			if (toc.body.length > 0) sections.push(toc.body);
-		}
-	}
-	// listNotes is most-recently-updated first within each home. Per-home quotas keep session
-	// churn from evicting project or personal notes; maps never take pocket seats.
-	const recentNotes = [
-		...listNotes(ctx, { scope: "session" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_SESSION_LIMIT),
-		...listNotes(ctx, { scope: "project" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_PROJECT_LIMIT),
-		...listNotes(ctx, { scope: "personal" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_PERSONAL_LIMIT),
-	];
-	if (recentNotes.length > 0) {
-		const lines = [`You find ${recentNotes.length} crumpled note${recentNotes.length === 1 ? "" : "s"} in your pocket (by home, most recent first within each: up to ${POCKET_SESSION_LIMIT} from this session, ${POCKET_PROJECT_LIMIT} from this project, ${POCKET_PERSONAL_LIMIT} from personal). A note's content never appears here, so its name has to say what the note is about:`];
-		const now = Date.now();
-		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, now)})`);
-		}
-		sections.push(lines.join("\n"));
-	}
-	return sections.join("\n\n");
-}
-
-function notesHomeBlock(): string {
-	return "Notes_* addresses have three homes: bare <vpath> is this session, @project/<vpath> is this project, and @personal/<vpath> is the human's cross-project home. @ means leaving home; there is no cross-home fallback. Any other note is a plain file — use the file tools.";
-}
-
-/**
- * Assemble the static, once-per-window boot block: the reset line for resets, the
- * <context_window> identity block, the recent-notes index at window-open time, and
- * the <context_window_protocol> teaching block. Nothing here is re-injected, so the
- * head of the window stays cache-stable.
- */
-export function bootBlock(ctx: ExtensionContext, currentId: string, previousId: string | undefined, resetLine: boolean): string {
-	const firstId = historyFromSession(ctx)[0]?.windowId ?? currentId;
-	const parts: string[] = [];
-	if (resetLine) parts.push(RESET_SUMMARY);
-	parts.push(identityBlock(ctx.sessionManager.getSessionName() ?? "root", firstId, currentId, previousId));
-	parts.push(notesHomeBlock());
-	const index = notesIndex(ctx);
-	if (index) parts.push(index);
-	parts.push(PROTOCOL_BLOCK);
-	return parts.join("\n\n");
-}
-
-/**
- * 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 function tokenBudgetGuidance(remaining: number): string {
-	return `${GUIDANCE_OPEN_TAG}\nYour brain is almost out of room — ${remaining} tokens left, and then your memory gets wiped. The wipe is automatic: there is no final turn to write then. Grab the notebook now — 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. Replacing an older checkpoint? Mark it stale. Then call wipe_memory yourself — anything you do after the checkpoint isn't in it.\n${GUIDANCE_CLOSE_TAG}`;
-}

package/src/reset-lifecycle.ts

@@ -1,173 +0,0 @@
-import type { ExtensionAPI, ExtensionContext, SessionBeforeCompactEvent } from "@earendil-works/pi-coding-agent";
-
-type ResetResult = { cancel: true } | {
-	compaction: { summary: string; firstKeptEntryId: string; tokensBefore: number; details: unknown };
-};
-
-/** A reset request is session-local. Only this module schedules compaction/continuation. */
-export function registerResetLifecycle(pi: ExtensionAPI, options: {
-	isEnabled: () => boolean;
-	continuation: Parameters<ExtensionAPI["sendMessage"]>[0];
-	buildReset: (event: SessionBeforeCompactEvent, ctx: ExtensionContext, explicit: boolean) => ResetResult;
-	isCurrentReset: (entryId: string, ctx: ExtensionContext) => boolean;
-	onReset: (entryId: string) => void;
-}) {
-	type Attempt = {
-		completed: boolean;
-		explicit: boolean;
-		nextRequested: boolean;
-		continuationStarted: boolean;
-		sessionId: string;
-		settled: boolean;
-		wait: Promise<void>;
-		release: () => void;
-	};
-	type Request =
-		| { phase: "idle" }
-		| { phase: "requested" }
-		| { phase: "compacting"; attempt: Attempt };
-	let state: Request = { phase: "idle" };
-	let handledEntry: string | undefined;
-	let active = true;
-
-	const release = (attempt: 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: Attempt, ctx: ExtensionContext) =>
-		active && options.isEnabled() && state.phase === "compacting" && state.attempt === request && ctx.sessionManager.getSessionId() === request.sessionId;
-
-	const begin = (ctx: ExtensionContext) => {
-		let releaseWait!: () => void;
-		const request: Attempt = {
-			completed: false,
-			explicit: true,
-			nextRequested: false,
-			continuationStarted: false,
-			sessionId: ctx.sessionManager.getSessionId(),
-			settled: false,
-			wait: new Promise<void>((resolve) => { releaseWait = resolve; }),
-			release: () => releaseWait(),
-		};
-		state = { phase: "compacting", attempt: request };
-		const onError = (error: 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/src/thresholds.ts

@@ -1,110 +0,0 @@
-import { SettingsManager, type ExtensionContext } 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";
-
-export type ResolvedThresholds = { reminder: number; reserve: number; warning: number };
-type PiContextSettings = { reminderMarginTokens?: unknown; dreamer?: unknown };
-
-function isSettingsObject(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/** Read the raw "pi-context" object from one parsed settings scope. */
-function piContextSettings(settings: unknown): Record<string, unknown> {
-	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: unknown, projectSettings: unknown): PiContextSettings {
-	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: unknown): number | undefined {
-	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: number, margins: PiContextSettings): { thresholds: ResolvedThresholds; warnings: string[] } {
-	const warnings: string[] = [];
-	const reminderKey = `${PI_CONTEXT_SETTINGS_KEY}.reminderMarginTokens`;
-	let reminderMargin: number;
-	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 };
-}
-
-export type DreamerSetting = { pattern?: string; warnings: string[] };
-
-/**
- * `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: PiContextSettings): DreamerSetting {
-	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()): DreamerSetting {
-	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: ResolvedThresholds | undefined;
-
-/**
- * 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: ExtensionContext): ResolvedThresholds {
-	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(): void {
-	cached = undefined;
-}

package/src/warning.ts

@@ -1,46 +0,0 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { WARNING_TYPE, GUIDANCE_OPEN_TAG, GUIDANCE_CLOSE_TAG, WARNING_PROMPT } from "./protocol.js";
-import { thresholdsFor, resetThresholds, type ResolvedThresholds } 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: number, thresholds: ResolvedThresholds): boolean {
-	return remaining <= thresholds.warning;
-}
-
-/** Delivery: what happens when it fires. */
-export function steerWarning(pi: ExtensionAPI, ctx: ExtensionContext, thresholds: ResolvedThresholds, remaining: number): void {
-	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: ExtensionAPI, isEnabled: () => boolean): void {
-	let firedInWindow: string | undefined;
-	// 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;
-	});
-}