Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(open-knowledge): gate terminal-CLI launch rows on PATH detection (#2621)

mike-inkeepd67655d4eaed
diff --git a/.changeset/gate-terminal-cli-rows-on-path.md b/.changeset/gate-terminal-cli-rows-on-path.md
new file mode 100644
index 000000000..eb59f11c0
--- /dev/null
+++ b/.changeset/gate-terminal-cli-rows-on-path.md
@@ -0,0 +1,13 @@
+---
+'@inkeep/open-knowledge': patch
+---
+
+**Terminal CLI launch rows now reflect what's installed.** Across every
+launch surface — the header / tab-strip "New chat", the "Ask X" composer
+button, and the "Open with AI" menus — the docked-terminal CLI rows are gated
+on a PATH-detection probe, so you only see the CLIs you actually have (e.g. no
+Codex or Cursor-agent row when they aren't on PATH). Claude always keeps its
+row as an install anchor. The gate fails open: a CLI whose install state is
+still unknown (probe pending, probe failure, or an older desktop bridge) stays
+visible rather than being silently dropped, so a probe miss never hides a CLI
+you have installed.
diff --git a/packages/app/src/App.tsx b/packages/app/src/App.tsx
index 7ad2518e8..965d6bd2a 100644
--- a/packages/app/src/App.tsx
+++ b/packages/app/src/App.tsx
@@ -30,6 +30,7 @@ import {
useDocumentTransition,
} from '@/editor/DocumentContext';
import { parseEditorTabId } from '@/editor/editor-tabs';
+import { useInstalledClis } from '@/hooks/use-installed-clis';
import { useReconcileSkillTabs } from '@/hooks/use-reconcile-skill-tabs';
import { ConfigProvider } from '@/lib/config-provider';
import {
@@ -472,11 +473,16 @@ function AppBody() {
// directive would point the agent at a surface the user is already viewing.
// Null on the web host (no real OS shell) so the menu rows that consume it
// render nothing.
+ // Which launchable CLIs are on PATH — each launch surface gates its rows from
+ // this map via `visibleTerminalClis` so a CLI that isn't installed (e.g.
+ // Antigravity) doesn't clutter the menu once the probe confirms it absent.
+ const installedClis = useInstalledClis();
const terminalLaunch: TerminalLaunchContextValue | null = desktopBridge
? {
launchInTerminal: (input, cli) => {
requestTerminalLaunch(composeTerminalLaunchPrompt(input, cli), cli);
},
+ installedClis,
}
: null;
diff --git a/packages/app/src/components/BottomComposer.dom.test.tsx b/packages/app/src/components/BottomComposer.dom.test.tsx
index 7d7f2b878..33b1b6658 100644
--- a/packages/app/src/components/BottomComposer.dom.test.tsx
+++ b/packages/app/src/components/BottomComposer.dom.test.tsx
@@ -244,7 +244,10 @@ async function renderComposer(
// Variant that supplies a docked-terminal launcher so the picker offers the
// "Claude CLI" option (desktop parity). Records every launched input.
-async function renderComposerWithTerminal(docName = 'notes') {
+async function renderComposerWithTerminal(
+ docName = 'notes',
+ installedClis: Record<string, boolean> = {},
+) {
const { BottomComposer } = await import('./BottomComposer');
const { TerminalLaunchProvider } = await import('./handoff/TerminalLaunchContext');
return render(
@@ -253,6 +256,11 @@ async function renderComposerWithTerminal(docName = 'notes') {
launchInTerminal: (input, cli) => {
terminalLaunchCalls.push({ input, cli });
},
+ // The composer reads the install map from here (not its own probe), so it
+ // drives both the no-pick default (resolveDefaultCli) and row gating
+ // (visibleTerminalClis). Default {} ⇒ probe unresolved ⇒ fail-open (all
+ // CLIs), matching the ungated rows most tests were written against.
+ installedClis,
}}
>
<BottomComposer docName={docName} surface="wysiwyg" />
@@ -271,6 +279,7 @@ async function renderComposerWithThrowingTerminal(docName = 'notes') {
launchInTerminal: () => {
throw new Error('no terminal session');
},
+ installedClis: {},
}}
>
<BottomComposer docName={docName} surface="wysiwyg" />
@@ -278,14 +287,15 @@ async function renderComposerWithThrowingTerminal(docName = 'notes') {
);
}
-// Desktop + a CLI install probe: installs a fake terminal bridge exposing
-// `cliInstalledMap` so the no-pick default resolves to the first-installed CLI.
-// (`terminalLaunch` still comes from the provider; the bridge only feeds the probe.)
+// Desktop + a known install map: the composer now reads the map straight from
+// the launch provider (not its own probe), so pass it through the provider value
+// to drive the no-pick default. The `okDesktop` bridge is set for parity with the
+// real desktop host but is no longer what feeds the composer's default.
async function renderComposerWithInstalledClis(installed: Record<string, boolean>) {
(window as { okDesktop?: unknown }).okDesktop = {
terminal: { cliInstalledMap: async () => installed },
};
- return renderComposerWithTerminal();
+ return renderComposerWithTerminal('notes', installed);
}
// Folder mode: the composer is scoped to a folder (no open doc, no surface).
diff --git a/packages/app/src/components/BottomComposer.tsx b/packages/app/src/components/BottomComposer.tsx
index d96f02c31..14c43230d 100644
--- a/packages/app/src/components/BottomComposer.tsx
+++ b/packages/app/src/components/BottomComposer.tsx
@@ -25,12 +25,7 @@
* shell is exclusively the selection-bubble path).
*/
-import {
- type TargetData,
- TERMINAL_CLI_IDS,
- TERMINAL_CLIS,
- type TerminalCli,
-} from '@inkeep/open-knowledge-core';
+import { type TargetData, TERMINAL_CLIS, type TerminalCli } from '@inkeep/open-knowledge-core';
import { Trans, useLingui } from '@lingui/react/macro';
import { ChevronDown, Loader2, TextQuote, X } from 'lucide-react';
import { useEffect, useRef, useState } from 'react';
@@ -39,7 +34,7 @@ import { ComposerContextChips } from '@/components/ComposerContextChips';
import { AgentSplitButton } from '@/components/handoff/AgentSplitButton';
import { TargetIcon } from '@/components/handoff/OpenInAgentMenuItem';
import { useTerminalLaunch } from '@/components/handoff/TerminalLaunchContext';
-import { cliIconTargetId } from '@/components/handoff/terminal-cli-display';
+import { cliIconTargetId, visibleTerminalClis } from '@/components/handoff/terminal-cli-display';
import {
buildComposerHandoffInput,
useHandoffDispatch,
@@ -58,7 +53,6 @@ import {
selectionSnapshotToCompose,
} from '@/editor/selection-context';
import type { EditorSurface } from '@/editor/selection-stats';
-import { useInstalledClis } from '@/hooks/use-installed-clis';
import { useSelectionContext } from '@/hooks/use-selection-context';
import { resolveDefaultCli } from '@/lib/default-cli-resolver';
import { VISIBLE_TARGETS } from '@/lib/handoff/targets';
@@ -216,10 +210,6 @@ export function BottomComposer({
// without a subscription.
const [stickyId] = useState(() => loadStickyAgent());
const [selectedId, setSelectedId] = useState<string | null>(null);
- // Which CLIs are on PATH (desktop probe, main-cached ~60s). Only used to pick
- // the no-pick desktop default (resolveDefaultCli below); an explicit CLI pick
- // still launches regardless of install. Shared with the header/tab-strip New chat.
- const installedClis = useInstalledClis();
// The rich input owns its content; the host tracks only emptiness (pushed up
// via `onEmptyChange`) to drive the placeholder + send-enabled state, and
// reads the instruction + chip mentions at submit via the imperative handle.
@@ -485,7 +475,9 @@ export function BottomComposer({
// what New chat launches. Derived, never saved, so a freshly-installed CLI can
// take over the default mid-session; web keeps the app-target default.
const defaultCli: TerminalCli | null =
- terminalLaunch !== null && effectiveId === null ? resolveDefaultCli(null, installedClis) : null;
+ terminalLaunch !== null && effectiveId === null
+ ? resolveDefaultCli(null, terminalLaunch.installedClis)
+ : null;
const selectedCli: TerminalCli | null = explicitCli ?? defaultCli;
const isTerminalSelected = selectedCli !== null;
const resolvedTarget = isTerminalSelected ? null : resolveStickyAgent(states, effectiveId);
@@ -508,12 +500,13 @@ export function BottomComposer({
// name carries "<name> CLI" (WCAG 2.5.3 — the accessible name contains the
// visible label) so AT users can tell a Terminal row apart from a same-named
// Desktop row. The "Terminal" section header plus the brand icon carry that
- // same distinction for sighted users. No install probe here — the terminal can
- // launch any CLI the user has on PATH, and a missing binary just prints
- // "command not found" (same as typing it).
+ // same distinction for sighted users. Gated by `visibleTerminalClis` (Claude
+ // plus CLIs the probe hasn't ruled out) so an uninstalled CLI doesn't appear
+ // once probed absent; `selectedCli` is kept so the current pick can't be gated
+ // out of its own dropdown. Single install-map source: the launch context.
const cliRows =
terminalLaunch !== null
- ? TERMINAL_CLI_IDS.map((cli) => {
+ ? visibleTerminalClis(terminalLaunch.installedClis, selectedCli).map((cli) => {
const { displayName } = TERMINAL_CLIS[cli];
return {
cli,
diff --git a/packages/app/src/components/TerminalNewChatButton.dom.test.tsx b/packages/app/src/components/TerminalNewChatButton.dom.test.tsx
index c07023b86..231c5edba 100644
--- a/packages/app/src/components/TerminalNewChatButton.dom.test.tsx
+++ b/packages/app/src/components/TerminalNewChatButton.dom.test.tsx
@@ -5,7 +5,10 @@ import userEvent from '@testing-library/user-event';
import { TooltipProvider } from '@/components/ui/tooltip';
import { TerminalNewChatButton, type TerminalNewTabChoice } from './TerminalNewChatButton';
-function renderButton(selected: TerminalNewTabChoice = 'claude') {
+function renderButton(
+ selected: TerminalNewTabChoice = 'claude',
+ visibleClis?: readonly TerminalCli[],
+) {
const onLaunchSelected = mock(() => {});
const onPickCli = mock((_cli: TerminalCli) => {});
const onPickTerminal = mock(() => {});
@@ -16,6 +19,7 @@ function renderButton(selected: TerminalNewTabChoice = 'claude') {
onLaunchSelected={onLaunchSelected}
onPickCli={onPickCli}
onPickTerminal={onPickTerminal}
+ visibleClis={visibleClis}
/>
</TooltipProvider>,
);
@@ -58,6 +62,23 @@ describe('TerminalNewChatButton', () => {
expect(screen.getByRole('menuitem', { name: 'Terminal' })).toBeDefined();
});
+ test('lists only the CLIs in visibleClis (Claude + detected), hiding the rest', async () => {
+ const user = userEvent.setup();
+ // The host passes the already-gated list from `visibleTerminalClis`: Claude
+ // (always-visible anchor) plus detected `codex`. Antigravity/Cursor weren't
+ // detected on PATH, so their rows are absent.
+ renderButton('claude', ['claude', 'codex']);
+
+ await user.click(screen.getByRole('button', { name: 'Choose CLI for new chat' }));
+
+ expect(await screen.findByRole('menuitem', { name: 'Claude CLI' })).toBeDefined();
+ expect(screen.getByRole('menuitem', { name: 'Codex CLI' })).toBeDefined();
+ expect(screen.queryByRole('menuitem', { name: 'Antigravity CLI' })).toBeNull();
+ expect(screen.queryByRole('menuitem', { name: 'Cursor CLI' })).toBeNull();
+ // The bare-shell Terminal row is independent of CLI gating — always present.
+ expect(screen.getByRole('menuitem', { name: 'Terminal' })).toBeDefined();
+ });
+
test('picking a CLI from the dropdown switches the default (persist + launch)', async () => {
const user = userEvent.setup();
const { onPickCli, onLaunchSelected, onPickTerminal } = renderButton('claude');
diff --git a/packages/app/src/components/TerminalNewChatButton.tsx b/packages/app/src/components/TerminalNewChatButton.tsx
index 2deb43312..0b68f4ff5 100644
--- a/packages/app/src/components/TerminalNewChatButton.tsx
+++ b/packages/app/src/components/TerminalNewChatButton.tsx
@@ -32,6 +32,12 @@ interface TerminalNewChatButtonProps {
/** Dropdown "Terminal" row — make a bare shell the new default (persist,
* terminal-only) AND open a new bare-shell tab. */
readonly onPickTerminal: () => void;
+ /** The CLIs to list — already gated by the host via {@link visibleTerminalClis}
+ * (Claude plus CLIs the probe hasn't ruled out, and always the current pick),
+ * so a CLI that's been probed absent doesn't appear. This is a presentational
+ * component: it renders the list as given. Falls back to the full
+ * {@link VISIBLE_CLIS} only for callers/tests that don't pass a gated list. */
+ readonly visibleClis?: readonly TerminalCli[];
readonly className?: string;
}
@@ -50,6 +56,7 @@ export function TerminalNewChatButton({
onLaunchSelected,
onPickCli,
onPickTerminal,
+ visibleClis = VISIBLE_CLIS,
className,
}: TerminalNewChatButtonProps) {
const { t } = useLingui();
@@ -99,7 +106,7 @@ export function TerminalNewChatButton({
<DropdownMenuLabel>
<Trans>New chat</Trans>
</DropdownMenuLabel>
- {VISIBLE_CLIS.map((cli) => {
+ {visibleClis.map((cli) => {
const { displayName: name } = TERMINAL_CLIS[cli];
return (
<DropdownMenuItem
diff --git a/packages/app/src/components/TerminalSessionsHost.tsx b/packages/app/src/components/TerminalSessionsHost.tsx
index 85a6733a7..a2a4fd1e7 100644
--- a/packages/app/src/components/TerminalSessionsHost.tsx
+++ b/packages/app/src/components/TerminalSessionsHost.tsx
@@ -13,6 +13,7 @@ import {
import { loadStickyAgent, saveStickyAgent, terminalCliId } from '@/lib/unified-agent-store';
import { cn } from '@/lib/utils';
import type { TerminalLaunchIntent } from './EditorPane';
+import { visibleTerminalClis } from './handoff/terminal-cli-display';
import { subscribeToActiveTerminalInput } from './handoff/terminal-input-events';
import { requestTerminalLaunch } from './handoff/terminal-launch-events';
import { TerminalGate } from './TerminalGate';
@@ -286,6 +287,10 @@ export function TerminalSessionsHost({
);
const newChatDefaultCli = resolveDefaultCli(stickyCliId, installedClis ?? {});
const newChatSelected: TerminalNewTabChoice = preferBareTerminal ? 'terminal' : newChatDefaultCli;
+ // Gate the New-chat dropdown rows to Claude + CLIs the probe hasn't ruled out,
+ // keeping the resolved default (`newChatDefaultCli`) so the split button's
+ // current pick is always present in its own dropdown (with its checkmark).
+ const newChatVisibleClis = visibleTerminalClis(installedClis ?? {}, newChatDefaultCli);
// Tab-strip New-chat primary: open a promptless session running `cli`.
function openNewChatSession(cli: TerminalCli) {
@@ -718,6 +723,7 @@ export function TerminalSessionsHost({
onNewChatLaunch={launchSelectedNewTab}
onNewChatPickCli={pickNewChatCli}
onNewChatPickTerminal={pickNewChatTerminal}
+ newChatVisibleClis={newChatVisibleClis}
onClose={closeSession}
onRename={setSessionCustomLabel}
// Pointer-drag reorder: the strip computes the new visual order and the
diff --git a/packages/app/src/components/TerminalTabStrip.tsx b/packages/app/src/components/TerminalTabStrip.tsx
index e7fae9095..de700524b 100644
--- a/packages/app/src/components/TerminalTabStrip.tsx
+++ b/packages/app/src/components/TerminalTabStrip.tsx
@@ -114,6 +114,10 @@ interface TerminalTabStripProps {
readonly onNewChatPickCli: (cli: TerminalCli) => void;
/** Dropdown "Terminal" — persist a bare shell as the default AND open one. */
readonly onNewChatPickTerminal: () => void;
+ /** CLIs to list in the New-chat dropdown — Claude plus PATH-detected CLIs
+ * (resolved by the host), so an uninstalled CLI doesn't appear unless
+ * detected. Optional: the button falls back to the full list. */
+ readonly newChatVisibleClis?: readonly TerminalCli[];
/** Fires with the session id when the user closes a tab. */
readonly onClose: (id: string) => void;
/**
@@ -201,6 +205,7 @@ export function TerminalTabStrip({
onNewChatLaunch,
onNewChatPickCli,
onNewChatPickTerminal,
+ newChatVisibleClis,
onClose,
onRename,
onReorder,
@@ -499,6 +504,7 @@ export function TerminalTabStrip({
onLaunchSelected={onNewChatLaunch}
onPickCli={onNewChatPickCli}
onPickTerminal={onNewChatPickTerminal}
+ visibleClis={newChatVisibleClis}
className={cn('shrink-0', draggable && '[-webkit-app-region:no-drag]')}
/>
{/* Spacer pushes the trailing controls to the far right. */}
diff --git a/packages/app/src/components/empty-state/CreatePromptComposer.dom.test.tsx b/packages/app/src/components/empty-state/CreatePromptComposer.dom.test.tsx
index 6d8094e02..6d6d8171e 100644
--- a/packages/app/src/components/empty-state/CreatePromptComposer.dom.test.tsx
+++ b/packages/app/src/components/empty-state/CreatePromptComposer.dom.test.tsx
@@ -153,7 +153,7 @@ async function renderComposer(
opts: { withTerminal: boolean; scenario?: CreateScenario } = { withTerminal: true },
) {
const value = opts.withTerminal
- ? { launchInTerminal: (i: HandoffDispatchInput) => launchCalls.push(i) }
+ ? { launchInTerminal: (i: HandoffDispatchInput) => launchCalls.push(i), installedClis: {} }
: null;
render(
<TerminalLaunchProvider value={value}>
diff --git a/packages/app/src/components/empty-state/CreatePromptComposer.tsx b/packages/app/src/components/empty-state/CreatePromptComposer.tsx
index 4835bde68..966bd8c66 100644
--- a/packages/app/src/components/empty-state/CreatePromptComposer.tsx
+++ b/packages/app/src/components/empty-state/CreatePromptComposer.tsx
@@ -14,7 +14,7 @@ import {
import { focusComposerInputOnCardPointer } from '@/components/focus-composer-on-card-pointer';
import { TargetIcon } from '@/components/handoff/OpenInAgentMenuItem';
import { useTerminalLaunch } from '@/components/handoff/TerminalLaunchContext';
-import { cliIconTargetId, VISIBLE_CLIS } from '@/components/handoff/terminal-cli-display';
+import { cliIconTargetId, visibleTerminalClis } from '@/components/handoff/terminal-cli-display';
import {
buildCreateHandoffInput,
getDisplayNameDefault,
@@ -289,6 +289,12 @@ export function CreatePromptComposer({ scenario, className }: CreatePromptCompos
// under "Terminal". The separator sits between them only when both render.
const showDesktopSection = selectableTargets.length > 0;
const showTerminalSection = terminalLaunch !== null;
+ // Claude plus every CLI the probe hasn't ruled out (fail-open), and always the
+ // current pick (`selectedCli`) so this composer's own Create target can't be
+ // gated out of its own dropdown.
+ const terminalClis = terminalLaunch
+ ? visibleTerminalClis(terminalLaunch.installedClis, selectedCli)
+ : [];
return (
<div className={cn('flex w-full flex-col gap-3', className)}>
@@ -402,7 +408,7 @@ export function CreatePromptComposer({ scenario, className }: CreatePromptCompos
brand name while the accessible name is "<Brand> CLI" so AT
users can tell it apart from the matching Desktop row (WCAG
2.5.3 — the name contains the visible label). */}
- {VISIBLE_CLIS.map((cli) => {
+ {terminalClis.map((cli) => {
const { displayName } = TERMINAL_CLIS[cli];
return (
<DropdownMenuItem
diff --git a/packages/app/src/components/handoff/OpenInAgentContextSubmenu.dom.test.tsx b/packages/app/src/components/handoff/OpenInAgentContextSubmenu.dom.test.tsx
index 382ac84ff..f34606f67 100644
--- a/packages/app/src/components/handoff/OpenInAgentContextSubmenu.dom.test.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentContextSubmenu.dom.test.tsx
@@ -92,7 +92,10 @@ async function renderSubmenu({
render(
withTerminal ? (
<TerminalLaunchProvider
- value={{ launchInTerminal: (i, cli) => launchCalls.push({ input: i, cli }) }}
+ value={{
+ launchInTerminal: (i, cli) => launchCalls.push({ input: i, cli }),
+ installedClis: {},
+ }}
>
{submenu}
</TerminalLaunchProvider>
diff --git a/packages/app/src/components/handoff/OpenInAgentContextSubmenu.tsx b/packages/app/src/components/handoff/OpenInAgentContextSubmenu.tsx
index 5fd2d36e1..a951e7be9 100644
--- a/packages/app/src/components/handoff/OpenInAgentContextSubmenu.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentContextSubmenu.tsx
@@ -5,9 +5,9 @@
* Behavior:
* - Render only targets where `installStates[t.id].installed === true`.
* - Installed app launchers sit under a "Desktop" section label; the docked
- * terminal launchers — one row per agent CLI in `VISIBLE_CLIS` (Claude,
- * Codex, Cursor) — sit under a "Terminal" section label, gated on a desktop
- * terminal bridge.
+ * terminal launchers — one row per PATH-gated CLI (`visibleTerminalClis`:
+ * Claude plus CLIs the probe hasn't ruled out) — sit under a "Terminal"
+ * section label, gated on a desktop terminal bridge.
* - Empty state: when no targets are install-detected and there is no
* terminal launcher, render a disabled "No installed agents found" item
* (no section labels then).
@@ -50,7 +50,7 @@ import { useIsEmbedded } from '@/hooks/use-is-embedded';
import { VISIBLE_TARGETS } from '@/lib/handoff/targets';
import { TargetIcon } from './OpenInAgentMenuItem';
import { useTerminalLaunch } from './TerminalLaunchContext';
-import { cliIconTargetId, VISIBLE_CLIS } from './terminal-cli-display';
+import { cliIconTargetId, visibleTerminalClis } from './terminal-cli-display';
import type { HandoffDispatchInput } from './useHandoffDispatch';
/**
@@ -109,6 +109,9 @@ export function OpenInAgentContextSubmenu(props: OpenInAgentContextSubmenuProps)
// When nothing is install-detected and there's no terminal launcher to fall
// back on, surface a disabled hint rather than an empty flyout.
const showEmptyHint = !showDesktopSection && !showTerminalSection;
+ // Claude plus every CLI the probe hasn't ruled out (fail-open); no "current
+ // pick" to preserve on this launch-only submenu, so no `keep`.
+ const terminalClis = terminalLaunch ? visibleTerminalClis(terminalLaunch.installedClis) : [];
return (
<DropdownMenuSub>
@@ -131,7 +134,7 @@ export function OpenInAgentContextSubmenu(props: OpenInAgentContextSubmenuProps)
(plus the "No workspace" hint when input is missing), so it
contains the visible label and AT users can tell it apart from a
Desktop row (WCAG 2.5.3 — name contains visible label). */}
- {VISIBLE_CLIS.map((cli) => {
+ {terminalClis.map((cli) => {
const { displayName } = TERMINAL_CLIS[cli];
return (
<DropdownMenuItem
diff --git a/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.dom.test.tsx b/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.dom.test.tsx
index 3453c2338..6e7f59959 100644
--- a/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.dom.test.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.dom.test.tsx
@@ -89,7 +89,10 @@ async function renderSubmenu({
render(
withTerminal ? (
<TerminalLaunchProvider
- value={{ launchInTerminal: (i, cli) => launchCalls.push({ input: i, cli }) }}
+ value={{
+ launchInTerminal: (i, cli) => launchCalls.push({ input: i, cli }),
+ installedClis: {},
+ }}
>
{menu}
</TerminalLaunchProvider>
diff --git a/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx b/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
index 7d47633cf..efc88b2be 100644
--- a/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
@@ -11,8 +11,8 @@
* because Radix submenus inherit roving focus from their parent root primitive.
*
* Installed app launchers sit under a "Desktop" section label; the docked
- * terminal launchers — one row per agent CLI in `VISIBLE_CLIS` (Claude, Codex,
- * Cursor) — sit under a "Terminal" section label.
+ * terminal launchers — one row per PATH-gated CLI (`visibleTerminalClis`: Claude
+ * plus CLIs the probe hasn't ruled out) — sit under a "Terminal" section label.
*
* When there is nothing to render (no installed targets and no terminal
* launcher), the entire submenu is hidden so the user doesn't land on an empty
@@ -42,7 +42,7 @@ import { useIsEmbedded } from '@/hooks/use-is-embedded';
import { VISIBLE_TARGETS } from '@/lib/handoff/targets';
import { TargetIcon } from './OpenInAgentMenuItem';
import { useTerminalLaunch } from './TerminalLaunchContext';
-import { cliIconTargetId, VISIBLE_CLIS } from './terminal-cli-display';
+import { cliIconTargetId, visibleTerminalClis } from './terminal-cli-display';
import type { HandoffDispatchInput } from './useHandoffDispatch';
/** Status hint shown alongside per-target rows when the input is not ready
@@ -97,6 +97,9 @@ export function OpenInAgentEmptySpaceSubmenu(props: OpenInAgentEmptySpaceSubmenu
if (!showDesktopSection && !showTerminalSection) {
return null;
}
+ // Claude plus every CLI the probe hasn't ruled out (fail-open); launch-only
+ // submenu with no "current pick" to preserve, so no `keep`.
+ const terminalClis = terminalLaunch ? visibleTerminalClis(terminalLaunch.installedClis) : [];
return (
<ContextMenuSub>
@@ -119,7 +122,7 @@ export function OpenInAgentEmptySpaceSubmenu(props: OpenInAgentEmptySpaceSubmenu
workspace" hint when input is missing), so it contains the
visible label and AT users can tell it apart from a Desktop row
(WCAG 2.5.3 — name contains visible label). */}
- {VISIBLE_CLIS.map((cli) => {
+ {terminalClis.map((cli) => {
const { displayName } = TERMINAL_CLIS[cli];
return (
<ContextMenuItem
diff --git a/packages/app/src/components/handoff/OpenInAgentMenu.dom.test.tsx b/packages/app/src/components/handoff/OpenInAgentMenu.dom.test.tsx
index 23e38f51b..ca9f4dae2 100644
--- a/packages/app/src/components/handoff/OpenInAgentMenu.dom.test.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentMenu.dom.test.tsx
@@ -75,7 +75,10 @@ async function renderMenuWithTerminal(menuInput: HandoffDispatchInput | null = i
render(
<TooltipProvider>
<TerminalLaunchProvider
- value={{ launchInTerminal: (i, cli) => launchCalls.push({ input: i, cli }) }}
+ value={{
+ launchInTerminal: (i, cli) => launchCalls.push({ input: i, cli }),
+ installedClis: {},
+ }}
>
<OpenInAgentMenu input={menuInput} />
</TerminalLaunchProvider>
diff --git a/packages/app/src/components/handoff/OpenInAgentMenu.tsx b/packages/app/src/components/handoff/OpenInAgentMenu.tsx
index 9113597a2..ed175bc53 100644
--- a/packages/app/src/components/handoff/OpenInAgentMenu.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentMenu.tsx
@@ -15,10 +15,10 @@
* - Render only targets where `states[t.id]?.installed === true`, scoped to
* `VISIBLE_TARGETS`.
* - Installed app launchers sit under a "Desktop" section label; the docked
- * terminal launchers — one row per agent CLI in `VISIBLE_CLIS` (Claude,
- * Codex, Cursor), each with a "<Brand> CLI" accessible name — sit under a
- * "Terminal" section label. The terminal section is absent on the web host
- * (`useTerminalLaunch()` is null — no shell).
+ * terminal launchers — one row per PATH-gated CLI (`visibleTerminalClis`:
+ * Claude plus CLIs the probe hasn't ruled out), each with a "<Brand> CLI"
+ * accessible name — sit under a "Terminal" section label. The terminal
+ * section is absent on the web host (`useTerminalLaunch()` is null — no shell).
* - Empty state: when nothing is install-detected and there is no terminal
* launcher, render a "No installed agents found" hint (no section labels).
*
@@ -44,7 +44,7 @@ import { useIsEmbedded } from '@/hooks/use-is-embedded';
import { VISIBLE_TARGETS } from '@/lib/handoff/targets';
import { TargetIcon } from './OpenInAgentMenuItem';
import { type TerminalLaunchContextValue, useTerminalLaunch } from './TerminalLaunchContext';
-import { cliIconTargetId, VISIBLE_CLIS } from './terminal-cli-display';
+import { cliIconTargetId, visibleTerminalClis } from './terminal-cli-display';
import { type HandoffDispatchInput, useHandoffDispatch } from './useHandoffDispatch';
import { useInstalledAgents } from './useInstalledAgents';
@@ -101,6 +101,9 @@ function OpenWithAiPanel({
const showDesktopSection = installedTargets.length > 0;
const showTerminalSection = terminalLaunch !== null;
const hasRows = showDesktopSection || showTerminalSection;
+ // Claude plus every CLI the probe hasn't ruled out (fail-open). No `keep`:
+ // this popover launches, it doesn't show a "current pick" to preserve.
+ const terminalClis = terminalLaunch ? visibleTerminalClis(terminalLaunch.installedClis) : [];
return (
<div className="flex flex-col gap-1">
@@ -129,7 +132,7 @@ function OpenWithAiPanel({
>
<Trans>Terminal</Trans>
</legend>
- {VISIBLE_CLIS.map((cli) => {
+ {terminalClis.map((cli) => {
const { displayName } = TERMINAL_CLIS[cli];
return (
<Button
diff --git a/packages/app/src/components/handoff/OpenInAgentTerminalRow.dom.test.tsx b/packages/app/src/components/handoff/OpenInAgentTerminalRow.dom.test.tsx
index 94af9fe6c..d65e384ee 100644
--- a/packages/app/src/components/handoff/OpenInAgentTerminalRow.dom.test.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentTerminalRow.dom.test.tsx
@@ -62,10 +62,21 @@ type LaunchCall = { input: HandoffDispatchInput; cli: TerminalCli };
async function renderMenu(opts: {
launcher: ((input: HandoffDispatchInput, cli: TerminalCli) => void) | null;
menuInput?: HandoffDispatchInput | null;
+ // The raw PATH-detection map the production provider supplies. The component
+ // gates its own rows via `visibleTerminalClis`, so feeding the map here (not a
+ // pre-gated list) exercises that production wiring. Defaults to `{}` (probe
+ // unresolved → fail-open, every CLI shown).
+ installedClis?: Partial<Record<TerminalCli, boolean>>;
}) {
const menuInput = 'menuInput' in opts ? opts.menuInput : input;
render(
- <TerminalLaunchProvider value={opts.launcher ? { launchInTerminal: opts.launcher } : null}>
+ <TerminalLaunchProvider
+ value={
+ opts.launcher
+ ? { launchInTerminal: opts.launcher, installedClis: opts.installedClis ?? {} }
+ : null
+ }
+ >
<OpenInAgentMenu input={menuInput ?? null} />
</TerminalLaunchProvider>,
);
@@ -91,6 +102,39 @@ describe('Open-with-AI Terminal CLI rows', () => {
expect(screen.getByTestId('open-in-agent-terminal-cursor')).toBeTruthy();
});
+ test('gates rows through the real probe map: Claude always, detected shown, probed-absent hidden', async () => {
+ // A complete resolved map: only `codex` on PATH. The component runs
+ // `visibleTerminalClis` itself, so this exercises the production wiring —
+ // Claude (always-visible anchor) plus `codex`; Cursor and Antigravity are
+ // probed absent (`false`), so their rows are gone.
+ await renderMenu({
+ launcher: () => {},
+ installedClis: {
+ claude: false,
+ codex: true,
+ opencode: false,
+ cursor: false,
+ pi: false,
+ antigravity: false,
+ },
+ });
+ await openMenu();
+ expect(screen.getByTestId('open-in-agent-terminal-claude')).toBeTruthy();
+ expect(screen.getByTestId('open-in-agent-terminal-codex')).toBeTruthy();
+ expect(screen.queryByTestId('open-in-agent-terminal-antigravity')).toBeNull();
+ expect(screen.queryByTestId('open-in-agent-terminal-cursor')).toBeNull();
+ });
+
+ test('fails open before the probe resolves (empty map) — installed CLIs stay launchable', async () => {
+ // Regression guard for the "probe failed / older bridge hides everything"
+ // defect: an empty map must show every CLI, not collapse to Claude-only.
+ await renderMenu({ launcher: () => {}, installedClis: {} });
+ await openMenu();
+ expect(screen.getByTestId('open-in-agent-terminal-claude')).toBeTruthy();
+ expect(screen.getByTestId('open-in-agent-terminal-codex')).toBeTruthy();
+ expect(screen.getByTestId('open-in-agent-terminal-cursor')).toBeTruthy();
+ });
+
test('hides the terminal section when no launcher is available (web host)', async () => {
await renderMenu({ launcher: null });
await openMenu();
diff --git a/packages/app/src/components/handoff/TerminalLaunchContext.tsx b/packages/app/src/components/handoff/TerminalLaunchContext.tsx
index f57263738..6b675970c 100644
--- a/packages/app/src/components/handoff/TerminalLaunchContext.tsx
+++ b/packages/app/src/components/handoff/TerminalLaunchContext.tsx
@@ -25,6 +25,15 @@ export interface TerminalLaunchContextValue {
* (deep-link parity). Human-only — driven by a UI click.
*/
readonly launchInTerminal: (input: HandoffDispatchInput, cli: TerminalCli) => void;
+ /**
+ * The PATH-detection map from the desktop probe — which launchable CLIs are on
+ * PATH. The single source every launch surface gates its rows from: each passes
+ * it through {@link visibleTerminalClis} (with its own current pick as `keep`)
+ * so gating logic lives in ONE place and can't drift between surfaces. A partial
+ * map: `undefined` = unknown/unresolved (shown, fail-open), `false` = probed
+ * absent (hidden), `true` = detected. Provided by `App.tsx` from the live probe.
+ */
+ readonly installedClis: Partial<Record<TerminalCli, boolean>>;
}
const TerminalLaunchContext = createContext<TerminalLaunchContextValue | null>(null);
diff --git a/packages/app/src/components/handoff/terminal-cli-display.test.ts b/packages/app/src/components/handoff/terminal-cli-display.test.ts
new file mode 100644
index 000000000..b19825afb
--- /dev/null
+++ b/packages/app/src/components/handoff/terminal-cli-display.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'bun:test';
+import { TERMINAL_CLI_IDS } from '@inkeep/open-knowledge-core';
+import { visibleTerminalClis } from './terminal-cli-display';
+
+/** A complete resolved probe map (every CLI keyed), all reported absent. Matches
+ * the shape `resolveCliInstalledMap` returns — the renderer only ever sees a
+ * complete map or the empty `{}` (unresolved). */
+const allAbsent = Object.fromEntries(TERMINAL_CLI_IDS.map((cli) => [cli, false]));
+
+describe('visibleTerminalClis', () => {
+ it('fails open on the empty map (probe unresolved / failed / older bridge)', () => {
+ // Regression guard: an empty map is "unknown", NOT "none installed". Hiding
+ // here would silently drop genuinely-installed CLIs from every launch surface
+ // for the whole session whenever the probe never resolves.
+ expect(visibleTerminalClis({})).toEqual([...TERMINAL_CLI_IDS]);
+ });
+
+ it('hides only CLIs the probe positively reports absent', () => {
+ expect(visibleTerminalClis({ ...allAbsent, codex: true, cursor: true })).toEqual([
+ 'claude',
+ 'codex',
+ 'cursor',
+ ]);
+ });
+
+ it('always keeps Claude — the install-nudge anchor — even when probed absent', () => {
+ expect(visibleTerminalClis(allAbsent)).toEqual(['claude']);
+ });
+
+ it('keeps `keep` (the current pick) even when probed absent', () => {
+ // A picker's own selected CLI must stay in its dropdown so it can be re-picked
+ // and shows its checkmark, even if the probe says it's not on PATH.
+ expect(visibleTerminalClis(allAbsent, 'codex')).toEqual(['claude', 'codex']);
+ });
+
+ it('preserves TERMINAL_CLI_IDS launch order', () => {
+ const allInstalled = Object.fromEntries(TERMINAL_CLI_IDS.map((cli) => [cli, true]));
+ expect(visibleTerminalClis(allInstalled)).toEqual([...TERMINAL_CLI_IDS]);
+ });
+});
diff --git a/packages/app/src/components/handoff/terminal-cli-display.ts b/packages/app/src/components/handoff/terminal-cli-display.ts
index f77a78aaf..c9450c7f1 100644
--- a/packages/app/src/components/handoff/terminal-cli-display.ts
+++ b/packages/app/src/components/handoff/terminal-cli-display.ts
@@ -1,8 +1,9 @@
/**
- * Shared display data for the docked-terminal CLI launch rows, so all four
- * "Open with AI" surfaces (header popover + the two right-click submenus + the
- * empty-state create composer) render the same set of CLIs in the same order
- * with the same brand icon and accessible name.
+ * Shared display data for the docked-terminal CLI launch rows, so every
+ * "Open with AI" / New-chat surface (header popover + the two right-click
+ * submenus + the empty-state create composer + the composer "Ask" split button +
+ * the tab-strip New-chat dropdown) renders the CLIs in the same order with the
+ * same brand icon and accessible name, gated the same way by {@link visibleTerminalClis}.
*/
import {
type HandoffTarget,
@@ -11,9 +12,46 @@ import {
type TerminalCli,
} from '@inkeep/open-knowledge-core';
-/** CLIs shown under the "Terminal" section, in launch order. */
+/** CLIs shown under the "Terminal" section, in launch order — the full set,
+ * before PATH-detection gating. Callers pass the installed-CLI map through
+ * {@link visibleTerminalClis} to drop CLIs that aren't installed. */
export const VISIBLE_CLIS: readonly TerminalCli[] = TERMINAL_CLI_IDS;
+/** Terminal CLIs surfaced as launch rows even when NOT detected on PATH. Claude
+ * is the install-nudge anchor: it's the default-CLI fallback (`resolveDefaultCli`)
+ * and has a "Get Claude" missing-CLI banner, so keeping its row is a discoverable
+ * install affordance rather than a dead end. Every other CLI is offered only once
+ * detected — a niche CLI (e.g. Antigravity) shouldn't clutter the menu for users
+ * who don't have it. */
+const ALWAYS_VISIBLE_CLIS: ReadonlySet<TerminalCli> = new Set<TerminalCli>(['claude']);
+
+/**
+ * The launch-row CLIs to show given the PATH-detection map, in
+ * {@link TERMINAL_CLI_IDS} launch order. Fails OPEN: a CLI is hidden only when
+ * the probe positively reports it absent (`installed[cli] === false`). Shown
+ * otherwise — always-visible anchors (Claude), `keep` (the current pick), any
+ * detected CLI, and — critically — any CLI whose state is still UNKNOWN.
+ *
+ * "Unknown" is `installed[cli] === undefined`. A resolved probe map is complete
+ * (every CLI keyed true/false — see `resolveCliInstalledMap`), so an undefined
+ * entry means the probe hasn't resolved yet, failed, or the desktop bridge is
+ * too old to expose it. Hiding on unknown would make a probe failure or a
+ * renderer/main version skew silently drop genuinely-installed CLIs from every
+ * launch surface for the whole session; failing open keeps them launchable (the
+ * pre-gating behavior) and lets the row settle once the probe confirms absence.
+ *
+ * @param keep the current pick (sticky/default CLI) — never hidden, even when
+ * probed absent, so a picker's dropdown always contains its own selected row.
+ */
+export function visibleTerminalClis(
+ installed: Partial<Record<TerminalCli, boolean>>,
+ keep?: TerminalCli | null,
+): readonly TerminalCli[] {
+ return TERMINAL_CLI_IDS.filter(
+ (cli) => ALWAYS_VISIBLE_CLIS.has(cli) || cli === keep || installed[cli] !== false,
+ );
+}
+
/** CLI id → the handoff target id whose brand icon `TargetIcon` renders. Reads
* the single source of truth on the registry (shared with prompt composition)
* rather than a parallel local map. */
diff --git a/packages/app/src/hooks/use-installed-clis.ts b/packages/app/src/hooks/use-installed-clis.ts
index c1899604b..221656224 100644
--- a/packages/app/src/hooks/use-installed-clis.ts
+++ b/packages/app/src/hooks/use-installed-clis.ts
@@ -3,14 +3,21 @@ import { useEffect, useState } from 'react';
/**
* Which launchable CLIs are on PATH, from the desktop probe (cached ~60s in
- * main). Shared by every default-CLI entry point — the header / tab-strip
- * "New chat" and the "Ask X" bubble — so they resolve the same installed set.
+ * main). Shared by every launch entry point — the header / tab-strip "New chat",
+ * the "Ask X" bubble, and the Open-with-AI menus — so they resolve and gate the
+ * same installed set.
*
- * Starts empty (unknown, not "none installed") until the async probe resolves;
- * `resolveDefaultCli` treats an unknown key optimistically. Capability-guarded:
- * a partial/older bridge, or the web host with no `terminal` surface, leaves the
- * map empty, and a probe failure degrades silently to "none installed" (New chat
- * then defaults to claude and the existing install banner handles the miss).
+ * Starts empty (unknown, not "none installed") until the async probe resolves.
+ * A partial/older bridge, the web host with no `terminal` surface, or a probe
+ * failure leaves keys `undefined` (unknown). Consumers must NOT read unknown as
+ * "absent": `resolveDefaultCli` treats it optimistically, and `visibleTerminalClis`
+ * fails open (an unknown CLI still renders), so a probe miss never silently drops
+ * an installed CLI from the launch surfaces for the whole session.
+ *
+ * Re-probes when the window regains focus so a CLI installed mid-session (the
+ * user left to a terminal/installer and came back) appears without an app
+ * restart, and a transient probe failure or a cold empty map self-heals. The
+ * main-process 60s cache keeps repeat focus events cheap.
*/
export function useInstalledClis(): Partial<Record<TerminalCli, boolean>> {
const [installedClis, setInstalledClis] = useState<Partial<Record<TerminalCli, boolean>>>({});
@@ -21,18 +28,23 @@ export function useInstalledClis(): Partial<Record<TerminalCli, boolean>> {
// synchronous "not a function" the .catch can't intercept.
if (typeof terminal?.cliInstalledMap !== 'function') return;
let cancelled = false;
- void terminal
- .cliInstalledMap()
- .then((map) => {
- if (!cancelled) setInstalledClis(map);
- })
- .catch((err) => {
- // Recoverable: the resolver degrades to "none installed" → claude default.
- // warn + [terminal] matches the terminal surface's probe-failure convention.
- console.warn('[terminal] cliInstalledMap probe failed; defaulting to none installed:', err);
- });
+ const probe = () => {
+ void terminal
+ .cliInstalledMap()
+ .then((map) => {
+ if (!cancelled) setInstalledClis(map);
+ })
+ .catch((err) => {
+ // Recoverable: unknown keys stay unknown (fail-open visibility; claude
+ // auto-pick default). warn + [terminal] matches the surface convention.
+ console.warn('[terminal] cliInstalledMap probe failed:', err);
+ });
+ };
+ probe();
+ window.addEventListener('focus', probe);
return () => {
cancelled = true;
+ window.removeEventListener('focus', probe);
};
}, []);
return installedClis;