@selesai/code 0.13.3 → 0.13.5

package/dist/extensions/pi-web-agent/src/tools/web-fetch.ts

@@ -1,31 +1,31 @@
-import { createHttpFetcher } from '../fetch/http-fetch.js';
-import { buildFetchPresentation } from '../presentation/fetch-presentation.js';
-import type { WebFetchResponse } from '../types.js';
-
-export function createWebFetchTool({
-  fetchPage = createHttpFetcher()
-}: {
-  fetchPage?: (url: string) => Promise<WebFetchResponse>;
-} = {}) {
-  return async function webFetch({ url }: { url: string }): Promise<WebFetchResponse> {
-    if (!/^https?:\/\//.test(url)) {
-      const result: WebFetchResponse = {
-        status: 'unsupported',
-        url,
-        metadata: { method: 'http', cacheHit: false },
-        error: { code: 'UNSUPPORTED_URL', message: 'Only http and https URLs are supported.' }
-      };
-
-      return {
-        ...result,
-        presentation: buildFetchPresentation(result)
-      };
-    }
-
-    const result = await fetchPage(url);
-    return {
-      ...result,
-      presentation: buildFetchPresentation(result)
-    };
-  };
-}
+import { createHttpFetcher } from '../fetch/http-fetch.js';
+import { buildFetchPresentation } from '../presentation/fetch-presentation.js';
+import type { WebFetchResponse } from '../types.js';
+
+export function createWebFetchTool({
+  fetchPage = createHttpFetcher()
+}: {
+  fetchPage?: (url: string) => Promise<WebFetchResponse>;
+} = {}) {
+  return async function webFetch({ url }: { url: string }): Promise<WebFetchResponse> {
+    if (!/^https?:\/\//.test(url)) {
+      const result: WebFetchResponse = {
+        status: 'unsupported',
+        url,
+        metadata: { method: 'http', cacheHit: false },
+        error: { code: 'UNSUPPORTED_URL', message: 'Only http and https URLs are supported.' }
+      };
+
+      return {
+        ...result,
+        presentation: buildFetchPresentation(result)
+      };
+    }
+
+    const result = await fetchPage(url);
+    return {
+      ...result,
+      presentation: buildFetchPresentation(result)
+    };
+  };
+}

package/dist/extensions/pi-web-agent/src/tools/web-search.ts

@@ -36,7 +36,11 @@ function htmlLooksBlocked(html: string) {
     normalized.includes('challenge') ||
     normalized.includes('verify you are human') ||
     normalized.includes('are you a robot') ||
-    normalized.includes('unusual traffic')
+    normalized.includes('unusual traffic') ||
+    normalized.includes('automated requests') ||
+    normalized.includes('automated queries') ||
+    normalized.includes('detected unusual') ||
+    normalized.includes('too many requests')
   );
 }
 
@@ -80,8 +84,15 @@ export function createWebSearchTool({
     }
 
     try {
-      const html = await searchHtml(normalizedQuery);
-      const parsed = parseDuckDuckGoResults(html);
+      let html = await searchHtml(normalizedQuery);
+      let parsed = parseDuckDuckGoResults(html);
+
+      // A 200-OK bot-wall reads as a successful fetch, so the fetch-layer retry never sees it.
+      // Give a page that looks blocked one more shot here before we classify it.
+      if (parsed.results.length === 0 && htmlLooksBlocked(html)) {
+        html = await searchHtml(normalizedQuery);
+        parsed = parseDuckDuckGoResults(html);
+      }
 
       if (parsed.results.length > 0) {
         const result: WebSearchResponse = {
@@ -96,14 +107,16 @@ export function createWebSearchTool({
         };
       }
 
-      if (parsed.noResults) {
+      // Check for a bot-wall before "no results": a page can carry both markers, and BLOCKED is
+      // the honest call since it routes to the fallback instead of a dead end.
+      if (htmlLooksBlocked(html)) {
         const result: WebSearchResponse = {
           status: 'error',
           results: [],
           metadata: { backend: 'duckduckgo', cacheHit: false },
           error: {
-            code: 'NO_RESULTS',
-            message: 'DuckDuckGo returned no usable results for this query.'
+            code: 'BLOCKED',
+            message: 'DuckDuckGo search appears to be blocked or rate limited.'
           }
         };
         return {
@@ -112,14 +125,14 @@ export function createWebSearchTool({
         };
       }
 
-      if (htmlLooksBlocked(html)) {
+      if (parsed.noResults) {
         const result: WebSearchResponse = {
           status: 'error',
           results: [],
           metadata: { backend: 'duckduckgo', cacheHit: false },
           error: {
-            code: 'BLOCKED',
-            message: 'DuckDuckGo search appears to be blocked or rate limited.'
+            code: 'NO_RESULTS',
+            message: 'DuckDuckGo returned no usable results for this query.'
           }
         };
         return {

package/dist/extensions/pi-web-agent/src/types.ts

@@ -16,20 +16,33 @@ export type SearchResult = {
   snippet: string;
 };
 
+export type SearchProviderName = 'duckduckgo' | 'searxng' | 'brave' | 'youcom' | 'exa' | 'tavily';
+
+export type FanoutMode = 'off' | 'on' | 'auto';
+
+export type FanoutMetadata = {
+  mode: Exclude<FanoutMode, 'off'>;
+  providers: SearchProviderName[]; // providers that actually contributed results
+  skipped?: SearchProviderName[];  // providers queried but errored or returned nothing
+};
+
 export type ToolError = {
   code: string;
   message: string;
 };
 
 export type SearchMetadata = {
-  backend: 'duckduckgo' | 'searxng' | 'brave';
+  backend: 'duckduckgo' | 'searxng' | 'brave' | 'youcom' | 'exa' | 'tavily';
   cacheHit: boolean;
-  fallbackFrom?: 'searxng' | 'brave';
+  fallbackFrom?: 'searxng' | 'brave' | 'youcom' | 'exa' | 'tavily' | 'duckduckgo';
   fallbackReason?: string;
+  fanout?: FanoutMetadata;
 };
 
+export type FetchMethod = 'http' | 'headless' | 'firecrawl' | 'github' | 'pdf' | 'youtube';
+
 export type FetchMetadata = {
-  method: 'http' | 'headless' | 'firecrawl';
+  method: FetchMethod;
   cacheHit: boolean;
   fallbackFrom?: 'firecrawl';
   fallbackReason?: string;
@@ -74,7 +87,7 @@ export type WebFetchHeadlessResponse = {
 export type WebExploreResponse = {
   status: 'ok' | 'error';
   findings: string[];
-  sources: Array<{ title: string; url: string; method?: 'http' | 'headless' | 'firecrawl' }>;
+  sources: Array<{ title: string; url: string; method?: FetchMethod }>;
   caveat?: string;
   metadata?: {
     searchPasses: number;
@@ -82,6 +95,8 @@ export type WebExploreResponse = {
     headlessAttempts: number;
     exhaustedBudget: boolean;
     caveatReasons?: string[];
+    fanoutProviders?: SearchProviderName[];
+    fanoutSkipped?: SearchProviderName[];
   };
   presentation?: PresentationEnvelope;
   error?: ToolError;

package/dist/extensions/pi-zentui/extensions/zentui/format.ts

@@ -1,6 +1,5 @@
 import { homedir, hostname, userInfo } from "node:os";
 import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { formatCost } from "../../../../core/usage-totals.ts";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type {
 	ColorSource,
@@ -127,6 +126,13 @@ type UsageCacheEntry = {
 
 const MAX_USAGE_TOTAL = Number.MAX_VALUE;
 
+function formatCost(cost: number): string {
+	if (cost === 0) return "$0.000";
+	if (cost >= 1) return `$${cost.toFixed(3)}`;
+	if (cost >= 0.01) return `$${cost.toFixed(4)}`;
+	return `$${cost.toFixed(6)}`;
+}
+
 let usageTotalsCache: UsageCacheEntry | undefined;
 let usageTotalsAggregationPassCount = 0;
 

package/dist/extensions/ponytail/package.json

@@ -1,8 +1,8 @@
-{
-  "name": "ponytail",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "test": "node --test ./test/*.test.js"
-  }
-}
+{
+  "name": "ponytail",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --test ./test/*.test.js"
+  }
+}

package/dist/extensions/question/constants.ts

@@ -1,31 +1,31 @@
-// All constants for the question extension.
-
-import { Key } from "@earendil-works/pi-tui";
-import type { ResolvedShortcut } from "./types.ts";
-
-export const QUESTION_VERSION = "2";
-
-export const SPLIT_PANE_MIN_WIDTH = 84;
-export const SPLIT_PANE_LEFT_MIN_WIDTH = 32;
-export const SPLIT_PANE_RIGHT_MIN_WIDTH = 28;
-export const SPLIT_PANE_SEPARATOR = " │ ";
-
-export const FREEFORM_LABEL = "Type custom answer — enter a custom response";
-export const COMMENT_TOGGLE_LABEL = "Add extra context after selection";
-
-export const DEFAULT_COMMENT_TOGGLE_KEY = "ctrl+g";
-
-export const BOX_BORDER_LEFT = "│ ";
-export const BOX_BORDER_RIGHT = " │";
-export const BOX_BORDER_OVERHEAD = BOX_BORDER_LEFT.length + BOX_BORDER_RIGHT.length;
-
-export const SHORTCUT_DISABLE_VALUES = new Set(["off", "none", "disabled", ""]);
-
-export const DISABLED_SHORTCUT: ResolvedShortcut = {
-	disabled: true,
-	spec: null,
-	matches: ((_data: string) => false) as (data: string) => false,
-};
-
-export const VIM_UP = Key.ctrl("k");
+// All constants for the question extension.
+
+import { Key } from "@earendil-works/pi-tui";
+import type { ResolvedShortcut } from "./types.ts";
+
+export const QUESTION_VERSION = "2";
+
+export const SPLIT_PANE_MIN_WIDTH = 84;
+export const SPLIT_PANE_LEFT_MIN_WIDTH = 32;
+export const SPLIT_PANE_RIGHT_MIN_WIDTH = 28;
+export const SPLIT_PANE_SEPARATOR = " │ ";
+
+export const FREEFORM_LABEL = "Type custom answer — enter a custom response";
+export const COMMENT_TOGGLE_LABEL = "Add extra context after selection";
+
+export const DEFAULT_COMMENT_TOGGLE_KEY = "ctrl+g";
+
+export const BOX_BORDER_LEFT = "│ ";
+export const BOX_BORDER_RIGHT = " │";
+export const BOX_BORDER_OVERHEAD = BOX_BORDER_LEFT.length + BOX_BORDER_RIGHT.length;
+
+export const SHORTCUT_DISABLE_VALUES = new Set(["off", "none", "disabled", ""]);
+
+export const DISABLED_SHORTCUT: ResolvedShortcut = {
+	disabled: true,
+	spec: null,
+	matches: ((_data: string) => false) as (data: string) => false,
+};
+
+export const VIM_UP = Key.ctrl("k");
 export const VIM_DOWN = Key.ctrl("j");

package/dist/extensions/question/helpers.ts

@@ -1,58 +1,58 @@
-// Pure helper functions for the question extension.
-
-import type { PreparedQuestion, QuestionOption, QuestionResponse } from "./types.ts";
-
-export function trimText(value: string | null | undefined): string | undefined {
-	const trimmed = value?.trim();
-	return trimmed || undefined;
-}
-
-export function oneLine(value: unknown, max = 100): string {
-	const text = String(value ?? "").replace(/\s+/g, " ").trim();
-	return text.length > max ? `${text.slice(0, Math.max(0, max - 1))}…` : text;
-}
-
-export function previewText(value: unknown, max = 160, maxLines = 2): string {
-	const lines = String(value ?? "").trim().split(/\r?\n/);
-	const limited = lines.slice(0, maxLines).join("\n");
-	const wasCut = lines.length > maxLines || limited.length > max;
-	const text = limited.length > max ? limited.slice(0, Math.max(0, max - 1)) : limited;
-	return wasCut ? `${text}…` : text;
-}
-
-export function createTextResponse(text: string | null | undefined): QuestionResponse | null {
-	const normalized = trimText(text);
-	return normalized ? { kind: "text", text: normalized } : null;
-}
-
-export function createSelectionResponse(values: string[], otherText?: string | null): QuestionResponse | null {
-	const normalizedValues = values.map((value) => value.trim()).filter(Boolean);
-	const normalizedOther = trimText(otherText);
-	if (normalizedValues.length === 0 && !normalizedOther) return null;
-	return normalizedOther
-		? { kind: "selection", values: normalizedValues, otherText: normalizedOther }
-		: { kind: "selection", values: normalizedValues };
-}
-
-export function formatResponseSummary(response: QuestionResponse): string {
-	if (response.kind === "text") return response.text;
-	return [...response.values, ...(response.otherText ? [response.otherText] : [])].join(", ");
-}
-
-export function formatQuestionResponse(question: PreparedQuestion, response: QuestionResponse): string {
-	if (response.kind === "text") return response.text;
-	const labels = response.values.map(
-		(value) => question.options.find((option) => option.value === value)?.label ?? value,
-	);
-	if (response.otherText) labels.push(`Other: ${response.otherText}`);
-	return labels.join(", ");
-}
-
-export function formatOptionsForMessage(options: QuestionOption[]): string {
-	return options
-		.map((option, index) => {
-			const description = option.description ? ` — ${option.description}` : "";
-			return `${index + 1}. ${option.label}${description}`;
-		})
-		.join("\n");
-}
+// Pure helper functions for the question extension.
+
+import type { PreparedQuestion, QuestionOption, QuestionResponse } from "./types.ts";
+
+export function trimText(value: string | null | undefined): string | undefined {
+	const trimmed = value?.trim();
+	return trimmed || undefined;
+}
+
+export function oneLine(value: unknown, max = 100): string {
+	const text = String(value ?? "").replace(/\s+/g, " ").trim();
+	return text.length > max ? `${text.slice(0, Math.max(0, max - 1))}…` : text;
+}
+
+export function previewText(value: unknown, max = 160, maxLines = 2): string {
+	const lines = String(value ?? "").trim().split(/\r?\n/);
+	const limited = lines.slice(0, maxLines).join("\n");
+	const wasCut = lines.length > maxLines || limited.length > max;
+	const text = limited.length > max ? limited.slice(0, Math.max(0, max - 1)) : limited;
+	return wasCut ? `${text}…` : text;
+}
+
+export function createTextResponse(text: string | null | undefined): QuestionResponse | null {
+	const normalized = trimText(text);
+	return normalized ? { kind: "text", text: normalized } : null;
+}
+
+export function createSelectionResponse(values: string[], otherText?: string | null): QuestionResponse | null {
+	const normalizedValues = values.map((value) => value.trim()).filter(Boolean);
+	const normalizedOther = trimText(otherText);
+	if (normalizedValues.length === 0 && !normalizedOther) return null;
+	return normalizedOther
+		? { kind: "selection", values: normalizedValues, otherText: normalizedOther }
+		: { kind: "selection", values: normalizedValues };
+}
+
+export function formatResponseSummary(response: QuestionResponse): string {
+	if (response.kind === "text") return response.text;
+	return [...response.values, ...(response.otherText ? [response.otherText] : [])].join(", ");
+}
+
+export function formatQuestionResponse(question: PreparedQuestion, response: QuestionResponse): string {
+	if (response.kind === "text") return response.text;
+	const labels = response.values.map(
+		(value) => question.options.find((option) => option.value === value)?.label ?? value,
+	);
+	if (response.otherText) labels.push(`Other: ${response.otherText}`);
+	return labels.join(", ");
+}
+
+export function formatOptionsForMessage(options: QuestionOption[]): string {
+	return options
+		.map((option, index) => {
+			const description = option.description ? ` — ${option.description}` : "";
+			return `${index + 1}. ${option.label}${description}`;
+		})
+		.join("\n");
+}

package/dist/extensions/question/navigation.ts

@@ -1,14 +1,14 @@
-// Vim-style navigation aliases (ctrl+j/k don't collide with fuzzy-search input).
-
-import type { KeybindingsManager } from "@selesai/code";
-import { matchesKey } from "@earendil-works/pi-tui";
-
-import { VIM_DOWN, VIM_UP } from "./constants.ts";
-
-export function matchesUp(data: string, keybindings: KeybindingsManager): boolean {
-	return keybindings.matches(data, "tui.select.up") || matchesKey(data, VIM_UP);
-}
-
-export function matchesDown(data: string, keybindings: KeybindingsManager): boolean {
-	return keybindings.matches(data, "tui.select.down") || matchesKey(data, VIM_DOWN);
-}
+// Vim-style navigation aliases (ctrl+j/k don't collide with fuzzy-search input).
+
+import type { KeybindingsManager } from "@selesai/code";
+import { matchesKey } from "@earendil-works/pi-tui";
+
+import { VIM_DOWN, VIM_UP } from "./constants.ts";
+
+export function matchesUp(data: string, keybindings: KeybindingsManager): boolean {
+	return keybindings.matches(data, "tui.select.up") || matchesKey(data, VIM_UP);
+}
+
+export function matchesDown(data: string, keybindings: KeybindingsManager): boolean {
+	return keybindings.matches(data, "tui.select.down") || matchesKey(data, VIM_DOWN);
+}

package/dist/extensions/question/package.json

@@ -1,19 +1,19 @@
-{
-	"name": "@selesai/question",
-	"version": "0.0.1",
-	"private": true,
-	"description": "Interactive question tool extension for the agent.",
-	"type": "module",
-	"pi": {
-		"extensions": ["./index.ts"]
-	},
-	"peerDependencies": {
-		"@selesai/code": "*",
-		"@earendil-works/pi-ai": "*",
-		"@earendil-works/pi-tui": "*",
-		"typebox": "*"
-	},
-	"scripts": {
-		"test": "tsx --test tests/**/*.test.ts"
-	}
-}
+{
+	"name": "@selesai/question",
+	"version": "0.0.1",
+	"private": true,
+	"description": "Interactive question tool extension for the agent.",
+	"type": "module",
+	"pi": {
+		"extensions": ["./index.ts"]
+	},
+	"peerDependencies": {
+		"@selesai/code": "*",
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	},
+	"scripts": {
+		"test": "tsx --test tests/**/*.test.ts"
+	}
+}

package/dist/extensions/question/selection-mode.ts

@@ -1,47 +1,47 @@
-// SelectionMode strategy — isolates single-vs-multi selection behavior.
-
-import type { QuestionOption } from "./types.ts";
-
-export interface QuestionListState {
-	selectedIndex: number;
-	checked: ReadonlySet<number>;
-	options: QuestionOption[];
-}
-
-export interface SelectionMode {
-	readonly multi: boolean;
-	toggle(checked: Set<number>, index: number): void;
-	buildResult(state: QuestionListState): string[];
-	/** Returns whether to toggle (multi) or just select (single), and the new selectedIndex. */
-	handleNumberKey(idx: number, count: number): { toggle: boolean; selectIndex: number };
-}
-
-export const SingleSelect: SelectionMode = {
-	multi: false,
-	toggle() {},
-	buildResult(state) {
-		const value = state.options[state.selectedIndex]?.value;
-		return value ? [value] : [];
-	},
-	handleNumberKey(idx, count) {
-		return { toggle: false, selectIndex: Math.min(idx, count - 1) };
-	},
-};
-
-export const MultiSelect: SelectionMode = {
-	multi: true,
-	toggle(checked, index) {
-		if (index < 0) return;
-		if (checked.has(index)) checked.delete(index);
-		else checked.add(index);
-	},
-	buildResult(state) {
-		return Array.from(state.checked)
-			.sort((a, b) => a - b)
-			.map((i) => state.options[i]?.value)
-			.filter((value): value is string => !!value);
-	},
-	handleNumberKey(idx, count) {
-		return { toggle: true, selectIndex: Math.min(idx, count - 1) };
-	},
+// SelectionMode strategy — isolates single-vs-multi selection behavior.
+
+import type { QuestionOption } from "./types.ts";
+
+export interface QuestionListState {
+	selectedIndex: number;
+	checked: ReadonlySet<number>;
+	options: QuestionOption[];
+}
+
+export interface SelectionMode {
+	readonly multi: boolean;
+	toggle(checked: Set<number>, index: number): void;
+	buildResult(state: QuestionListState): string[];
+	/** Returns whether to toggle (multi) or just select (single), and the new selectedIndex. */
+	handleNumberKey(idx: number, count: number): { toggle: boolean; selectIndex: number };
+}
+
+export const SingleSelect: SelectionMode = {
+	multi: false,
+	toggle() {},
+	buildResult(state) {
+		const value = state.options[state.selectedIndex]?.value;
+		return value ? [value] : [];
+	},
+	handleNumberKey(idx, count) {
+		return { toggle: false, selectIndex: Math.min(idx, count - 1) };
+	},
+};
+
+export const MultiSelect: SelectionMode = {
+	multi: true,
+	toggle(checked, index) {
+		if (index < 0) return;
+		if (checked.has(index)) checked.delete(index);
+		else checked.add(index);
+	},
+	buildResult(state) {
+		return Array.from(state.checked)
+			.sort((a, b) => a - b)
+			.map((i) => state.options[i]?.value)
+			.filter((value): value is string => !!value);
+	},
+	handleNumberKey(idx, count) {
+		return { toggle: true, selectIndex: Math.min(idx, count - 1) };
+	},
 };

package/dist/extensions/question/shortcuts.ts

@@ -1,44 +1,44 @@
-// Shortcut resolution for the optional-comment toggle key.
-
-import { matchesKey } from "@earendil-works/pi-tui";
-
-import { DEFAULT_COMMENT_TOGGLE_KEY, DISABLED_SHORTCUT, SHORTCUT_DISABLE_VALUES } from "./constants.ts";
-import type { ResolvedShortcut, ResolvedShortcuts } from "./types.ts";
-
-export function normalizeShortcutSpec(value: string | null | undefined): string | null | undefined {
-	if (value === undefined) return undefined;
-	if (value === null) return null;
-	const trimmed = value.trim().toLowerCase();
-	if (SHORTCUT_DISABLE_VALUES.has(trimmed)) return null;
-	return trimmed;
-}
-
-export function isValidShortcutSpec(spec: string): boolean {
-	if (!spec) return false;
-	if (!/^[a-z0-9+_\-!@#$%^&*()|~`'":;,./<>?[\]{}=\\]+$/i.test(spec)) return false;
-	if (spec.startsWith("+") || spec.endsWith("+")) return false;
-	if (spec.includes("++")) return false;
-	return true;
-}
-
-export function buildShortcut(spec: string): ResolvedShortcut {
-	return { disabled: false, spec, matches: (data: string) => matchesKey(data, spec as any) };
-}
-
-export function resolveShortcut(
-	paramValue: string | null | undefined,
-	envValue: string | undefined,
-	defaultSpec: string,
-): ResolvedShortcut {
-	for (const raw of [paramValue, envValue, defaultSpec]) {
-		const normalized = normalizeShortcutSpec(raw);
-		if (normalized === undefined) continue;
-		if (normalized === null) return DISABLED_SHORTCUT;
-		if (isValidShortcutSpec(normalized)) return buildShortcut(normalized);
-	}
-	return DISABLED_SHORTCUT;
-}
-
-export function resolveShortcuts(commentToggleKey: string | null | undefined, commentEnv: string | undefined): ResolvedShortcuts {
-	return { commentToggle: resolveShortcut(commentToggleKey, commentEnv, DEFAULT_COMMENT_TOGGLE_KEY) };
-}
+// Shortcut resolution for the optional-comment toggle key.
+
+import { matchesKey } from "@earendil-works/pi-tui";
+
+import { DEFAULT_COMMENT_TOGGLE_KEY, DISABLED_SHORTCUT, SHORTCUT_DISABLE_VALUES } from "./constants.ts";
+import type { ResolvedShortcut, ResolvedShortcuts } from "./types.ts";
+
+export function normalizeShortcutSpec(value: string | null | undefined): string | null | undefined {
+	if (value === undefined) return undefined;
+	if (value === null) return null;
+	const trimmed = value.trim().toLowerCase();
+	if (SHORTCUT_DISABLE_VALUES.has(trimmed)) return null;
+	return trimmed;
+}
+
+export function isValidShortcutSpec(spec: string): boolean {
+	if (!spec) return false;
+	if (!/^[a-z0-9+_\-!@#$%^&*()|~`'":;,./<>?[\]{}=\\]+$/i.test(spec)) return false;
+	if (spec.startsWith("+") || spec.endsWith("+")) return false;
+	if (spec.includes("++")) return false;
+	return true;
+}
+
+export function buildShortcut(spec: string): ResolvedShortcut {
+	return { disabled: false, spec, matches: (data: string) => matchesKey(data, spec as any) };
+}
+
+export function resolveShortcut(
+	paramValue: string | null | undefined,
+	envValue: string | undefined,
+	defaultSpec: string,
+): ResolvedShortcut {
+	for (const raw of [paramValue, envValue, defaultSpec]) {
+		const normalized = normalizeShortcutSpec(raw);
+		if (normalized === undefined) continue;
+		if (normalized === null) return DISABLED_SHORTCUT;
+		if (isValidShortcutSpec(normalized)) return buildShortcut(normalized);
+	}
+	return DISABLED_SHORTCUT;
+}
+
+export function resolveShortcuts(commentToggleKey: string | null | undefined, commentEnv: string | undefined): ResolvedShortcuts {
+	return { commentToggle: resolveShortcut(commentToggleKey, commentEnv, DEFAULT_COMMENT_TOGGLE_KEY) };
+}