feat(native-chat): /clear waits in line while the agent works, and runs when its turn comes

config/scripts/vitest-sqlite-runtime-files.mjs

@@ -105,7 +105,19 @@ export const SQLITE_RUNTIME_INCLUDE = [
   'src/main/native-chat/agent-session-wire/structured-agent-session-provider-restore.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-provider-started-catalog.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-provider-started.test.ts',
+  'src/main/native-chat/agent-session-wire/structured-agent-session-queued-card-holds.test.ts',
+  'src/main/native-chat/agent-session-wire/structured-agent-session-queued-clear.test.ts',
+  'src/main/native-chat/agent-session-wire/structured-agent-session-queued-clear-atomic.test.ts',
+  'src/main/native-chat/agent-session-wire/structured-agent-session-queued-command.test.ts',
+  'src/main/native-chat/agent-session-wire/structured-agent-session-queued-compact.test.ts',
+  'src/main/native-chat/agent-session-wire/structured-agent-session-queued-gate.test.ts',
+  'src/main/native-chat/agent-session-wire/structured-agent-session-queued-messages.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-queued-newer-orca.test.ts',
+  'src/main/native-chat/agent-session-wire/structured-agent-session-queued-pause-lift.test.ts',
+  'src/main/native-chat/agent-session-wire/structured-agent-session-queued-published-bytes.test.ts',
+  'src/main/native-chat/agent-session-wire/structured-agent-session-queued-quit.test.ts',
+  'src/main/native-chat/agent-session-wire/structured-agent-session-queued-repeat-press.test.ts',
+  'src/main/native-chat/agent-session-wire/structured-agent-session-queued-withdrawn-draft.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-read-restore.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-readable-restorer.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-reasoning-sweep.test.ts',
@@ -158,7 +170,9 @@ export const SQLITE_RUNTIME_INCLUDE = [
   'src/main/native-chat/agent-session-wire/structured-agent-session-view-start-after-failed-start.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-wedged-profile-migration.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-wire-admission.test.ts',
+  'src/main/native-chat/agent-session-wire/structured-conversation-command-child-work.test.ts',
   'src/main/native-chat/agent-session-wire/structured-conversation-command.test.ts',
+  'src/main/native-chat/agent-session-wire/structured-conversation-compaction.test.ts',
   'src/main/opencode/opencode-acp-stored-messages.test.ts',
   'src/main/orcad/orcad-automations.test.ts',
   'src/main/orcad/orcad-local-serve-selection.test.ts',

mobile/src/session/MobileNativeChatQueuedMessages.test.tsx

@@ -157,6 +157,16 @@ describe('MobileNativeChatQueuedMessages', () => {
     expect(nodeTypes(rows[1]!)).toContain('CornerDownRight')
   })
 
+  it('a /clear the queue is about to run offers Delete but no Send', async () => {
+    const mounted = await mount({
+      cards: [card({ messageId: 'clear', text: '/clear', command: true, runsOnItsOwn: true })]
+    })
+    expect(texts(mounted).filter((text) => text === 'Send' || text === 'Steer')).toEqual([])
+    expect(
+      mounted.root.findAllByProps({ accessibilityLabel: 'Delete this queued message' })
+    ).toHaveLength(1)
+  })
+
   it('a command card never steers: Send only while the agent is idle, and no menu', async () => {
     const onSend = vi.fn(async () => true)
     const mounted = await mount({

mobile/src/session/MobileNativeChatQueuedMessages.tsx

@@ -142,8 +142,9 @@ export function MobileNativeChatQueuedMessages({
                   </Text>
                 ) : null}
               </View>
-              {/* A command never steers: its Send shows only while the agent is idle. */}
-              {card.waitsForAgent ? null : (
+              {/* A command never steers: its Send shows only while the agent is idle, and never on
+                  a /clear the queue is about to run. */}
+              {card.waitsForAgent || card.runsOnItsOwn ? null : (
                 <Pressable
                   accessibilityRole="button"
                   accessibilityState={{ disabled: busy || steerHeld }}

mobile/src/session/mobile-native-chat-eligibility.ts

@@ -35,6 +35,8 @@ export type MobileNativeChatTab = {
   launchDraftCreatedAt?: number
   sessionId?: string | null
   agent?: string | null
+  /** The conversation a /clear replaced with this one. */
+  replacesSessionId?: string
 }
 
 /** Resolve a session tab to the transcript identity native chat needs, or

mobile/src/session/mobile-native-chat-merged-snapshot-parity-hooks.test.tsx

@@ -89,6 +89,7 @@ const HOST_SUPPORT = {
   questionAnswers: true,
   queuedMessages: true,
   queuedCommands: false,
+  queuedClear: false,
   statusFeed: true,
   quietRepeatedStop: true
 }

mobile/src/session/mobile-structured-agent-session-host-support.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 import {
   AGENT_SESSION_PROMPT_CANCEL_RUNTIME_CAPABILITY,
   AGENT_SESSION_QUESTION_ANSWERS_RUNTIME_CAPABILITY,
+  AGENT_SESSION_QUEUED_CLEAR_RUNTIME_CAPABILITY,
   AGENT_SESSION_QUEUED_COMMANDS_RUNTIME_CAPABILITY,
   AGENT_SESSION_QUEUED_MESSAGES_RUNTIME_CAPABILITY,
   AGENT_SESSION_STATUS_FEED_RUNTIME_CAPABILITY,
@@ -16,6 +17,7 @@ describe('structuredAgentSessionHostSupport', () => {
       questionAnswers: false,
       queuedMessages: false,
       queuedCommands: false,
+      queuedClear: false,
       quietRepeatedStop: false,
       statusFeed: false
     }
@@ -38,5 +40,8 @@ describe('structuredAgentSessionHostSupport', () => {
     expect(
       structuredAgentSessionHostSupport([AGENT_SESSION_STATUS_FEED_RUNTIME_CAPABILITY])
     ).toEqual({ ...none, statusFeed: true })
+    expect(
+      structuredAgentSessionHostSupport([AGENT_SESSION_QUEUED_CLEAR_RUNTIME_CAPABILITY])
+    ).toEqual({ ...none, queuedClear: true })
   })
 })

mobile/src/session/mobile-structured-agent-session-host-support.ts

@@ -1,5 +1,6 @@
 import {
   AGENT_SESSION_PROMPT_CANCEL_RUNTIME_CAPABILITY,
+  AGENT_SESSION_QUEUED_CLEAR_RUNTIME_CAPABILITY,
   AGENT_SESSION_QUESTION_ANSWERS_RUNTIME_CAPABILITY,
   AGENT_SESSION_QUEUED_COMMANDS_RUNTIME_CAPABILITY,
   AGENT_SESSION_QUEUED_MESSAGES_RUNTIME_CAPABILITY,
@@ -15,6 +16,8 @@ export type StructuredAgentSessionHostSupport = {
   queuedMessages: boolean
   /** A /compact sent while the agent works waits as a card; an older host refuses it. */
   queuedCommands: boolean
+  /** A /clear sent while the agent works waits as a card the host runs; an older host refuses it. */
+  queuedClear: boolean
   /** The host publishes every session's status on one stream. A host from before phones could
    *  read it refuses the call, which reads the same as its absence. */
   statusFeed: boolean
@@ -30,6 +33,7 @@ export function structuredAgentSessionHostSupport(
     questionAnswers: capabilities.includes(AGENT_SESSION_QUESTION_ANSWERS_RUNTIME_CAPABILITY),
     queuedMessages: capabilities.includes(AGENT_SESSION_QUEUED_MESSAGES_RUNTIME_CAPABILITY),
     queuedCommands: capabilities.includes(AGENT_SESSION_QUEUED_COMMANDS_RUNTIME_CAPABILITY),
+    queuedClear: capabilities.includes(AGENT_SESSION_QUEUED_CLEAR_RUNTIME_CAPABILITY),
     statusFeed: capabilities.includes(AGENT_SESSION_STATUS_FEED_RUNTIME_CAPABILITY),
     quietRepeatedStop: capabilities.includes(AGENT_SESSION_REPEATED_STOP_RUNTIME_CAPABILITY)
   }

mobile/src/session/mobile-structured-composer-command.test.ts

@@ -9,7 +9,10 @@ const asyncStorage = vi.hoisted(() => ({
 
 vi.mock('@react-native-async-storage/async-storage', () => ({ default: asyncStorage }))
 
-import { dispatchMobileStructuredCommand } from './mobile-structured-composer-command'
+import {
+  dispatchMobileStructuredCommand,
+  mobileStructuredCommandWaitsInLine
+} from './mobile-structured-composer-command'
 
 function setup() {
   const sendRequest = vi.fn<
@@ -204,3 +207,23 @@ describe('mobile structured conversation commands', () => {
     expect(sendRequest).not.toHaveBeenCalled()
   })
 })
+
+describe('which commands wait in line on this host', () => {
+  const host = { commandsWait: true, clearWaits: false, promptsUnanswerableHere: false }
+
+  it('each command by its own capability: a host that holds only /compact still refuses /clear', () => {
+    expect(mobileStructuredCommandWaitsInLine('compact', host)).toBe(true)
+    expect(mobileStructuredCommandWaitsInLine('clear', host)).toBe(false)
+    expect(mobileStructuredCommandWaitsInLine('clear', { ...host, clearWaits: true })).toBe(true)
+  })
+
+  it('never behind a prompt nothing here can answer', () => {
+    expect(
+      mobileStructuredCommandWaitsInLine('clear', {
+        commandsWait: true,
+        clearWaits: true,
+        promptsUnanswerableHere: true
+      })
+    ).toBe(false)
+  })
+})

mobile/src/session/mobile-structured-composer-command.ts

@@ -27,6 +27,18 @@ function busyCommandText(
   )
 }
 
+/** Whether the host holds this command as a card while the agent works: /compact and /clear each
+ *  need their own capability (and the queue), and a prompt nothing here can answer would hold the
+ *  card forever. */
+export function mobileStructuredCommandWaitsInLine(
+  command: AgentSessionConversationCommand,
+  host: { commandsWait: boolean; clearWaits: boolean; promptsUnanswerableHere: boolean }
+): boolean {
+  return (
+    (command === 'compact' ? host.commandsWait : host.clearWaits) && !host.promptsUnanswerableHere
+  )
+}
+
 export async function dispatchMobileStructuredCommand(input: {
   text: string
   hasAttachments: boolean

mobile/src/session/mobile-structured-operation-id-retirement.test.ts

@@ -254,11 +254,11 @@ describe('what a structured refusal says on the phone', () => {
       clientOperationId: `1900000000000-${'e'.repeat(32)}`
     })
 
+    // The phone hands a refused send's text back, so it says where that text is.
     expect(result).toEqual({
       status: 'refused',
       code: 'agent_session_operation_invalid',
-      message:
-        'This conversation has been cleared. Your message was not sent. Open the current conversation to continue.'
+      message: "The chat was cleared before your message went out. It's back in the composer."
     })
   })
 

mobile/src/session/mobile-structured-queued-message-cards.test.ts

@@ -102,6 +102,97 @@ describe('mobileQueuedMessageCards', () => {
     ).toMatchObject({ command: true, waitsForAgent: true })
   })
 
+  it('a /clear next in line that nothing holds offers no Send: the queue is about to run it', () => {
+    const clear = (overrides: Partial<AgentSessionQueuedMessage> = {}) =>
+      draft({
+        messageId: 'c',
+        body: {
+          kind: 'message',
+          role: 'user',
+          blocks: [{ type: 'text', text: '/clear' }],
+          command: { name: 'clear' }
+        },
+        ...overrides
+      })
+    const idle = { pendingPrompt: false }
+    expect(mobileQueuedMessageCards([clear()], [], idle)[0]).toMatchObject({ runsOnItsOwn: true })
+    // Anything the person must act on keeps its Send, as does a /clear behind another card.
+    for (const [cards, facts] of [
+      [[clear()], { ...idle, queuePaused: true }],
+      [[clear()], { pendingPrompt: true }],
+      [[clear({ paused: true, pausedReason: QUEUED_MESSAGE_PAUSED_SEND_FAILED })], idle],
+      [[draft({ messageId: 'a' }), clear()], idle]
+    ] as const) {
+      expect(mobileQueuedMessageCards(cards, [], facts).some((card) => card.runsOnItsOwn)).toBe(
+        false
+      )
+    }
+  })
+
+  it('a /clear next in line that only background tasks hold says so; nothing else does', () => {
+    const clear = draft({
+      messageId: 'c',
+      body: {
+        kind: 'message',
+        role: 'user',
+        blocks: [{ type: 'text', text: '/clear' }],
+        command: { name: 'clear' }
+      }
+    })
+    const tasks = { pendingPrompt: false, backgroundTasksRunning: true }
+    const [first, second] = mobileQueuedMessageCards(
+      [clear, draft({ messageId: 'm', position: 2 })],
+      [],
+      tasks
+    )
+    expect(first).toMatchObject({
+      caption: 'Waiting for background tasks to finish',
+      runsOnItsOwn: true
+    })
+    expect(second?.caption).toBeNull()
+    // Behind a turn or an answer, that is what it waits on; behind another card, its turn.
+    expect(
+      mobileQueuedMessageCards([clear], [], { ...tasks, agentWorking: true })[0]?.caption
+    ).toBeNull()
+    expect(
+      mobileQueuedMessageCards([clear], [], { ...tasks, pendingPrompt: true })[0]?.caption
+    ).toBe('Waiting for your answer')
+    expect(
+      mobileQueuedMessageCards([draft({ messageId: 'm' }), { ...clear, position: 2 }], [], tasks)[1]
+        ?.caption
+    ).toBeNull()
+  })
+
+  it('skips a failed card ahead of clear, respecting returned and queue-pause barriers', () => {
+    const clear = draft({
+      messageId: 'clear',
+      position: 2,
+      body: {
+        kind: 'message',
+        role: 'user',
+        blocks: [{ type: 'text', text: '/clear' }],
+        command: { name: 'clear' }
+      }
+    })
+    const held = draft({
+      messageId: 'held',
+      paused: true,
+      pausedReason: QUEUED_MESSAGE_PAUSED_SEND_FAILED
+    })
+    expect(
+      mobileQueuedMessageCards([held, clear], [], { pendingPrompt: false })[1]?.runsOnItsOwn
+    ).toBe(true)
+    expect(
+      mobileQueuedMessageCards([{ ...held, state: 'returned' }, clear], [], {
+        pendingPrompt: false
+      })[1]?.runsOnItsOwn
+    ).toBeUndefined()
+    expect(
+      mobileQueuedMessageCards([held, clear], [], { pendingPrompt: false, queuePaused: true })[1]
+        ?.runsOnItsOwn
+    ).toBeUndefined()
+  })
+
   it("a send-failed command card's caption names Send only when Send is there", () => {
     const failed = draft({
       messageId: 'c',