diff --git a/docs/chat-steering.md b/docs/chat-steering.md new file mode 100644 index 00000000..f1307a78 --- /dev/null +++ b/docs/chat-steering.md @@ -0,0 +1,44 @@ +# Steering an active conversation + +While an agent is running, you can queue a follow-up or guide the current task. + +| Action | Behavior | +| --- | --- | +| Enter or the send button | Queue the draft to send after the current answer finishes. | +| Command+Enter or Alt/Option+Enter | Send the draft as guidance for the active task. With an empty draft, promote the first eligible queued message. | +| Up arrow on a queued message | Send that message as guidance immediately. | +| Remove on a queued message | Remove the queued message. | +| Stop button | Stop generation. This replaces the send button while the agent is running and the draft is empty. | +| Shift+Enter or Ctrl+Enter | Insert a newline. | + +Outside an active agent run, Enter sends a normal message. Input methods can +confirm composed text without accidentally sending it. Modes without steering +support keep the stop action during generation. + +Queued messages appear in a compact strip immediately above the input's focus +border. Guidance moves into the conversation immediately; delivery failures can +be retried or removed. Earlier work remains visible, and guidance does not mark +the ongoing task as complete. Sending and entering a newly created session keep +the composer ready for further input. + +Guidance applies to the task in progress. The agent retains unfinished goals and +constraints unless the user explicitly changes or cancels them. A short tagged +reminder accompanies each guidance message; existing context and tool results +are reused without an additional model call to classify the message. Message IDs +and execution boundaries preserve ordering across live updates and history reloads. + +The conversation outline includes both user and assistant messages and highlights +all messages intersecting the visible conversation area. + +## Component previews + +These previews use sample messages and isolated production components; they do +not contain real conversation data or invoke a model. + +Running with an empty draft: + +![Queued guidance, visible outline entries, and Stop](images/chat-steer-preview.png) + +Running with a draft: + +![The same primary control becomes Send](images/chat-steer-send-preview.png) diff --git a/docs/images/chat-steer-preview.png b/docs/images/chat-steer-preview.png new file mode 100644 index 00000000..b0d08258 Binary files /dev/null and b/docs/images/chat-steer-preview.png differ diff --git a/docs/images/chat-steer-send-preview.png b/docs/images/chat-steer-send-preview.png new file mode 100644 index 00000000..3fc3b625 Binary files /dev/null and b/docs/images/chat-steer-send-preview.png differ diff --git a/frontend/src/api/chat/steer.ts b/frontend/src/api/chat/steer.ts index 443bc9cf..e2292e71 100644 --- a/frontend/src/api/chat/steer.ts +++ b/frontend/src/api/chat/steer.ts @@ -9,16 +9,17 @@ export type SteerQueueItem = { mentioned_items?: unknown[] promoting?: boolean awaitingIdleSend?: boolean - // True while POST /steer is in flight. The overlay uses a client-side - // id until the server replies with the durable one; promote/remove are - // disabled in that window so they cannot hit /steer/{client_id}. + // True while POST /steer is in flight. The stable client UUID is also the + // durable server ID; disable actions until its queue entry exists. pending?: boolean + failed?: boolean + expected_assistant_message_id?: string client_id?: string } /** * Append a message to a running agent turn. - * Returns { success, status: 'queued' | 'new_run', steer_id?, delivery?, assistant_message_id? }. + * Returns { success, status: 'queued' | 'already_injected' | 'new_run', steer_id?, delivery?, assistant_message_id? }. * - delivery 'after' (default): waits until the current run exits, then starts a follow-up turn. * - delivery 'inject': the running engine injects it at the next round boundary. * - 'new_run': no run is live; the caller should fall back to a normal send. @@ -30,9 +31,13 @@ export async function steerSession( query: string, mentionedItems: any[] = [], delivery: SteerDelivery = 'after', + expectedAssistantMessageId?: string, + steerId?: string, ) { return post(`/api/v1/sessions/${session_id}/steer`, { query, + expected_assistant_message_id: expectedAssistantMessageId, + steer_id: steerId, mentioned_items: mentionedItems, channel: 'web', delivery, diff --git a/frontend/src/components/Input-field.agent-switch.test.mjs b/frontend/src/components/Input-field.agent-switch.test.mjs index 67cc2f10..571f0bbd 100644 --- a/frontend/src/components/Input-field.agent-switch.test.mjs +++ b/frontend/src/components/Input-field.agent-switch.test.mjs @@ -1,10 +1,41 @@ import assert from 'node:assert/strict' import { readFileSync } from 'node:fs' import test from 'node:test' +import vm from 'node:vm' +import ts from 'typescript' +import { computed, reactive, ref } from 'vue' +import { chatSubmitShortcut } from '../utils/chatSubmitShortcut.ts' const inputField = readFileSync(new URL('./Input-field.vue', import.meta.url), 'utf8') const settingsStore = readFileSync(new URL('../stores/settings.ts', import.meta.url), 'utf8') +test('composer shortcuts queue Enter, inject drafts, and promote the first queued message when empty', () => { + const code = inputField.slice(inputField.indexOf('const steerShortcutLabel ='), inputField.indexOf('const onPaste =')) + const sends = [], promotes = [] + const query = ref('draft') + const composing = ref(false) + const props = reactive({ isReplying: true, canSteer: true, queuedSteers: [ + { steer_id: 'pending', delivery: 'after', pending: true }, + { steer_id: 'first', delivery: 'after' }, { steer_id: 'second', delivery: 'after' }, + ] }) + const { onKeydown } = vm.runInNewContext(ts.transpile(`${code}\n({ onKeydown })`), { + navigator: { platform: 'MacIntel' }, computed, props, query, chatSubmitShortcut, + isComposing: composing, showMention: ref(false), + createSession: (...args) => sends.push(args), emit: (...args) => promotes.push(args), + }) + const enter = { key: 'Enter', keyCode: 13, preventDefault() {}, shiftKey: false, ctrlKey: false, altKey: false } + onKeydown(query.value, { e: enter }) + onKeydown(query.value, { e: { ...enter, altKey: true } }) + onKeydown(query.value, { e: { ...enter, metaKey: true } }) + assert.deepEqual(sends, [['draft', 'after'], ['draft', 'inject'], ['draft', 'inject']]) + query.value = '' + onKeydown('', { e: { ...enter, metaKey: true } }) + assert.deepEqual(promotes, [['promote-steer', 'first']]) + composing.value = true + onKeydown('', { e: { ...enter, altKey: true } }) + assert.equal(promotes.length, 1, 'IME confirmation must not promote a message') +}) + test('selecting an agent leaves web search off until the user enables it', () => { const selectAgentStart = settingsStore.indexOf('selectAgent(agentId: string') const getSelectedAgentStart = settingsStore.indexOf('getSelectedAgentId()', selectAgentStart) @@ -36,17 +67,18 @@ test('shared-agent web search button waits for source readiness metadata', () => assert.match(showWebSearchButton, /selectedSharedAgent\.value\?\.web_search_ready/) }) -test('replying keeps stop visible; typed text also shows send', () => { +test('one composer action switches between stop and send', () => { const controlsStart = inputField.indexOf('class="control-right"') - const controls = inputField.slice(controlsStart, controlsStart + 1200) + const controls = inputField.slice(controlsStart, controlsStart + 2200) assert.notEqual(controlsStart, -1) assert.doesNotMatch(inputField, /steer-delivery-toggle/) assert.doesNotMatch(inputField, /setSteerDelivery/) - assert.match(inputField, /emit\('steer-msg', val\.trim\(\), steerMentions, 'after'\)/) - assert.match(controls, /v-if="isReplying"/) + assert.match(inputField, /emit\('steer-msg', val\.trim\(\), steerMentions, delivery\)/) + assert.match(controls, /v-if="isReplying && \(!canSteer \|\| !query\.trim\(\)\)"/) assert.match(controls, /handleStop/) - assert.match(controls, /v-if="!isReplying \|\| query\.trim\(\)"[\s\S]*createSession\(query\)[\s\S]*send-btn/) - assert.doesNotMatch(controls, /v-if="isReplying && \(!canSteer \|\| !query\.trim\(\)\)"/) + assert.match(controls, /v-else[\s\S]*createSession\(query\)[\s\S]*send-btn/) + assert.match(controls, /]*'time'/) }) // Only agent turns have a round boundary to take a mid-run message at, and a @@ -74,7 +106,7 @@ test('queued follow-ups sit in one block with send-now and remove', () => { assert.match(inputField, /queuedSteers/) assert.match(inputField, /emit\('promote-steer', item\.steer_id\)/) assert.match(inputField, /emit\('remove-steer', item\.steer_id\)/) - assert.match(inputField, /class="steer-queue-remove"/) + assert.match(inputField, /class="steer-queue-action steer-queue-remove"/) assert.match(inputField, /\$t\('input\.steerQueueSendNow'\)/) assert.match(inputField, /:disabled="item\.promoting \|\| item\.pending"/) assert.match(inputField, /\.steer-queue-item \+ \.steer-queue-item/) diff --git a/frontend/src/components/Input-field.focus.test.mjs b/frontend/src/components/Input-field.focus.test.mjs new file mode 100644 index 00000000..560c2a3c --- /dev/null +++ b/frontend/src/components/Input-field.focus.test.mjs @@ -0,0 +1,81 @@ +import assert from 'node:assert/strict' +import { readFileSync } from 'node:fs' +import test from 'node:test' +import vm from 'node:vm' +import ts from 'typescript' + +const source = readFileSync(new URL('./Input-field.vue', import.meta.url), 'utf8') +const focusCode = source.slice(source.indexOf('const focusInput ='), source.indexOf('const onInput =')) +const sendCode = source.slice(source.indexOf('const createSession ='), source.indexOf('const updateAgentModeDropdownPosition =')) + +for (const mode of ['normal', 'embedded', 'after', 'inject']) { + test(`${mode} send clears the draft and restores focus after the DOM update`, async () => { + const effects = [], ticks = [] + const textarea = { + isConnected: true, + focus: options => effects.push(['focus', options.preventScroll]), + blur: () => { throw new Error('sending must not blur the textarea') }, + } + const context = { + props: { isReplying: ['after', 'inject'].includes(mode), canSteer: true, embeddedMode: mode === 'embedded' }, + uploadedAttachments: { value: [] }, uploadedImages: { value: [] }, + allSelectedItems: { value: [] }, selectedModelId: { value: 'model' }, + selectedAgent: { value: { config: {} } }, + settingsStore: {}, chatResources: { isFresh: () => true }, + collectAgentNotReadyReasons: () => ({ keys: [], labels: [] }), + attachmentUploadRef: { value: null }, + emit: name => effects.push([name]), + clearvalue: () => effects.push(['clear']), + getTextareaEl: () => textarea, + nextTick: () => new Promise(resolve => ticks.push(resolve)), + } + const send = vm.runInNewContext(ts.transpile(`${focusCode}\n${sendCode}\ncreateSession`), context) + await send('hello', mode === 'inject' ? 'inject' : 'after') + assert.deepEqual(effects, [[context.props.isReplying ? 'steer-msg' : 'send-msg'], ['clear']]) + for (const resolve of ticks) resolve() + await new Promise(setImmediate) + assert.deepEqual(effects.at(-1), ['focus', true]) + }) +} + +test('a queued focus does not focus a textarea removed during navigation', async () => { + let resolveTick, connected = true, focused = false + const focus = vm.runInNewContext(`${focusCode}\nfocusInput`, { + nextTick: () => new Promise(resolve => { resolveTick = resolve }), + getTextareaEl: () => ({ isConnected: connected, focus: () => { focused = true } }), + }) + const pending = focus() + connected = false + resolveTick() + await pending + assert.equal(focused, false) +}) + +test('teardown blurs the active textarea before it is detached', () => { + const code = source.slice(source.indexOf('onBeforeUnmount(() =>'), source.indexOf('onUnmounted(() =>')) + let teardown, blurred = false + const textarea = { isConnected: true, blur: () => { blurred = true } } + vm.runInNewContext(code, { + onBeforeUnmount: fn => { teardown = fn }, getTextareaEl: () => textarea, + document: { activeElement: textarea }, + }) + teardown() + assert.equal(blurred, true) +}) + +test('new-session focus survives consumption of the first query and runs on child mount', () => { + const page = readFileSync(new URL('../views/chat/index.vue', import.meta.url), 'utf8') + const snapshot = page.match(/const focusComposerOnMount = [^;]+;/)[0] + const firstQuery = { value: 'initial question' } + const autoFocus = vm.runInNewContext(`${snapshot}\nfirstQuery.value = ''; focusComposerOnMount`, { firstQuery }) + assert.equal(autoFocus, true) + assert.match(page, /:auto-focus="focusComposerOnMount"/) + const mountStart = source.slice(source.indexOf('onMounted(() => {'), source.indexOf('// Embed 渠道')) + let mounted, focused = false + vm.runInNewContext(`${mountStart}\n});`, { + props: { autoFocus }, onMounted: fn => { mounted = fn }, focusInput: () => { focused = true }, + }) + assert.equal(focused, false) + mounted() + assert.equal(focused, true) +}) diff --git a/frontend/src/components/Input-field.vue b/frontend/src/components/Input-field.vue index 2d476af8..ae983678 100644 --- a/frontend/src/components/Input-field.vue +++ b/frontend/src/components/Input-field.vue @@ -1,5 +1,5 @@