Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(menu): group the add menu behind submenus, derived per surface

enesfc5ca167ed90
diff --git a/CLAUDE.md b/CLAUDE.md
index 71feec2a4..3eb3f2858 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -3213,6 +3213,47 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
be hidden, whatever settings.json says. The group-frame menu's colors strip answers to the same
`colors` id; builders run through `tidySeparators` so a hidden row leaves no dangling rule.
- **Add menu** = bottom dock (`Dock.tsx`) `+`, mirrored by the pane menu and command palette.
+ `lib/addMenuSpec` is the one source for WHICH kinds are addable, and since 2026-09 also for how
+ the two `ContextMenu` surfaces GROUP them: `New terminal` · `New remote…` · the account-capable
+ agents · `New agent ▸` · `New view ▸` · `Files ▸` · `Orchestrate ▸`, then the canvas actions. It
+ replaced a flat 18-row list, on the rationale that ⌘K already makes every one of these
+ searchable and the keybinding registry already carries a remappable command per agent and per
+ node kind (`node.new*`) — so this menu does not have to be EXHAUSTIVE, it has to be FAST.
+ Four rules hold it together, and the first is the one that is easy to get wrong:
+ - **The submenu depth cap is STRUCTURAL.** `ContextMenu` renders a submenu's children with
+ `if (child.type === 'colors' || child.type === 'submenu') return null` — a third level is
+ dropped with no error and nothing on screen. Claude's and Codex's **account pickers are already
+ level-two submenus**, so nesting either row behind `New agent ▸` would silently delete the
+ account picker for exactly the users who have managed accounts. MEASURED, not assumed, in
+ `components/ContextMenu.submenu-depth.test.tsx`; teach the component a third level and that
+ test goes red so the pin can be reconsidered deliberately.
+ - **Which agent rows stay at the first level is DERIVED, never a spelled-out agent id**
+ (`isPinnedAgentEntry`): a row that IS a submenu (structural, per above) **or** whose agent is in
+ `ACCOUNT_CAPABLE_AGENT_IDS` (`shared/agents/account-binding.ts` — the same list `boundAccountId`
+ reads, so a third agent gaining managed accounts cannot light up one and not the other). The
+ second half exists because rule one alone would move Codex in and out of the submenu as the
+ user adds or removes accounts, and a menu that rearranges itself is a menu nobody can learn.
+ A new builtin agent joins `New agent ▸` by itself; one that gains accounts is promoted by itself.
+ - **`ADD_ITEM_GROUP` is a total `Record` over the kind union on purpose** — a new `AddItem` kind
+ is a compile error until somebody routes it, instead of silently landing in one bucket forever.
+ `remote` stays top-level because it is not an agent: burying the one SSH-session entry point
+ under a menu named "New agent" puts it where nobody would look.
+ - **Grouping is a rearrangement, never a filter, and a nested row keeps its REASON.** The rows
+ still come from `contentAddItemsToMenuItems`, so `New worktree…` is greyed with
+ `WORKTREE_SSH_HINT` inside `Orchestrate ▸` exactly as it was at the top level (the cap drops
+ nested submenus, never a leaf's `disabled`/`hint`). Tests pin that nothing becomes unreachable.
+ **Per surface**: the pane right-click and the sessions-sidebar project-header "+" share the
+ grouped tree (`buildGroupedAddMenu`); the **group-frame** menu shares the agent half
+ (`agentEntriesToMenuItems`) and keeps its own three content rows; the **Dock stays FLAT** (its
+ popup is opened deliberately, it already omits terminal + remote, and its agent flyouts are
+ bespoke JSX — grouping it means a second submenu implementation for crowding nobody reported);
+ the **kanban column "+ New session" is NOT a consumer of the spec and never was** — its
+ `KanbanCreateChoice` is a closed union of the kinds that become a CARD, so feeding it this list
+ would offer kinds the board can never show. `addMenuSpec.surfaces.test.ts` pins all four.
+ None of the add rows are in `ui-visibility`'s hide inventory (it covers the NODE menu and the
+ terminal header), so grouping does not interact with hiding today; a future hideable add row
+ would need the group's own row to disappear when it empties, which `buildGroupedAddMenu` already
+ does — it emits no submenu for an empty bucket.
- **Edges** are all one React Flow type, `floating` (`canvas/FloatingEdge.tsx` over the pure
`lib/floatingEdge.ts`): every family — ropes, context bridges, note links, subagent/loop card
edges, trigger edges — is drawn between the midpoints of the two nodes' facing sides instead of
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f414ff8e3..96a85e162 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -500,6 +500,27 @@ yourself and apply it with `setViewport` (`renderer/lib/nodeFocus.ts`, `canvas/f
lands now and against the canvas you meant. `fitAll` is the one deliberate exception: an explicit
user gesture on a settled canvas.
+**A context menu is two levels deep, and the third level is discarded in silence.**
+`ContextMenu` renders a submenu's children with
+`if (child.type === 'colors' || child.type === 'submenu') return null` — no error, no warning,
+nothing on screen. That matters most where you cannot see it: Claude's and Codex's **account
+pickers are themselves submenus**, so moving one of those rows into another submenu deletes the
+account picker for exactly the users who have managed accounts, and looks perfect to everyone
+else. If you group rows in an add menu, get the decision from `isPinnedAgentEntry`
+(`renderer/lib/addMenuSpec`) rather than judging by eye — and never spell an agent id there: which
+rows stay at the top is derived from the row's own shape plus `ACCOUNT_CAPABLE_AGENT_IDS`, so a new
+agent is handled the day it is added. The cap is measured in
+`components/ContextMenu.submenu-depth.test.tsx`; if you teach the component a third level, that
+test tells you which pin to revisit.
+
+**Adding a node kind means touching the add menus once, not four times.**
+`renderer/lib/addMenuSpec` owns which kinds are addable and how they are grouped, for the canvas
+pane right-click, the sessions-sidebar "+" and the Dock. `ADD_ITEM_GROUP` is a total `Record` over
+the kind union, so a new kind is a **compile error** until you route it. The kanban column's
+"+ New session" is deliberately not a consumer — it can only offer kinds that become a card — and
+`addMenuSpec.surfaces.test.ts` pins that split so "make them all consistent" stays a decision
+rather than a reflex.
+
**A setting read at mount reads the DEFAULT, not the user's.** `useSettings` starts on
`DEFAULT_SETTINGS` and hydrates from disk asynchronously, while `<Canvas />` is mounted before that
lands. A `useState(() => settings.foo ? ...)` initializer therefore reads the shipped default and
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 9da9d9d28..1e3aab77f 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -165,7 +165,9 @@ import {
import { planServerChange } from '../lib/serverChange'
import {
CONTENT_ADD_ITEMS,
- contentAddItemsToMenuItems,
+ agentEntriesToMenuItems,
+ buildGroupedAddMenu,
+ type AgentAddEntry,
type AddHandlers
} from '../lib/addMenuSpec'
import { planSetProjectFolder } from '../lib/setProjectFolder'
@@ -8492,10 +8494,15 @@ export function Canvas() {
session.source
])
- /** "New <agent>" creation entries shared by the pane and group context menus.
- * `at` is the flow position to create at; with `groupId` the node is parented into that group. */
- const agentCreationItems = useCallback(
- (at?: { x: number; y: number }, groupId?: string): MenuItem[] => {
+ /** "New <agent>" creation entries shared by the pane, sidebar and group context menus.
+ * `at` is the flow position to create at; with `groupId` the node is parented into that group.
+ *
+ * Each row is TAGGED with its agent id ({@link AgentAddEntry}) because the grouped menu has to
+ * decide which rows may be nested behind "New agent ▸" and which must stay at the first level —
+ * a decision `isPinnedAgentEntry` makes from the id and the row's own shape, never from a
+ * hardcoded agent name here. */
+ const agentCreationEntries = useCallback(
+ (at?: { x: number; y: number }, groupId?: string): AgentAddEntry[] => {
const disabled = useSettings.getState().settings.disabledAgents
// Read the active project LIVE from the store (not the closure value) so a menu built right
// after a `switchProject` — e.g. the sessions-sidebar "+" opening this menu on a non-active
@@ -8532,93 +8539,99 @@ export function Canvas() {
undefined,
useSystemCodexAccount.getState().email
)
- return [
- ...BUILTIN_AGENT_IDS.filter((aid) => !disabled.includes(aid)).map((aid): MenuItem => {
- // Claude gets an account picker submenu when ≥1 account exists. The System row is an
- // EXPLICIT pick (`null`), never "no pick": before that distinction, clicking the row
- // labelled with the user's system email launched the PROJECT DEFAULT managed account
- // (#419). Other agents stay flat (accounts are Claude-only).
- if (aid === 'claude' && (accounts.length > 0 || accountsHint)) {
- return {
- type: 'submenu',
- label: `New ${AGENT_CONFIG[aid].label}`,
- icon: <AgentIcon agentId={aid} />,
- children: [
- {
- label: withDefaultMark(systemLabel),
+ const itemForBuiltin = (aid: (typeof BUILTIN_AGENT_IDS)[number]): MenuItem => {
+ // Claude gets an account picker submenu when ≥1 account exists. The System row is an
+ // EXPLICIT pick (`null`), never "no pick": before that distinction, clicking the row
+ // labelled with the user's system email launched the PROJECT DEFAULT managed account
+ // (#419). Other agents stay flat (accounts are Claude-only).
+ if (aid === 'claude' && (accounts.length > 0 || accountsHint)) {
+ return {
+ type: 'submenu',
+ label: `New ${AGENT_CONFIG[aid].label}`,
+ icon: <AgentIcon agentId={aid} />,
+ children: [
+ {
+ label: withDefaultMark(systemLabel),
+ icon: <AgentIcon agentId="claude" />,
+ onClick: () => addAgentNode('claude', at, groupId, null)
+ },
+ ...accounts.map(
+ (a): MenuItem => ({
+ label: withDefaultMark(a.label, a.id),
icon: <AgentIcon agentId="claude" />,
- onClick: () => addAgentNode('claude', at, groupId, null)
- },
- ...accounts.map(
- (a): MenuItem => ({
- label: withDefaultMark(a.label, a.id),
- icon: <AgentIcon agentId="claude" />,
- onClick: () => addAgentNode('claude', at, groupId, a.id)
- })
- ),
- ...(accountsHint
- ? [
- {
- label: 'No accounts on this host yet',
- onClick: () => {},
- disabled: true,
- hint: accountsHint
- } satisfies MenuItem
- ]
- : [])
- ]
- }
- }
- // Codex gets its own account picker submenu when ≥1 managed account lives on this
- // project's machine (S6 §3.4). Every managed row is gated through `codexAccountSelectable`
- // — a missing/hostile/unconnected account renders DISABLED, so the fail-closed refusal is
- // enforced before the click, and again in `addAgentNode` (the UI is not the boundary).
- if (aid === 'codex' && codexAccountsHere.length > 0) {
- return {
- type: 'submenu',
- label: `New ${AGENT_CONFIG[aid].label}`,
- icon: <AgentIcon agentId={aid} />,
- children: [
- {
- label: codexSystemLabel,
- icon: <AgentIcon agentId="codex" />,
- onClick: () => addAgentNode('codex', at, groupId)
- },
- ...codexAccountsHere.map((a): MenuItem => {
- const sel = codexAccountSelectable(
- a.id,
- codexAccountsHere,
- connectedProjectIdForHost
- )
- return {
- label: a.label,
- icon: <AgentIcon agentId="codex" />,
- disabled: !sel.ok,
- hint: sel.ok
- ? undefined
- : sel.reason === 'no-connection'
- ? 'This account lives on a host that is not connected — connect its SSH project first.'
- : 'This account is no longer available.',
- onClick: () => addAgentNode('codex', at, groupId, a.id)
- }
+ onClick: () => addAgentNode('claude', at, groupId, a.id)
})
- ]
- }
+ ),
+ ...(accountsHint
+ ? [
+ {
+ label: 'No accounts on this host yet',
+ onClick: () => {},
+ disabled: true,
+ hint: accountsHint
+ } satisfies MenuItem
+ ]
+ : [])
+ ]
}
+ }
+ // Codex gets its own account picker submenu when ≥1 managed account lives on this
+ // project's machine (S6 §3.4). Every managed row is gated through `codexAccountSelectable`
+ // — a missing/hostile/unconnected account renders DISABLED, so the fail-closed refusal is
+ // enforced before the click, and again in `addAgentNode` (the UI is not the boundary).
+ if (aid === 'codex' && codexAccountsHere.length > 0) {
return {
+ type: 'submenu',
label: `New ${AGENT_CONFIG[aid].label}`,
icon: <AgentIcon agentId={aid} />,
- onClick: () => addAgentNode(aid, at, groupId)
+ children: [
+ {
+ label: codexSystemLabel,
+ icon: <AgentIcon agentId="codex" />,
+ onClick: () => addAgentNode('codex', at, groupId)
+ },
+ ...codexAccountsHere.map((a): MenuItem => {
+ const sel = codexAccountSelectable(
+ a.id,
+ codexAccountsHere,
+ connectedProjectIdForHost
+ )
+ return {
+ label: a.label,
+ icon: <AgentIcon agentId="codex" />,
+ disabled: !sel.ok,
+ hint: sel.ok
+ ? undefined
+ : sel.reason === 'no-connection'
+ ? 'This account lives on a host that is not connected — connect its SSH project first.'
+ : 'This account is no longer available.',
+ onClick: () => addAgentNode('codex', at, groupId, a.id)
+ }
+ })
+ ]
}
- }),
+ }
+ return {
+ label: `New ${AGENT_CONFIG[aid].label}`,
+ icon: <AgentIcon agentId={aid} />,
+ onClick: () => addAgentNode(aid, at, groupId)
+ }
+ }
+ return [
+ ...BUILTIN_AGENT_IDS.filter((aid) => !disabled.includes(aid)).map(
+ (aid): AgentAddEntry => ({ agentId: aid, item: itemForBuiltin(aid) })
+ ),
...useSettings
.getState()
.settings.customAgents.filter((c) => !disabled.includes(c.id))
.map(
- (c): MenuItem => ({
- label: `New ${c.label}`,
- icon: <AgentIcon agentId={c.id} />,
- onClick: () => addAgentNode(c.id, at, groupId)
+ (c): AgentAddEntry => ({
+ agentId: c.id,
+ item: {
+ label: `New ${c.label}`,
+ icon: <AgentIcon agentId={c.id} />,
+ onClick: () => addAgentNode(c.id, at, groupId)
+ }
})
)
]
@@ -8671,7 +8684,11 @@ export function Canvas() {
icon: <IconTerminal />,
onClick: () => addTerminal(at, undefined, groupId)
},
- ...agentCreationItems(at, groupId),
+ // Same agent grouping as the pane menu (`New agent ▸` behind the account-capable rows), so
+ // one canvas does not show two different shapes for the same list. This menu's three
+ // content rows are hand-written and deliberately left alone — a frame offers the kinds
+ // that make sense INSIDE a frame, which is not the pane's full list.
+ ...agentEntriesToMenuItems(agentCreationEntries(at, groupId)),
{ label: 'New sticky note', icon: <IconNote />, onClick: () => addSticky(at, groupId) },
// Inside a worktree-bound frame this roots the manager at the WORKTREE, not the project —
// `cwdForNewNodeIn` is what makes a frame per branch also mean a file tree per branch.
@@ -8710,7 +8727,7 @@ export function Canvas() {
openWorktreeDialog,
isSshProject,
addTerminal,
- agentCreationItems,
+ agentCreationEntries,
addSticky,
addToExistingGroup,
groupSelection
@@ -8758,7 +8775,7 @@ export function Canvas() {
// CONTENT items from (see lib/addMenuSpec.ts). Built once here so the pane menu, the sidebar
// project-header "+", and any other ContextMenu-based surface pass the same handlers and can no
// longer drift on which kinds are addable. Agent entries are layered on by each surface from
- // `agentCreationItems` (already shared) — the spec owns the content list only.
+ // `agentCreationEntries` (already shared) — the spec owns the content list only.
const addCtx = useMemo(
() => ({
hasCwd: !!(useProjects.getState().getProject(activeProjectId)?.ssh?.remoteCwd ??
@@ -8802,13 +8819,15 @@ export function Canvas() {
e.preventDefault()
const at = screenToFlowPosition({ x: e.clientX, y: e.clientY })
const screenPos = { x: e.clientX, y: e.clientY }
- // Split the canonical content list around the agent block: the pane menu shows terminal,
- // THEN agents, THEN the rest (remote, browser, …, worktree). The spec is still the single
- // source for WHICH kinds appear and in what order — only the agent interleaving is local.
- const [terminalItem, ...restContent] = contentAddItemsToMenuItems(
+ // GROUPED (see lib/addMenuSpec): terminal + remote, the account-capable agents, then
+ // `New agent ▸` / `New view ▸` / `Files ▸` / `Orchestrate ▸`. The spec is still the single
+ // source for WHICH kinds appear, in what order, and with which disabled reason — this
+ // surface only chooses to render the grouped tree rather than the flat list.
+ const items = buildGroupedAddMenu(
CONTENT_ADD_ITEMS,
addHandlers,
addCtx,
+ agentCreationEntries(at),
at,
screenPos
)
@@ -8816,9 +8835,7 @@ export function Canvas() {
x: e.clientX,
y: e.clientY,
items: [
- terminalItem,
- ...agentCreationItems(at),
- ...restContent,
+ ...items,
{ type: 'separator' },
// Canvas actions.
{ label: 'Select all', icon: <IconSelectAll />, onClick: selectAll },
@@ -8848,7 +8865,7 @@ export function Canvas() {
},
[
screenToFlowPosition,
- agentCreationItems,
+ agentCreationEntries,
addHandlers,
addCtx,
selectAll,
@@ -12350,20 +12367,22 @@ export function Canvas() {
// project LIVE (`useProjects.getState()`) at click time, guarded by `canCreateOnCanvas`.
if (projectId !== activeProjectId) switchProject(projectId)
const pos = e ? { x: e.clientX, y: e.clientY } : { x: 80, y: 120 }
- const [terminalItem, ...restContent] = contentAddItemsToMenuItems(
- CONTENT_ADD_ITEMS,
- addHandlers,
- addCtx,
- undefined,
- pos
- )
setMenu({
x: pos.x,
y: pos.y,
- items: [terminalItem, ...agentCreationItems(), ...restContent]
+ // The SAME grouped tree the pane right-click builds — this surface exists to mirror that
+ // menu, so it must not be the one place that still renders the flat 18-row list.
+ items: buildGroupedAddMenu(
+ CONTENT_ADD_ITEMS,
+ addHandlers,
+ addCtx,
+ agentCreationEntries(),
+ undefined,
+ pos
+ )
})
},
- [activeProjectId, switchProject, addHandlers, addCtx, agentCreationItems]
+ [activeProjectId, switchProject, addHandlers, addCtx, agentCreationEntries]
)
// Sidebar drag-to-group: reparent a session into a canvas group (groupId) or out (null).
diff --git a/src/renderer/components/ContextMenu.submenu-depth.test.tsx b/src/renderer/components/ContextMenu.submenu-depth.test.tsx
new file mode 100644
index 000000000..0517f8dac
--- /dev/null
+++ b/src/renderer/components/ContextMenu.submenu-depth.test.tsx
@@ -0,0 +1,105 @@
+// @vitest-environment jsdom
+//
+// MEASURES the submenu depth cap, rather than asserting it from the source.
+//
+// `ContextMenu` renders a submenu's children with
+// `if (child.type === 'colors' || child.type === 'submenu') return null` — so a THIRD level is
+// dropped with no error, no warning and nothing on screen. That is not a style rule anybody can
+// choose to ignore: it is why `lib/addMenuSpec`'s `isPinnedAgentEntry` refuses to nest an agent
+// row that is already a submenu. Claude's and Codex's account pickers ARE such rows, so nesting
+// one would silently delete the account picker for exactly the users who have managed accounts —
+// the "looks like it worked" failure, visible only to the people it breaks.
+//
+// If someone teaches ContextMenu to render a third level, this test goes red and the pin in
+// addMenuSpec can be reconsidered deliberately. Until then it is the fact the grouping rests on.
+import { act } from 'react'
+import { createRoot } from 'react-dom/client'
+import { afterEach, describe, expect, it } from 'vitest'
+import { ContextMenu, type MenuItem } from './ContextMenu'
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+// jsdom ships no ResizeObserver, and `useMenuFlip` (the edge-flip this menu uses) observes itself.
+// The flip geometry is not what is under test here — reachability of the rows is — so a inert stub
+// is enough, and leaves the component's real render path untouched.
+class NoopResizeObserver {
+ observe(): void {}
+ unobserve(): void {}
+ disconnect(): void {}
+}
+;(globalThis as { ResizeObserver?: unknown }).ResizeObserver ??= NoopResizeObserver
+
+const noop = () => {}
+
+afterEach(() => {
+ document.body.innerHTML = ''
+})
+
+/** Renders into a body portal; hovers the row with `label` so its flyout opens. */
+function renderMenu(items: MenuItem[], hoverLabel?: string): void {
+ const host = document.createElement('div')
+ document.body.appendChild(host)
+ act(() => {
+ createRoot(host).render(<ContextMenu x={0} y={0} items={items} onClose={noop} />)
+ })
+ if (!hoverLabel) return
+ const row = [...document.querySelectorAll('.ctx-item--submenu')].find((el) =>
+ el.textContent?.includes(hoverLabel)
+ )
+ if (!row) throw new Error(`no submenu row labelled ${hoverLabel}`)
+ // React synthesises onMouseEnter from the delegated mouseover event.
+ act(() => {
+ row.dispatchEvent(new MouseEvent('mouseover', { bubbles: true }))
+ })
+}
+
+describe('ContextMenu submenu depth', () => {
+ it('renders a second-level LEAF, including its disabled state and reason', () => {
+ renderMenu(
+ [
+ {
+ type: 'submenu',
+ label: 'Orchestrate',
+ children: [
+ { label: 'New branch checkout…', onClick: noop, disabled: true, hint: 'Not supported in SSH' }
+ ]
+ }
+ ],
+ 'Orchestrate'
+ )
+ const leaf = [...document.querySelectorAll('.ctx-submenu button')].find((b) =>
+ b.textContent?.includes('New branch checkout…')
+ ) as HTMLButtonElement | undefined
+ expect(leaf).toBeDefined()
+ // A leaf keeps BOTH halves of an explicit degrade inside a flyout — the depth cap drops
+ // nested submenus, never a leaf's disabled state or its reason.
+ expect(leaf?.disabled).toBe(true)
+ expect(leaf?.getAttribute('title')).toBe('Not supported in SSH')
+ })
+
+ it('DROPS a third-level submenu silently — nothing is rendered for it', () => {
+ renderMenu(
+ [
+ {
+ type: 'submenu',
+ label: 'New agent',
+ children: [
+ { label: 'New Gemini', onClick: noop },
+ {
+ type: 'submenu',
+ label: 'New Codex',
+ children: [{ label: '[email protected]', onClick: noop }]
+ }
+ ]
+ }
+ ],
+ 'New agent'
+ )
+ const flyout = document.querySelector('.ctx-submenu')
+ expect(flyout?.textContent).toContain('New Gemini')
+ // The measurement this whole design rests on: the nested submenu row is GONE, and so is the
+ // account it held. No error, no placeholder — which is why the grouping must never create one.
+ expect(flyout?.textContent).not.toContain('New Codex')
+ expect(flyout?.textContent).not.toContain('[email protected]')
+ })
+})
diff --git a/src/renderer/lib/addMenuSpec.surfaces.test.ts b/src/renderer/lib/addMenuSpec.surfaces.test.ts
new file mode 100644
index 000000000..a6d49b8ed
--- /dev/null
+++ b/src/renderer/lib/addMenuSpec.surfaces.test.ts
@@ -0,0 +1,67 @@
+// Four-surface parity for the "add node" menus, pinned at SOURCE level.
+//
+// Why source level: three of the four surfaces are assembled inside `Canvas.tsx`, a file no unit
+// test mounts, so the only thing a behavioural test could reach is the pure builder those call
+// sites are supposed to use — and "is supposed to" is exactly the part that drifts. This repo has
+// shipped a one-of-two-shells change three times (`hook-verified-parity.test.ts` exists for the
+// same reason); the add menus have already drifted once, which is why `addMenuSpec` was created.
+//
+// What it does NOT claim: that the menus look right, or that a flyout opens. It claims that every
+// surface still reads from the ONE spec, and that the two surfaces which deliberately do not are
+// still deliberate.
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const SRC = join(__dirname, '..', '..')
+const read = (rel: string): string => readFileSync(join(SRC, rel), 'utf8')
+
+const CANVAS = read('renderer/canvas/Canvas.tsx')
+const DOCK = read('renderer/components/Dock.tsx')
+const KANBAN = read('renderer/components/kanban/KanbanView.tsx')
+
+describe('add-menu surfaces', () => {
+ // ── 1 + 2: the two ContextMenu surfaces render the GROUPED tree ──────────────────────────────
+ it('builds the pane right-click AND the sidebar "+" from the same grouped builder', () => {
+ const calls = CANVAS.match(/buildGroupedAddMenu\(/g) ?? []
+ // One for `onPaneContextMenu`, one for `addToProject` (the sessions-sidebar project-header
+ // "+"). If a third add surface appears in Canvas it should be here too — bump this with it.
+ expect(calls.length).toBe(2)
+ })
+
+ it('leaves no flat content list behind in Canvas', () => {
+ // The old shape was `const [terminalItem, ...restContent] = contentAddItemsToMenuItems(...)`,
+ // splitting the canonical list POSITIONALLY around the agent block — which silently depended
+ // on `terminal` being first in CONTENT_ADD_ITEMS. Both call sites moved to the grouped
+ // builder; if one is ever reverted, this is what says so.
+ expect(CANVAS).not.toContain('contentAddItemsToMenuItems')
+ expect(CANVAS).not.toContain('restContent')
+ })
+
+ // ── 3: the group-frame menu shares the agent grouping ───────────────────────────────────────
+ it('groups agents on the group-frame menu too, from the same helper', () => {
+ expect(CANVAS).toContain('agentEntriesToMenuItems(agentCreationEntries(')
+ })
+
+ it('tags every agent row with its id, so nothing decides nesting from a hardcoded name', () => {
+ expect(CANVAS).toContain('AgentAddEntry')
+ // The pin that matters: Canvas must not re-implement `isPinnedAgentEntry`'s judgement by
+ // spelling an agent id at the menu-assembly layer.
+ expect(CANVAS).not.toContain('PINNED_AGENT')
+ })
+
+ // ── 4: the Dock is deliberately NOT grouped ─────────────────────────────────────────────────
+ it('keeps the Dock on the flat row adapter — a decision, not an oversight', () => {
+ expect(DOCK).toContain('contentAddItemsToDockRows')
+ expect(DOCK).not.toContain('buildGroupedAddMenu')
+ })
+
+ // ── the kanban column "+ New session" is a different list, not a lagging copy ────────────────
+ it('does not feed the kanban column menu from the content spec', () => {
+ // `KanbanCreateChoice` is a closed union of the kinds that BECOME a card
+ // (`canvas/toKanbanSession.ts`); the spec's list contains kinds the board can never show.
+ // The module doc used to name this surface as a consumer — it never was.
+ expect(KANBAN).not.toContain('CONTENT_ADD_ITEMS')
+ expect(KANBAN).not.toContain('buildGroupedAddMenu')
+ })
+})
diff --git a/src/renderer/lib/addMenuSpec.test.tsx b/src/renderer/lib/addMenuSpec.test.tsx
index 029b29d85..fa6611e13 100644
--- a/src/renderer/lib/addMenuSpec.test.tsx
+++ b/src/renderer/lib/addMenuSpec.test.tsx
@@ -1,6 +1,11 @@
import { describe, it, expect } from 'vitest'
+import type { MenuItem } from '../components/ContextMenu'
import {
+ ADD_GROUP_LABEL,
+ ADD_ITEM_GROUP,
+ AGENT_GROUP_LABEL,
CONTENT_ADD_ITEMS,
+ buildGroupedAddMenu,
contentAddItemsToMenuItems,
contentAddItemsToDockRows,
FILES_NO_CWD_HINT,
@@ -8,9 +13,13 @@ import {
WORKTREE_NO_CWD_HINT,
WORKTREE_SSH_HINT,
type AddItem,
- type AddHandlers
+ type AddHandlers,
+ type AgentAddEntry
} from './addMenuSpec'
+/** The SSH-gated row's label, spelled once so the assertions below read cleanly. */
+const SSH_GATED_ROW = 'New worktree…'
+
const noop = () => {}
const handlers = (overrides: Partial<AddHandlers> = {}): AddHandlers => ({
terminal: noop,
@@ -199,4 +208,257 @@ describe('contentAddItemsToDockRows', () => {
expect(newFile?.hint).toBe(NEW_FILE_NO_CWD_HINT)
expect(rows.find((r) => r.kind === 'worktree')?.hint).toBe(WORKTREE_NO_CWD_HINT)
})
+
+ // The per-surface decision, pinned so it is a decision rather than an oversight: the Dock's
+ // rows stay FLAT. Its popup is opened deliberately, it already omits terminal + remote (10 rows,
+ // not 18), and its agent flyouts are bespoke JSX — grouping it would mean a second submenu
+ // implementation with its own geometry, for crowding nobody reported.
+ it('stays FLAT — the Dock adapter emits rows, never groups', () => {
+ const rows = contentAddItemsToDockRows(CONTENT_ADD_ITEMS, handlers(), {
+ hasCwd: true,
+ isSshProject: false
+ })
+ expect(rows.every((r) => typeof r.label === 'string' && 'onClick' in r)).toBe(true)
+ expect(rows.map((r) => r.kind)).not.toContain(undefined)
+ })
+})
+
+// ─── Grouping ────────────────────────────────────────────────────────────────────────────────
+// The pane right-click and the sidebar "+" render the GROUPED tree; the Dock deliberately does
+// not (see the per-surface note in the module doc and the Dock case just above).
+
+const agent = (agentId: string, label = `New ${agentId}`): AgentAddEntry => ({
+ agentId,
+ item: { label, onClick: noop }
+})
+/** An agent row that already owns an account picker — Claude's and Codex's real shape. */
+const agentWithAccounts = (agentId: string, accounts: string[]): AgentAddEntry => ({
+ agentId,
+ item: {
+ type: 'submenu',
+ label: `New ${agentId}`,
+ children: accounts.map((a) => ({ label: a, onClick: noop }))
+ }
+})
+
+/** Every label the user can actually REACH, at either level. */
+function reachableLabels(items: readonly MenuItem[]): string[] {
+ const out: string[] = []
+ for (const item of items) {
+ if (item.type === 'submenu') {
+ out.push(item.label)
+ for (const child of item.children) if ('label' in child) out.push(child.label)
+ } else if ('label' in item) out.push(item.label)
+ }
+ return out
+}
+
+const topLabels = (items: readonly MenuItem[]): string[] =>
+ items.map((i) => ('label' in i ? i.label : `[${i.type}]`))
+
+describe('ADD_ITEM_GROUP', () => {
+ // The compile-time half is the total Record; this is the runtime half, so a kind added with a
+ // cast or a loosened type still cannot slip through unrouted.
+ it('routes every content kind', () => {
+ for (const kind of allKinds) expect(ADD_ITEM_GROUP[kind]).toBeTruthy()
+ expect(Object.keys(ADD_ITEM_GROUP).sort()).toEqual([...allKinds].sort())
+ })
+})
+
+describe('buildGroupedAddMenu', () => {
+ const ctx = { hasCwd: true, isSshProject: false }
+ const agents = [
+ agentWithAccounts('claude', ['System account', '[email protected]']),
+ agent('codex', 'New Codex'),
+ agent('gemini', 'New Gemini'),
+ agent('grok', 'New Grok'),
+ agent('custom:1', 'New My Agent')
+ ]
+
+ it('shows terminal + remote, the account-capable agents, then four submenus — in that order', () => {
+ const items = buildGroupedAddMenu(CONTENT_ADD_ITEMS, handlers(), ctx, agents)
+ expect(topLabels(items)).toEqual([
+ 'New terminal',
+ 'New remote…',
+ 'New claude',
+ 'New Codex',
+ AGENT_GROUP_LABEL,
+ ADD_GROUP_LABEL.view,
+ ADD_GROUP_LABEL.files,
+ ADD_GROUP_LABEL.orchestrate
+ ])
+ })
+
+ it('puts each content kind in its declared group', () => {
+ const items = buildGroupedAddMenu(CONTENT_ADD_ITEMS, handlers(), ctx, agents)
+ const children = (label: string): string[] => {
+ const sub = items.find((i) => i.type === 'submenu' && i.label === label)
+ return sub && sub.type === 'submenu'
+ ? sub.children.map((c) => ('label' in c ? c.label : ''))
+ : []
+ }
+ expect(children(ADD_GROUP_LABEL.view)).toEqual([
+ 'New browser',
+ 'New web view…',
+ 'New sticky note',
+ 'New file manager',
+ 'New dino game'
+ ])
+ expect(children(ADD_GROUP_LABEL.files)).toEqual(['Open file…', 'New file…'])
+ expect(children(ADD_GROUP_LABEL.orchestrate)).toEqual([
+ 'New trigger…',
+ 'Spawn a team…',
+ SSH_GATED_ROW
+ ])
+ expect(children(AGENT_GROUP_LABEL)).toEqual(['New Gemini', 'New Grok', 'New My Agent'])
+ })
+
+ // Grouping must be a REARRANGEMENT, never a filter: the ⌘K palette makes this menu
+ // non-exhaustive by choice, but a row that silently vanished from it would be a feature nobody
+ // can find.
+ it('loses nothing — every flat row is still reachable', () => {
+ const flat = contentAddItemsToMenuItems(CONTENT_ADD_ITEMS, handlers(), ctx)
+ const grouped = buildGroupedAddMenu(CONTENT_ADD_ITEMS, handlers(), ctx, agents)
+ const reachable = new Set(reachableLabels(grouped))
+ for (const row of flat) if ('label' in row) expect(reachable).toContain(row.label)
+ for (const a of agents) if ('label' in a.item) expect(reachable).toContain(a.item.label)
+ })
+
+ // The structural invariant the whole shape rests on (MEASURED in
+ // components/ContextMenu.submenu-depth.test.tsx: a third level renders as NOTHING).
+ it('never emits a third level', () => {
+ const items = buildGroupedAddMenu(CONTENT_ADD_ITEMS, handlers(), ctx, agents)
+ for (const item of items) {
+ if (item.type !== 'submenu') continue
+ for (const child of item.children) expect(child.type).not.toBe('submenu')
+ }
+ })
+
+ it('keeps an agent row that OWNS an account picker at the first level', () => {
+ // Codex only grows a submenu once the user has managed Codex accounts. Nesting it then would
+ // delete the picker silently — so the row must stay at the top in BOTH shapes.
+ const withCodexAccounts = [
+ agentWithAccounts('claude', ['System account']),
+ agentWithAccounts('codex', ['System account', '[email protected]']),
+ agent('gemini', 'New Gemini')
+ ]
+ const items = buildGroupedAddMenu(CONTENT_ADD_ITEMS, handlers(), ctx, withCodexAccounts)
+ const codex = items.find((i) => 'label' in i && i.label === 'New codex')
+ expect(codex).toBeDefined()
+ expect(codex?.type).toBe('submenu')
+ expect(reachableLabels(items)).toContain('[email protected]')
+ })
+
+ // The half of `isPinnedAgentEntry` that has NO live example yet, and is therefore the half a
+ // refactor deletes as dead code. Today the only agents that grow a picker (claude, codex) are
+ // also the account-capable ones, so the id rule alone would look sufficient — it is not: the
+ // refusal is about the ROW's shape, and an agent that grows a submenu for any other reason
+ // would be nested and rendered as nothing. Written as a hypothetical on purpose.
+ it('keeps ANY submenu row at the first level, account-capable or not', () => {
+ const items = buildGroupedAddMenu(CONTENT_ADD_ITEMS, handlers(), ctx, [
+ agent('claude', 'New Claude Code'),
+ // Not in ACCOUNT_CAPABLE_AGENT_IDS, but its row is a submenu.
+ agentWithAccounts('gemini', ['profile-a', 'profile-b'])
+ ])
+ expect(topLabels(items)).toContain('New gemini')
+ expect(reachableLabels(items)).toContain('profile-b')
+ const agentSub = items.find((i) => i.type === 'submenu' && i.label === AGENT_GROUP_LABEL)
+ expect(agentSub).toBeUndefined()
+ })
+
+ it('pins an account-capable agent even while it has NO accounts, so the shape is stable', () => {
+ // Otherwise the Codex row would jump between the top level and the submenu as accounts come
+ // and go — a menu that rearranges itself is a menu nobody can learn.
+ const flatCodex = buildGroupedAddMenu(CONTENT_ADD_ITEMS, handlers(), ctx, [
+ agent('claude', 'New Claude Code'),
+ agent('codex', 'New Codex'),
+ agent('gemini', 'New Gemini')
+ ])
+ expect(topLabels(flatCodex).slice(0, 4)).toEqual([
+ 'New terminal',
+ 'New remote…',
+ 'New Claude Code',
+ 'New Codex'
+ ])
+ })
+
+ it('emits NO agent submenu when every agent is pinned — an empty flyout is a dead target', () => {
+ const items = buildGroupedAddMenu(CONTENT_ADD_ITEMS, handlers(), ctx, [
+ agent('claude'),
+ agent('codex')
+ ])
+ expect(topLabels(items)).not.toContain(AGENT_GROUP_LABEL)
+ })
+
+ // The explicit-degrade rule (#621) has to survive the move into a flyout: a row that is off for
+ // a reason the user cannot see teaches nothing.
+ it('carries the disabled state AND its reason into the submenu', () => {
+ const ssh = buildGroupedAddMenu(
+ CONTENT_ADD_ITEMS,
+ handlers(),
+ { hasCwd: true, isSshProject: true },
+ agents
+ )
+ const orchestrate = ssh.find(
+ (i) => i.type === 'submenu' && i.label === ADD_GROUP_LABEL.orchestrate
+ )
+ const row =
+ orchestrate?.type === 'submenu'
+ ? orchestrate.children.find((c) => 'label' in c && c.label === SSH_GATED_ROW)
+ : undefined
+ expect(row && 'disabled' in row && row.disabled).toBe(true)
+ expect(row && 'hint' in row && row.hint).toBe(WORKTREE_SSH_HINT)
+
+ const noCwd = buildGroupedAddMenu(
+ CONTENT_ADD_ITEMS,
+ handlers(),
+ { hasCwd: false, isSshProject: false },
+ agents
+ )
+ const files = noCwd.find((i) => i.type === 'submenu' && i.label === ADD_GROUP_LABEL.files)
+ const newFile =
+ files?.type === 'submenu'
+ ? files.children.find((c) => 'label' in c && c.label === 'New file…')
+ : undefined
+ expect(newFile && 'hint' in newFile && newFile.hint).toBe(NEW_FILE_NO_CWD_HINT)
+ })
+
+ it('wires every handler through the grouped tree', () => {
+ const calls: string[] = []
+ const h = handlers({
+ terminal: () => calls.push('terminal'),
+ remote: () => calls.push('remote'),
+ browser: () => calls.push('browser'),
+ web: () => calls.push('web'),
+ sticky: () => calls.push('sticky'),
+ files: () => calls.push('files'),
+ dino: () => calls.push('dino'),
+ trigger: () => calls.push('trigger'),
+ openFile: () => calls.push('openFile'),
+ newFile: () => calls.push('newFile'),
+ spawnTeam: () => calls.push('spawnTeam'),
+ worktree: () => calls.push('scopedCheckout')
+ })
+ const items = buildGroupedAddMenu(CONTENT_ADD_ITEMS, h, ctx, agents)
+ for (const item of items) {
+ if (item.type === 'submenu') {
+ for (const child of item.children) if ('onClick' in child) child.onClick()
+ } else if ('onClick' in item) item.onClick()
+ }
+ // Every content handler is reachable — nothing was orphaned by the move into a flyout.
+ expect(calls.sort()).toEqual([
+ 'browser',
+ 'dino',
+ 'files',
+ 'newFile',
+ 'openFile',
+ 'remote',
+ 'scopedCheckout',
+ 'spawnTeam',
+ 'sticky',
+ 'terminal',
+ 'trigger',
+ 'web'
+ ])
+ })
})
diff --git a/src/renderer/lib/addMenuSpec.tsx b/src/renderer/lib/addMenuSpec.tsx
index 6d158d071..fc96e4f7b 100644
--- a/src/renderer/lib/addMenuSpec.tsx
+++ b/src/renderer/lib/addMenuSpec.tsx
@@ -1,9 +1,16 @@
/**
- * The single declarative source of truth for the "add node" content items that appear in every
- * creation menu: the canvas pane right-click, the sessions-sidebar project-header "+", the bottom
- * Dock "+", and the kanban column "+ New session".
+ * The single declarative source of truth for the "add node" content items that appear in the
+ * creation menus that can offer every node kind: the canvas pane right-click, the
+ * sessions-sidebar project-header "+", and the bottom Dock "+".
*
- * The duplication this kills: each of those four surfaces used to hand-maintain its own list of
+ * **The kanban column's "+ New session" is deliberately NOT one of them** — this doc used to list
+ * it as a fourth consumer, which was never true and is worth stating so nobody "fixes" it by
+ * wiring it up. Its `KanbanCreateChoice` is a closed union of terminal / browser / sticky / agent
+ * because those are the only kinds `canvas/toKanbanSession.ts` turns INTO A CARD; feeding it this
+ * list would offer kinds (a trigger, a worktree, an editor) that create a node the board can never
+ * show. A surface that can only render part of the list is a different list, not a lagging copy.
+ *
+ * The duplication this kills: each of those surfaces used to hand-maintain its own list of
* which node kinds you can add, so they drifted out of parity (the pane menu had "New browser" but
* the Dock and the sidebar "+" did not, etc.). Now they all derive their CONTENT items from
* {@link CONTENT_ADD_ITEMS}, filtered by project context (cwd / SSH). Agent entries are layered on
@@ -11,7 +18,9 @@
* `agentCreationItems()`, and the Dock's agent-account hover flyouts are intentionally bespoke UX —
* so this spec owns the CONTENT list only, not the agents.
*
- * Two render adapters map the same {@link AddItem} list to the two menu worlds:
+ * Three render adapters map the same {@link AddItem} list to the menu worlds:
+ * - {@link buildGroupedAddMenu} → the GROUPED tree the two `ContextMenu` surfaces show (see the
+ * grouping section at the bottom of this file for why, and for the submenu depth cap).
* - {@link contentAddItemsToMenuItems} → the {@link MenuItem} type the `ContextMenu` component
* consumes (pane menu, project-header "+").
* - {@link contentAddItemsToDockRows} → the Dock's custom `<button>` JSX.
@@ -20,8 +29,11 @@
*/
import type { ReactNode } from 'react'
import type { MenuItem } from '../components/ContextMenu'
+import { ACCOUNT_CAPABLE_AGENT_IDS } from '@shared/agents/account-binding'
import {
+ IconAgent,
IconBranch,
+ IconCanvasView,
IconDino,
IconEditor,
IconExplorer,
@@ -316,3 +328,168 @@ export function contentAddItemsToDockRows(
}
return out
}
+
+// ─── Grouping (the pane right-click and the sidebar "+") ─────────────────────────────────────
+//
+// Both of those surfaces used to render the whole flat list — 18 "New …" rows before the four
+// canvas actions — which is a list you read rather than a menu you aim at. The ⌘K palette already
+// makes every one of these searchable, and the keybinding registry already carries a remappable
+// command per agent and per node kind (`node.new*`, #365), so this menu does not have to be
+// EXHAUSTIVE; it has to be FAST. Grouping trades one hover for a target you can hit without
+// reading, and leaves the exhaustive paths exactly where they already were.
+//
+// **The depth cap is structural, not stylistic.** `ContextMenu` renders a submenu's children with
+// `if (child.type === 'colors' || child.type === 'submenu') return null` — a third level is
+// silently dropped, with no error and nothing on screen. That single line decides the whole shape
+// below: an agent row that is ALREADY a submenu (Claude's and Codex's account pickers) can never
+// be nested, or the picker disappears for exactly the users who have managed accounts.
+
+/** Which section of the grouped menu a content kind belongs to. `top` = stays a first-level row. */
+export type AddGroupId = 'top' | 'view' | 'files' | 'orchestrate'
+
+/**
+ * The routing table, as a total `Record` over the kind union **on purpose**: a new `AddItem` kind
+ * is a COMPILE ERROR here until somebody decides where it belongs. The alternative (a lookup with
+ * a default) would silently drop a new kind into one bucket forever, which is the drift this
+ * module exists to prevent.
+ *
+ * `terminal` and `remote` stay at the top because they are the two fastest paths to a session, and
+ * because `remote` is not an agent — the one entry point to an SSH session must not be buried
+ * under a menu named "New agent", where nobody would look for it.
+ */
+export const ADD_ITEM_GROUP: Record<AddItem['kind'], AddGroupId> = {
+ terminal: 'top',
+ remote: 'top',
+ browser: 'view',
+ web: 'view',
+ sticky: 'view',
+ files: 'view',
+ dino: 'view',
+ 'open-file': 'files',
+ 'new-file': 'files',
+ 'spawn-team': 'orchestrate',
+ trigger: 'orchestrate',
+ worktree: 'orchestrate'
+}
+
+/** Submenu labels, kept here so every surface names the same group the same way. */
+export const AGENT_GROUP_LABEL = 'New agent'
+export const ADD_GROUP_LABEL: Record<Exclude<AddGroupId, 'top'>, string> = {
+ view: 'New view',
+ files: 'Files',
+ orchestrate: 'Orchestrate'
+}
+
+/**
+ * One "New <agent>" row plus the agent it belongs to. The surfaces build the ROW (accounts,
+ * disabled reasons and custom agents all live in Canvas); this module only needs the id to decide
+ * whether the row may be nested.
+ */
+export interface AgentAddEntry {
+ agentId: string
+ item: MenuItem
+}
+
+/**
+ * Whether an agent row must stay at the FIRST level. Two independent reasons, and both are
+ * refusals rather than preferences:
+ *
+ * 1. **It is already a submenu.** Nesting it makes `ContextMenu` render it as nothing (see the
+ * depth cap above) — the account picker would vanish silently, for exactly the users who have
+ * accounts. This half is derived from the row itself, so an agent that grows a picker later is
+ * protected on the day it does.
+ * 2. **It CAN own a managed account** (`ACCOUNT_CAPABLE_AGENT_IDS`). Rule 1 alone would move a
+ * row in and out of the submenu as the user adds or removes accounts — a menu that rearranges
+ * itself is a menu you cannot learn. Pinning the account-capable agents keeps the shape stable
+ * whether or not an account exists yet.
+ *
+ * Both halves are DERIVED — no agent id is spelled here — so a new builtin agent joins the
+ * submenu by itself, and one that gains managed accounts is promoted by itself.
+ */
+export function isPinnedAgentEntry(entry: AgentAddEntry): boolean {
+ if (entry.item.type === 'submenu') return true
+ return ACCOUNT_CAPABLE_AGENT_IDS.includes(entry.agentId)
+}
+
+/**
+ * Pinned agent rows, then the rest behind one `New agent ▸`. An empty tail emits NO submenu — an
+ * empty flyout is a dead target.
+ */
+export function agentEntriesToMenuItems(agents: readonly AgentAddEntry[]): MenuItem[] {
+ const pinned = agents.filter(isPinnedAgentEntry).map((e) => e.item)
+ const rest = agents.filter((e) => !isPinnedAgentEntry(e)).map((e) => e.item)
+ return [
+ ...pinned,
+ ...(rest.length > 0
+ ? [
+ {
+ type: 'submenu',
+ label: AGENT_GROUP_LABEL,
+ icon: <IconAgent />,
+ children: rest
+ } as MenuItem
+ ]
+ : [])
+ ]
+}
+
+const GROUP_ICON: Record<Exclude<AddGroupId, 'top'>, ReactNode> = {
+ view: <IconCanvasView />,
+ files: <IconEditor />,
+ orchestrate: <IconGroup />
+}
+
+/**
+ * The grouped "add" menu shared by the canvas pane right-click and the sessions-sidebar "+".
+ *
+ * Rows come from {@link contentAddItemsToMenuItems} — the same per-kind builder the flat list and
+ * the Dock use — so a row's label, icon, handler and **disabled reason** are written exactly once.
+ * That is what keeps "New worktree…" greyed with `WORKTREE_SSH_HINT` inside its submenu instead of
+ * quietly losing the explanation on the way in: a `hint` on a leaf renders in a flyout the same as
+ * at the top level (the depth cap drops nested SUBMENUS, never a leaf's disabled state).
+ *
+ * Order is the canonical one: top rows, then agents, then view / files / orchestrate. A group
+ * whose rows are all filtered out emits no submenu at all.
+ */
+export function buildGroupedAddMenu(
+ items: readonly AddItem[],
+ handlers: AddHandlers,
+ ctx: AddCtx,
+ agents: readonly AgentAddEntry[],
+ at?: AddPos,
+ screenPos?: { x: number; y: number }
+): MenuItem[] {
+ const top: MenuItem[] = []
+ const buckets: Record<Exclude<AddGroupId, 'top'>, MenuItem[]> = {
+ view: [],
+ files: [],
+ orchestrate: []
+ }
+ for (const item of items) {
+ // Built one at a time through the SHARED mapper rather than re-implemented here: a second
+ // copy of the per-kind rows is exactly how these surfaces drifted apart before this module.
+ const [row] = contentAddItemsToMenuItems([item], handlers, ctx, at, screenPos)
+ if (!row) continue
+ const group = ADD_ITEM_GROUP[item.kind]
+ if (group === 'top') top.push(row)
+ else buckets[group].push(row)
+ }
+ const submenu = (id: Exclude<AddGroupId, 'top'>): MenuItem[] =>
+ buckets[id].length > 0
+ ? [
+ {
+ type: 'submenu',
+ label: ADD_GROUP_LABEL[id],
+ icon: GROUP_ICON[id],
+ children: buckets[id]
+ } as MenuItem
+ ]
+ : []
+ return [
+ ...top,
+ ...agentEntriesToMenuItems(agents),
+ ...submenu('view'),
+ ...submenu('files'),
+ ...submenu('orchestrate')
+ ]
+}
diff --git a/src/shared/agents/account-binding.ts b/src/shared/agents/account-binding.ts
index b23969875..bc24ff81e 100644
--- a/src/shared/agents/account-binding.ts
+++ b/src/shared/agents/account-binding.ts
@@ -1,3 +1,14 @@
+/**
+ * The builtin agents that can own a MANAGED ACCOUNT — the one list behind both the binding rule
+ * below and the add menus' decision about which agent rows stay out of the `New agent` submenu
+ * (`renderer/lib/addMenuSpec`). Those two facts really are the same fact: an agent that can grow
+ * an account picker is an agent whose row can become a SUBMENU, and `ContextMenu` renders a
+ * submenu inside a submenu as NOTHING — so nesting such a row silently deletes its account picker
+ * for exactly the users who have accounts. Written once here so a third agent gaining managed
+ * accounts cannot light up one of the two and not the other.
+ */
+export const ACCOUNT_CAPABLE_AGENT_IDS: readonly string[] = ['claude', 'codex']
+
/**
* Which managed account a node is actually BOUND to — the one rule behind both `data.accountId`
* and the account's default node color.
@@ -27,6 +38,6 @@ export function boundAccountId(
agentId: string | undefined
): string | undefined {
if (!accountId) return undefined
- if (agentId !== undefined && agentId !== 'claude' && agentId !== 'codex') return undefined
+ if (agentId !== undefined && !ACCOUNT_CAPABLE_AGENT_IDS.includes(agentId)) return undefined
return accountId
}