Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Correct the agent-picker docs and comments against the shipped menu (#3804)

Nick Gomezb1e619f5b496
diff --git a/.changeset/acp-picker-docs-accuracy.md b/.changeset/acp-picker-docs-accuracy.md
new file mode 100644
index 000000000..3fe311192
--- /dev/null
+++ b/.changeset/acp-picker-docs-accuracy.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Documentation: the editor's agent-handoff reference now matches the picker that ships. It names the **External apps** rows as they render (**Claude Desktop**, **ChatGPT Desktop**, **Cursor Desktop**), says that the terminal tab strip's **+** dropdown both switches what a new tab starts and opens one, and states how detection and **Configure agents** combine — detection supplies each section's default, including **In app**, and **Configure agents** overrides that default in both directions. No behavior changed.
diff --git a/docs/content/features/editor.mdx b/docs/content/features/editor.mdx
index babcd8f61..8dca74644 100644
--- a/docs/content/features/editor.mdx
+++ b/docs/content/features/editor.mdx
@@ -92,7 +92,7 @@ Surfaces with their own specialized right-click menus — asset and wiki-link ch
An **Ask AI** composer is docked at the bottom of the editor — in the desktop app and in a regular browser — whenever a doc or folder view is open. It's a slim, single-line entry field that expands as you type to accept a fuller prompt (and `@`-mentions); in the desktop app, `Cmd+L` opens and focuses it. Type an instruction — "condense this doc", "research X", "make a spec from this user story" — and press Enter to hand it to an agent. `Shift+Enter` inserts a newline; the field clears once the prompt is sent.
-It's the primary in-editor way to hand work to an agent, and the freetext companion to the menu-driven [Open with AI](#open-with-ai) (whole file / folder / project). Submitting dispatches the typed prompt to your **default agent**, scoped to the current doc (or, in a folder view, the folder), which the agent receives as an `@`-mention. Until you pick something else, that default is an **In app** agent, so the conversation stays inside OpenKnowledge; it falls back to a **Terminal** CLI, and then to an **External app**, when no higher option is available here. The agent picker beside the field overrides the default per send, listing In app agents first, then the [Terminal](#open-with-ai) CLIs available on this machine (desktop app only), then the external agent apps detected here. Whatever you pick is remembered on that machine and stays your default until you change it or turn it off in **Configure agents**. Success and failure use the same handoff toast as Open with AI.
+It's the primary in-editor way to hand work to an agent, and the freetext companion to the menu-driven [Open with AI](#open-with-ai) (whole file / folder / project). Submitting dispatches the typed prompt to your **default agent**, scoped to the current doc (or, in a folder view, the folder), which the agent receives as an `@`-mention. Until you pick something else, that default is an **In app** agent, so the conversation stays inside OpenKnowledge; it falls back to a **Terminal** CLI — preferring one detected on this machine — and then to an **External app**, when no higher option is available here. The agent picker beside the field overrides the default per send, listing In app agents first, then the [Terminal](#open-with-ai) CLIs available on this machine (macOS and Linux desktop apps), then the external agent apps detected here. Whatever you pick is remembered on that machine and stays your default until you change it or turn it off in **Configure agents**. Success and failure use the same handoff toast as Open with AI.
The composer stays out of the way where it doesn't belong: it's hidden inside an AI editor's embedded view, while the [docked terminal](#terminal) is open (the terminal is its own AI entry point), and when no doc or folder is open (the empty state already offers project handoff). It's also dismissible — an **Ask AI** badge in the status bar brings it back.
@@ -104,7 +104,7 @@ Select text in the WYSIWYG editor and the selection bubble menu shows a **Commen
The desktop app on macOS and Linux has a built-in terminal with real interactive shells inside the editor window. On Linux, OpenKnowledge inherits Electron's supported distribution range: releases of the major distributions that both Chromium and the distribution vendor still support. Toggle it with `Cmd+J` on macOS or `Ctrl+J` on Linux, with `` Ctrl+` `` on either platform (which also works from inside a focused terminal), or with **View ▸ Show / Hide Terminal**. It opens at the placement saved for this installation (the bottom dock by default). Right-click a bottom-dock tab and choose **Move to right panel**, use the matching command in the command palette or **Terminal** menu, or use the right-panel header button to move it back to the bottom. Moving or hiding the Terminal keeps its live shells, tabs, and scrollback intact.
-The terminal is also the editor's AI-chat surface: opening it starts your default CLI when no session is open, and the tab strip's **New chat** split button opens another CLI tab — its dropdown switches CLI (the pick sticks, shared with the Ask AI composer) or opens a plain shell tab. With text selected in the editor, `Cmd+J` on macOS, `Ctrl+J` on Linux, and `` Ctrl+` `` on either platform stage the passage into the active CLI's input (or open a new CLI tab when none is running) instead of toggling — they share one handler. `Cmd+Shift+J` on macOS or `Ctrl+Shift+J` on Linux always stages it into a new CLI tab; the passage sits in the input for you to add to, and nothing is submitted until you press Enter. **Terminal ▸ New Terminal Window** (see [Terminal menu](#terminal-menu)) opens a dedicated window with the same multi-session tabs, `Cmd+<number>` tab switching, and shells starting at the project root.
+The terminal is also the editor's AI-chat surface: opening it starts your remembered CLI pick, or a plain shell when you have none, and the tab strip's **+** button opens another tab with whatever you picked last — a CLI chat or a plain shell. Its dropdown switches that pick and opens a tab in the thing you picked, in one action. A CLI pick sticks and is shared with the Ask AI composer; the plain-shell pick is remembered for the terminal only. In-app agents run in the Agents panel, which has its own tab strip and **+** button; picking an agent there sticks the same way and also becomes your Ask AI default. With text selected in the editor, `Cmd+J` on macOS, `Ctrl+J` on Linux, and `` Ctrl+` `` on either platform stage the passage into the active CLI's input (or open a new CLI tab when none is running) instead of toggling — they share one handler. `Cmd+Shift+J` on macOS or `Ctrl+Shift+J` on Linux always stages it into a new CLI tab; the passage sits in the input for you to add to, and nothing is submitted until you press Enter. **Terminal ▸ New Terminal Window** (see [Terminal menu](#terminal-menu)) opens a dedicated window with the same multi-session tabs, `Cmd+<number>` tab switching, and shells starting at the project root.
Rename a tab by double-clicking it or pressing `F2`; the name you set pins over whatever title the running program reports, and clearing it falls back to that title. Reorder tabs by dragging, or move the active tab with `Cmd+Shift+←` / `Cmd+Shift+→` — untitled tabs keep a number that stays with their session as the strip is rearranged.
@@ -188,11 +188,11 @@ The trailing `Open the OK editor in web view.` directive is dropped when the [`a
To send your own freetext instruction along with the handoff, use the bottom [Ask AI](#ask-ai) composer (or the empty-state create composer on a fresh project) rather than these one-click submenus.
-**Install detection** filters the Terminal and External apps sections to the agents you actually have; **Settings → Configure agents** decides which of those — and which In app agents — appear at all. The desktop app probes locally; the web build asks the server (`GET /api/installed-agents`), so the answer reflects the machine the server runs on — exact on `localhost`, while against a remote server (a hosted preview, SSH tunnel, remote dev) it's the server's installs that count. In app agents don't ride on that probe: they're server-hosted, so they're available wherever OpenKnowledge is. When nothing is enabled or detected, the submenu is just the **Configure agents** row.
+**Install detection** supplies the defaults for all three sections: Terminal and External apps rows probe for the CLI or app itself, and In app rows probe for the agent's underlying CLI — and for an agent whose sign-in lives where OpenKnowledge can read it (Codex today, through the namespace it shares with the Codex CLI), an existing sign-in counts on its own even with no CLI installed. **Settings → Configure agents** overrides those defaults in both directions — turn off something detected, or turn on something you haven't installed yet. **Terminal** rows always use the desktop app's own PATH probe. For **External apps** the desktop app checks the OS protocol handlers locally, while the web build asks the server (`GET /api/installed-agents`), so that answer reflects the machine the server runs on — exact on `localhost`, but against a remote server (a hosted preview, SSH tunnel, remote dev) it's the server's installs that count. The **In app** signal is always the server's: it rides the agent catalog, not either probe. When nothing is enabled or detected, the submenu is just the **Configure agents** row.
See the [per-integration pages](../integrations/claude-code.mdx) for what each agent receives once dispatched.
-The menu is organized into three sections, in the order the default follows. **In app** leads: a row for each in-app agent you've enabled, which opens the conversation in OpenKnowledge's Agents panel without leaving the app. **Terminal** (macOS and Linux desktop apps) follows: a row for every agent CLI OpenKnowledge can launch — **Claude**, **Codex**, **OpenCode**, **Cursor**, **GitHub Copilot**, **Pi**, **Antigravity**, **OpenClaw**, and **Hermes** — each running its own command in OpenKnowledge's [docked terminal](#terminal) with the same scoped prompt. A CLI the PATH probe reports absent is hidden. **External apps** comes last, listing the agent apps detected on this machine (Claude, Codex, Cursor); selecting one launches it via its deep link and hands the work out of OpenKnowledge. Because the sections can list the same name, a Terminal **Claude** (the CLI) and an External **Claude** (the app) can appear together; screen readers tell them apart by the Terminal row's "Claude CLI" accessible name. Each section renders only when it has something to launch, so on the web build and in the Windows app, which has no docked terminal, the Terminal section is absent, and a saved CLI pick degrades to the same order the default follows: an In app agent when one is available, otherwise an external app. A **Configure agents** row is always last, and is the whole menu when nothing is enabled yet.
+The menu is organized into three sections, in the order the default follows. **In app** leads: a row for each in-app agent you've enabled or that detection turned up, which opens the conversation in OpenKnowledge's Agents panel without leaving the app. **Terminal** (macOS and Linux desktop apps) follows: a row for every agent CLI OpenKnowledge can launch — **Claude**, **Codex**, **OpenCode**, **Cursor**, **GitHub Copilot**, **Pi**, **Antigravity**, **OpenClaw**, and **Hermes** — each running its own command in OpenKnowledge's [docked terminal](#terminal) with the same scoped prompt. A CLI the PATH probe reports absent is hidden until you turn it on in **Configure agents**. **External apps** comes last, listing the agent apps detected on this machine — **Claude Desktop**, **ChatGPT Desktop** (Codex's desktop app is branded ChatGPT), and **Cursor Desktop** — plus any you turned on in **Configure agents** (those route to the app's installer); selecting one launches it via its deep link and hands the work out of OpenKnowledge. Because the sections can carry the same brand name, the **Desktop** suffix is what tells a Terminal **Claude** (the CLI) apart from an External apps **Claude Desktop** (the app) on screen; screen readers additionally get "Claude CLI" as the Terminal row's accessible name. Each section renders only when it has something to launch, so on the web build and in the Windows app, which has no docked terminal, the Terminal section is absent, and a saved CLI pick degrades to the same order the default follows: an In app agent when one is available, otherwise an external app. A **Configure agents** row is always last.
The empty-state create composer on a fresh project carries the same three-way split: its In app rows pick the in-app agent the **Create** button uses, its Terminal rows (desktop only, disabled until the workspace resolves) launch any of those CLIs with the brief you typed, and its External apps rows hand that brief to an agent app installed here.
diff --git a/docs/content/integrations/cursor.mdx b/docs/content/integrations/cursor.mdx
index 0c2c2ef9e..a765fca4d 100644
--- a/docs/content/integrations/cursor.mdx
+++ b/docs/content/integrations/cursor.mdx
@@ -16,11 +16,11 @@ Cursor prompts you to approve a new MCP server when you next open the project. A
## Open with AI
-From the editor, **Open with AI ▸ Cursor** dispatches the current file, folder, or project to Cursor. Entry points: the sidebar's right-click menu (file / folder / empty space), the command palette, and the **File → Open with AI** menu. You can also hand the current doc to Cursor from the bottom **Ask AI** composer.
+From the editor, **Open with AI ▸ Cursor Desktop** dispatches the current file, folder, or project to Cursor. Entry points: the sidebar's right-click menu (file / folder / empty space), the command palette, and the **File → Open with AI** menu. You can also hand the current doc to Cursor from the bottom **Ask AI** composer.
Cursor uses a two-step handoff: OpenKnowledge spawns `cursor <projectDir>` to open the workspace first, then fires the `cursor://` URL with a short prompt asking Cursor to open the target in OpenKnowledge's web preview. The agent then grounds the rest of the conversation through MCP. See [Editor → Open with AI](/docs/features/editor#open-with-ai) for the full UX.
-Both steps run through the local server's `POST /api/handoff`, the same path in the web app and the desktop app — so the **Open with AI ▸ Cursor** row works in both.
+Both steps run through the local server's `POST /api/handoff`, the same path in the web app and the desktop app — so the **Open with AI ▸ Cursor Desktop** row works in both.
## Verify
diff --git a/packages/app/src/components/BottomComposer.tsx b/packages/app/src/components/BottomComposer.tsx
index 4d048ab9f..a16a3b468 100644
--- a/packages/app/src/components/BottomComposer.tsx
+++ b/packages/app/src/components/BottomComposer.tsx
@@ -19,8 +19,8 @@
* Submitting dispatches the typed instruction to the resolved default agent
* (first installed, or the user's sticky pick) scoped to the current doc or
* folder, via the shared handoff plumbing (`useHandoffDispatch` -> ask-scope
- * input -> `composeAskPrompt`). Picking a Terminal CLI (Claude / Codex /
- * OpenCode / Cursor) hands the composed prompt to the docked terminal instead
+ * input -> `composeAskPrompt`). Picking a Terminal CLI (any `TerminalCli`)
+ * hands the composed prompt to the docked terminal instead
* of a deep-link dispatch — always in a new terminal tab (reusing a live
* shell is exclusively the selection-bubble path).
*/
@@ -773,9 +773,10 @@ export function BottomComposer({
return outcome.ok;
};
- // Compose the current draft (instruction + chips + pinned selection) into a
- // handoff input — shared by `submit` (which dispatches it) and the picker's
- // "Choose another agent…" row (which carries it into the catalog).
+ // Collect the current draft — typed instruction, `@`-mention chips, and any
+ // pinned selection passage — into one handoff input. `submit` is the only
+ // caller; the picker's Configure agents row takes no input and just opens
+ // Settings.
const composeCurrentInput = () => {
const { instruction, mentions } = inputRef.current?.getContent() ?? {
instruction: '',
diff --git a/packages/app/src/components/TerminalNewChatButton.dom.test.tsx b/packages/app/src/components/TerminalNewChatButton.dom.test.tsx
index 6793ba291..373589302 100644
--- a/packages/app/src/components/TerminalNewChatButton.dom.test.tsx
+++ b/packages/app/src/components/TerminalNewChatButton.dom.test.tsx
@@ -93,6 +93,21 @@ describe('TerminalNewChatButton (merged sessions-dock New button)', () => {
expect(screen.getByRole('menuitem', { name: 'Terminal' })).toBeDefined();
});
+ // Real Radix, no menu double. Arrow-key menu navigation skips the visible
+ // `DropdownMenuLabel`, so the group's `aria-label` is the only section context
+ // an AT user gets while stepping through rows — an unnamed group is an a11y
+ // regression the `menuitem` assertions above cannot see.
+ test('names the In app group "In app" and carries no maturity badge', async () => {
+ const user = userEvent.setup();
+ renderButton();
+
+ await user.click(screen.getByRole('button', { name: 'Choose what a new tab starts' }));
+
+ const inApp = await screen.findByRole('group', { name: 'In app' });
+ expect(inApp.textContent).toContain('In app');
+ expect(inApp.textContent).not.toContain('Beta');
+ });
+
test('lists only the CLIs in visibleClis (Claude + detected), hiding the rest', async () => {
const user = userEvent.setup();
// The host passes the already-gated list (via `isTerminalCliEnabled`): here
diff --git a/packages/app/src/components/TerminalNewChatButton.tsx b/packages/app/src/components/TerminalNewChatButton.tsx
index 481d26440..1e83894d3 100644
--- a/packages/app/src/components/TerminalNewChatButton.tsx
+++ b/packages/app/src/components/TerminalNewChatButton.tsx
@@ -69,8 +69,9 @@ interface TerminalNewChatButtonProps {
* launch of the current pick with a dropdown to switch it across all three
* families. The primary opens whatever is currently selected: a bare terminal, a
* CLI chat, or an in-app agent thread. The menu mirrors the Ask-AI surfaces: an
- * "In this app" group (enabled agents), then — on the desktop host — a "Terminal"
- * group (every CLI plus a bare "Terminal" shell), then a "Configure agents" footer last.
+ * "In app" group (enabled agents), then — on the desktop host — a "Terminal"
+ * group (the CLIs the host admits via `visibleClis`, plus a bare "Terminal"
+ * shell), then a "Configure agents" footer last.
*
* The pick sticks: agent + CLI picks via the shared Ask-AI store, the bare-terminal
* pick via a terminal-only flag. The brand icon / agent avatar mirrors the Ask-AI
@@ -160,14 +161,14 @@ export function TerminalNewChatButton({
</DropdownMenuTrigger>
) : null}
<DropdownMenuContent align="start" className="max-h-80 min-w-[200px]">
- {/* Same section structure as the Ask-AI menus — an "In this app" group
+ {/* Same section structure as the Ask-AI menus — an "In app" group
over the agent rows, a "Terminal" group over the CLIs, and a
"Configure agents" footer last — so the dock picker reads consistently. The
bare "Terminal" (plain shell) is the last row of the Terminal group,
where it belongs alongside the CLIs. */}
{showAgents && registeredAgents.length > 0 ? (
<DropdownMenuGroup aria-label={t`In app`}>
- <DropdownMenuLabel className="flex items-center gap-1.5">
+ <DropdownMenuLabel>
<Trans>In app</Trans>
</DropdownMenuLabel>
{registeredAgents.map((agent) => {
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 6c223fcd1..33a4e96e1 100644
--- a/packages/app/src/components/empty-state/CreatePromptComposer.dom.test.tsx
+++ b/packages/app/src/components/empty-state/CreatePromptComposer.dom.test.tsx
@@ -72,10 +72,15 @@ vi.doMock('@/components/ui/dropdown-menu', () => ({
{children}
</div>
),
- // Transparent passthrough — the real role="group" semantics are exercised
- // against real Radix in OpenInAgentMenu/OpenInAgentTerminalRow .dom tests;
- // here the dropdown is fully mocked, so asserting the role would test the mock.
- DropdownMenuGroup: ({ children }: MenuChild) => <>{children}</>,
+ // Mirrors Radix `Menu.Group` (`<Primitive.div role="group" {...props} />`).
+ // A bare fragment would erase the role and swallow `aria-label`, so the
+ // section's accessible name could not be asserted at all.
+ DropdownMenuGroup: ({ children, ...props }: MenuChild) => (
+ // biome-ignore lint/a11y/useSemanticElements: must mirror Radix's `<div role="group">`
+ <div role="group" {...props}>
+ {children}
+ </div>
+ ),
DropdownMenuItem: ({ children, disabled, onSelect, ...props }: MenuChild) => (
<button type="button" role="menuitem" disabled={disabled} onClick={onSelect} {...props}>
{children}
@@ -258,6 +263,19 @@ describe('CreatePromptComposer External apps / Terminal sections', () => {
expect(launchCalls).toEqual([]);
});
+ // This menu hand-duplicates AgentSplitButton's three-section structure rather
+ // than reusing it, so the In-app section is asserted here independently.
+ test('names the In-app section "In app" and carries no maturity badge', async () => {
+ registerAgent({ source: 'registry', id: 'claude-acp', name: 'Claude Agent' });
+ states = { ...installedAll };
+ workspaceValue = { contentDir: '/tmp/project', pathSeparator: '/' };
+ await renderComposer({ withTerminal: true });
+
+ const inApp = screen.getByRole('group', { name: 'In app' });
+ expect(inApp.textContent).toContain('In app');
+ expect(inApp.textContent).not.toContain('Beta');
+ });
+
test('Enter in thread mode starts the in-app agent — not an app-agent dispatch', async () => {
registerAgent({ source: 'registry', id: 'claude-acp', name: 'Claude Agent' });
states = { ...installedAll };
diff --git a/packages/app/src/components/empty-state/CreatePromptComposer.tsx b/packages/app/src/components/empty-state/CreatePromptComposer.tsx
index 574f08fb5..626a69290 100644
--- a/packages/app/src/components/empty-state/CreatePromptComposer.tsx
+++ b/packages/app/src/components/empty-state/CreatePromptComposer.tsx
@@ -87,15 +87,14 @@ interface CreatePromptComposerProps {
* composes the create-scope prompt — brief + the explicit `@path` mentions — so
* the agent scaffolds the project to match.
*
- * The chevron menu has two sections. "External apps" lists the desktop apps
- * detected on this machine (an app that can't be launched is never offered —
- * mirrors the "Open with AI" menu); picking one sets the default the primary
- * button creates with. "Terminal" (desktop only) adds a row per agent CLI
- * (Claude, Codex, Cursor) that launches the docked-terminal CLI with the same
- * create-scope input. The two differ on purpose: every row selects the create
- * target — an external-app row picks an installed desktop app, a Terminal row
- * picks the docked-terminal CLI — and the button performs the selected target
- * (app deep-link or terminal launch).
+ * The chevron menu has three sections, in render order. "In app" lists the
+ * enabled in-app agents; picking one makes that agent the create target.
+ * "Terminal" (desktop only) adds a row per enabled agent CLI, which launches
+ * the docked-terminal CLI with the same create-scope input. "External apps"
+ * lists the desktop apps detected on this machine (an app that can't be
+ * launched is never offered — mirrors the "Open with AI" menu). Every row
+ * selects the create target rather than acting on it; the button performs the
+ * selected target (thread start, terminal launch, or app deep-link).
* When nothing is installed, Create is disabled and the footer shows a "no
* agents" hint.
*
@@ -522,7 +521,7 @@ export function CreatePromptComposer({ scenario, className }: CreatePromptCompos
an empty section (all disabled) is hidden entirely. */}
{showThreadSection ? (
<DropdownMenuGroup aria-label={t`In app`}>
- <DropdownMenuLabel className="flex items-center gap-1.5">
+ <DropdownMenuLabel>
<Trans>In app</Trans>
</DropdownMenuLabel>
{enabledThreadAgents.map((agent) => (
@@ -551,8 +550,9 @@ export function CreatePromptComposer({ scenario, className }: CreatePromptCompos
<DropdownMenuSeparator />
) : null}
{showTerminalSection ? (
- // Terminal section leads (the in-app terminal is the
- // first-class path). Labeled `role="group"` so assistive tech
+ // Terminal sits between In app and External apps (the
+ // docked terminal is the first-class of the two
+ // external-handoff routes). Labeled `role="group"` so assistive tech
// announces the section the visual header conveys (the label
// alone is skipped by arrow-key menu navigation).
<DropdownMenuGroup aria-label={t`Terminal`}>
diff --git a/packages/app/src/components/handoff/AgentSplitButton.non-modal.dom.test.tsx b/packages/app/src/components/handoff/AgentSplitButton.non-modal.dom.test.tsx
index ccee187cd..2fb0114a9 100644
--- a/packages/app/src/components/handoff/AgentSplitButton.non-modal.dom.test.tsx
+++ b/packages/app/src/components/handoff/AgentSplitButton.non-modal.dom.test.tsx
@@ -1,7 +1,15 @@
/**
- * The composer agent picker can hand directly to the modal agent catalog.
- * Keeping the picker non-modal prevents Radix's dropdown pointer lock from
- * surviving that surface transition and making the app appear frozen.
+ * The composer agent picker's "Configure agents" row hands directly to the modal
+ * Settings dialog. Keeping the picker non-modal prevents Radix's dropdown
+ * pointer lock from surviving that surface transition and making the app appear
+ * frozen.
+ *
+ * This suite also pins `AgentSplitButton`'s In app group accessible name against
+ * a real Radix `DropdownMenuGroup`. The suites that reach it through
+ * `BottomComposer` (`BottomComposer.dom.test.tsx`, `composer-shared-draft`)
+ * double `DropdownMenuGroup` as a bare fragment that discards `aria-label`, and
+ * the suites that would reach it through `CommentSendFooter` stub that
+ * component out.
*/
import { cleanup, render, screen } from '@testing-library/react';
@@ -28,6 +36,39 @@ if (globalWithDomShims.ResizeObserver === undefined) {
globalWithDomShims.ResizeObserver = NoopResizeObserver;
}
+// No `terminal`/`terminals` and an empty `enabledTargets`, so the menu this mounts is
+// In app -> Configure agents. Both tests below are scoped to that: nothing here
+// exercises the Terminal or External apps sections.
+function renderSplitButton() {
+ render(
+ <AgentSplitButton
+ primary="Ask Claude"
+ onPrimary={() => {}}
+ enabledTargets={[]}
+ selectedTargetId={null}
+ onSelectTarget={() => {}}
+ threadAgents={[
+ {
+ key: 'registry:claude-acp',
+ id: 'claude-acp',
+ name: 'Claude',
+ selected: true,
+ onSelect: () => {},
+ },
+ ]}
+ onOpenSettings={() => {}}
+ triggerAriaLabel="Choose agent"
+ testIds={{
+ primary: 'primary',
+ trigger: 'trigger',
+ menu: 'menu',
+ option: (id) => `option-${id}`,
+ terminal: 'terminal',
+ }}
+ />,
+ );
+}
+
describe('AgentSplitButton non-modal contract', () => {
afterEach(() => {
cleanup();
@@ -36,38 +77,26 @@ describe('AgentSplitButton non-modal contract', () => {
test('opening the composer picker leaves the rest of the app interactive', async () => {
const user = userEvent.setup();
- render(
- <AgentSplitButton
- primary="Ask Claude"
- onPrimary={() => {}}
- enabledTargets={[]}
- selectedTargetId={null}
- onSelectTarget={() => {}}
- thread={{ selected: true, onSelect: () => {} }}
- threadAgents={[
- {
- key: 'registry:claude-acp',
- id: 'claude-acp',
- name: 'Claude',
- selected: true,
- onSelect: () => {},
- },
- ]}
- onBrowseThreadAgents={() => {}}
- triggerAriaLabel="Choose agent"
- testIds={{
- primary: 'primary',
- trigger: 'trigger',
- menu: 'menu',
- option: (id) => `option-${id}`,
- terminal: 'terminal',
- threadBrowse: 'browse',
- }}
- />,
- );
+ renderSplitButton();
await user.click(screen.getByTestId('trigger'));
expect(screen.getByTestId('menu')).toBeDefined();
expect(document.body.style.pointerEvents).not.toBe('none');
});
+
+ // Resolves through the accessibility tree against a real Radix
+ // `DropdownMenuGroup` — `getByRole` computes both the role and the accessible
+ // name. On a Radix group that name comes from `aria-label` while the visible
+ // heading is a separate label node, so both are worth pinning, along with the
+ // absence of the maturity badge this group used to carry.
+ test('names the In app group "In app" and carries no maturity badge', async () => {
+ const user = userEvent.setup();
+ renderSplitButton();
+
+ await user.click(screen.getByTestId('trigger'));
+
+ const inApp = screen.getByRole('group', { name: 'In app' });
+ expect(inApp.textContent).toContain('In app');
+ expect(inApp.textContent).not.toContain('Beta');
+ });
});
diff --git a/packages/app/src/components/handoff/AgentSplitButton.tsx b/packages/app/src/components/handoff/AgentSplitButton.tsx
index d7819fae2..3386544b2 100644
--- a/packages/app/src/components/handoff/AgentSplitButton.tsx
+++ b/packages/app/src/components/handoff/AgentSplitButton.tsx
@@ -18,29 +18,10 @@ import {
DropdownMenuTrigger,
} from '@/components/ui/dropdown-menu';
-/**
- * Presentational split button that pairs a primary action with an agent picker:
- * `[ primary ▸ | ⌄ ]`. Shared by the empty-state create composer and the footer
- * "Ask <agent>" composer so the two surfaces can't drift.
- *
- * It owns only the view — the joined `ButtonGroup`, the primary button, and the
- * chevron menu listing the detected desktop apps ("External apps") plus the
- * optional docked-terminal Claude CLI ("Terminal"). Everything stateful (which agent is
- * selected, where that preference is stored, what the primary button does, the
- * pending/disabled affordance, the label verb) stays in the parent and arrives
- * as props. The parent composes `primary` (icon + label + any spinner) and the
- * caller decides whether to render this at all (e.g. the empty-state swaps in a
- * disabled standalone button until an agent resolves).
- *
- * Uses a non-modal DropdownMenu (not a Popover): these are menu actions, but
- * "Choose another agent" hands directly to a modal dialog. A modal dropdown
- * would leave Radix's body pointer lock active during that handoff and make the
- * catalog appear frozen.
- */
/**
* One CLI row in the "Terminal" section — a docked-terminal launcher for a
- * single CLI agent (Claude / Codex / Cursor). The parent supplies the visible
- * label + accessible name; the row reports its own selected check.
+ * single agent CLI. The parent supplies the visible label + accessible name;
+ * the row reports its own selected check.
*/
export interface TerminalCliRow {
/** Which CLI this row launches — drives the per-CLI sticky id + testid. */
@@ -54,10 +35,10 @@ export interface TerminalCliRow {
}
/**
- * One registered in-app agent in the "In this app" section — selecting it
- * makes that agent the thread target (the parent owns registration/default
- * bumping). When any of these exist, they replace the single generic
- * "Start an agent" row so the first registration never locks the choice in.
+ * One registered in-app agent in the "In app" section — selecting it makes
+ * that agent the thread target (the parent owns registration/default bumping).
+ * One row per enabled agent, so the first registration never locks the choice
+ * in; when none are enabled the whole section is hidden.
*/
export interface ThreadAgentRow {
/** Stable row key (`<source>:<id>`). */
@@ -92,6 +73,31 @@ export interface AgentSplitButtonTestIds {
settings?: string;
}
+/**
+ * Presentational split button that pairs a primary action with an agent picker:
+ * `[ primary ▸ | ⌄ ]`. Shared by the footer "Ask <agent>" composer
+ * (`BottomComposer`) and the Comments panel's send control
+ * (`CommentSendFooter`) so those two surfaces can't drift. The empty-state
+ * create composer is NOT a consumer — it renders the same three sections from
+ * its own menu, so a change to the section structure here has to be made there
+ * too.
+ *
+ * It owns only the view — the joined `ButtonGroup`, the primary button, and the
+ * chevron menu: any caller-supplied `menuLeading` rows first, then the enabled
+ * in-app agents ("In app"), the docked-terminal CLI rows ("Terminal"), the
+ * enabled app targets ("External apps"), and a "Configure agents" row last.
+ * Everything stateful (which agent is
+ * selected, where that preference is stored, what the primary button does, the
+ * pending/disabled affordance, the label verb) stays in the parent and arrives
+ * as props. The parent composes `primary` (icon + label + any spinner) and the
+ * caller decides whether to render this at all (e.g. the empty-state swaps in a
+ * disabled standalone button until an agent resolves).
+ *
+ * Uses a non-modal DropdownMenu (not a Popover): these are menu actions, but the
+ * "Configure agents" row hands directly to the modal Settings dialog. A modal
+ * dropdown would leave Radix's body pointer lock active during that handoff and
+ * make that dialog appear frozen.
+ */
export function AgentSplitButton({
primary,
onPrimary,
@@ -127,7 +133,7 @@ export function AgentSplitButton({
*/
terminal?: { selected: boolean; onSelect: () => void };
/**
- * Docked-terminal CLI rows — one per launchable CLI (Claude / Codex / Cursor).
+ * Docked-terminal CLI rows — one per launchable CLI.
* Omit (or pass empty) on the web host. When non-empty, the "Terminal" section
* renders these rows instead of the legacy single {@link terminal} slot.
*/
@@ -215,7 +221,7 @@ export function AgentSplitButton({
// section (all disabled) is hidden entirely.
<>
<DropdownMenuGroup aria-label={t`In app`}>
- <DropdownMenuLabel className="flex items-center gap-1.5">
+ <DropdownMenuLabel>
<Trans>In app</Trans>
</DropdownMenuLabel>
{threadAgents?.map((row) => (
@@ -242,8 +248,9 @@ export function AgentSplitButton({
{hasOptions ? (
<>
{showTerminal ? (
- // Terminal section leads (the in-app terminal is the first-class
- // path). Labeled `role="group"` so assistive tech announces the
+ // Terminal sits between In app and External apps (the docked
+ // terminal is the first-class of the two external-handoff
+ // routes). Labeled `role="group"` so assistive tech announces the
// section the visual header conveys (the label alone is skipped by
// arrow-key menu navigation).
<DropdownMenuGroup aria-label={t`Terminal`}>
diff --git a/packages/app/src/components/handoff/OpenInAgentContextSubmenu.tsx b/packages/app/src/components/handoff/OpenInAgentContextSubmenu.tsx
index 7a2ae000e..c78f109b2 100644
--- a/packages/app/src/components/handoff/OpenInAgentContextSubmenu.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentContextSubmenu.tsx
@@ -6,10 +6,11 @@
* - Render the targets `isDesktopTargetEnabled` admits: probed-installed,
* plus any explicitly enabled in Settings (those route to their
* installer), minus any turned off.
- * - Detected desktop apps sit under an "External apps" section label; the docked
- * terminal launchers — one row per enabled CLI (`isTerminalCliEnabled`:
- * CLIs the probe hasn't ruled out) — sit under a "Terminal"
- * section label, gated on a desktop terminal bridge.
+ * - Three section labels, in render order: "In app" over the enabled in-app
+ * agents, "Terminal" over the docked terminal launchers — one row per
+ * enabled CLI (`isTerminalCliEnabled`: CLIs the probe hasn't ruled out),
+ * gated on a desktop terminal bridge — and "External apps" over the
+ * enabled app targets.
* - Empty state: when no section has rows, only the Configure-agents item
* remains visible — no section labels, no hint text.
* - Status-hint code path remains for the `inputMissing` case (right-click
@@ -148,7 +149,7 @@ export function OpenInAgentContextSubmenu(props: OpenInAgentContextSubmenuProps)
hidden. Enablement is managed in Configure agents (footer). */}
{showThreadSection ? (
<DropdownMenuGroup aria-label={t`In app`}>
- <DropdownMenuLabel className="flex items-center gap-1.5">
+ <DropdownMenuLabel>
<Trans>In app</Trans>
</DropdownMenuLabel>
{enabledRegisteredAgents.map((agent) => {
@@ -187,7 +188,8 @@ export function OpenInAgentContextSubmenu(props: OpenInAgentContextSubmenuProps)
<DropdownMenuSeparator />
) : null}
{showTerminalSection ? (
- // Terminal section leads (the in-app terminal is the first-class path).
+ // Terminal sits between In app and External apps (the docked terminal
+ // is the first-class of the two external-handoff routes).
// Labeled `role="group"` so assistive tech announces the section the
// visual header conveys (the label alone is skipped by arrow-key nav).
<DropdownMenuGroup aria-label={t`Terminal`}>
diff --git a/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx b/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
index 554407c00..d4cf4222f 100644
--- a/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
@@ -10,9 +10,10 @@
* `DropdownMenuSub` inside `ContextMenuContent`) detaches keyboard navigation
* because Radix submenus inherit roving focus from their parent root primitive.
*
- * Detected desktop apps sit under an "External apps" section label; the docked
- * terminal launchers — one row per enabled CLI (`isTerminalCliEnabled`: CLIs the
- * probe hasn't ruled out) — sit under a "Terminal" section label.
+ * Three section labels, in render order: "In app" over the enabled in-app
+ * agents, "Terminal" over the docked terminal launchers — one row per enabled
+ * CLI (`isTerminalCliEnabled`: CLIs the probe hasn't ruled out), gated on a
+ * desktop terminal bridge — and "External apps" over the enabled app targets.
*
* The submenu always renders with at least the Configure-agents item; when no
* agent section has rows, that item is all that remains (no section labels).
@@ -128,7 +129,7 @@ export function OpenInAgentEmptySpaceSubmenu(props: OpenInAgentEmptySpaceSubmenu
hidden. Enablement is managed in Configure agents (footer). */}
{showThreadSection ? (
<ContextMenuGroup aria-label={t`In app`}>
- <ContextMenuLabel className="flex items-center gap-1.5">
+ <ContextMenuLabel>
<Trans>In app</Trans>
</ContextMenuLabel>
{enabledRegisteredAgents.map((agent) => {
@@ -166,7 +167,8 @@ export function OpenInAgentEmptySpaceSubmenu(props: OpenInAgentEmptySpaceSubmenu
<ContextMenuSeparator />
) : null}
{showTerminalSection ? (
- // Terminal section leads (the in-app terminal is the first-class path).
+ // Terminal sits between In app and External apps (the docked terminal
+ // is the first-class of the two external-handoff routes).
// Labeled `role="group"` so assistive tech announces the section the
// visual header conveys (the label alone is skipped by arrow-key nav).
<ContextMenuGroup aria-label={t`Terminal`}>
diff --git a/packages/app/src/components/handoff/OpenInAgentMenu.dom.test.tsx b/packages/app/src/components/handoff/OpenInAgentMenu.dom.test.tsx
index 933265a12..c5be96ddc 100644
--- a/packages/app/src/components/handoff/OpenInAgentMenu.dom.test.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentMenu.dom.test.tsx
@@ -247,6 +247,21 @@ describe('OpenInAgentMenu runtime behavior', () => {
expect(screen.queryByTestId('open-in-agent-claude-web-fallback')).toBeNull();
});
+ // This surface is a <fieldset> named by its <legend> (not a Radix group, and
+ // never an `aria-label` — the "In app (beta)" name lived on the five Radix
+ // group surfaces; here the badge was simply the legend's second child). So
+ // the name and the heading are one node: `getByRole` pins that the fieldset
+ // still exposes role="group" and that the legend still names it, and the
+ // badge's absence is the separate thing worth asserting.
+ test('names the In-app section "In app" and carries no maturity badge', async () => {
+ registerAgent({ source: 'registry', id: 'claude-acp', name: 'Claude Agent' });
+ await renderMenu();
+ await openMenu();
+
+ const inApp = screen.getByRole('group', { name: 'In app' });
+ expect(inApp.textContent).not.toContain('Beta');
+ });
+
test('hides the In-app section when no agent is enabled, keeping Configure agents', async () => {
states = {
'claude-cowork': { installed: null },
diff --git a/packages/app/src/components/handoff/OpenInAgentMenu.tsx b/packages/app/src/components/handoff/OpenInAgentMenu.tsx
index 643ca31fd..333e7d917 100644
--- a/packages/app/src/components/handoff/OpenInAgentMenu.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentMenu.tsx
@@ -16,13 +16,16 @@
* `VISIBLE_TARGETS`: the ones the probe reports installed, plus any the
* user explicitly enabled in Settings (those route to their installer),
* minus any they turned off.
- * - Detected app launchers sit under an "External apps" section label; the docked
- * terminal launchers — one row per enabled CLI (`isTerminalCliEnabled`:
- * 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 no section has rows, only the Configure-agents item
- * remains visible — no section labels, no hint text.
+ * - Three section labels, in render order: "In app" over the enabled in-app
+ * agents, "Terminal" over the docked-terminal launchers — one row per
+ * enabled CLI (`isTerminalCliEnabled`: CLIs the probe hasn't ruled out),
+ * each with a "<Brand> CLI" accessible name — and "External apps" over the
+ * enabled app targets. Each renders only when it has rows, so an empty
+ * section header never shows, and the terminal section is absent on the
+ * web host (`useTerminalLaunch()` is null — no shell).
+ * - Empty state: when no section has rows, the instruction input (which
+ * renders unconditionally) and the Configure-agents item remain — no
+ * section labels, no hint text.
*
* The `input` prop is supplied by the surface (EditorHeader). When `null` (no
* active doc / workspace not loaded), the trigger is disabled.
@@ -85,8 +88,13 @@ interface OpenWithAiPanelProps {
* (no active doc / workspace not loaded). The trigger is also disabled in
* that state, so this is a defensive guard for the controlled-open path. */
readonly disabled: boolean;
- /** Registered in-app agents — one launch row each. Empty before the first
- * catalog registration, where the single "Start an agent" row renders. */
+ /** Registered in-app agents — the unfiltered list; this panel applies
+ * `isInAppAgentEnabled` itself. Empty until an agent is registered or the
+ * server reports a detected harness — `useRegisteredAgents` merges both
+ * upstream, before this prop is passed.
+ * When it is empty, or every registered agent is disabled in Configure
+ * agents, the whole "In app" section is hidden; there is no generic
+ * fallback row. */
readonly registeredAgents: readonly RegisteredAgent[];
/** Fired when the user picks an agent; carries the typed instruction — the
* empty string when the user dispatched without typing one. */
@@ -103,8 +111,8 @@ interface OpenWithAiPanelProps {
}
/**
- * Popover body — the instruction input and the External apps / Terminal row
- * sections. Pure: install state, the launcher, and the pick handlers are
+ * Popover body — the instruction input and the In app / Terminal / External apps
+ * row sections. Pure: install state, the launcher, and the pick handlers are
* injected, so it renders deterministically in tests without the dispatch /
* install-probe hooks. Instruction state is local and resets on each open
* because the popover unmounts its content when closed.
@@ -129,18 +137,17 @@ function OpenWithAiPanel({
const enabledTargets = VISIBLE_TARGETS.filter((target) =>
isDesktopTargetEnabled(overrides, target.id, installStates[target.id]?.installed),
);
- // Only the in-app agents the user has enabled appear as rows.
+ // Registered in-app agents — explicit picks plus harness-detected suggestions
+ // (`useRegisteredAgents` merges both) — minus anything turned off in Configure
+ // agents, and minus anything the catalog reports unsupported here, which
+ // `isInAppAgentEnabled` force-hides ahead of any override. The `true` is the
+ // default it resolves against: being on the merged list is what shows a row.
const enabledRegisteredAgents = registeredAgents.filter((agent) =>
isInAppAgentEnabled(overrides, agent.source, agent.id, true, agent.supported),
);
- // Three labeled sections orient the user: "In this app" over the server-
- // hosted agent-thread launcher (always present — threads work on every
- // host), "External apps" over the detected desktop apps, "Terminal" over the
- // docked-terminal CLI rows. The Agents row always shows, so the empty state
- // never appears while it is present.
- // The Terminal CLIs the user ENABLED in Configure agents. Each section renders
- // only when it has rows, so an empty section header never shows.
+ // Terminal CLIs the probe hasn't ruled out, minus anything turned off in
+ // Configure agents (fail-open — see `isTerminalCliEnabled`).
const terminalClis = terminalLaunch
? TERMINAL_CLI_IDS.filter((cli) =>
isTerminalCliEnabled(overrides, cli, terminalLaunch.installedClis),
@@ -169,7 +176,7 @@ function OpenWithAiPanel({
{showThreadSection ? (
<fieldset className="m-0 flex min-w-0 flex-col gap-0.5 border-0 p-0">
<legend
- className="flex items-center gap-1.5 px-1.5 py-1 font-medium text-muted-foreground text-xs"
+ className="px-1.5 py-1 font-medium text-muted-foreground text-xs"
data-testid="open-in-agent-thread-label"
>
<Trans>In app</Trans>
diff --git a/packages/app/src/components/handoff/useHandoffDispatch.ts b/packages/app/src/components/handoff/useHandoffDispatch.ts
index 5437dfccf..96e6776aa 100644
--- a/packages/app/src/components/handoff/useHandoffDispatch.ts
+++ b/packages/app/src/components/handoff/useHandoffDispatch.ts
@@ -877,8 +877,8 @@ export function selectScopedPrompt(
* surface, load the OK contract, read the open file if there is one, then
* stop. It does NOT invite open-ended work — the user drives the next turn
* from the terminal themselves. CLI-agnostic: the load + read + stop wording
- * is identical across Claude / Codex / Cursor (no `@`-mention encoding to
- * vary per target).
+ * is identical for every `TerminalCli` (no `@`-mention encoding to vary per
+ * target), which is why the bare branch takes no `cli` argument at all.
* - **Instruction / create launch** — the unified "Ask AI" composer (carries
* its intent in `input.compose`: instruction + `@`-mentions + optional
* selection passage), the toolbar "Open with AI" popover (top-level
diff --git a/packages/app/src/components/settings/ConfigureAgentsSection.tsx b/packages/app/src/components/settings/ConfigureAgentsSection.tsx
index cfeb9bf44..424a2ec95 100644
--- a/packages/app/src/components/settings/ConfigureAgentsSection.tsx
+++ b/packages/app/src/components/settings/ConfigureAgentsSection.tsx
@@ -107,9 +107,13 @@ function AgentGroup({
children,
labelId,
}: {
- label: ReactNode;
+ /** Plain heading text. The `<h4>` is the `<section>`'s `aria-labelledby`
+ * target, so this string IS the region's accessible name. */
+ label: string;
/** Decorative mark beside the heading — the external-action arrow on the
- * external-apps group, matching that section's launcher headers. */
+ * external-apps group, matching that section's launcher headers. It renders
+ * inside that same `<h4>`, so it must carry its own `aria-hidden`; anything
+ * that should be announced belongs in `label`. */
labelIcon?: ReactNode;
labelId: string;
children: ReactNode;
diff --git a/packages/app/src/lib/acp/agent-visibility.ts b/packages/app/src/lib/acp/agent-visibility.ts
index cab980dc4..d0b28fa22 100644
--- a/packages/app/src/lib/acp/agent-visibility.ts
+++ b/packages/app/src/lib/acp/agent-visibility.ts
@@ -6,7 +6,8 @@
* Enablement = the user's explicit override (from `enabled-agents.ts`) when
* present, else the category default computed from the runtime signal the
* caller supplies:
- * - In app → registered (enabling registers; nothing installs to detect)
+ * - In app → registered, and callers fold harness detection into that
+ * input (`isHarnessDetected`), so a detected agent counts
* - Terminal → fail-open: shown unless positively absent on PATH
* (`installed[cli] === false`); an unresolved probe still shows
* - Desktop → detected: shown when the OS-level probe reports the app
diff --git a/packages/app/src/lib/unified-agent-store.ts b/packages/app/src/lib/unified-agent-store.ts
index 9b50e582d..639234fb9 100644
--- a/packages/app/src/lib/unified-agent-store.ts
+++ b/packages/app/src/lib/unified-agent-store.ts
@@ -1,9 +1,14 @@
import { useSyncExternalStore } from 'react';
/**
- * ONE sticky-agent store shared by every "Ask AI" composer placement (the bottom
- * docked field and the create/empty-screen hero). It carries the docked-terminal
- * CLI sentinel (`terminal-cli:<cli>`) alongside the installed-app `HandoffTarget`
- * ids, so a default chosen in one placement is the default the other reads back.
+ * ONE sticky-agent store behind "the agent you chose last is your agent". Every
+ * surface that lets the user pick an agent writes it — the bottom docked Ask AI
+ * field, the create/empty-screen hero, the Agents and terminal tab strips
+ * (`SessionsHost`), and the Comments panel's send control — and every surface
+ * that launches one reads it back, including the file sidebar's Open with AI
+ * rows. It carries the docked-terminal CLI sentinel (`terminal-cli:<cli>`)
+ * alongside the installed-app `HandoffTarget` ids, so a pick made anywhere is
+ * the default everywhere. Adding a picker means writing here too; that is the
+ * contract, not an incidental coupling.
*
* Before this consolidation the two surfaces wrote to two divergent localStorage
* keys — the bottom composer to `ok-ask-ai-default-agent-v1` (with the CLI
@@ -27,7 +32,7 @@ import {
} from '@inkeep/open-knowledge-core';
import { VISIBLE_TARGETS } from '@/lib/handoff/targets';
-/** The unified key both placements read and write. */
+/** The unified key every agent-picker surface reads and writes. */
export const UNIFIED_AGENT_KEY = 'ok-ask-ai-agent-v2';
/**