Function maybeFireHistorian

packages/pi-plugin/src/context-handler.ts:2980–3279

* Trigger evaluation + fire-and-forget historian invocation. Runs * after the synchronous tagging pass so trigger logic sees the * just-assigned tags. * * The actual historian subagent spawn (`runPiHistorian`) is async * and intentionally NOT awaited — the LLM call should never wait on * histo

(args: {
	ctx: ExtensionContext;
	sessionId: string;
	db: ContextDatabase;
	historian: PiHistorianOptions;
	isFirstContextPassForSession?: boolean;
	activeTags?: ReturnType<typeof getActiveTagsBySession>;
	rawMessageProvider?: {
		readMessages: () => ReturnType<typeof readPiSessionMessages>;
	};
})

 * agent turn continues regardless of historian outcome.
 */
function maybeFireHistorian(args: {
	ctx: ExtensionContext;
	sessionId: string;
	db: ContextDatabase;
	historian: PiHistorianOptions;
	isFirstContextPassForSession?: boolean;
	activeTags?: ReturnType<typeof getActiveTagsBySession>;
	rawMessageProvider?: {
		readMessages: () => ReturnType<typeof readPiSessionMessages>;
	};
}): void {
	const { ctx, sessionId, db, historian, isFirstContextPassForSession } = args;

	if (inFlightHistorian.has(sessionId)) {
		sessionLog(sessionId, "historian trigger eval: in-flight, skipping");
		return;
	}

	// Prefer OpenCode-equivalent pressure persisted by message_end.
	// Pi's built-in `ctx.getContextUsage()` reports total-tokens
	// percent (input + output + cache), but historian/trigger math
	// expects wire-input pressure (input + cacheRead + cacheWrite).
	// `session_meta.lastContextPercentage` carries the corrected value
	// computed by `pi-pressure.ts` against the effective context
	// limit (with detected_context_limit override applied).
	let usage: { percentage: number; inputTokens: number };
	let usageContextLimit: number | undefined;
	try {
		const piUsage = ctx.getContextUsage?.();
		let usageSource: "session_meta" | "piUsage fallback";
		// Sane-bound (isSaneLimit, NOT `> 0`) so a garbage-but-positive window
		// can't drive the trigger budget — mirrors the main pressure pass.
		usageContextLimit = isSaneLimit(piUsage?.contextWindow)
			? piUsage.contextWindow
			: undefined;
		// Cold-start: fall back to the model's window when usage hasn't reported
		// a sane one yet (first pass after restart).
		if (
			usageContextLimit === undefined &&
			isSaneLimit(ctx.model?.contextWindow)
		) {
			usageContextLimit = ctx.model.contextWindow;
		}
		// Apply the detected-overflow cap (authoritative real limit) just like the
		// main pass — otherwise the trigger budget uses the wrong (larger) limit.
		try {
			const overflowState = getOverflowState(db, sessionId);
			if (overflowState.detectedContextLimit > 0) {
				usageContextLimit = Math.min(
					usageContextLimit ?? overflowState.detectedContextLimit,
					overflowState.detectedContextLimit,
				);
			}
		} catch {
			// Best-effort — fall through with the uncorrected limit.
		}
		const sessionMetaForUsage = getOrCreateSessionMeta(db, sessionId);
		if (