@herbertgao/sol-pi 0.1.0

package/src/sol-pi/extensions/online-context-compact/index.ts

@@ -0,0 +1,49 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_CACHE_WRITE_READ_RATIO } from "../../config.ts";
+import { createOnlineContextCompactExtension } from "./extension.ts";
+
+export {
+	DEFAULT_COMPACTION_ECONOMICS,
+	decideCompaction,
+	estimateRemainingRequests,
+	type CompactionDecision,
+	type CompactionEconomics,
+	type CompactionReason,
+} from "./economics.ts";
+export {
+	BOUNDARY_COMPACTION_INSTRUCTIONS,
+	createOnlineContextCompactExtension,
+	DEFAULT_KEEP_RECENT_TOKENS,
+	DEFAULT_NATIVE_SUMMARY_TOKEN_ESTIMATE,
+	POST_COMPACTION_PLAN_REMINDER,
+	type OnlineContextCompactOptions,
+	resolveKeepRecentTokens,
+} from "./extension.ts";
+export {
+	analyzePlanTransition,
+	formatPlanSnapshot,
+	parsePlanSteps,
+	type PlanStatus,
+	type PlanStep,
+} from "./plan.ts";
+export {
+	initialOnlineState,
+	ONLINE_STATE_ENTRY,
+	restoreOnlineState,
+	type OnlineState,
+	type ProgressSummary,
+} from "./state.ts";
+export type { PlanProgress, PlanUpdateInput } from "./tools.ts";
+
+export function registerOnlineContextCompact(
+	pi: ExtensionAPI,
+	cacheWriteReadRatio = DEFAULT_CACHE_WRITE_READ_RATIO,
+): void {
+	createOnlineContextCompactExtension({ cacheWriteReadRatio })(pi);
+}
+
+export default registerOnlineContextCompact;

package/src/sol-pi/extensions/online-context-compact/plan.ts

@@ -0,0 +1,79 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+export const PLAN_STATUSES = ["pending", "in_progress", "completed"] as const;
+
+export type PlanStatus = (typeof PLAN_STATUSES)[number];
+
+export type PlanStep = {
+	readonly id: string;
+	readonly goal: string;
+	readonly status: PlanStatus;
+};
+
+export type PlanTransition = {
+	readonly completedSteps: readonly PlanStep[];
+	readonly advice: readonly string[];
+};
+
+const MAX_PLAN_STEPS = 128;
+const MAX_PLAN_STRING_BYTES = 16_384;
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isBoundedString(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0 && Buffer.byteLength(value) <= MAX_PLAN_STRING_BYTES;
+}
+
+function isPlanStatus(value: unknown): value is PlanStatus {
+	return PLAN_STATUSES.some((status) => status === value);
+}
+
+export function parsePlanSteps(value: unknown): readonly PlanStep[] | undefined {
+	if (!Array.isArray(value) || value.length > MAX_PLAN_STEPS) return;
+	const steps: PlanStep[] = [];
+	for (const item of value) {
+		if (
+			!isRecord(item) ||
+			Object.keys(item).length !== 3 ||
+			!isBoundedString(item.id) ||
+			!isBoundedString(item.goal) ||
+			!isPlanStatus(item.status)
+		) {
+			return;
+		}
+		steps.push({ id: item.id, goal: item.goal, status: item.status });
+	}
+	if (new Set(steps.map((step) => step.id)).size !== steps.length) return;
+	return steps;
+}
+
+export function analyzePlanTransition(previous: readonly PlanStep[], next: readonly PlanStep[]): PlanTransition {
+	const previousById = new Map(previous.map((step) => [step.id, step]));
+	const completedSteps: PlanStep[] = [];
+	const advice: string[] = [];
+
+	for (const step of next) {
+		const prior = previousById.get(step.id);
+		if ((!prior || prior.status !== "completed") && step.status === "completed") completedSteps.push(step);
+		if (prior && prior.goal !== step.goal) {
+			advice.push(`Plan step ${JSON.stringify(step.id)} changed goal; reuse an id only for the same goal.`);
+		}
+	}
+
+	const inProgress = next.filter((step) => step.status === "in_progress").length;
+	if (inProgress > 1) advice.push("Keep at most one plan step in_progress.");
+	if (inProgress === 0 && next.some((step) => step.status === "pending")) {
+		advice.push("Mark one pending plan step in_progress before starting it.");
+	}
+
+	return { completedSteps, advice };
+}
+
+export function formatPlanSnapshot(steps: readonly PlanStep[]): string {
+	return `<sol-pi-plan task_status="active">${JSON.stringify({ steps })}</sol-pi-plan>`;
+}

package/src/sol-pi/extensions/online-context-compact/state.ts

@@ -0,0 +1,208 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+import type { ExtensionAPI, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { parsePlanSteps, type PlanStep } from "./plan.ts";
+
+export const ONLINE_STATE_ENTRY = "sol-pi-online-context-state-v1";
+
+export type ProgressSummary = {
+	readonly stepId: string;
+	readonly goal: string;
+	readonly filesChanged: readonly string[];
+	readonly verification: readonly string[];
+	readonly decisions: readonly string[];
+	readonly nextWork: readonly string[];
+};
+
+export type OnlineState = {
+	readonly version: 1;
+	readonly epoch: number;
+	readonly plan: readonly PlanStep[];
+	readonly pendingProgress: readonly ProgressSummary[];
+	readonly requestCount: number;
+	readonly lastBoundaryRequestCount: number;
+	readonly completedBoundaryRequestCounts: readonly number[];
+	readonly lastContextTokens: number | null;
+	readonly positiveContextDeltaTotal: number;
+	readonly positiveContextDeltaCount: number;
+	readonly nativeCompactionCount: number;
+	readonly cacheDebtTokens: number;
+	readonly cacheDebtRepaymentTokens: number;
+};
+
+export function initialOnlineState(): OnlineState {
+	return {
+		version: 1,
+		epoch: 0,
+		plan: [],
+		pendingProgress: [],
+		requestCount: 0,
+		lastBoundaryRequestCount: 0,
+		completedBoundaryRequestCounts: [],
+		lastContextTokens: null,
+		positiveContextDeltaTotal: 0,
+		positiveContextDeltaCount: 0,
+		nativeCompactionCount: 0,
+		cacheDebtTokens: 0,
+		cacheDebtRepaymentTokens: 0,
+	};
+}
+
+function nonNegativeInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function finiteNonNegative(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function stringArray(value: unknown): readonly string[] | undefined {
+	if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) return;
+	return [...value];
+}
+
+function progressSummary(value: unknown): ProgressSummary | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return;
+	const record = value as Record<string, unknown>;
+	const filesChanged = stringArray(record.filesChanged);
+	const verification = stringArray(record.verification);
+	const decisions = stringArray(record.decisions);
+	const nextWork = stringArray(record.nextWork);
+	if (
+		typeof record.stepId !== "string" ||
+		typeof record.goal !== "string" ||
+		!filesChanged ||
+		!verification ||
+		!decisions ||
+		!nextWork
+	) {
+		return;
+	}
+	return { stepId: record.stepId, goal: record.goal, filesChanged, verification, decisions, nextWork };
+}
+
+function parseOnlineState(value: unknown): OnlineState | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return;
+	const record = value as Record<string, unknown>;
+	const plan = parsePlanSteps(record.plan);
+	const pendingProgress = Array.isArray(record.pendingProgress)
+		? record.pendingProgress.map(progressSummary)
+		: undefined;
+	const completedBoundaryRequestCounts = Array.isArray(record.completedBoundaryRequestCounts)
+		? record.completedBoundaryRequestCounts
+		: undefined;
+	if (
+		record.version !== 1 ||
+		!plan ||
+		!pendingProgress ||
+		pendingProgress.some((item) => item === undefined) ||
+		!completedBoundaryRequestCounts ||
+		!completedBoundaryRequestCounts.every(nonNegativeInteger) ||
+		!nonNegativeInteger(record.epoch) ||
+		!nonNegativeInteger(record.requestCount) ||
+		!nonNegativeInteger(record.lastBoundaryRequestCount) ||
+		record.lastBoundaryRequestCount > record.requestCount ||
+		!(record.lastContextTokens === null || nonNegativeInteger(record.lastContextTokens)) ||
+		!finiteNonNegative(record.positiveContextDeltaTotal) ||
+		!nonNegativeInteger(record.positiveContextDeltaCount) ||
+		!nonNegativeInteger(record.nativeCompactionCount) ||
+		!finiteNonNegative(record.cacheDebtTokens) ||
+		!finiteNonNegative(record.cacheDebtRepaymentTokens)
+	) {
+		return;
+	}
+	return {
+		version: 1,
+		epoch: record.epoch,
+		plan,
+		pendingProgress: pendingProgress as readonly ProgressSummary[],
+		requestCount: record.requestCount,
+		lastBoundaryRequestCount: record.lastBoundaryRequestCount,
+		completedBoundaryRequestCounts: completedBoundaryRequestCounts as readonly number[],
+		lastContextTokens: record.lastContextTokens,
+		positiveContextDeltaTotal: record.positiveContextDeltaTotal,
+		positiveContextDeltaCount: record.positiveContextDeltaCount,
+		nativeCompactionCount: record.nativeCompactionCount,
+		cacheDebtTokens: record.cacheDebtTokens,
+		cacheDebtRepaymentTokens: record.cacheDebtRepaymentTokens,
+	};
+}
+
+export function restoreOnlineState(entries: readonly SessionEntry[]): OnlineState {
+	for (let index = entries.length - 1; index >= 0; index--) {
+		const entry = entries[index];
+		if (entry?.type !== "custom" || entry.customType !== ONLINE_STATE_ENTRY) continue;
+		const state = parseOnlineState(entry.data);
+		if (state) return state;
+	}
+	return initialOnlineState();
+}
+
+export function appendOnlineState(pi: ExtensionAPI, state: OnlineState): void {
+	pi.appendEntry(ONLINE_STATE_ENTRY, state);
+}
+
+export function recordProviderRequest(state: OnlineState, contextTokens: number): OnlineState {
+	const delta = state.lastContextTokens === null ? 0 : contextTokens - state.lastContextTokens;
+	const cacheDebtTokens = Math.max(0, state.cacheDebtTokens - state.cacheDebtRepaymentTokens);
+	return {
+		...state,
+		requestCount: state.requestCount + 1,
+		lastContextTokens: contextTokens,
+		positiveContextDeltaTotal: state.positiveContextDeltaTotal + Math.max(0, delta),
+		positiveContextDeltaCount: state.positiveContextDeltaCount + (delta > 0 ? 1 : 0),
+		cacheDebtTokens,
+		cacheDebtRepaymentTokens: cacheDebtTokens === 0 ? 0 : state.cacheDebtRepaymentTokens,
+	};
+}
+
+export function recordBoundary(
+	state: OnlineState,
+	plan: readonly PlanStep[],
+	progress: ProgressSummary | undefined,
+): OnlineState {
+	const interval = Math.max(0, state.requestCount - state.lastBoundaryRequestCount);
+	return {
+		...state,
+		plan: [...plan],
+		pendingProgress: progress ? [...state.pendingProgress, progress] : state.pendingProgress,
+		lastBoundaryRequestCount: state.requestCount,
+		completedBoundaryRequestCounts: [...state.completedBoundaryRequestCounts, interval],
+	};
+}
+
+export function recordCompaction(
+	state: OnlineState,
+	debt: { readonly debtTokens: number; readonly repaymentTokens: number },
+): OnlineState {
+	return {
+		...state,
+		epoch: state.epoch + 1,
+		plan: [],
+		pendingProgress: [],
+		lastContextTokens: null,
+		positiveContextDeltaTotal: 0,
+		positiveContextDeltaCount: 0,
+		nativeCompactionCount: state.nativeCompactionCount + 1,
+		cacheDebtTokens: Math.max(0, debt.debtTokens),
+		cacheDebtRepaymentTokens: Math.max(0, debt.repaymentTokens),
+	};
+}
+
+export function recordCorrection(state: OnlineState): OnlineState {
+	return {
+		...state,
+		epoch: state.epoch + 1,
+		plan: [],
+		pendingProgress: [],
+		lastBoundaryRequestCount: state.requestCount,
+		completedBoundaryRequestCounts: [],
+		lastContextTokens: null,
+		positiveContextDeltaTotal: 0,
+		positiveContextDeltaCount: 0,
+		cacheDebtTokens: 0,
+		cacheDebtRepaymentTokens: 0,
+	};
+}

package/src/sol-pi/extensions/online-context-compact/tools.ts

@@ -0,0 +1,100 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { renderSolPiTool } from "../../tui.ts";
+import { PLAN_STATUSES, type PlanStep } from "./plan.ts";
+
+export type PlanProgress = {
+	readonly files_changed: readonly string[];
+	readonly verification: readonly string[];
+	readonly decisions: readonly string[];
+};
+
+export type PlanUpdateInput = {
+	readonly toolCallId: string;
+	readonly steps: readonly PlanStep[];
+	readonly progress: PlanProgress | undefined;
+	readonly signal: AbortSignal | undefined;
+	readonly context: ExtensionContext;
+};
+
+export type OnlineToolHandlers = {
+	readonly updatePlan: (input: PlanUpdateInput) => Promise<AgentToolResult<Readonly<Record<string, unknown>>>>;
+};
+
+const progressSchema = Type.Object(
+	{
+		files_changed: Type.Array(Type.String({ maxLength: 1000 }), { maxItems: 128 }),
+		verification: Type.Array(Type.String({ maxLength: 1000 }), { maxItems: 64 }),
+		decisions: Type.Array(Type.String({ maxLength: 1000 }), { maxItems: 64 }),
+	},
+	{ additionalProperties: false },
+);
+
+const planStepSchema = Type.Object(
+	{
+		id: Type.String({ minLength: 1, maxLength: 16_384 }),
+		goal: Type.String({ minLength: 1, maxLength: 16_384 }),
+		status: Type.Union(PLAN_STATUSES.map((status) => Type.Literal(status))),
+	},
+	{ additionalProperties: false },
+);
+
+export function registerOnlineTools(pi: ExtensionAPI, handlers: OnlineToolHandlers): void {
+	pi.registerTool({
+		name: "update_plan",
+		label: "Update plan",
+		description:
+			"Replace the complete working plan. A newly completed step becomes a safe point where SoL-Pi may compact context if doing so is economical.",
+		promptSnippet: "Keep the working plan current",
+		promptGuidelines: [
+			"Send the complete plan on every update_plan call.",
+			"Keep at most one step in_progress and mark finished steps completed.",
+			"When completing a step, include concise progress evidence when available.",
+		],
+		renderShell: "self",
+		parameters: Type.Object(
+			{
+				steps: Type.Array(planStepSchema, { minItems: 1, maxItems: 128 }),
+				progress: Type.Optional(progressSchema),
+			},
+			{ additionalProperties: false },
+		),
+		executionMode: "sequential",
+		execute: async (toolCallId, params, signal, _onUpdate, context) =>
+			await handlers.updatePlan({
+				toolCallId,
+				steps: params.steps,
+				progress: params.progress,
+				signal,
+				context,
+			}),
+		renderCall(params, theme) {
+			const completed = params.steps.filter((step) => step.status === "completed").length;
+			return renderSolPiTool(
+				theme,
+				"Online Context Compact",
+				"compacts only when projected savings are positive",
+				new Text(theme.fg("dim", `Plan: ${params.steps.length} steps, ${completed} completed`), 0, 0),
+			);
+		},
+		renderResult(result, { isPartial }, theme) {
+			const boundary = (result.details as { boundary?: boolean } | undefined)?.boundary === true;
+			return renderSolPiTool(
+				theme,
+				"Online Context Compact",
+				"compacts only when projected savings are positive",
+				new Text(
+					theme.fg(isPartial ? "warning" : "dim", isPartial ? "Updating plan..." : boundary ? "Progress boundary recorded" : "Plan recorded"),
+					0,
+					0,
+				),
+			);
+		},
+	});
+}

package/src/sol-pi/index.ts

@@ -0,0 +1,42 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+import { getAgentDir, type ExtensionAPI, type ExtensionContext, type ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { loadSolPiConfig, type SolPiConfig } from "./config.ts";
+import { registerActionFusion } from "./extensions/action-fusion/index.ts";
+import { registerEvidencePreservingReducer } from "./extensions/evidence-preserving-reducer/index.ts";
+import { registerObservationPack } from "./extensions/observation-pack/index.ts";
+import { registerOnlineContextCompact } from "./extensions/online-context-compact/index.ts";
+
+export function registerConfiguredFeatures(pi: ExtensionAPI, config: SolPiConfig): void {
+	if (config.actionFusion) registerActionFusion(pi);
+	if (config.observationPack) registerObservationPack(pi);
+	if (config.evidencePreservingReducer) {
+		registerEvidencePreservingReducer(pi, {
+			reducerModel: config.evidencePreservingReducerModel,
+			reducerProvider: config.evidencePreservingReducerProvider,
+		});
+	}
+	if (config.onlineContextCompact) registerOnlineContextCompact(pi, config.cacheWriteReadRatio);
+}
+
+export type SolPiConfigLoader = (ctx: ExtensionContext) => SolPiConfig;
+
+export function createSolPiExtension(
+	loadConfig: SolPiConfigLoader = (ctx) => loadSolPiConfig(ctx.cwd, getAgentDir(), ctx.isProjectTrusted()),
+): ExtensionFactory {
+	return (pi) => {
+		let initialized = false;
+		pi.on("session_start", (_event, ctx) => {
+			if (initialized) return;
+			initialized = true;
+			registerConfiguredFeatures(pi, loadConfig(ctx));
+		});
+	};
+}
+
+export default function solPiExtension(pi: ExtensionAPI): void {
+	createSolPiExtension()(pi);
+}

package/src/sol-pi/runtime-paths.ts

@@ -0,0 +1,17 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+import { join } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export function runtimeRoot(ctx: ExtensionContext): string {
+	const sessionDir = ctx.sessionManager.getSessionDir();
+	if (!sessionDir) throw new Error("SoL-Pi requires a persistent Pi session directory");
+	const sessionId = ctx.sessionManager.getSessionId();
+	if (!/^[a-z0-9][a-z0-9._-]*$/iu.test(sessionId)) {
+		throw new Error("SoL-Pi requires a safe Pi session id");
+	}
+	return join(sessionDir, "sol-pi", sessionId);
+}

package/src/sol-pi/tui.ts

@@ -0,0 +1,71 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, Container, Text } from "@earendil-works/pi-tui";
+
+export type SolPiTuiMechanism =
+	| "Action Fusion"
+	| "Observation Pack"
+	| "Luna Delegating"
+	| "Online Context Compact";
+
+const STATUS_KEY = "sol-pi-savings";
+const STATUS_DURATION_MS = 4_000;
+const INTEGER_FORMAT = new Intl.NumberFormat("en-US", { maximumFractionDigits: 0 });
+const statusTimers = new WeakMap<ExtensionContext["ui"], ReturnType<typeof setTimeout>>();
+
+export function formatSavingsCount(value: number, unit: string): string {
+	const count = Number.isFinite(value) ? Math.max(0, Math.round(value)) : 0;
+	return `${INTEGER_FORMAT.format(count)} ${unit}`;
+}
+
+function compactDecimal(value: number): string {
+	return value.toFixed(1).replace(/\.0$/u, "");
+}
+
+export function formatSavingsBytes(value: number): string {
+	const bytes = Number.isFinite(value) ? Math.max(0, Math.round(value)) : 0;
+	if (bytes >= 1024 * 1024) {
+		return `${compactDecimal(bytes / (1024 * 1024))} MiB removed from future prompts`;
+	}
+	if (bytes >= 1024) return `${compactDecimal(bytes / 1024)} KiB removed from future prompts`;
+	return `${INTEGER_FORMAT.format(bytes)} B removed from future prompts`;
+}
+
+export function renderSolPiTool(
+	theme: Theme,
+	mechanism: SolPiTuiMechanism,
+	saving: string,
+	base?: Component,
+): Component {
+	const container = new Container();
+	const title = `${theme.fg("warning", "⚡")} ${theme.fg("accent", theme.bold(`SoL-Pi · ${mechanism}`))}`;
+	container.addChild(new Text(title, 0, 0));
+	container.addChild(new Text(theme.fg("success", `Money saved · ${saving}`), 0, 0));
+	if (base) container.addChild(base);
+	return container;
+}
+
+export function showSolPiSavings(
+	context: ExtensionContext,
+	mechanism: SolPiTuiMechanism,
+	saving: string,
+): void {
+	if (context.mode !== "tui") return;
+	const message = `⚡ SoL-Pi · ${mechanism}\nMoney saved · ${saving}`;
+	context.ui.notify(message, "info");
+	context.ui.setStatus(STATUS_KEY, `⚡ ${mechanism} · ${saving}`);
+
+	const previous = statusTimers.get(context.ui);
+	if (previous) clearTimeout(previous);
+	const timer = setTimeout(() => {
+		if (statusTimers.get(context.ui) !== timer) return;
+		statusTimers.delete(context.ui);
+		context.ui.setStatus(STATUS_KEY, undefined);
+	}, STATUS_DURATION_MS);
+	if (typeof timer === "object" && "unref" in timer) timer.unref();
+	statusTimers.set(context.ui, timer);
+}