opencode-clm 0.1.0

package/src/budget.ts

@@ -0,0 +1,304 @@
+/**
+ * Budget and reminder policy.
+ *
+ * Adapted from pi-clm src/budget.ts (MIT, Copyright 2026 Emanuel Casco).
+ * Default reminder steps (25/50/75 % of the budget) follow the CLM paper harness design;
+ * pi-clm uses 50/75/90. Text written for this package.
+ *
+ * Two measurements are kept apart and always labelled:
+ *
+ * - `estimated`: the harness estimate of the conversation in the *next* request (pinned
+ *   task + editable context + notices). Available before every call.
+ * - `observed`: the provider-reported input size of the *previous* request (OpenCode's
+ *   assistant `tokens`). Authoritative but one call late, and it includes the system
+ *   prompt and tool schemas, which the budget does not cover.
+ *
+ * The estimate alone governs reminder tiers and the reminder text; `observed` is shown
+ * for reference only, because it covers more than the budget does. The harness never
+ * blocks a request; the overflow guard (overflow.ts) withholds old tool output when the
+ * estimate exceeds budget - reserve.
+ */
+export interface BudgetPolicyConfig {
+	/**
+	 * Context budget in tokens the reminders are measured against. Advisory: requests are
+	 * never blocked or rolled back. `undefined` means "use the model context window".
+	 */
+	contextBudget?: number;
+	/** Generation headroom reserved below the budget. The final reminder fires at budget - reserve. */
+	reserve: number;
+	/** Fractions of the budget at which escalating reminders fire (0 < f < 1), ascending. */
+	remindAtFractions: readonly number[];
+	/** Whether to fire the final "budget - reserve" reminder. */
+	remindAtReserve: boolean;
+}
+
+export const DEFAULT_BUDGET_POLICY: BudgetPolicyConfig = {
+	contextBudget: 32000,
+	reserve: 2048,
+	remindAtFractions: [0.25, 0.5, 0.75],
+	remindAtReserve: true,
+};
+
+export interface BudgetReading {
+	/** Effective budget in tokens (config or model window). */
+	budget: number;
+	reserve: number;
+	/**
+	 * Harness estimate of the conversation in the next request, in tokens: pinned task,
+	 * editable context, and notices. Excludes the system prompt and tool schemas.
+	 */
+	estimated: number;
+	/** What the estimate knowingly leaves out, named in the notice so the gap is not misread. */
+	estimateExcludes?: string;
+	/** Calibration factor applied to the raw character estimate (1 = none). */
+	calibration?: number;
+	/**
+	 * Provider-reported tokens of the previous request, when known. Includes the system
+	 * prompt and tool schemas, so it is displayed but never governs reminders.
+	 */
+	observed?: number;
+	/**
+	 * True when a context edit was accepted after the observed request, so `observed`
+	 * describes a context that no longer exists. The notice says so.
+	 */
+	observedStale?: boolean;
+	/** Where `budget` came from, for status text. */
+	source: "config" | "model-window";
+}
+
+/** A reminder threshold in absolute tokens plus a stable label for re-arming. */
+export interface BudgetTier {
+	label: string;
+	tokens: number;
+}
+
+export function resolveBudgetPolicy(overrides: Partial<BudgetPolicyConfig> | undefined): BudgetPolicyConfig {
+	const merged: BudgetPolicyConfig = { ...DEFAULT_BUDGET_POLICY, ...(overrides ?? {}) };
+	if (merged.contextBudget !== undefined && (!Number.isFinite(merged.contextBudget) || merged.contextBudget <= 0)) {
+		throw new Error(`contextBudget must be a positive number of tokens, got ${String(merged.contextBudget)}`);
+	}
+	if (!Number.isFinite(merged.reserve) || merged.reserve < 0) {
+		throw new Error(`reserve must be a nonnegative number of tokens, got ${String(merged.reserve)}`);
+	}
+	const fractions = [...merged.remindAtFractions];
+	for (const fraction of fractions) {
+		if (!Number.isFinite(fraction) || fraction <= 0 || fraction >= 1) {
+			throw new Error(`remindAtFractions entries must be in (0, 1), got ${String(fraction)}`);
+		}
+	}
+	fractions.sort((left, right) => left - right);
+	return { ...merged, remindAtFractions: fractions };
+}
+
+/**
+ * Effective budget: the configured budget (default 32,000), capped by the model's context
+ * window minus its output allowance when that is smaller. `undefined` contextBudget means
+ * "use the window". An output limit that is not finite, <= 0, or >= the window is ignored.
+ */
+export function resolveBudget(
+	policy: BudgetPolicyConfig,
+	modelContextWindow: number | undefined,
+	modelOutputLimit = 0,
+): Pick<BudgetReading, "budget" | "reserve" | "source"> | undefined {
+	const window = modelContextWindow !== undefined && Number.isFinite(modelContextWindow) && modelContextWindow > 0
+		? modelContextWindow - (Number.isFinite(modelOutputLimit) && modelOutputLimit > 0 && modelOutputLimit < modelContextWindow ? modelOutputLimit : 0)
+		: undefined;
+	if (policy.contextBudget !== undefined && (window === undefined || policy.contextBudget <= window)) {
+		return { budget: policy.contextBudget, reserve: Math.min(policy.reserve, policy.contextBudget), source: "config" };
+	}
+	if (window !== undefined) {
+		return { budget: window, reserve: Math.min(policy.reserve, window), source: "model-window" };
+	}
+	return undefined;
+}
+
+export function budgetTiers(policy: BudgetPolicyConfig, budget: number, reserve: number): BudgetTier[] {
+	const tiers: BudgetTier[] = policy.remindAtFractions.map((fraction) => ({
+		label: `${Math.round(fraction * 100)}%`,
+		tokens: Math.floor(budget * fraction),
+	}));
+	if (policy.remindAtReserve && reserve > 0 && budget - reserve > 0) {
+		tiers.push({ label: "budget-reserve", tokens: budget - reserve });
+	}
+	tiers.sort((left, right) => left.tokens - right.tokens);
+	// Drop tiers that collapse onto the same token count; keep the more urgent label.
+	return tiers.filter((tier, index) => index === tiers.length - 1 || tier.tokens !== tiers[index + 1]!.tokens);
+}
+
+/**
+ * The value reminders are judged against: the estimate alone. The provider count also
+ * covers the system prompt and tool schemas, which the budget excludes.
+ */
+export function governingTokens(reading: Pick<BudgetReading, "estimated">): number {
+	return reading.estimated;
+}
+
+/**
+ * Escalating, re-arming tier tracker over absolute token thresholds. Re-derives its state
+ * when the tier set changes (for example after the budget changes).
+ */
+export class BudgetTracker {
+	private fired = new Set<string>();
+	private tierKey = "";
+
+	reset(): void {
+		this.fired.clear();
+	}
+
+	/** Returns the highest newly crossed tier, or undefined when nothing new fired. */
+	observe(reading: BudgetReading, tiers: readonly BudgetTier[]): BudgetTier | undefined {
+		const key = tiers.map((tier) => `${tier.label}:${tier.tokens}`).join("|");
+		if (key !== this.tierKey) {
+			this.tierKey = key;
+			this.fired.clear();
+		}
+		const tokens = governingTokens(reading);
+		this.fired = new Set([...this.fired].filter((label) => {
+			const tier = tiers.find((candidate) => candidate.label === label);
+			return tier !== undefined && tokens >= tier.tokens;
+		}));
+		const crossed = tiers.filter((tier) => tokens >= tier.tokens && !this.fired.has(tier.label));
+		if (crossed.length === 0) return undefined;
+		const top = crossed[crossed.length - 1]!;
+		for (const tier of tiers) if (tier.tokens <= top.tokens) this.fired.add(tier.label);
+		return top;
+	}
+}
+
+/** `12345` -> `12,345`. */
+export function formatTokens(value: number): string {
+	return value.toLocaleString("en-US");
+}
+
+function calibrated(reading: Pick<BudgetReading, "calibration">): boolean {
+	return reading.calibration !== undefined && reading.calibration > 1.005;
+}
+
+/** One line for status text: budget, estimate, and observation, each labelled. */
+export function budgetSummaryLine(reading: BudgetReading): string {
+	const parts = [
+		`budget ${formatTokens(reading.budget)} tok (${reading.source === "config" ? "configured" : "model window"}, reserve ${formatTokens(reading.reserve)})`,
+		`estimated next request ${formatTokens(reading.estimated)}${calibrated(reading) ? ` (×${reading.calibration!.toFixed(2)} calibrated)` : ""}`,
+	];
+	parts.push(
+		reading.observed === undefined
+			? "observed previous request: unknown"
+			: `observed previous request ${formatTokens(reading.observed)}${reading.observedStale ? " (before the last accepted edit)" : ""}`,
+	);
+	return parts.join(" · ");
+}
+
+/**
+ * The model-facing reminder. States the estimate and the provider count separately, the
+ * budget and the tokens left, the mirror path, and, from the third tier up, what the
+ * overflow guard does above `overflowLimit` (default budget - reserve). Pass `null` when the
+ * guard is off: the notice then leaves the guard out.
+ */
+export function budgetNoticeText(
+	reading: BudgetReading,
+	tier: BudgetTier,
+	mirrorPath: string | undefined,
+	overflowLimit: number | null = reading.budget - reading.reserve,
+): string {
+	const governing = governingTokens(reading);
+	const remaining = Math.max(0, reading.budget - governing);
+	const where = mirrorPath ?? "the context mirror";
+	const calibration = calibrated(reading) ? ` (calibrated ×${reading.calibration!.toFixed(2)} from provider counts)` : "";
+	const excludes = `${calibration}${reading.estimateExcludes ? `, excluding ${reading.estimateExcludes}` : ""}`;
+	const measurement =
+		reading.observed === undefined
+			? `estimated ${formatTokens(reading.estimated)} tokens for the next request${excludes}; provider-reported size of the previous request unknown`
+			: `estimated ${formatTokens(reading.estimated)} tokens for the next request${excludes}; the provider reported ${formatTokens(reading.observed)} for the previous one, system prompt and tool schemas included${reading.observedStale ? ", before your last accepted edit" : ""}`;
+	const overflow = overflowLimit === null
+		? ""
+		: ` Above ${formatTokens(overflowLimit)} tokens the overflow guard holds back the oldest new tool results and saves them to files.`;
+	if (tier.label === "budget-reserve") {
+		return (
+			`[CLM BUDGET] Context is at ${formatTokens(governing)} of a ${formatTokens(reading.budget)}-token budget ` +
+			`(${measurement}). Only ${formatTokens(remaining)} tokens remain, which is inside the ${formatTokens(reading.reserve)}-token generation reserve. ` +
+			`Edit ${where} now to free space.${overflow}`
+		);
+	}
+	const base =
+		`[CLM BUDGET] Context crossed ${tier.label} of a ${formatTokens(reading.budget)}-token budget: ${measurement}. ` +
+		`${formatTokens(remaining)} tokens remain. You may reorganize ${where} at any time; the final reminder comes at ${formatTokens(reading.budget - reading.reserve)} tokens.`;
+	const fraction = tier.tokens / reading.budget;
+	if (fraction <= 0.25) return base;
+	if (fraction <= 0.5) return `${base} Summaries should keep what you would otherwise have to look up again.`;
+	return `${base}${overflow}`;
+}
+
+/**
+ * Runtime calibration of the character-based estimator against the provider's own counts.
+ *
+ * chars/4 undercounts many inputs (random strings, code, non-English text tokenize at
+ * 2-3 chars per token). Each request carries an estimate; when the provider reports the
+ * actual size of that request, the ratio updates a factor that scales future estimates.
+ * The factor never drops below 1 (only undercounting is corrected) and is capped so one
+ * odd sample cannot run away.
+ */
+export class EstimateCalibrator {
+	private pending: { estimate: number; rawCount: number } | undefined;
+	private current = 1;
+	private samples = 0;
+
+	constructor(private readonly options: { min?: number; max?: number; smoothing?: number; initial?: number } = {}) {
+		const smoothing = options.smoothing;
+		if (smoothing !== undefined && (!Number.isFinite(smoothing) || smoothing <= 0 || smoothing > 1)) {
+			throw new Error(`smoothing must be in (0, 1], got ${String(smoothing)}`);
+		}
+		this.current = this.initialFactor();
+	}
+
+	get factor(): number {
+		return this.current;
+	}
+
+	get sampleCount(): number {
+		return this.samples;
+	}
+
+	reset(): void {
+		this.pending = undefined;
+		this.current = this.initialFactor();
+		this.samples = 0;
+	}
+
+	/**
+	 * Remember the raw (uncalibrated) estimate of the request about to be sent. The estimate
+	 * must cover the same scope as the provider count it will be compared with; an estimate
+	 * that omits the system prompt and tool schemas reads their size as undercounting.
+	 */
+	record(estimate: number, rawCount: number): void {
+		if (estimate > 0) this.pending = { estimate, rawCount };
+	}
+
+	/**
+	 * Feed the newest provider-reported request size. `index` is the position of the
+	 * reporting assistant message in the raw transcript; only a message appended after the
+	 * recorded request counts as its measurement.
+	 */
+	observe(observed: { tokens: number; index: number } | undefined): number {
+		if (!observed || !this.pending || observed.index < this.pending.rawCount) return this.current;
+		const sample = observed.tokens / this.pending.estimate;
+		this.pending = undefined;
+		if (!Number.isFinite(sample) || sample <= 0) return this.current;
+		const smoothing = this.options.smoothing ?? 0.5;
+		const next = this.samples === 0 ? sample : this.current * (1 - smoothing) + sample * smoothing;
+		this.current = this.clamp(next);
+		this.samples += 1;
+		return this.current;
+	}
+
+	apply(estimate: number): number {
+		return Math.ceil(estimate * this.current);
+	}
+
+	private clamp(value: number): number {
+		return Math.min(this.options.max ?? 4, Math.max(this.options.min ?? 1, value));
+	}
+
+	private initialFactor(): number {
+		return this.clamp(this.options.initial ?? 1);
+	}
+}