@oh-my-pi/pi-coding-agent 16.1.3 → 16.1.5

package/src/modes/components/cache-invalidation-marker.ts

@@ -4,9 +4,9 @@ import { formatNumber } from "@oh-my-pi/pi-utils";
 import { theme } from "../../modes/theme/theme";
 
 /**
- * Minimum cached prefix (read + write) the previous turn must have established
- * before a collapse on the current turn counts as an invalidation. Filters out
- * tiny contexts and providers below the cacheable-prefix floor, where a zero
+ * Minimum prefix the previous turn must have READ back from cache before a
+ * collapse on the current turn counts as an invalidation. Filters out tiny
+ * contexts and providers below the cacheable-prefix floor, where a zero
  * `cacheRead` is expected rather than a reset.
  */
 const MIN_CACHE_FOOTPRINT = 2048;
@@ -18,25 +18,41 @@ export interface CacheInvalidation {
 }
 
 /**
- * Decide whether `current` turn lost the prompt cache that `prev` established.
+ * Decide whether `current` turn lost a *working* prompt cache that `prev` was
+ * reusing.
  *
  * The provider reports a warm prefix as `cacheRead`; a model/thinking/tool/
  * system-prompt change (or a history rewrite) breaks the prefix, so the next
- * request reads nothing from cache and re-pays for the whole prompt. We detect
- * that as: the previous turn cached a meaningful prefix, yet this turn's
+ * request reads nothing from cache and re-pays for the whole prompt. We flag
+ * only the transition where a demonstrably warm cache goes cold: the previous
+ * turn must have actually READ a meaningful prefix back, and this turn's
  * `cacheRead` collapsed to zero while it still reprocessed a non-trivial prompt.
- * Returns `undefined` (no marker) for the first turn, tiny contexts, turns
- * that reused any cache, and — crucially — turns on providers with *implicit*
- * best-effort caching. Only an explicit, prefix-controlled cache (Anthropic /
- * Bedrock `cache_control`) re-creates the prefix on a cold turn (`cacheWrite >
- * 0`); implicit caches (Google / OpenAI / Fireworks) report `cacheWrite: 0` and
- * drop `cacheRead` to zero intermittently as routine propagation noise that
- * self-heals the next turn, so flagging it would be a false positive.
+ *
+ * Requiring a prior warm read is deliberate. A turn that merely WROTE the prefix
+ * (`cacheRead` 0) has not proven the cache is live — that is the session's first
+ * request, or a re-write after expiry — so a following cold turn there is
+ * expected, not an invalidation the user caused (e.g. a long-running first tool
+ * call outliving the provider's 5-minute cache TTL surfaced a spurious "cache
+ * miss" right under the opening message). It also collapses a run of consecutive
+ * cold turns to the single marker at the moment the cache actually broke, instead
+ * of repeating the banner on every turn while it re-warms.
+ *
+ * Returns `undefined` (no marker) for the first turn, turns whose predecessor
+ * never read a warm prefix, tiny contexts, turns that reused any cache, and —
+ * crucially — turns on providers with *implicit* best-effort caching. Only an
+ * explicit, prefix-controlled cache (Anthropic / Bedrock `cache_control`)
+ * re-creates the prefix on a cold turn (`cacheWrite > 0`); implicit caches
+ * (Google / OpenAI / Fireworks) report `cacheWrite: 0` and drop `cacheRead` to
+ * zero intermittently as routine propagation noise that self-heals the next
+ * turn, so flagging it would be a false positive.
  */
 export function detectCacheInvalidation(prev: Usage | undefined, current: Usage): CacheInvalidation | undefined {
 	if (!prev) return undefined;
-	const prevFootprint = prev.cacheRead + prev.cacheWrite;
-	if (prevFootprint < MIN_CACHE_FOOTPRINT) return undefined;
+	// Only flag a warm→cold transition: the previous turn must have actually read
+	// a meaningful prefix from cache. A write-only predecessor (first request, or
+	// a re-write after expiry) has not proven the cache is live, so a cold turn
+	// behind it is expected — not an invalidation worth surfacing.
+	if (prev.cacheRead < MIN_CACHE_FOOTPRINT) return undefined;
 	// Any cache reuse this turn means the prefix survived (at least partly).
 	if (current.cacheRead > 0) return undefined;
 	// Only an explicit, prefix-controlled cache re-creates the prefix on a cold

package/src/modes/components/custom-editor.test.ts

@@ -39,11 +39,12 @@ function feedGaps(editor: CustomEditor, gaps: number[]): void {
 	}
 }
 
-async function decorateInFreshProcess(text: string): Promise<string> {
+async function decorateInFreshProcess(text: string, imageLinks?: readonly string[]): Promise<string> {
 	const customEditorUrl = new URL("./custom-editor.ts", import.meta.url).href;
 	const script = `
 import { CustomEditor } from ${JSON.stringify(customEditorUrl)};
 const editor = new CustomEditor({});
+editor.imageLinks = ${JSON.stringify(imageLinks)};
 process.stdout.write(editor.decorateText(${JSON.stringify(text)}));
 `;
 	const child = await $`bun -e ${script}`.quiet().nothrow();
@@ -59,8 +60,8 @@ describe("CustomEditor placeholder decoration", () => {
 		expect(output).toBe("[Paste #1, +30 lines]");
 	});
 
-	it("renders image placeholders before theme initialization", async () => {
-		const output = await decorateInFreshProcess("[Image #1]");
+	it("renders linked image placeholders before theme and settings initialization", async () => {
+		const output = await decorateInFreshProcess("[Image #1]", ["/tmp/example.png"]);
 		expect(output).toBe("[Image #1]");
 	});
 });

package/src/modes/components/status-line/component.ts

@@ -154,6 +154,8 @@ interface ContextUsageMemo {
 }
 
 const EMPTY_MESSAGES: readonly AgentMessage[] = [];
+const STATUS_USAGE_START_DELAY_MS = 0;
+const STATUS_USAGE_REFRESH_TIMEOUT_MS = 2_000;
 
 function hasContextSegment(segments: readonly StatusLineSegmentId[]): boolean {
 	return segments.includes("context_pct") || segments.includes("context_total");
@@ -212,6 +214,7 @@ export class StatusLineComponent implements Component {
 	} | null = null;
 	#usageFetchedAt = 0;
 	#usageInFlight = false;
+	#usageStartTimer: Timer | null = null;
 	// Context-usage memo. The status line redraws on every agent event, so the
 	// hot path must not recompute context tokens unless an input changed.
 	// `getContextUsage()` anchors on the last assistant's real prompt-token
@@ -344,16 +347,24 @@ export class StatusLineComponent implements Component {
 	dispose(): void {
 		this.#disposed = true;
 		this.#onBranchChange = null;
+		this.#clearUsageStartTimer();
 		if (this.#gitWatcher) {
 			this.#gitWatcher.close();
 			this.#gitWatcher = null;
 		}
 	}
 
+	#clearUsageStartTimer(): void {
+		if (!this.#usageStartTimer) return;
+		clearTimeout(this.#usageStartTimer);
+		this.#usageStartTimer = null;
+	}
+
 	invalidate(): void {
 		this.#invalidateGitCaches();
 	}
 	#invalidateSessionCaches(): void {
+		this.#clearUsageStartTimer();
 		this.#cachedUsage = null;
 		this.#usageFetchedAt = 0;
 		this.#usageInFlight = false;
@@ -521,38 +532,73 @@ export class StatusLineComponent implements Component {
 	}
 
 	/**
-	 * Background-refresh the Anthropic OAuth quota report. Guarded by a 5-min
-	 * TTL on both success (cache lifetime) and error (backoff). Exposed
-	 * (non-private) so unit tests can verify the backoff invariant.
+	 * Startup redraws only arm a short-delayed task; timeout releases the render
+	 * cadence while a late successful fetch can still refresh the cached segment.
 	 */
 	refreshUsageInBackground(): void {
 		const now = Date.now();
-		if (this.#usageInFlight) return;
+		if (this.#usageInFlight || this.#usageStartTimer) return;
 		if (this.#usageFetchedAt > 0 && now - this.#usageFetchedAt < 5 * 60_000) return;
 		const session = this.session;
-		const fetcher = (session as { fetchUsageReports?: () => Promise<unknown> }).fetchUsageReports;
+		const fetcher = (session as { fetchUsageReports?: (signal?: AbortSignal) => Promise<unknown> }).fetchUsageReports;
 		if (typeof fetcher !== "function") return;
 		this.#usageInFlight = true;
-		void fetcher
-			.call(session)
+		this.#usageStartTimer = setTimeout(() => {
+			this.#usageStartTimer = null;
+			void this.#runUsageRefresh(session, fetcher);
+		}, STATUS_USAGE_START_DELAY_MS);
+	}
+
+	async #runUsageRefresh(session: AgentSession, fetcher: (signal?: AbortSignal) => Promise<unknown>): Promise<void> {
+		if (this.#disposed || this.session !== session) {
+			this.#usageInFlight = false;
+			return;
+		}
+		const signal = AbortSignal.timeout(STATUS_USAGE_REFRESH_TIMEOUT_MS);
+		let reportsPromise: Promise<unknown> | undefined;
+		try {
+			reportsPromise = fetcher.call(session, signal);
+			this.#applyUsageRefreshReports(session, await this.#raceUsageRefreshWithSignal(reportsPromise, signal));
+		} catch {
+			if (this.session !== session) return;
+			this.#usageFetchedAt = Date.now();
+			if (signal.aborted && reportsPromise) {
+				this.#observeLateUsageRefresh(session, reportsPromise);
+			}
+		} finally {
+			if (this.session === session) this.#usageInFlight = false;
+		}
+	}
+
+	#applyUsageRefreshReports(session: AgentSession, reports: unknown): void {
+		if (this.#disposed || this.session !== session) return;
+		this.#cachedUsage = this.#normalizeUsageReports(reports);
+		this.#usageFetchedAt = Date.now();
+	}
+
+	#observeLateUsageRefresh(session: AgentSession, reportsPromise: Promise<unknown>): void {
+		void reportsPromise
 			.then(reports => {
-				if (this.session !== session) return;
-				this.#cachedUsage = this.#normalizeUsageReports(reports);
-				this.#usageFetchedAt = Date.now();
+				this.#applyUsageRefreshReports(session, reports);
 			})
 			.catch(() => {
-				if (this.session !== session) return;
-				// Backoff on error: stamp the fetch time so the 5-min TTL guard
-				// also acts as an error budget. Without this, every render
-				// kicks off another fetch (gated only by #usageInFlight),
-				// which hammers the endpoint during a network outage / 5xx.
+				if (this.#disposed || this.session !== session) return;
 				this.#usageFetchedAt = Date.now();
-			})
-			.finally(() => {
-				if (this.session === session) this.#usageInFlight = false;
 			});
 	}
 
+	async #raceUsageRefreshWithSignal(promise: Promise<unknown>, signal: AbortSignal): Promise<unknown> {
+		if (signal.aborted) throw signal.reason;
+		const aborted = Promise.withResolvers<never>();
+		const onAbort = () => aborted.reject(signal.reason);
+		signal.addEventListener("abort", onAbort, { once: true });
+		try {
+			return await Promise.race([promise, aborted.promise]);
+		} finally {
+			signal.removeEventListener("abort", onAbort);
+		}
+	}
+
 	#normalizeUsageReports(reports: unknown): {
 		fiveHour?: { percent: number; resetMinutes?: number };
 		sevenDay?: { percent: number; resetHours?: number };

package/src/sdk.ts

@@ -687,6 +687,37 @@ export async function loadSessionExtensions(
 	return result;
 }
 
+/**
+ * Load discovered/configured extensions and register their providers into
+ * `modelRegistry`, then discover the dynamic provider catalogs. One-shot CLIs
+ * (`omp bench`, dry-balance) build a bare {@link ModelRegistry} that only knows
+ * built-in catalog providers; without this, providers contributed by an
+ * extension (e.g. a custom OpenAI-compatible provider under
+ * `~/.omp/agent/extensions/`) never reach model resolution. Mirrors the
+ * session / `omp models` path: drain the queued provider registrations, then
+ * `refreshRuntimeProviders` so dynamically-discovered models exist before
+ * selectors are resolved.
+ */
+export async function loadCliExtensionProviders(
+	modelRegistry: ModelRegistry,
+	settings: Settings,
+	cwd: string,
+	options: Pick<CreateAgentSessionOptions, "disableExtensionDiscovery" | "additionalExtensionPaths"> = {},
+): Promise<void> {
+	const eventBus = new EventBus();
+	const extensionsResult = await loadSessionExtensions(options, cwd, settings, eventBus);
+	const activeSources = extensionsResult.extensions.map(extension => extension.path);
+	modelRegistry.syncExtensionSources(activeSources);
+	for (const sourceId of new Set(activeSources)) {
+		modelRegistry.clearSourceRegistrations(sourceId);
+	}
+	for (const { name, config, sourceId } of extensionsResult.runtime.pendingProviderRegistrations) {
+		modelRegistry.registerProvider(name, config, sourceId);
+	}
+	extensionsResult.runtime.pendingProviderRegistrations = [];
+	await modelRegistry.refreshRuntimeProviders();
+}
+
 /**
  * Discover skills from cwd and agentDir.
  */
@@ -1518,6 +1549,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					timestamp: Date.now(),
 				}),
 			peekQueueInvoker: () => session.peekQueueInvoker(),
+			peekPendingInvoker: () => session.peekPendingInvoker(),
+			clearPendingInvokers: () => session.clearPendingInvokers(),
 			peekStandingResolveHandler: () => session.peekStandingResolveHandler(),
 			setStandingResolveHandler: handler => session.setStandingResolveHandler(handler),
 			allocateOutputArtifact: async toolType => {

package/src/session/agent-session.ts

@@ -2141,8 +2141,9 @@ export class AgentSession {
 		return this.#agentId;
 	}
 
-	/** Advance the tool-choice queue and return the next directive for the upcoming LLM call. */
-	nextToolChoice(): ToolChoice | undefined {
+	/** Dequeue the next HARD forced tool choice for the upcoming LLM call, dropping
+	 *  (and rejecting) one whose named tool is no longer active. */
+	#nextHardToolChoice(): ToolChoice | undefined {
 		const choice = this.#toolChoiceQueue.nextToolChoice();
 		if (isToolChoiceActive(choice, this.agent.state.tools)) {
 			return choice;
@@ -2154,7 +2155,7 @@ export class AgentSession {
 	/**
 	 * The per-turn tool-choice directive for the agent loop's `getToolChoice`. Priority:
 	 *   1. a HARD forced choice from the queue (genuine forces: user-force, eager-todo, …) —
-	 *      consuming, unchanged from `nextToolChoice`;
+	 *      consuming (advances the queue generator);
 	 *   2. else, when a non-forcing preview is pending, a {@link SoftToolRequirement} — a
 	 *      PEEK (advances/pops nothing), so the agent-loop injects the reminder once per head
 	 *      and escalates to a forced `resolve` only if the model declines. A compliant turn
@@ -2162,7 +2163,7 @@ export class AgentSession {
 	 *   3. else undefined.
 	 */
 	nextToolChoiceDirective(): ToolChoiceDirective | undefined {
-		const hard = this.nextToolChoice();
+		const hard = this.#nextHardToolChoice();
 		if (hard !== undefined) return hard;
 		const head = this.#toolChoiceQueue.peekPendingHead();
 		if (head !== undefined) {
@@ -2181,6 +2182,11 @@ export class AgentSession {
 		return this.#toolChoiceQueue.peekPendingInvoker();
 	}
 
+	/** Clear stale non-forcing pending preview invokers after `resolve` proves none can run. */
+	clearPendingInvokers(): void {
+		this.#toolChoiceQueue.clearPendingInvokers();
+	}
+
 	/**
 	 * Force the next model call to target a specific active tool, then terminate
 	 * the agent loop. Pushes a two-step sequence [forced, "none"] so the model

package/src/session/tool-choice-queue.ts

@@ -231,6 +231,12 @@ export class ToolChoiceQueue {
 		this.#pendingInvokers = this.#pendingInvokers.filter(p => p.id !== id);
 	}
 
+	/** Drop every pending preview invoker without touching hard tool-choice directives. */
+	clearPendingInvokers(): void {
+		if (this.#pendingInvokers.length === 0) return;
+		this.#pendingInvokers = [];
+	}
+
 	/** True when at least one non-forcing pending preview is registered. */
 	get hasPendingInvoker(): boolean {
 		return this.#pendingInvokers.length > 0;

package/src/tools/index.ts

@@ -316,6 +316,8 @@ export interface ToolSession {
 	 *  tool dispatches to it so a staged preview resolves WITHOUT forcing tool_choice — the
 	 *  agent-loop's SoftToolRequirement lifecycle owns reminder injection and escalation. */
 	peekPendingInvoker?(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
+	/** Clear stale pending preview markers when `resolve` cannot dispatch them. */
+	clearPendingInvokers?(): void;
 	/** Peek the long-lived "standing" resolve handler registered by a mode (e.g. plan mode).
 	 *  Consulted by the `resolve` tool as a fallback when no queue invoker is in flight,
 	 *  letting modes accept `resolve` invocations without forcing the tool choice every turn. */

package/src/tools/resolve.ts

@@ -212,6 +212,7 @@ export class ResolveTool implements AgentTool<typeof resolveSchema, ResolveToolD
 				this.session.peekPendingInvoker?.() ??
 				this.session.peekStandingResolveHandler?.();
 			if (!invoker) {
+				this.session.clearPendingInvokers?.();
 				// `discard` is a request to cancel/abort a staged action. When nothing is
 				// pending, the desired end-state (no staged change) already holds, so honor
 				// it as a successful cancellation instead of surfacing a hard error to the

package/src/tui/hyperlink.ts

@@ -7,7 +7,7 @@
  */
 import * as url from "node:url";
 import { TERMINAL } from "@oh-my-pi/pi-tui";
-import { settings } from "../config/settings";
+import { isSettingsInitialized, settings } from "../config/settings";
 import {
 	LocalProtocolHandler,
 	memoryRootsFromRegistry,
@@ -45,8 +45,10 @@ function buildFileUri(filePath: string, opts?: { line?: number; col?: number }):
  * - `"off"`: never
  * - `"auto"`: when `process.stdout.isTTY`, `NO_COLOR` is unset, and the detected terminal reports hyperlink support
  * - `"always"`: unconditionally (useful for viewers that support OSC 8 without advertising it)
+ * Before settings initialization, returns false so early render paths stay plain text.
  */
 export function isHyperlinkEnabled(): boolean {
+	if (!isSettingsInitialized()) return false;
 	const mode = settings.get("tui.hyperlinks");
 	if (mode === "off") return false;
 	if (mode === "always") return true;
@@ -104,10 +106,11 @@ export function urlHyperlink(url: string, displayText: string): string {
  * Wrap `displayText` in an OSC 8 hyperlink pointing at an HTTP(S) URL,
  * bypassing terminal capability auto-detection. Used for auth prompts where
  * an inert "click" label blocks login on terminals whose capabilities are
- * not advertised. Still returns plain text when the user has explicitly
- * opted out via `tui.hyperlinks=off`.
+ * not advertised. Still returns plain text before settings initialization or
+ * when the user has explicitly opted out via `tui.hyperlinks=off`.
  */
 export function urlHyperlinkAlways(url: string, displayText: string): string {
+	if (!isSettingsInitialized()) return displayText;
 	if (settings.get("tui.hyperlinks") === "off") return displayText;
 	const normalized = url.match(/^www\./i) ? `https://${url}` : url;
 	try {