Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

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.tsx
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.md
index 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 the
current 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: Macro
shows “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 resets
the 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 closes
and 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