@oh-my-pi/pi-coding-agent 15.8.3 → 15.9.1

package/dist/types/utils/session-color.d.ts

@@ -1,8 +1,13 @@
 /**
  * Derive a stable CSS hex accent color from a session name.
- * High saturation, vivid — suitable for both status bar text and border coloring.
+ *
+ * On dark themes (`surfaceLuminance` undefined) the accent is vivid (high
+ * saturation, high lightness). On light themes the lightness is reduced until the
+ * accent's perceived luminance clears {@link ACCENT_MIN_CONTRAST} against the
+ * actual surface it renders on — so it stays legible on near-white *and* mid-light
+ * backgrounds — while keeping the same per-session hue.
  */
-export declare function getSessionAccentHex(name: string): string;
+export declare function getSessionAccentHex(name: string, surfaceLuminance?: number): string;
 /**
  * Convert a hex accent color to an ANSI-16m foreground escape sequence.
  * Returns `undefined` if `hex` is nullish or Bun.color conversion fails.

package/dist/types/web/search/index.d.ts

@@ -50,7 +50,7 @@ export declare function runSearchQuery(params: SearchQueryParams, options?: {
 /**
  * Web search tool implementation.
  *
- * Supports Anthropic, Perplexity, Exa, Brave, Jina, Kimi, Gemini, Codex, Z.AI, SearXNG, and Synthetic providers with automatic fallback.
+ * Supports the configured web-search provider chain with automatic fallback.
  */
 export declare class WebSearchTool implements AgentTool<typeof webSearchSchema, SearchRenderDetails> {
     #private;

package/dist/types/web/search/provider.d.ts

@@ -1,8 +1,9 @@
 import type { AuthStorage } from "@oh-my-pi/pi-ai";
 import type { SearchProvider } from "./providers/base";
-import type { SearchProviderId } from "./types";
+import { type SearchProviderId } from "./types";
 export type { SearchParams } from "./providers/base";
 export { SearchProvider } from "./providers/base";
+export { SEARCH_PROVIDER_ORDER } from "./types";
 /** Cheap, sync metadata accessor — never triggers a provider load. */
 export declare function getSearchProviderLabel(id: SearchProviderId): string;
 /**
@@ -10,7 +11,6 @@ export declare function getSearchProviderLabel(id: SearchProviderId): string;
  * underlying module; subsequent calls return the cached singleton.
  */
 export declare function getSearchProvider(id: SearchProviderId): Promise<SearchProvider>;
-export declare const SEARCH_PROVIDER_ORDER: SearchProviderId[];
 /** Set the preferred web search provider from settings */
 export declare function setPreferredSearchProvider(provider: SearchProviderId | "auto"): void;
 /**

package/dist/types/web/search/providers/base.d.ts

@@ -58,8 +58,22 @@ export declare abstract class SearchProvider {
      * Indicates whether this provider has the credentials/config it needs to
      * service a request right now. Implementations consult the passed
      * {@link AuthStorage} — never a sibling store.
+     *
+     * Drives auto-chain admission: providers that return `false` are skipped
+     * when {@link resolveProviderChain} walks the order. Explicit selection
+     * uses {@link isExplicitlyAvailable} instead.
      */
     abstract isAvailable(authStorage: AuthStorage): Promise<boolean> | boolean;
+    /**
+     * Returns `true` when this provider should run when the user explicitly
+     * selects it, even if {@link isAvailable} would reject it for the auto
+     * chain. Providers that ship an unauthenticated fallback (e.g. Exa's
+     * public MCP) override this so explicit selection still routes through
+     * the fallback rather than silently falling back to another provider.
+     *
+     * Defaults to mirroring {@link isAvailable}.
+     */
+    isExplicitlyAvailable(authStorage: AuthStorage): Promise<boolean> | boolean;
     /**
      * Execute a search. Credentials MUST be resolved through `params.authStorage`.
      */

package/dist/types/web/search/providers/exa.d.ts

@@ -50,9 +50,18 @@ export declare function buildExaRequestBody(params: ExaSearchParams): Record<str
 export declare function searchExa(params: ExaSearchParams): Promise<SearchResponse>;
 /** Search provider for Exa. */
 export declare class ExaProvider extends SearchProvider {
+    #private;
     readonly id = "exa";
     readonly label = "Exa";
     isAvailable(authStorage: AuthStorage): boolean;
+    /**
+     * Exa ships an unauthenticated public MCP fallback, so an explicit
+     * selection (programmatic or via `providers.webSearch: exa`) routes
+     * through MCP even when no credential is configured. The auto chain
+     * still uses {@link isAvailable} so an unrelated configured provider
+     * keeps priority over the public fallback.
+     */
+    isExplicitlyAvailable(_authStorage: AuthStorage): boolean;
     search(params: SearchParams): Promise<SearchResponse>;
 }
 export {};

package/dist/types/web/search/providers/perplexity.d.ts

@@ -16,11 +16,11 @@ export interface PerplexitySearchParams {
     system_prompt?: string;
     search_recency_filter?: "hour" | "day" | "week" | "month" | "year";
     num_results?: number;
-    /** Maximum output tokens. Defaults to 4096. */
+    /** Maximum output tokens. Defaults to 8192. */
     max_tokens?: number;
     /** Sampling temperature (0–1). Lower = more focused/factual. Defaults to 0.2. */
     temperature?: number;
-    /** Number of search results to retrieve. Defaults to 10. */
+    /** Number of search results to retrieve. Defaults to 20. */
     num_search_results?: number;
     authStorage: AuthStorage;
     sessionId?: string;

package/dist/types/web/search/types.d.ts

@@ -3,8 +3,72 @@
  *
  * Unified types for web search responses across supported providers.
  */
+export declare const SEARCH_PROVIDER_ORDER: readonly ["tavily", "perplexity", "brave", "jina", "kimi", "anthropic", "gemini", "codex", "zai", "exa", "parallel", "kagi", "synthetic", "searxng"];
 /** Supported web search providers */
-export type SearchProviderId = "exa" | "brave" | "jina" | "kimi" | "zai" | "anthropic" | "perplexity" | "gemini" | "codex" | "tavily" | "parallel" | "kagi" | "synthetic" | "searxng";
+export type SearchProviderId = (typeof SEARCH_PROVIDER_ORDER)[number];
+export declare const SEARCH_PROVIDER_PREFERENCES: readonly ["auto", "tavily", "perplexity", "brave", "jina", "kimi", "anthropic", "gemini", "codex", "zai", "exa", "parallel", "kagi", "synthetic", "searxng"];
+export declare const SEARCH_PROVIDER_OPTIONS: readonly [{
+    readonly value: "auto";
+    readonly label: "Auto";
+    readonly description: "Automatically uses the first configured web-search provider";
+}, {
+    readonly value: "tavily";
+    readonly label: "Tavily";
+    readonly description: "Requires TAVILY_API_KEY";
+}, {
+    readonly value: "perplexity";
+    readonly label: "Perplexity";
+    readonly description: "Requires PERPLEXITY_COOKIES or PERPLEXITY_API_KEY";
+}, {
+    readonly value: "brave";
+    readonly label: "Brave";
+    readonly description: "Requires BRAVE_API_KEY";
+}, {
+    readonly value: "jina";
+    readonly label: "Jina";
+    readonly description: "Requires JINA_API_KEY";
+}, {
+    readonly value: "kimi";
+    readonly label: "Kimi";
+    readonly description: "Requires MOONSHOT_SEARCH_API_KEY or MOONSHOT_API_KEY";
+}, {
+    readonly value: "anthropic";
+    readonly label: "Anthropic";
+    readonly description: "Claude's native web_search tool (uses Anthropic OAuth or ANTHROPIC_API_KEY)";
+}, {
+    readonly value: "gemini";
+    readonly label: "Gemini";
+    readonly description: "Google Search grounding via Gemini (uses google-gemini-cli or google-antigravity OAuth)";
+}, {
+    readonly value: "codex";
+    readonly label: "OpenAI";
+    readonly description: "OpenAI's native web_search (uses ChatGPT OAuth via /login openai-codex)";
+}, {
+    readonly value: "zai";
+    readonly label: "Z.AI";
+    readonly description: "Calls Z.AI webSearchPrime MCP";
+}, {
+    readonly value: "exa";
+    readonly label: "Exa";
+    readonly description: "Uses Exa API when EXA_API_KEY is set; falls back to Exa MCP";
+}, {
+    readonly value: "parallel";
+    readonly label: "Parallel";
+    readonly description: "Requires PARALLEL_API_KEY";
+}, {
+    readonly value: "kagi";
+    readonly label: "Kagi";
+    readonly description: "Requires KAGI_API_KEY and Kagi Search API beta access";
+}, {
+    readonly value: "synthetic";
+    readonly label: "Synthetic";
+    readonly description: "Requires SYNTHETIC_API_KEY";
+}, {
+    readonly value: "searxng";
+    readonly label: "SearXNG";
+    readonly description: "Requires SEARXNG_ENDPOINT or searxng.endpoint";
+}];
+export declare const SEARCH_PROVIDER_LABELS: Record<SearchProviderId, string>;
 export declare function isSearchProviderId(value: string): value is SearchProviderId;
 export declare function isSearchProviderPreference(value: string): value is SearchProviderId | "auto";
 /** Source returned by search (all providers) */
@@ -339,6 +403,7 @@ export interface PerplexityResponse {
     choices: PerplexityChoice[];
     citations?: string[] | null;
     search_results?: PerplexitySearchResult[] | null;
+    related_questions?: string[] | null;
     type?: PerplexityCompletionResponseType | null;
     status?: PerplexityCompletionResponseStatus | null;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "15.8.3",
+	"version": "15.9.1",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -47,14 +47,20 @@
 		"@agentclientprotocol/sdk": "0.22.1",
 		"@babel/parser": "^7.29.7",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/hashline": "15.8.3",
-		"@oh-my-pi/omp-stats": "15.8.3",
-		"@oh-my-pi/pi-agent-core": "15.8.3",
-		"@oh-my-pi/pi-ai": "15.8.3",
-		"@oh-my-pi/pi-mnemopi": "15.8.3",
-		"@oh-my-pi/pi-natives": "15.8.3",
-		"@oh-my-pi/pi-tui": "15.8.3",
-		"@oh-my-pi/pi-utils": "15.8.3",
+		"@oh-my-pi/hashline": "15.9.1",
+		"@oh-my-pi/omp-stats": "15.9.1",
+		"@oh-my-pi/pi-agent-core": "15.9.1",
+		"@oh-my-pi/pi-ai": "15.9.1",
+		"@oh-my-pi/pi-mnemopi": "15.9.1",
+		"@oh-my-pi/pi-natives": "15.9.1",
+		"@oh-my-pi/pi-tui": "15.9.1",
+		"@oh-my-pi/pi-utils": "15.9.1",
+		"@opentelemetry/api": "^1.9.1",
+		"@opentelemetry/context-async-hooks": "^2.7.1",
+		"@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",
+		"@opentelemetry/resources": "^2.7.1",
+		"@opentelemetry/sdk-trace-base": "^2.7.1",
+		"@opentelemetry/sdk-trace-node": "^2.7.1",
 		"@puppeteer/browsers": "^3.0.4",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/scripts/build-binary.ts

@@ -1,10 +1,20 @@
 #!/usr/bin/env bun
 
+import { createRequire } from "node:module";
 import * as path from "node:path";
 
 const packageDir = path.join(import.meta.dir, "..");
 const outputPath = path.join(packageDir, "dist", "omp");
 
+// Transformers.js is an optional, native-heavy dependency that is never bundled
+// into the binary; the tiny-model worker `bun install`s it into a runtime cache
+// on first use. The `catalog:` spec cannot be resolved from inside the compiled
+// bunfs (issue #1763), so embed the concrete installed version here for the
+// worker to pin its runtime install against.
+const transformersVersion = (
+	createRequire(import.meta.url)("@huggingface/transformers/package.json") as { version: string }
+).version;
+
 function shouldAdhocSignDarwinBinary(): boolean {
 	return process.platform === "darwin";
 }
@@ -40,6 +50,8 @@ async function main(): Promise<void> {
 					"--keep-names",
 					"--define",
 					'process.env.PI_COMPILED="true"',
+					"--define",
+					`process.env.PI_TINY_TRANSFORMERS_VERSION=${JSON.stringify(transformersVersion)}`,
 					"--external",
 					"mupdf",
 					"--root",

package/src/capability/skill.ts

@@ -21,6 +21,13 @@ export interface SkillFrontmatter {
 	 * rather than ones the model should auto-discover.
 	 */
 	hide?: boolean;
+	/**
+	 * Agent Skills standard equivalent of `hide`.
+	 * When `true`, the skill is excluded from the system prompt listing.
+	 * Normalized from kebab-case `disable-model-invocation` in YAML frontmatter.
+	 * @see https://agentskills.io/specification
+	 */
+	disableModelInvocation?: boolean;
 	[key: string]: unknown;
 }
 

package/src/cli/args.ts

@@ -313,7 +313,7 @@ ${chalk.bold("Available Tools (default-enabled unless noted):")}
   inspect_image - Analyze images with a vision model
   browser       - Browser automation (Puppeteer)
   task          - Launch sub-agents for parallel tasks
-  todo_write    - Manage todo/task lists
+  todo          - Manage todo/task lists
   web_search    - Search the web
   ask           - Ask user questions (interactive mode only)
 

package/src/cli/session-picker.ts

@@ -64,6 +64,7 @@ export async function selectSession(
 				loadAllSessions: () => SessionManager.listAll(storage),
 				allSessions: options?.allSessions,
 				startInAllScope: options?.startInAllScope,
+				getTerminalRows: () => ui.terminal.rows,
 			},
 		);
 		return selector;

package/src/cli/update-cli.ts

@@ -27,6 +27,33 @@ const PACKAGE = "@oh-my-pi/pi-coding-agent";
  */
 const NPM_REGISTRY = "https://registry.npmjs.org/";
 
+/**
+ * Core native addon package. Bumped in lock-step with {@link PACKAGE} so the
+ * version sentinel the loader looks up at runtime matches the `.node` on
+ * disk; see {@link buildBunInstallArgs} for why this must be installed
+ * explicitly rather than inherited as a transitive dependency.
+ */
+const NATIVES_PACKAGE = "@oh-my-pi/pi-natives";
+
+/**
+ * Platform tags the release pipeline publishes as
+ * `@oh-my-pi/pi-natives-<tag>` leaves. Mirrors `SUPPORTED_PLATFORMS` in
+ * `packages/natives/native/loader-state.js` and `LEAF_TARGETS` in
+ * `packages/natives/scripts/gen-npm-packages.ts`; kept here as the local
+ * source of truth so the update path stays free of cross-package imports.
+ */
+const SUPPORTED_NATIVE_TAGS: ReadonlySet<string> = new Set([
+	"linux-x64",
+	"linux-arm64",
+	"darwin-x64",
+	"darwin-arm64",
+	"win32-x64",
+]);
+
+function currentNativeTag(): string {
+	return `${process.platform}-${process.arch}`;
+}
+
 interface ReleaseInfo {
 	tag: string;
 	version: string;
@@ -319,9 +346,34 @@ export async function replaceBinaryForUpdate(options: BinaryReplacementOptions):
  *
  * Together these two flags make `omp update` produce exactly the registry
  * lookup the version check just performed. See #1686.
+ *
+ * Also pins {@link NATIVES_PACKAGE} and the platform-specific
+ * `@oh-my-pi/pi-natives-<tag>` leaf to `expectedVersion`. `bun install -g`
+ * does not reliably refresh transitive `optionalDependencies` when the
+ * top-level package is the only one bumped, so the native addon and its
+ * version sentinel can drift out of sync with the freshly installed
+ * `@oh-my-pi/pi-coding-agent` and the loader aborts at
+ * `validateLoadedBindings` on the next launch
+ * (`The .node file on disk is from a different release than this loader`).
+ * Listing the natives explicitly forces bun to replace them in lock-step.
+ * The leaf is added only on tags the release pipeline actually publishes
+ * ({@link SUPPORTED_NATIVE_TAGS}) so unsupported platforms still fail with
+ * the original "no matching version" message instead of `EBADPLATFORM`.
+ * See #1824.
  */
-export function buildBunInstallArgs(expectedVersion: string): string[] {
-	return ["install", "-g", "--no-cache", `--registry=${NPM_REGISTRY}`, `${PACKAGE}@${expectedVersion}`];
+export function buildBunInstallArgs(expectedVersion: string, nativeTag: string = currentNativeTag()): string[] {
+	const args = [
+		"install",
+		"-g",
+		"--no-cache",
+		`--registry=${NPM_REGISTRY}`,
+		`${PACKAGE}@${expectedVersion}`,
+		`${NATIVES_PACKAGE}@${expectedVersion}`,
+	];
+	if (SUPPORTED_NATIVE_TAGS.has(nativeTag)) {
+		args.push(`${NATIVES_PACKAGE}-${nativeTag}@${expectedVersion}`);
+	}
+	return args;
 }
 
 /**

package/src/commands/completions.ts

@@ -51,7 +51,7 @@ export default class Completions extends Command {
 
 		const config: CliConfig = { bin: APP_NAME, version: VERSION, commands: map };
 		const spec = buildSpec(config, ROOT_COMMAND, aliasMap);
-		process.stdout.write(generateCompletion(shell, spec));
+		await Bun.write(Bun.stdout, generateCompletion(shell, spec));
 	}
 }
 

package/src/config/append-only-context-mode.ts

@@ -0,0 +1,37 @@
+/** Provider metadata needed to resolve append-only context mode. */
+export interface AppendOnlyContextModel {
+	provider: string;
+	baseUrl: string;
+	compat?: object;
+}
+
+function isXiaomiHost(baseUrl: string): boolean {
+	try {
+		const host = new URL(baseUrl).hostname;
+		return host === "xiaomimimo.com" || host.endsWith(".xiaomimimo.com");
+	} catch {
+		return false;
+	}
+}
+
+function shouldAutoEnableAppendOnlyContext(model: AppendOnlyContextModel | null | undefined): boolean {
+	if (!model) return false;
+	if (model.provider === "deepseek") return true;
+	if (isXiaomiHost(model.baseUrl)) return true;
+	return !!model.compat && "supportsStore" in model.compat && model.compat.supportsStore === true;
+}
+
+/** Resolves whether append-only context should be active for a model and setting. */
+export function shouldEnableAppendOnlyContext(
+	setting: "auto" | "on" | "off" | undefined,
+	model: AppendOnlyContextModel | null | undefined,
+): boolean {
+	switch (setting ?? "auto") {
+		case "on":
+			return true;
+		case "off":
+			return false;
+		default:
+			return shouldAutoEnableAppendOnlyContext(model);
+	}
+}

package/src/config/models-config-schema.ts

@@ -41,6 +41,7 @@ export const OpenAICompatSchema = z.object({
 	openRouterRouting: OpenRouterRoutingSchema.optional(),
 	vercelGatewayRouting: VercelGatewayRoutingSchema.optional(),
 	extraBody: z.record(z.string(), z.unknown()).optional(),
+	cacheControlFormat: z.enum(["anthropic"]).optional(),
 	supportsStrictMode: z.boolean().optional(),
 	toolStrictMode: z.enum(["all_strict", "none"]).optional(),
 });

package/src/config/settings-schema.ts

@@ -23,6 +23,7 @@ import {
 	TINY_TITLE_MODEL_VALUES,
 } from "../tiny/models";
 import { EDIT_MODES } from "../utils/edit-mode";
+import { SEARCH_PROVIDER_OPTIONS, SEARCH_PROVIDER_PREFERENCES } from "../web/search/types";
 
 /** Unified settings schema - single source of truth for all settings.
  * Unified settings schema - single source of truth for all settings.
@@ -608,6 +609,24 @@ export const SETTINGS_SCHEMA = {
 			"Maximum height in terminal rows for inline images (default 20). Set to 0 to use only the viewport-based limit (60% of terminal height).",
 	},
 
+	"tui.maxInlineImages": {
+		type: "number",
+		default: 8,
+		description:
+			"Maximum number of inline images kept as live terminal graphics (default 8). Older images fall back to a text placeholder via a full redraw once the limit is exceeded. Set to 0 to keep every image (no limit).",
+	},
+
+	"tui.textSizing": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "appearance",
+			label: "Large Headings (Kitty)",
+			description:
+				"Render Markdown H1 headings at 2x scale using Kitty's OSC 66 text-sizing protocol. Only takes effect on Kitty terminals; ignored everywhere else. Off by default.",
+		},
+	},
+
 	"tui.hyperlinks": {
 		type: "enum",
 		values: ["off", "auto", "always"] as const,
@@ -2104,7 +2123,7 @@ export const SETTINGS_SCHEMA = {
 	"todo.enabled": {
 		type: "boolean",
 		default: true,
-		ui: { tab: "tools", label: "Todos", description: "Enable the todo_write tool for task tracking" },
+		ui: { tab: "tools", label: "Todos", description: "Enable the todo tool for task tracking" },
 	},
 
 	"todo.reminders": {
@@ -2866,65 +2885,13 @@ export const SETTINGS_SCHEMA = {
 	// Provider selection
 	"providers.webSearch": {
 		type: "enum",
-		values: [
-			"auto",
-			"exa",
-			"brave",
-			"jina",
-			"kimi",
-			"zai",
-			"perplexity",
-			"anthropic",
-			"gemini",
-			"codex",
-			"tavily",
-			"kagi",
-			"synthetic",
-			"parallel",
-			"searxng",
-		] as const,
+		values: SEARCH_PROVIDER_PREFERENCES,
 		default: "auto",
 		ui: {
 			tab: "providers",
 			label: "Web Search Provider",
 			description: "Provider for web search tool",
-			options: [
-				{
-					value: "auto",
-					label: "Auto",
-					description: "Preferred web-search provider",
-				},
-				{ value: "exa", label: "Exa", description: "Requires EXA_API_KEY" },
-				{ value: "brave", label: "Brave", description: "Requires BRAVE_API_KEY" },
-				{ value: "jina", label: "Jina", description: "Requires JINA_API_KEY" },
-				{ value: "kimi", label: "Kimi", description: "Requires MOONSHOT_SEARCH_API_KEY or MOONSHOT_API_KEY" },
-				{
-					value: "perplexity",
-					label: "Perplexity",
-					description: "Requires PERPLEXITY_COOKIES or PERPLEXITY_API_KEY",
-				},
-				{
-					value: "anthropic",
-					label: "Anthropic",
-					description: "Claude's native web_search tool (uses Anthropic OAuth or ANTHROPIC_API_KEY)",
-				},
-				{
-					value: "codex",
-					label: "OpenAI",
-					description: "OpenAI's native web_search (uses ChatGPT OAuth via /login openai-codex)",
-				},
-				{
-					value: "gemini",
-					label: "Gemini",
-					description: "Google Search grounding via Gemini (uses google-gemini-cli or google-antigravity OAuth)",
-				},
-				{ value: "zai", label: "Z.AI", description: "Calls Z.AI webSearchPrime MCP" },
-				{ value: "tavily", label: "Tavily", description: "Requires TAVILY_API_KEY" },
-				{ value: "kagi", label: "Kagi", description: "Requires KAGI_API_KEY (Kagi V1 Search API)" },
-				{ value: "synthetic", label: "Synthetic", description: "Requires SYNTHETIC_API_KEY" },
-				{ value: "parallel", label: "Parallel", description: "Requires PARALLEL_API_KEY" },
-				{ value: "searxng", label: "SearXNG", description: "Requires SEARXNG_ENDPOINT or searxng.endpoint" },
-			],
+			options: SEARCH_PROVIDER_OPTIONS,
 		},
 	},
 	"providers.image": {
@@ -3090,9 +3057,9 @@ export const SETTINGS_SCHEMA = {
 			tab: "providers",
 			label: "Append-Only Context",
 			description:
-				"Cache system prompt + tool specs and keep an append-only message log so provider prefix caches (DeepSeek, Anthropic) hit at maximum rate. Auto enables for DeepSeek.",
+				"Cache system prompt + tool specs and keep an append-only message log so provider prefix caches (DeepSeek, Xiaomi/SGLang, Anthropic) hit at maximum rate. Auto enables for known prefix-cache providers.",
 			options: [
-				{ value: "auto", label: "Auto", description: "Enable for DeepSeek (recommended)" },
+				{ value: "auto", label: "Auto", description: "Enable for known prefix-cache providers (recommended)" },
 				{ value: "on", label: "On", description: "Always enable append-only context" },
 				{ value: "off", label: "Off", description: "Disable append-only context" },
 			],

package/src/debug/index.ts

@@ -6,7 +6,17 @@
 import * as fs from "node:fs/promises";
 import * as url from "node:url";
 import { getWorkProfile } from "@oh-my-pi/pi-natives";
-import { Container, Loader, type SelectItem, SelectList, Spacer, Text } from "@oh-my-pi/pi-tui";
+import {
+	Container,
+	isNotificationSuppressed,
+	Loader,
+	type SelectItem,
+	SelectList,
+	Spacer,
+	TERMINAL,
+	type TerminalNotification,
+	Text,
+} from "@oh-my-pi/pi-tui";
 import { getSessionsDir } from "@oh-my-pi/pi-utils";
 import { DynamicBorder } from "../modes/components/dynamic-border";
 import { getSelectListTheme, getSymbolTheme, theme } from "../modes/theme/theme";
@@ -15,10 +25,12 @@ import { formatBytes } from "../tools/render-utils";
 import { openPath } from "../utils/open";
 import { DebugLogViewerComponent } from "./log-viewer";
 import { generateHeapSnapshotData, type ProfilerSession, startCpuProfile } from "./profiler";
+import { buildSampleImage, ProtocolProbeComponent } from "./protocol-probe";
 import { RawSseViewerComponent } from "./raw-sse";
 import { resolveRawSseDebugBuffer } from "./raw-sse-buffer";
 import { clearArtifactCache, createDebugLogSource, createReportBundle, getArtifactCacheStats } from "./report-bundle";
 import { collectSystemInfo, formatSystemInfo } from "./system-info";
+import { collectTerminalState, formatTerminalState } from "./terminal-info";
 
 /** Debug menu options */
 const DEBUG_MENU_ITEMS: SelectItem[] = [
@@ -29,6 +41,12 @@ const DEBUG_MENU_ITEMS: SelectItem[] = [
 	{ value: "memory", label: "Report: memory issue", description: "Heap snapshot + bundle" },
 	{ value: "logs", label: "View: recent logs", description: "Show last 50 log entries" },
 	{ value: "system", label: "View: system info", description: "Show environment details" },
+	{ value: "terminal", label: "View: terminal state", description: "Subprotocols, geometry, scrollback strategy" },
+	{
+		value: "protocols",
+		label: "Test: terminal protocols",
+		description: "Styling, links, text sizing, graphics, notify",
+	},
 	{ value: "raw-sse", label: "View: raw SSE stream", description: "Show live provider SSE frames" },
 	{
 		value: "transcript",
@@ -106,6 +124,12 @@ export class DebugSelectorComponent extends Container {
 			case "system":
 				await this.#handleViewSystemInfo();
 				break;
+			case "terminal":
+				await this.#handleViewTerminalState();
+				break;
+			case "protocols":
+				await this.#handleViewProtocols();
+				break;
 			case "transcript":
 				await this.#handleTranscriptExport();
 				break;
@@ -352,6 +376,48 @@ export class DebugSelectorComponent extends Container {
 		this.ctx.ui.requestRender();
 	}
 
+	async #handleViewTerminalState(): Promise<void> {
+		const info = collectTerminalState({
+			columns: this.ctx.ui.terminal.columns,
+			rows: this.ctx.ui.terminal.rows,
+			synchronizedOutput: this.ctx.ui.synchronizedOutput,
+		});
+		const formatted = formatTerminalState(info);
+
+		this.ctx.chatContainer.addChild(new Spacer(1));
+		this.ctx.chatContainer.addChild(new DynamicBorder());
+		this.ctx.chatContainer.addChild(new Text(formatted, 1, 0));
+		this.ctx.chatContainer.addChild(new DynamicBorder());
+		this.ctx.ui.requestRender();
+	}
+
+	async #handleViewProtocols(): Promise<void> {
+		// Fire the desktop notification as a real side effect, then render a
+		// panel that samples every other special protocol and reports the
+		// notification outcome.
+		const suppressed = isNotificationSuppressed();
+		if (!suppressed) {
+			const sessionName = this.ctx.sessionManager.getSessionName();
+			const notification: TerminalNotification = {
+				title: sessionName || "Oh My Pi",
+				body: "Terminal protocol test",
+				type: "test",
+				actions: "focus",
+			};
+			TERMINAL.sendNotification(notification);
+		}
+
+		this.ctx.chatContainer.addChild(new Spacer(1));
+		this.ctx.chatContainer.addChild(
+			new ProtocolProbeComponent({
+				image: buildSampleImage(),
+				imageBudget: this.ctx.ui.imageBudget,
+				notificationSuppressed: suppressed,
+			}),
+		);
+		this.ctx.ui.requestRender();
+	}
+
 	async #handleTranscriptExport(): Promise<void> {
 		await this.ctx.handleDebugTranscriptCommand();
 	}