Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
feat(agent): live/background start toggle on the session composer (#6383)
Eric Hayese2c55e201475
diff --git a/apps/web/src/features/block-agent/component/ComposeAgentSession.test.tsx b/apps/web/src/features/block-agent/component/ComposeAgentSession.test.tsxindex 5b470999b7..4164c55b6c 100644--- a/apps/web/src/features/block-agent/component/ComposeAgentSession.test.tsx+++ b/apps/web/src/features/block-agent/component/ComposeAgentSession.test.tsx@@ -24,7 +24,12 @@ const cursorConnection = vi.hoisted(() => ({registered: true,isPlaceholderData: false,}));-const hotkeys = vi.hoisted(() => ({ submit: (): boolean => false }));+const hotkeys = vi.hoisted(() => ({+ enter: (): boolean => false,+ cmdEnter: (): boolean => false,+}));+const toasts = vi.hoisted(() => ({ success: vi.fn() }));+const cmd = vi.hoisted(() => ({ held: false }));vi.mock('@core/context/user', () => ({useUserId: () => () => 'test-user',@@ -41,6 +46,7 @@ vi.mock('@components/app/split-layout/layout', () => ({useSplitLayout: () => ({ openWithSplit: navigation.open }),}));vi.mock('@components/app/split-layout/layoutUtils', () => ({+ useCanAutofocusSplitContent: () => true,useSplitPanelOrThrow: () => ({handle: {close: navigation.close,@@ -51,10 +57,25 @@ vi.mock('@components/app/split-layout/layoutUtils', () => ({}));vi.mock('@core/hotkey/hotkeys', () => ({useHotkeyDOMScope: () => [vi.fn(), 'test'],- registerHotkey: (options: { keyDownHandler: () => boolean }) => {- hotkeys.submit = options.keyDownHandler;+ registerHotkey: (options: {+ hotkey?: string | string[];+ keyDownHandler: () => boolean;+ }) => {+ const keys = Array.isArray(options.hotkey)+ ? options.hotkey+ : [options.hotkey];+ for (const key of keys) {+ if (key === 'enter') hotkeys.enter = options.keyDownHandler;+ if (key === 'cmd+enter') hotkeys.cmdEnter = options.keyDownHandler;+ }},}));+vi.mock('@core/hotkey/state', () => ({+ pressedKeys: () => new Set(cmd.held ? ['cmd'] : []),+}));+vi.mock('@core/component/Toast/Toast', () => ({+ toast: { success: (...args: unknown[]) => toasts.success(...args) },+}));vi.mock('@queries/agents/agents', () => ({useAgentsQuery: () => ({isSuccess: true,@@ -153,8 +174,13 @@ vi.mock('@ui', () => {SubTrigger: Container,SubContent: Container,}),+ Tooltip: (props: { children?: import('solid-js').JSX.Element }) =>+ props.children,+ Hotkey: () => null,+ SingleSelectCheck: () => null,badgeTriggerClasses: () => '',- cn: () => '',+ cn: (...inputs: Array<string | false | undefined>) =>+ inputs.filter(Boolean).join(' '),};});@@ -168,6 +194,7 @@ let client: QueryClient;beforeEach(() => {cursorConnection.registered = true;cursorConnection.isPlaceholderData = false;+ cmd.held = false;window.localStorage.clear();vi.clearAllMocks();vi.spyOn(console, 'error').mockImplementation(() => {});@@ -198,6 +225,12 @@ function enterPrompt() {}describe('agent session creation', () => {+ it('autofocuses the prompt when the composer opens', async () => {+ mount();+ const prompt = screen.getByRole('textbox', { name: 'Task for the agent' });+ await waitFor(() => expect(document.activeElement).toBe(prompt));+ });+it('keeps Create agent outside the slider and opens the new-agent form', () => {mount();const createAgent = screen.getByRole('button', { name: 'Create agent' });@@ -248,7 +281,8 @@ describe('agent session creation', () => {);mount(true);fireEvent.click(screen.getByRole('button', { name: 'Start session' }));- hotkeys.submit();+ hotkeys.enter();+ hotkeys.cmdEnter();await waitFor(() =>expect(agentHarnessServiceClient.create).toHaveBeenCalledTimes(1));@@ -364,7 +398,7 @@ describe('agent session creation', () => {)).toBeNull();expect(prompt.placeholder).toBe('What would you like Cursor to work on?');- hotkeys.submit();+ hotkeys.enter();await waitFor(() => expect(navigation.open).toHaveBeenCalled());expect(agentHarnessServiceClient.create).toHaveBeenCalledWith({botId: CURSOR_BOT_ID,@@ -381,7 +415,7 @@ describe('agent session creation', () => {fireEvent.click(screen.getByRole('button', { name: MODEL_PRETTYNAME[model] }));- hotkeys.submit();+ hotkeys.enter();await screen.findByRole('alert');expect(navigation.open).not.toHaveBeenCalled();fireEvent.click(screen.getByRole('button', { name: 'Retry' }));@@ -426,7 +460,7 @@ describe('agent session creation', () => {fireEvent.click(screen.getByRole('button', { name: MODEL_PRETTYNAME[model] }));- hotkeys.submit();+ hotkeys.enter();await screen.findByRole('alert');expect(agentHarnessServiceClient.control).toHaveBeenCalledTimes(1);expect(navigation.open).not.toHaveBeenCalled();@@ -460,4 +494,87 @@ describe('agent session creation', () => {);expect(agentHarnessServiceClient.create).toHaveBeenCalledTimes(1);});++ it('starts in the background from the toggle without opening the session', async () => {+ mount();+ fireEvent.click(screen.getByRole('button', { name: 'Background' }));+ expect(+ screen+ .getByRole('group', { name: 'Session start mode' })+ .getAttribute('data-session-start-mode')+ ).toBe('background');+ fireEvent.click(+ screen.getByRole('button', { name: 'Start session in background' })+ );+ await waitFor(() => expect(toasts.success).toHaveBeenCalled());+ expect(navigation.close).toHaveBeenCalledOnce();+ expect(navigation.open).not.toHaveBeenCalled();+ expect(toasts.success).toHaveBeenCalledWith(+ 'Session started in background',+ expect.objectContaining({+ actions: [+ expect.objectContaining({+ label: 'Open session',+ onClick: expect.any(Function),+ }),+ ],+ })+ );+ expect(+ window.localStorage.getItem('agent-session-start-mode-v1:test-user')+ ).toBe('background');+ const open = toasts.success.mock.calls[0][1].actions[0]+ .onClick as () => void;+ open();+ expect(navigation.open).toHaveBeenCalledWith(+ { type: 'agent', id: sessionId },+ { referredFrom: 'launcher', preferNewSplit: false }+ );+ });++ it('restores a persisted background choice and starts in the background on enter', async () => {+ window.localStorage.setItem(+ 'agent-session-start-mode-v1:test-user',+ 'background'+ );+ mount();+ expect(+ screen.getByRole('button', { name: 'Start session in background' })+ ).toBeTruthy();+ hotkeys.enter();+ await waitFor(() => expect(toasts.success).toHaveBeenCalled());+ expect(navigation.open).not.toHaveBeenCalled();+ expect(navigation.close).toHaveBeenCalledOnce();+ });++ it('starts in the background on cmd+enter without persisting the toggle', async () => {+ cmd.held = true;+ mount();+ expect(+ screen+ .getByRole('group', { name: 'Session start mode' })+ .getAttribute('data-session-start-mode')+ ).toBe('background');+ hotkeys.cmdEnter();+ await waitFor(() => expect(toasts.success).toHaveBeenCalled());+ expect(navigation.open).not.toHaveBeenCalled();+ expect(+ window.localStorage.getItem('agent-session-start-mode-v1:test-user')+ ).toBeNull();+ });++ it('ignores cmd when background is already the committed mode', async () => {+ window.localStorage.setItem(+ 'agent-session-start-mode-v1:test-user',+ 'background'+ );+ cmd.held = true;+ mount();+ hotkeys.enter();+ await waitFor(() => expect(toasts.success).toHaveBeenCalled());+ expect(navigation.open).not.toHaveBeenCalled();+ expect(+ window.localStorage.getItem('agent-session-start-mode-v1:test-user')+ ).toBe('background');+ });});diff --git a/apps/web/src/features/block-agent/component/ComposeAgentSession.tsx b/apps/web/src/features/block-agent/component/ComposeAgentSession.tsxindex 3f2d28d61c..7df8b5c20c 100644--- a/apps/web/src/features/block-agent/component/ComposeAgentSession.tsx+++ b/apps/web/src/features/block-agent/component/ComposeAgentSession.tsx@@ -1,6 +1,10 @@import { useSplitLayout } from '@components/app/split-layout/layout';-import { useSplitPanelOrThrow } from '@components/app/split-layout/layoutUtils';+import {+ useCanAutofocusSplitContent,+ useSplitPanelOrThrow,+} from '@components/app/split-layout/layoutUtils';import { MODEL_PRETTYNAME, Model } from '@core/component/AI/constant/model';+import { toast } from '@core/component/Toast/Toast';import {CURSOR_BOT_HANDLE,CURSOR_BOT_ID,@@ -13,6 +17,7 @@ import {import { useSettingsState } from '@core/constant/SettingsState';import { useUserId } from '@core/context/user';import { registerHotkey, useHotkeyDOMScope } from '@core/hotkey/hotkeys';+import { isTouchDevice } from '@core/mobile/isTouchDevice';import { idToDisplayName } from '@core/user/util';import CaretDownIcon from '@phosphor/caret-down.svg';import CaretRightIcon from '@phosphor/caret-right.svg';@@ -30,14 +35,7 @@ import {useCursorModelsQuery,} from '@queries/auth/cursor-api-key';import { useNavigate } from '@solidjs/router';-import {- Button,- badgeTriggerClasses,- cn,- Dropdown,- SendButton,- Surface,-} from '@ui';+import { Button, badgeTriggerClasses, cn, Dropdown, Surface } from '@ui';import {createMemo,createSignal,@@ -58,6 +56,8 @@ import {personaDefaultLabel,shortlistModelOptions,} from './compose-agent-session-options';+import { createSessionStartMode } from './create-session-start-mode';+import { SessionStartToggle } from './SessionStartToggle';/*** Macro's own agent: the deployment's managed default. Sent without a@@ -115,14 +115,22 @@ function ComposeAgentSessionContent(props: ComposeAgentSessionProps) {const controlMutation = useAgentSessionControlMutation();const userId = useUserId();const recentAgents = createRecentAgentSelections(userId());+ const startMode = createSessionStartMode(userId());const [prompt, setPrompt] = createSignal('');const [personaId, setPersonaId] = createSignal(MACRO_PERSONA_ID);const [modelOverride, setModelOverride] = createSignal('');const [submitting, setSubmitting] = createSignal(false);const [sessionId, setSessionId] = createSignal<string>();const [error, setError] = createSignal<string>();+ const [submitMode, setSubmitMode] = createSignal<+ 'live' | 'background' | undefined+ >();let appliedModel: string | undefined;const [containerRef, setContainerRef] = createSignal<HTMLDivElement>();+ let promptRef: HTMLTextAreaElement | undefined;+ const canAutofocusSplitContent = useCanAutofocusSplitContent();+ const shouldAutofocusPrompt = () =>+ canAutofocusSplitContent && !isTouchDevice();// The two first-party agents lead, then the user's own personas.const personas = createMemo<PersonaOption[]>(() => [@@ -244,6 +252,8 @@ function ComposeAgentSessionContent(props: ComposeAgentSessionProps) {const createSession = async () => {const persona = selectedPersona();if (submitting() || !persona || persona.unavailableReason) return;+ const background = startMode.effective() === 'background';+ setSubmitMode(background ? 'background' : 'live');setSubmitting(true);setError(undefined);const model = modelOverride();@@ -285,6 +295,27 @@ function ComposeAgentSessionContent(props: ComposeAgentSessionProps) {return;} finally {setSubmitting(false);+ setSubmitMode(undefined);+ }+ if (background) {+ close();+ toast.success('Session started in background', {+ duration: 8000,+ actions: [+ {+ label: 'Open session',+ onClick: () =>+ openWithSplit(+ { type: 'agent', id },+ {+ referredFrom: 'launcher',+ preferNewSplit: props.preferNewSplit,+ }+ ),+ },+ ],+ });+ return;}openSession(id);};@@ -297,9 +328,15 @@ function ComposeAgentSessionContent(props: ComposeAgentSessionProps) {splitPanel.handle.setDisplayName('New agent session');const container = containerRef();if (container) attachHotkeys(container);+ if (!shouldAutofocusPrompt()) return;+ const focusPrompt = () => promptRef?.focus({ preventScroll: true });+ focusPrompt();+ // Dialog focus-on-open can run after this mount; reclaim the prompt.+ queueMicrotask(focusPrompt);+ requestAnimationFrame(focusPrompt);});registerHotkey({- hotkey: 'cmd+enter',+ hotkey: ['enter', 'cmd+enter'],scopeId: hotkeyScope,description: 'Create agent session',keyDownHandler: () => {@@ -368,8 +405,12 @@ function ComposeAgentSessionContent(props: ComposeAgentSessionProps) {solid><textarea+ ref={(el) => {+ promptRef = el;+ }}rows={3}aria-label="Task for the agent"+ autofocus={shouldAutofocusPrompt()}class="ph-no-capture min-h-20 w-full flex-1 resize-none bg-transparent px-4 pt-4 pb-2 text-sm/6 text-ink outline-none placeholder:text-ink-placeholder touch:text-base"placeholder={`What would you like ${selectedPersona()?.name ?? MACRO_AGENT_NAME} to work on?`}value={prompt()}@@ -422,16 +463,14 @@ function ComposeAgentSessionContent(props: ComposeAgentSessionProps) {</Suspense></div>- <SendButton- type="button"- aria-label={- submitting() ? 'Starting…' : error() ? 'Retry' : 'Start session'- }- tooltip={error() ? 'Retry' : 'Start session'}- shortcut="cmd+enter"+ <SessionStartToggle+ mode={submitMode() ?? startMode.effective()}+ committed={startMode.committed()}pending={submitting()}+ error={!!error()}disabled={submitting() || !!selectedPersona()?.unavailableReason}- onClick={() => void createSession()}+ onModeChange={startMode.setCommitted}+ onStart={() => void createSession()}/></div></Surface>diff --git a/apps/web/src/features/block-agent/component/SessionStartToggle.test.tsx b/apps/web/src/features/block-agent/component/SessionStartToggle.test.tsxnew file mode 100644index 0000000000..420b1da2ba--- /dev/null+++ b/apps/web/src/features/block-agent/component/SessionStartToggle.test.tsx@@ -0,0 +1,127 @@+import { fireEvent, render, screen } from '@solidjs/testing-library';+import { describe, expect, it, vi } from 'vitest';+import { SessionStartToggle } from './SessionStartToggle';++vi.mock('@ui', async (importOriginal) => {+ const actual = await importOriginal<typeof import('@ui')>();+ const Pass = (props: { children?: import('solid-js').JSX.Element }) =>+ props.children;+ return {+ ...actual,+ Dropdown: Object.assign(Pass, {+ Trigger: (+ props: import('solid-js').JSX.ButtonHTMLAttributes<HTMLButtonElement>+ ) => (+ <button aria-label={props['aria-label']} disabled={props.disabled}>+ {props.children}+ </button>+ ),+ Content: Pass,+ Group: Pass,+ Item: (+ props: import('solid-js').JSX.ButtonHTMLAttributes<HTMLButtonElement> & {+ onSelect: () => void;+ }+ ) => (+ <button+ role={props.role}+ aria-checked={props['aria-checked']}+ onClick={props.onSelect}+ >+ {props.children}+ </button>+ ),+ }),+ };+});++describe('SessionStartToggle', () => {+ it('starts the selected mode from the send button and changes mode from the dropdown', () => {+ const onModeChange = vi.fn();+ const onStart = vi.fn();+ render(() => (+ <SessionStartToggle+ mode="live"+ committed="live"+ onModeChange={onModeChange}+ onStart={onStart}+ />+ ));++ fireEvent.click(screen.getByRole('button', { name: 'Start session' }));+ expect(onStart).toHaveBeenCalledOnce();+ expect(onModeChange).not.toHaveBeenCalled();++ fireEvent.click(screen.getByRole('menuitemradio', { name: /Background/ }));+ expect(onModeChange).toHaveBeenCalledWith('background');+ expect(onStart).toHaveBeenCalledOnce();+ });++ it('starts in background when that mode is already selected', () => {+ const onModeChange = vi.fn();+ const onStart = vi.fn();+ render(() => (+ <SessionStartToggle+ mode="background"+ committed="background"+ onModeChange={onModeChange}+ onStart={onStart}+ />+ ));++ fireEvent.click(+ screen.getByRole('button', { name: 'Start session in background' })+ );+ expect(onStart).toHaveBeenCalledOnce();+ fireEvent.click(screen.getByRole('menuitemradio', { name: /Live/ }));+ expect(onModeChange).toHaveBeenCalledWith('live');+ });++ it('keeps the mode dropdown to the left of the send button', () => {+ render(() => (+ <SessionStartToggle+ mode="live"+ committed="live"+ onModeChange={vi.fn()}+ onStart={vi.fn()}+ />+ ));+ const group = screen.getByRole('group', { name: 'Session start mode' });+ const mode = screen.getByRole('button', { name: 'Session start mode' });+ const send = screen.getByRole('button', { name: 'Start session' });+ expect(group.contains(mode)).toBe(true);+ expect(group.contains(send)).toBe(true);+ expect(+ mode.compareDocumentPosition(send) & Node.DOCUMENT_POSITION_FOLLOWING+ ).toBeTruthy();+ });++ it('previews background on the trigger without changing the committed check', () => {+ render(() => (+ <SessionStartToggle+ mode="background"+ committed="live"+ onModeChange={vi.fn()}+ onStart={vi.fn()}+ />+ ));+ expect(+ screen+ .getByRole('group', { name: 'Session start mode' })+ .getAttribute('data-session-start-mode')+ ).toBe('background');+ expect(+ screen.getByRole('button', { name: 'Start session in background' })+ ).toBeTruthy();+ expect(+ screen+ .getByRole('menuitemradio', { name: /Live/ })+ .getAttribute('aria-checked')+ ).toBe('true');+ expect(+ screen+ .getByRole('menuitemradio', { name: /Background/ })+ .getAttribute('aria-checked')+ ).toBe('false');+ });+});diff --git a/apps/web/src/features/block-agent/component/SessionStartToggle.tsx b/apps/web/src/features/block-agent/component/SessionStartToggle.tsxnew file mode 100644index 0000000000..3310cf2fb1--- /dev/null+++ b/apps/web/src/features/block-agent/component/SessionStartToggle.tsx@@ -0,0 +1,89 @@+import CaretDownIcon from '@phosphor/caret-down.svg';+import {+ badgeTriggerClasses,+ cn,+ Dropdown,+ Hotkey,+ SendButton,+ SingleSelectCheck,+} from '@ui';+import type { SessionStartMode } from './session-start-mode';++export function SessionStartToggle(props: {+ mode: SessionStartMode;+ /** Committed choice for menu checks. Cmd preview only changes `mode`. */+ committed?: SessionStartMode;+ pending?: boolean;+ disabled?: boolean;+ error?: boolean;+ onModeChange: (mode: SessionStartMode) => void;+ onStart: () => void;+}) {+ const background = () => props.mode === 'background';+ const selected = () => props.committed ?? props.mode;+ const startLabel = () => {+ if (props.pending) return 'Starting…';+ if (props.error) return 'Retry';+ return background() ? 'Start session in background' : 'Start session';+ };++ return (+ <div+ role="group"+ aria-label="Session start mode"+ data-session-start-mode={props.mode}+ class={cn(+ 'flex h-7 shrink-0 items-center gap-1.5',+ props.disabled && 'opacity-60'+ )}+ >+ <Dropdown placement="top-end">+ <Dropdown.Trigger+ variant="outline"+ size="sm"+ class={badgeTriggerClasses({+ variant: 'outline',+ size: 'sm',+ class:+ 'gap-1 px-2 text-ink-muted data-expanded:bg-hover data-expanded:text-ink',+ })}+ aria-label="Session start mode"+ disabled={props.disabled}+ >+ <span class="text-ink">{background() ? 'Background' : 'Live'}</span>+ <CaretDownIcon class="size-3 shrink-0 text-current/70" />+ </Dropdown.Trigger>+ <Dropdown.Content class="min-w-40">+ <Dropdown.Group>+ <Dropdown.Item+ class="h-8"+ role="menuitemradio"+ aria-checked={selected() === 'live'}+ onSelect={() => props.onModeChange('live')}+ >+ <span class="min-w-0 flex-1 truncate">Live</span>+ <SingleSelectCheck active={selected() === 'live'} />+ </Dropdown.Item>+ <Dropdown.Item+ class="h-8"+ role="menuitemradio"+ aria-checked={selected() === 'background'}+ onSelect={() => props.onModeChange('background')}+ >+ <span class="min-w-0 flex-1 truncate">Background</span>+ <Hotkey shortcut="cmd" theme="subtle" />+ <SingleSelectCheck active={selected() === 'background'} />+ </Dropdown.Item>+ </Dropdown.Group>+ </Dropdown.Content>+ </Dropdown>+ <SendButton+ aria-label={startLabel()}+ tooltip={startLabel()}+ pending={props.pending}+ disabled={props.disabled}+ onClick={() => props.onStart()}+ />+ </div>+ );+}diff --git a/apps/web/src/features/block-agent/component/create-session-start-mode.test.ts b/apps/web/src/features/block-agent/component/create-session-start-mode.test.tsnew file mode 100644index 0000000000..ce66811bd8--- /dev/null+++ b/apps/web/src/features/block-agent/component/create-session-start-mode.test.ts@@ -0,0 +1,88 @@+import { createRoot, createSignal } from 'solid-js';+import { beforeEach, describe, expect, it, vi } from 'vitest';+import { createSessionStartMode } from './create-session-start-mode';+import { SESSION_START_MODE_STORAGE_KEY } from './session-start-mode';++beforeEach(() => window.localStorage.clear());++function storageKey(userId: string) {+ return `${SESSION_START_MODE_STORAGE_KEY}:${encodeURIComponent(userId)}`;+}++describe('session start mode persistence', () => {+ it('defaults to live and persists a user-chosen background mode', () => {+ createRoot((dispose) => {+ const [cmdHeld] = createSignal(false);+ const mode = createSessionStartMode('user-a', cmdHeld);+ expect(mode.committed()).toBe('live');+ expect(mode.effective()).toBe('live');+ mode.setCommitted('background');+ expect(mode.committed()).toBe('background');+ expect(window.localStorage.getItem(storageKey('user-a'))).toBe(+ 'background'+ );+ dispose();+ });+ createRoot((dispose) => {+ const [cmdHeld] = createSignal(false);+ expect(createSessionStartMode('user-a', cmdHeld).committed()).toBe(+ 'background'+ );+ expect(createSessionStartMode('user-b', cmdHeld).committed()).toBe(+ 'live'+ );+ dispose();+ });+ });++ it('previews background while cmd is held and restores live on release', () => {+ createRoot((dispose) => {+ const [cmdHeld, setCmdHeld] = createSignal(false);+ const mode = createSessionStartMode('user-a', cmdHeld);+ setCmdHeld(true);+ expect(mode.effective()).toBe('background');+ expect(mode.committed()).toBe('live');+ expect(window.localStorage.getItem(storageKey('user-a'))).toBeNull();+ setCmdHeld(false);+ expect(mode.effective()).toBe('live');+ dispose();+ });+ });++ it('ignores cmd when the user has already chosen background', () => {+ createRoot((dispose) => {+ const [cmdHeld, setCmdHeld] = createSignal(false);+ const mode = createSessionStartMode('user-a', cmdHeld);+ mode.setCommitted('background');+ setCmdHeld(true);+ expect(mode.effective()).toBe('background');+ setCmdHeld(false);+ expect(mode.effective()).toBe('background');+ dispose();+ });+ });++ it('ignores malformed storage and keeps working when writes fail', () => {+ window.localStorage.setItem(storageKey('user-a'), 'nope');+ createRoot((dispose) => {+ const [cmdHeld] = createSignal(false);+ expect(createSessionStartMode('user-a', cmdHeld).committed()).toBe(+ 'live'+ );+ dispose();+ });+ const write = vi+ .spyOn(Storage.prototype, 'setItem')+ .mockImplementation(() => {+ throw new Error('Storage unavailable');+ });+ createRoot((dispose) => {+ const [cmdHeld] = createSignal(false);+ const mode = createSessionStartMode('user-a', cmdHeld);+ mode.setCommitted('background');+ expect(mode.committed()).toBe('background');+ dispose();+ });+ write.mockRestore();+ });+});diff --git a/apps/web/src/features/block-agent/component/create-session-start-mode.ts b/apps/web/src/features/block-agent/component/create-session-start-mode.tsnew file mode 100644index 0000000000..ad8328c149--- /dev/null+++ b/apps/web/src/features/block-agent/component/create-session-start-mode.ts@@ -0,0 +1,41 @@+import { makePersistedState } from '@app/lib/persistence';+import { pressedKeys } from '@core/hotkey/state';+import { createUserScopedStorage } from '@core/util/userScopedStorage';+import { createSignal } from 'solid-js';+import {+ effectiveSessionStartMode,+ parseSessionStartMode,+ SESSION_START_MODE_STORAGE_KEY,+ type SessionStartMode,+} from './session-start-mode';++/**+ * Committed live/background choice for the session composer, persisted per+ * user on this device. Cmd/Ctrl previews background without writing storage.+ */+export function createSessionStartMode(+ userId: string | undefined,+ cmdHeld: () => boolean = () => pressedKeys().has('cmd')+) {+ const storage = createUserScopedStorage(SESSION_START_MODE_STORAGE_KEY);+ const [committed, setCommitted] = makePersistedState(+ createSignal<SessionStartMode>('live'),+ {+ storages: {+ restore: () => {+ if (!userId) return;+ return parseSessionStartMode(storage.read(userId));+ },+ write: (value) => {+ if (userId) storage.write(userId, value);+ },+ },+ }+ );++ return {+ committed,+ setCommitted,+ effective: () => effectiveSessionStartMode(committed(), cmdHeld()),+ };+}diff --git a/apps/web/src/features/block-agent/component/session-start-mode.test.ts b/apps/web/src/features/block-agent/component/session-start-mode.test.tsnew file mode 100644index 0000000000..8ae5690571--- /dev/null+++ b/apps/web/src/features/block-agent/component/session-start-mode.test.ts@@ -0,0 +1,21 @@+import { describe, expect, it } from 'vitest';+import {+ effectiveSessionStartMode,+ parseSessionStartMode,+} from './session-start-mode';++describe('session start mode', () => {+ it('treats only an explicit background value as background', () => {+ expect(parseSessionStartMode('background')).toBe('background');+ expect(parseSessionStartMode('live')).toBe('live');+ expect(parseSessionStartMode(null)).toBe('live');+ expect(parseSessionStartMode('nope')).toBe('live');+ });++ it('previews background while cmd is held only if the user left live selected', () => {+ expect(effectiveSessionStartMode('live', false)).toBe('live');+ expect(effectiveSessionStartMode('live', true)).toBe('background');+ expect(effectiveSessionStartMode('background', false)).toBe('background');+ expect(effectiveSessionStartMode('background', true)).toBe('background');+ });+});diff --git a/apps/web/src/features/block-agent/component/session-start-mode.ts b/apps/web/src/features/block-agent/component/session-start-mode.tsnew file mode 100644index 0000000000..19b81ec3c9--- /dev/null+++ b/apps/web/src/features/block-agent/component/session-start-mode.ts@@ -0,0 +1,27 @@+/** How a newly created agent session should be opened. */+export type SessionStartMode = 'live' | 'background';++/** User-scoped localStorage key for the composer's start-mode toggle. */+export const SESSION_START_MODE_STORAGE_KEY = 'agent-session-start-mode-v1';++export function isSessionStartMode(value: unknown): value is SessionStartMode {+ return value === 'live' || value === 'background';+}++/** Unknown or missing storage values fall back to a live session. */+export function parseSessionStartMode(value: unknown): SessionStartMode {+ return isSessionStartMode(value) ? value : 'live';+}++/**+ * Cmd/Ctrl previews background only while the committed choice is live.+ * A user-set background mode ignores the modifier so releasing it cannot+ * bounce the dropdown back to live.+ */+export function effectiveSessionStartMode(+ committed: SessionStartMode,+ cmdHeld: boolean+): SessionStartMode {+ if (committed === 'background') return 'background';+ return cmdHeld ? 'background' : 'live';+}diff --git a/docs/AGENT_GUIDE/ai-chat.md b/docs/AGENT_GUIDE/ai-chat.mdindex 0c4a897ce7..db93e1e849 100644--- a/docs/AGENT_GUIDE/ai-chat.md+++ b/docs/AGENT_GUIDE/ai-chat.md@@ -66,8 +66,8 @@ and arrow send button, with a three-line editing area. It names thecurrent selection:`What would you like Macro to work on?` becomes`What would you like Cursor to work on?` when Cursor is selected. Its aria-label-is `Task for the agent`. The dialog's default autofocus lands on the selected-agent row, its first tabbable control.+is `Task for the agent`. Autofocus lands on that prompt so you can type+immediately; skip it on touch so the keyboard does not jump up unsolicited.The prompt and agent strip share the same surface layer and background.A centered caption below the prompt describes the selected runtime: Macroshows “Starts quickly and runs in-memory. Great for workspace tasks”; Cursor@@ -82,10 +82,21 @@ While a default is unknown, the selector reads `default`. Changing agent resetsthe override. Tab order is selected agent row (and any connection action) →**Create agent** → prompt → model → **Start session**.Escape in the prompt first blurs to the dialog; a second Escape closes it.-Press the arrow send button (labelled **Start session**) or `Cmd/Ctrl+Enter`;-the button shows a spinner and is labelled **Starting…**+The prompt footer’s start control is a **Live / Background** dropdown+(`aria-label="Session start mode"`) to the left of the circular send button.+**Live** (default) opens the new session; **Background** closes the composer+and shows a bottom-right toast **Session started in background** with an+**Open session** action. The send button starts the selected mode. The+dropdown lists both options; **Background** shows `Cmd` / `Ctrl`. The choice+persists per user in localStorage.+Holding `Cmd`/`Ctrl` previews Background on the dropdown and send button only+while Live is selected; releasing restores Live. If Background is already+selected, the modifier does nothing.+`Enter` starts the selected mode (`Shift+Enter` still inserts a newline).+`Cmd`/`Ctrl+Enter` starts in the background when Live is selected.+The send button shows a spinner and is labelled **Starting…**while the server creates the session, applies the model override, and accepts the-first prompt. It then closes+first prompt. Live mode then closesand opens the real `/app/agent/<uuid>` URL. It never navigates to a temporary`pending-…` URL. Creation failures keep the prompt in the modal and show **Retry**.If model setup or prompt delivery fails after creation, **Retry** reuses that