@mobius-os/mobius 0.3.43 → 0.3.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mobius-os/mobius",
-  "version": "0.3.43",
+  "version": "0.3.46",
   "type": "module",
   "description": "Mobius terminal client. Reuses Mobius frontend TypeScript types and jsonl entry shapes.",
   "bin": {

package/src/aimux.ts

@@ -92,7 +92,7 @@ async function pythonForAimux(onProgress?: (p: InstallProgress) => void): Promis
 // 系统 python（如被精简掉 ensurepip 的容器镜像）。aimux 全部依赖为纯 Python，
 // 故三平台可共用同一套打包产物，分别按 arch 发布到 CDN。
 const BUNDLE_VER = '3'
-const BUNDLE_AIMUX_VERSION = '0.1.28'
+const BUNDLE_AIMUX_VERSION = '0.1.29'
 /** Version expected from the installed or bundled AIMUX runtime. */
 export const AIMUX_VERSION = BUNDLE_AIMUX_VERSION
 const bundleDir = () => path.join(mobiusHome(), 'python-bundle')

package/src/api.ts

@@ -6,7 +6,10 @@
  * bearer token (header `Authorization: Bearer <jwt>`); there is no cookie auth.
  */
 import type {
+  AnyEntry,
   AuthConfig,
+  HistoryGroup,
+  HistoryPendingOpener,
   Issue,
   LoginResponse,
   Memory,
@@ -160,6 +163,22 @@ export class MobiusClient {
     return this.request<SessionRuntimeStatus>(`/api/sessions/${encodeURIComponent(sessionId)}/status`, { signal })
   }
 
+  // ── agent-history (协议 ①②: 组元数据 + 整组条目) ──────────────────────────
+  /** ① 全部组元数据, 一次给全; 顺带返回挂起中的开轮卡 (pending). */
+  async listHistoryGroups(sessionId: string): Promise<{ session_version: number; groups: HistoryGroup[]; pending: HistoryPendingOpener[] }> {
+    return this.request(`/api/sessions/${encodeURIComponent(sessionId)}/groups`)
+  }
+
+  /** 打断当前 turn 并出队下一条排队指令 (不追加新 prompt). */
+  async pauseToDequeue(sessionId: string): Promise<{ ok: boolean }> {
+    return this.request(`/api/sessions/${encodeURIComponent(sessionId)}/pause-to-dequeue`, { method: 'POST', body: '{}' })
+  }
+
+  /** ② 某组全部条目 (全量, 无分页, 条目不可变). */
+  async listHistoryGroupEntries(sessionId: string, groupId: string): Promise<{ group_id: string; version: number; entries: AnyEntry[] }> {
+    return this.request(`/api/sessions/${encodeURIComponent(sessionId)}/groups/${encodeURIComponent(groupId)}/entries`)
+  }
+
   // ── preference lookups ────────────────────────────────────────────────────
   async modelOptions(): Promise<SessionModelOption[]> {
     const r = await this.request<any>('/api/sessions/model-options')

package/src/components/Chat.tsx

@@ -152,8 +152,7 @@ export function ChatScreen({ client, ready, webUserId, resumeSessionId, onClear,
 
   // First query of a fresh session triggers the full backend bootstrap (lazy
   // session creation, worker spawn, context load) before any output streams.
-  // Label that phase "第一个问题，正在初始化+全平台同步中，请稍候" instead of "Working"
-  // so it reads as startup rather than a stuck agent. Once the first assistant
+  // Label that phase as startup rather than a stuck agent. Once the first assistant
   // output is observed (or the session is a resumed one with prior history),
   // the indicator falls back to the normal Working label for every turn.
   const firstQueryInFlight = !resumeSessionId && !chat.entries.some(isAssistantOutput)
@@ -162,15 +161,32 @@ export function ChatScreen({ client, ready, webUserId, resumeSessionId, onClear,
   // (type:user / response_item.message[user] / event_msg.user_message) 合并成 1 条,
   // 避免在累积视图里把同一条提问显示多次.
   const dedupedEntries = useMemo(() => dedupeUserEntries(chat.entries), [chat.entries])
-  const pendingEntry = useMemo<AnyEntry | null>(() => chat.pendingUser === null ? null : ({
-    type: 'user',
-    __id: '__pending-user__',
-    message: { role: 'user', content: chat.pendingUser },
-  }), [chat.pendingUser])
-  const transcriptEntries = useMemo(
-    () => pendingEntry ? [...dedupedEntries, pendingEntry] : dedupedEntries,
-    [dedupedEntries, pendingEntry],
-  )
+  const pendingEntry = useMemo<AnyEntry | null>(() => {
+    // 忙时提交的指令已由排队行统一呈现, 乐观占位退役 (避免 "You:" 与 "排队" 双重显示).
+    if (chat.pending.length > 0) return null
+    return chat.pendingUser === null ? null : ({
+      type: 'user',
+      __id: '__pending-user__',
+      message: { role: 'user', content: chat.pendingUser },
+    })
+  }, [chat.pendingUser, chat.pending.length])
+  // 排队行 (合成条目): 显示最后一条挂起指令 + 总数, 紧跟对话末尾.
+  const pendingQueueEntry = useMemo<AnyEntry | null>(() => {
+    if (chat.pending.length === 0) return null
+    const last = chat.pending[chat.pending.length - 1]
+    return {
+      type: '__pending_queue__',
+      __id: '__pending-queue__',
+      text: last?.user_summary ?? '',
+      count: chat.pending.length,
+    }
+  }, [chat.pending])
+  const transcriptEntries = useMemo(() => {
+    const parts = [...dedupedEntries]
+    if (pendingEntry) parts.push(pendingEntry)
+    if (pendingQueueEntry) parts.push(pendingQueueEntry)
+    return parts
+  }, [dedupedEntries, pendingEntry, pendingQueueEntry])
 
   // Markdown parsing and wrapping are paid once per entry/terminal width. Keep
   // the two most recent widths so resize-back does not immediately reparse the
@@ -415,6 +431,8 @@ export function ChatScreen({ client, ready, webUserId, resumeSessionId, onClear,
           commands={SLASH_COMMANDS}
           onHeightChange={setComposerRows}
           inputActiveRef={chatInputActiveRef}
+          onPauseToDequeue={chat.pauseToDequeue}
+          hasPending={chat.pending.length > 0}
         />
         <StatusArea
           ready={ready}
@@ -500,7 +518,8 @@ function ScreenText({ row, text }: { row: ScreenRow; text: string }) {
       : tone === 'edit_header' || tone === 'reasoning' ? 'magenta'
         : tone === 'edit_new' ? 'green'
           : tone === 'system' ? 'yellow'
-            : undefined
+            : tone === 'pending' ? 'yellow'
+              : undefined
   const dimColor = tone === 'tool_result' || tone === 'tool_error' || tone === 'reasoning' || tone === 'system'
   return <Text wrap="truncate-end" bold={tone === 'user'} dimColor={dimColor} color={color}>{text}</Text>
 }
@@ -615,9 +634,12 @@ interface ComposerProps {
   commands: { cmd: string; desc: string }[]
   onHeightChange?: (rows: number) => void
   inputActiveRef?: React.RefObject<boolean>
+  // 排队插队: 有挂起指令时空输入回车触发; hasPending 控制提示文案与触发开关.
+  onPauseToDequeue?: () => void
+  hasPending?: boolean
 }
 
-export function Composer({ onSubmit, onStop, onQuit, typing, commands, onHeightChange, inputActiveRef }: ComposerProps) {
+export function Composer({ onSubmit, onStop, onQuit, typing, commands, onHeightChange, inputActiveRef, onPauseToDequeue, hasPending }: ComposerProps) {
   const [value, setValue] = useState('')
   const [cursor, setCursor] = useState(0)
   const [popupIdx, setPopupIdx] = useState(0)
@@ -838,6 +860,9 @@ export function Composer({ onSubmit, onStop, onQuit, typing, commands, onHeightC
         onSubmit(submitted)
         edit('', 0)
         setHistIdx(null)
+      } else if (hasPending) {
+        // 空输入回车 = 插队: 打断当前 turn 并出队下一条排队指令.
+        void onPauseToDequeue?.()
       }
       return
     }
@@ -970,7 +995,10 @@ export function Composer({ onSubmit, onStop, onQuit, typing, commands, onHeightC
         <Box justifyContent="space-between">
           {confirmQuit
             ? <Text color="yellowBright" bold>请再次按下Ctrl+C退出</Text>
-            : <Text dimColor>{(stdout.columns ?? 80) >= 72 ? 'Enter 发送 · Shift+Enter / Alt+Enter / Ctrl+J 换行' : 'Enter 发送 · Alt+Enter / Ctrl+J 换行'}</Text>}
+            : <Text dimColor>
+                {hasPending ? <Text color="yellowBright">空回车插队 · </Text> : null}
+                {(stdout.columns ?? 80) >= 72 ? 'Enter 发送 · Shift+Enter / Alt+Enter / Ctrl+J 换行' : 'Enter 发送 · Alt+Enter / Ctrl+J 换行'}
+              </Text>}
           <Text dimColor>{wrapped.length > maxRows ? `${visualCursor + 1}/${wrapped.length} 行` : `${wrapped.length} 行`}</Text>
         </Box>
       </Box>

package/src/hooks/useChat.ts

@@ -4,11 +4,14 @@
  * Lifecycle (per the TUI spec):
  *   - lazily create a session (POST /api/issues/:issueId/sessions) on the first
  *     submitted message, using the saved preferences;
- *   - open the SSE stream (GET /api/sessions/:id/events?token=) and append
- *     `jsonl_entry` payloads to the transcript as they arrive;
+ *   - open the SSE stream (GET /api/sessions/:id/events?token=); on subscribe
+ *     bootstrap the transcript via ① groups + ② tail-group entries, then apply
+ *     live `entries` batches (watermark + uuid dedup) as they arrive;
+ *   - reconnects re-run the same ① negotiation (stateless reconciliation):
+ *     groups whose version changed are refetched whole, transcript rebuilt;
  *   - keep the agent's busy state synchronized with the runtime status API.
  * `/clear` remounts the hook (fresh session next time); `/resume` injects a
- * pre-existing sessionId so the stream replays its history.
+ * pre-existing sessionId.
  */
 import { useCallback, useEffect, useRef, useState } from 'react'
 import { MobiusClient, ApiError } from '../api.js'
@@ -16,7 +19,7 @@ import { SseConnection } from '../sse.js'
 import { updateIssuePreference } from '../config.js'
 import { tuiAimuxIdentifier, probeAimuxBridgeConnection } from '../aimux.js'
 import { viewsForEntry } from '../lib/entry-view.js'
-import type { AnyEntry } from '../types.js'
+import type { AnyEntry, HistoryPendingOpener } from '../types.js'
 import type { ReadyState } from '../components/PrepScreen.js'
 
 export interface ChatApi {
@@ -28,12 +31,14 @@ export interface ChatApi {
 export interface ChatController {
   entries: AnyEntry[]
   pendingUser: string | null
+  pending: HistoryPendingOpener[]
   typing: boolean
   sending: boolean
   error: string | null
   sessionId: string | null
   send: (text: string) => Promise<void>
   stop: () => Promise<void>
+  pauseToDequeue: () => Promise<void>
 }
 
 let ID = 0
@@ -42,7 +47,7 @@ function nextId(): number { ID += 1; return ID }
 /**
  * Does this entry represent the user's just-submitted message? Used to retire the
  * optimistic `pendingUser` placeholder once the real entry is observed — including
- * via a reconnect's history replay (the live `jsonl_entry` path already clears it).
+ * via a reconnect's history reconciliation (the live `entries` path already clears it).
  *
  * Mobius may prepend injected context (project/issue framing) to a user turn, so we
  * match the typed text as a suffix of the entry's normalized text rather than
@@ -66,6 +71,22 @@ function entryKey(entry: AnyEntry): string | null {
   return typeof entry?.uuid === 'string' ? entry.uuid : null
 }
 
+// 首次 bootstrap 拉取的末尾组数 (旧 SSE 尾部回放的等价物; 更早的组按需不拉,
+// TUI 是平铺字幕, 没有轮次展开概念, 末尾几组已覆盖活跃对话).
+const BOOTSTRAP_GROUP_COUNT = 3
+// A fresh session can spend several seconds creating the worker and loading
+// context before /status reports alive=true. Keep the first-turn indicator
+// visible during that bootstrap window instead of letting the short generic
+// hint expire and leaving the user with no feedback.
+const FIRST_TURN_BOOTSTRAP_GRACE_MS = 30_000
+
+/** Mini group store: 组序 + 水位线 (version) + 组内条目. */
+interface GroupSlot {
+  seq: number
+  version: number
+  entries: AnyEntry[]
+}
+
 // Retry transient gateway/transport errors so a brief 502/503/504 (a reverse-
 // proxy blip, a backend worker recycling after a deploy, a transient upstream
 // failure) doesn't immediately fail a message dispatch. 4xx errors are not
@@ -91,10 +112,13 @@ export function useChat({ client, ready, resumeSessionId }: ChatApi): ChatContro
   const [sessionId, setSessionId] = useState<string | null>(resumeSessionId ?? null)
   const [entries, setEntries] = useState<AnyEntry[]>([])
   const [pendingUser, setPendingUser] = useState<string | null>(null)
+  const [pending, setPending] = useState<HistoryPendingOpener[]>([])
   const [typing, setTyping] = useState(false)
   const [sending, setSending] = useState(false)
   const [error, setError] = useState<string | null>(null)
   const sseRef = useRef<SseConnection | null>(null)
+  // agent-history mini group store (协议 ①②③ 的 TUI 侧消费形态).
+  const groupSlotsRef = useRef<Map<string, GroupSlot>>(new Map())
   const pollNowRef = useRef<(() => void) | null>(null)
   const typingRef = useRef(false)
   const sendingRef = useRef(false)
@@ -103,7 +127,7 @@ export function useChat({ client, ready, resumeSessionId }: ChatApi): ChatContro
   // SSE auto-reconnect state. A reverse proxy's idle timeout (or a server
   // restart) drops the stream mid-session; without reconnect the TUI stops
   // receiving new jsonl entries even though the web client keeps updating.
-  // On reconnect the server replays jsonl_history, so no entries are lost.
+  // On reconnect the stateless ①② reconciliation refills any missed entries.
   const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
   const reconnectAttemptRef = useRef(0)
   const aliveRef = useRef(true)
@@ -119,7 +143,7 @@ export function useChat({ client, ready, resumeSessionId }: ChatApi): ChatContro
   const appendEntries = useCallback((newOnes: AnyEntry[]) => {
     if (!newOnes.length) return
     setEntries(prev => {
-      // De-duplicate by uuid so a live jsonl_entry that also appears in a
+      // De-duplicate by uuid so a live `entries` batch that also appears in a
       // reconnect's history replay is never shown twice.
       const seen = new Set<string>()
       for (const e of prev) { const k = entryKey(e); if (k) seen.add(k) }
@@ -145,6 +169,65 @@ export function useChat({ client, ready, resumeSessionId }: ChatApi): ChatContro
     setEntries(out)
   }, [])
 
+  // ── agent-history (协议 ①②③): bootstrap / 重连对账 ──────────────────────
+
+  /** 按组序摊平重建 transcript (uuid 去重由 setHistory 兜底). */
+  const rebuildEntriesFromGroups = useCallback(() => {
+    const slots = [...groupSlotsRef.current.values()].sort((a, b) => a.seq - b.seq)
+    const flat: AnyEntry[] = []
+    for (const s of slots) flat.push(...s.entries)
+    setHistory(flat)
+  }, [setHistory])
+
+  /**
+   * Stateless 对账 (订阅时/重连时同一条路径):
+   *   ① 拿全部组元数据 → 本地没有的或 version 变了的组 ② 整组重拉 → 重建 transcript.
+   * 首次 (本地空) 只拉末尾 BOOTSTRAP_GROUP_COUNT 组; 之后每次只补差额, 常态零请求.
+   */
+  const reconcileHistory = useCallback(async (sid: string) => {
+    try {
+      const data = await client.listHistoryGroups(sid)
+      const groups: any[] = Array.isArray(data?.groups) ? data.groups : []
+      // 挂起中的开轮卡 (排队指令): /groups 是权威快照, 覆盖本地增量.
+      setPending(Array.isArray(data?.pending) ? data.pending : [])
+      const local = groupSlotsRef.current
+      const targets = local.size === 0 ? groups.slice(-BOOTSTRAP_GROUP_COUNT) : groups
+      let changed = false
+      for (const g of targets) {
+        const gid = String(g?.id ?? '')
+        if (!gid) continue
+        const ver = Number(g?.version) || 0
+        const cur = local.get(gid)
+        if (cur && cur.version >= ver) continue
+        try {
+          const r = await client.listHistoryGroupEntries(sid, gid)
+          local.set(gid, {
+            seq: Number(g?.seq) || (local.size + 1),
+            version: Number(r?.version) || 0,
+            entries: Array.isArray(r?.entries) ? r.entries : [],
+          })
+          changed = true
+        } catch { /* 单组失败不阻塞其余组 */ }
+      }
+      // 服务端已不存在的组 → 丢弃 (会话被删/重建的防御).
+      const alive = new Set(groups.map((g: any) => String(g?.id ?? '')))
+      for (const gid of [...local.keys()]) {
+        if (!alive.has(gid)) { local.delete(gid); changed = true }
+      }
+      if (changed) rebuildEntriesFromGroups()
+      // 对账补齐后, 若乐观占位已被真实条目覆盖 → 退掉 (断线期间整轮完成的场景).
+      setPendingUser(prev => {
+        if (prev === null) return prev
+        const slots = [...local.values()].sort((a, b) => a.seq - b.seq)
+        const flat: AnyEntry[] = []
+        for (const s of slots) flat.push(...s.entries)
+        return flat.some(e => entryMatchesPendingUser(e, prev)) ? null : prev
+      })
+    } catch (e) {
+      if (process.env.MOBIUS_TUI_DEBUG) console.error('[history-reconcile]', (e as Error)?.message ?? e)
+    }
+  }, [client, rebuildEntriesFromGroups])
+
   // ── SSE connection ────────────────────────────────────────────────────────
   const connect = useCallback((sid: string) => {
     if (process.env.MOBIUS_TUI_DEBUG) console.error('[connect]', sid)
@@ -153,23 +236,62 @@ export function useChat({ client, ready, resumeSessionId }: ChatApi): ChatContro
     if (reconnectTimerRef.current) { clearTimeout(reconnectTimerRef.current); reconnectTimerRef.current = null }
     const url = `${client.server}/api/sessions/${encodeURIComponent(sid)}/events?token=${encodeURIComponent(client.token)}`
     const conn = new SseConnection(url, {
-      onHistoryEntries: (es, _done) => {
-        if (es.length) setHistory(es)
-        // A reconnect replays the session tail. If our optimistic placeholder is
-        // now backed by its real entry, retire it so the user's input isn't shown
-        // twice (once as the entry, once as the placeholder). The live jsonl_entry
-        // path already clears pendingUser, but a dropped SSE stream (reverse-proxy
-        // idle timeout) can deliver the message only via this history replay — and
-        // if the whole turn finished while disconnected, no live entry ever comes
-        // to clear it, leaving the duplication on screen until the next send.
-        setPendingUser(prev => (prev !== null && es.some(e => entryMatchesPendingUser(e, prev)) ? null : prev))
+      onGroupCreated: (group) => {
+        if (!group || typeof group !== 'object') return
+        const gid = String(group.id ?? '')
+        if (!gid || groupSlotsRef.current.has(gid)) return  // 元数据不可变, 已知即忽略
+        groupSlotsRef.current.set(gid, {
+          seq: Number(group.seq) || (groupSlotsRef.current.size + 1),
+          version: Number(group.version) || 1,
+          entries: [],
+        })
+        // 新组开轮 = 后端已把挂起的 pending_round_openers 一次性出队 (flushPendingOpenersToSink).
+        // 排队行随之清空; 随后 entries 事件会把这一整组内容补齐.
+        setPending([])
       },
-      onEntry: (entry) => {
-        if (process.env.MOBIUS_TUI_DEBUG) console.error('[onEntry]', entry?.type, (entry?.message?.content?.[0]?.text ?? '').slice(0, 40))
-        appendEntries([entry])
+      onEntries: ({ group_id, group_id_version, entries }) => {
+        if (process.env.MOBIUS_TUI_DEBUG) console.error('[onEntries]', group_id, group_id_version, entries.length)
+        const gid = String(group_id ?? '')
+        if (!gid) return
+        let slot = groupSlotsRef.current.get(gid)
+        if (!slot) {
+          // 事件早到且本地无该组 (错过 group_created): 建槽后按水位线对账.
+          slot = { seq: groupSlotsRef.current.size + 1, version: 0, entries: [] }
+          groupSlotsRef.current.set(gid, slot)
+        }
+        const version = Number(group_id_version) || 0
+        if (slot.entries.length > 0 && version <= slot.version) return  // 水位线: ≤ 本地即丢弃
+        // uuid 去重保险丝: 与整组重拉/对账重叠的条目只留一份.
+        const known = new Set<string>()
+        for (const e of slot.entries) { const k = entryKey(e); if (k) known.add(k) }
+        const fresh = entries.filter(e => {
+          const k = entryKey(e)
+          if (k && known.has(k)) return false
+          if (k) known.add(k)
+          return true
+        })
+        slot.entries = slot.entries.concat(fresh)
+        slot.version = Math.max(slot.version, version)
+        if (fresh.length > 0) {
+          appendEntries(fresh)
+          setPendingUser(null)
+        }
+      },
+      onPendingOpener: (opener) => {
+        // 忙时提交的新指令被挂起: 追加到排队行 (uuid 去重), 乐观占位随之退役.
+        if (!opener || typeof opener !== 'object') return
+        const id = String(opener.id ?? '')
+        setPending(prev => {
+          if (id && prev.some(p => p.id === id)) return prev
+          return [...prev, { id, opener_ts: opener.opener_ts ?? null, user_summary: opener.user_summary ?? '' }]
+        })
         setPendingUser(null)
       },
-      onSubscribed: () => { reconnectAttemptRef.current = 0 },
+      onSubscribed: () => {
+        reconnectAttemptRef.current = 0
+        // 订阅即对账 (首开 = bootstrap 拉末尾几组; 重连 = stateless 补差额).
+        void reconcileHistory(sid)
+      },
       onTyping: (active) => {
         // SSE is a low-latency hint, not the source of truth. A `true` event
         // lights the indicator immediately; either edge requests a fresh
@@ -179,7 +301,11 @@ export function useChat({ client, ready, resumeSessionId }: ChatApi): ChatContro
           workingHintUntilRef.current = Date.now() + 1_500
           updateTyping(true)
         } else {
-          workingHintUntilRef.current = 0
+          // A fresh turn uses a longer bootstrap grace period.  Some agents
+          // emit an early typing=false edge before their worker is observable;
+          // do not let that transient edge erase the first-turn indicator.
+          const remaining = workingHintUntilRef.current - Date.now()
+          if (remaining < 5_000) workingHintUntilRef.current = 0
         }
         pollNowRef.current?.()
       },
@@ -204,7 +330,7 @@ export function useChat({ client, ready, resumeSessionId }: ChatApi): ChatContro
     })
     sseRef.current = conn
     conn.start()
-  }, [client.server, client.token, appendEntries, setHistory, updateTyping])
+  }, [client.server, client.token, appendEntries, setHistory, updateTyping, reconcileHistory])
   doConnectRef.current = connect
 
   const ensureSseForSend = useCallback((sid: string): boolean => {
@@ -374,7 +500,8 @@ export function useChat({ client, ready, resumeSessionId }: ChatApi): ChatContro
     setError(null)
     setPendingUser(body)
     statusEpochRef.current += 1
-    workingHintUntilRef.current = Date.now() + 2_000
+    const firstTurn = !sessionId && entries.length === 0
+    workingHintUntilRef.current = Date.now() + (firstTurn ? FIRST_TURN_BOOTSTRAP_GRACE_MS : 2_000)
     sendingRef.current = true
     updateTyping(true)
     setSending(true)
@@ -400,7 +527,7 @@ export function useChat({ client, ready, resumeSessionId }: ChatApi): ChatContro
       setSending(false)
       pollNowRef.current?.()
     }
-  }, [sending, ensureSession, ensureSseForSend, client, updateTyping])
+  }, [sending, sessionId, entries.length, ensureSession, ensureSseForSend, client, updateTyping])
 
   const stop = useCallback(async () => {
     if (!sessionId) return
@@ -412,5 +539,18 @@ export function useChat({ client, ready, resumeSessionId }: ChatApi): ChatContro
     pollNowRef.current?.()
   }, [sessionId, client, updateTyping])
 
-  return { entries, pendingUser, typing, sending, error, sessionId, send, stop }
+  // 打断当前 turn 并出队下一条排队指令 (空输入回车 / 插队). 不追加新 prompt,
+  // 后端对 claude-code/codex 发一次 C-c, deepseek harness 是空实现. 排队行会在
+  // 新组开轮 (group_created) 时被清空, 这里只需触发并刷新状态轮询.
+  const pauseToDequeue = useCallback(async () => {
+    if (!sessionId) return
+    statusEpochRef.current += 1
+    try { await client.pauseToDequeue(sessionId) } catch (e: any) {
+      const msg = e instanceof ApiError ? e.message : `插队失败: ${e?.message ?? e}`
+      setError(msg)
+    }
+    pollNowRef.current?.()
+  }, [sessionId, client])
+
+  return { entries, pendingUser, pending, typing, sending, error, sessionId, send, stop, pauseToDequeue }
 }

package/src/lib/entry-view.ts

@@ -31,6 +31,7 @@ export type EntryView =
   | { kind: 'write_file'; filePath: string; content: string }
   | { kind: 'system'; text: string }
   | { kind: 'error'; text: string }
+  | { kind: 'pending'; text: string; count: number }
 
 export interface ToolResultView {
   text: string
@@ -113,7 +114,7 @@ function extractLocalCommandParts(entry: AnyEntry): LocalCommandPart[] {
 }
 
 /**
- * 整卡隐藏的噪声: 对齐 web entry-classify.ts isHiddenJsonlNoiseEntry 的 7 类
+ * 整卡隐藏的噪声: 对齐 web entry-classify.ts isHiddenJsonlNoiseEntry 的 8 类
  *   - token_count         : codex 每轮 token 用量统计 (event_msg)
  *   - environment_context : codex 每轮注入的 <environment_context> 纯系统 user 消息
  *   - session_meta        : codex 会话首条元数据
@@ -121,10 +122,12 @@ function extractLocalCommandParts(entry: AnyEntry): LocalCommandPart[] {
  *   - turn_duration       : Claude Code 每轮结束注入的 system 耗时统计
  *   - skill_listing       : Claude Code 注入的可用 Skill 清单
  *   - agent_listing_delta : Claude Code 注入的可用 subagent 清单
+ *   - mcp_tool_call_end   : MCP 工具调用完成生命周期标记
  * 注: context_compacted 不在此列 (对齐 web — 它保留为可见事件, TUI 显示成 system 行).
  */
 export function isHiddenNoise(entry: AnyEntry): boolean {
   if (entry?.type === 'event_msg' && entry?.payload?.type === 'token_count') return true
+  if (entry?.type === 'event_msg' && entry?.payload?.type === 'mcp_tool_call_end') return true
   if (entry?.type === 'session_meta') return true
   if (entry?.type === 'turn_context') return true
   if (entry?.type === 'system' && entry?.subtype === 'turn_duration') return true
@@ -515,6 +518,10 @@ function parseCustomToolCall(raw: any): { name: string; input: Record<string, an
 export function viewsForBlock(block: Block): EntryView[] {
   const entry = block.entry
   if (!entry || typeof entry !== 'object') return [{ kind: 'skip' }]
+  // 排队行 (合成条目): 显示忙时挂起的用户指令, 与 web 排队卡片同形.
+  if (entry.type === '__pending_queue__') {
+    return [{ kind: 'pending', text: String(entry.text ?? ''), count: Number(entry.count) || 1 }]
+  }
   if (isHiddenNoise(entry)) return [{ kind: 'skip' }]
   const type = entry.type
 

package/src/lib/screen-text.ts

@@ -118,6 +118,7 @@ export type ScreenRowTone =
   | 'reasoning'
   | 'system'
   | 'error'
+  | 'pending'
 
 export interface ScreenRow {
   /** Visible text used for geometry, hit-testing, and clipboard extraction. */
@@ -204,6 +205,11 @@ export function viewScreenRows(view: EntryView, columns: number): ScreenRows {
       const rows = view.text.split('\n').map((l, i) => `${i === 0 ? '⚠ ' : '  '}${l}`)
       return { marginTop: true, rows: fit(rows, 'error') }
     }
+    case 'pending': {
+      const summary = clampLines(view.text, width - 6, 1)[0] || '(无内容)'
+      const tail = view.count > 1 ? ` · 等 ${view.count} 条指令` : ''
+      return { marginTop: true, rows: fit([`⚡ 排队 · ${summary}${tail}`], 'pending') }
+    }
     default:
       return { marginTop: false, rows: [] }
   }

package/src/sse.ts

@@ -15,8 +15,12 @@ import type { AnyEntry } from './types.js'
 export interface SseHandlers {
   onOpen?: () => void
   onSubscribed?: (session: any) => void
-  onHistoryEntries?: (entries: AnyEntry[], done: boolean) => void
-  onEntry?: (entry: AnyEntry) => void
+  /** ③ 新组元数据 (开轮卡本身随随后的 entries 事件到达). */
+  onGroupCreated?: (group: any) => void
+  /** ③ 组条目增量: version = 应用该批后的组版本 (调用方水位线判据). */
+  onEntries?: (payload: { group_id: string; group_id_version: number; entries: AnyEntry[] }) => void
+  /** 挂起开轮卡 (忙时提交、尚未出队的用户指令): { id, opener_ts, user_summary }. */
+  onPendingOpener?: (pending: { id: string; opener_ts: string | null; user_summary: string }) => void
   onTyping?: (active: boolean) => void
   onError?: (message: string, category?: string) => void
   onClose?: () => void
@@ -105,11 +109,18 @@ export class SseConnection {
     const ev = p?.event ?? eventName
     switch (ev) {
       case 'subscribed': this.handlers.onSubscribed?.(p.session); break
-      case 'jsonl_history':
-        this.handlers.onHistoryEntries?.(p.entries ?? [], !!p.done)
+      case 'group_created':
+        this.handlers.onGroupCreated?.(p.group)
         break
-      case 'jsonl_entry':
-        this.handlers.onEntry?.(p.entry)
+      case 'entries':
+        this.handlers.onEntries?.({
+          group_id: String(p.group_id ?? ''),
+          group_id_version: Number(p.group_id_version) || 0,
+          entries: Array.isArray(p.entries) ? p.entries : [],
+        })
+        break
+      case 'pending_opener':
+        this.handlers.onPendingOpener?.(p.entry)
         break
       case 'typing':
         this.handlers.onTyping?.(!!p.active)
@@ -119,7 +130,7 @@ export class SseConnection {
         this.handlers.onError?.(p.message ?? p.error ?? '未知错误', p.category)
         break
       default:
-        // history / jsonl_meta / message / stream / etc. — currently unused by the TUI.
+        // history / message / stream / etc. — currently unused by the TUI.
         break
     }
   }

package/src/types.ts

@@ -193,14 +193,33 @@ export interface ResourceAccess {
 // ════════════════════════════════════════════════════════════════════════════
 export type AnyEntry = Record<string, any>
 
+// ── agent-history 组元数据 (协议 ① 的载荷) ───────────────────────────────────
+export interface HistoryGroup {
+  id: string
+  seq: number
+  opener_ts: string | null
+  user_summary: string
+  version: number
+  entry_count: number
+}
+
+/**
+ * 挂起中的开轮卡 (pending_round_openers): 忙时提交、尚未出队的用户指令.
+ * /groups 端点返回的 `pending` 数组与 SSE `pending_opener` 事件的 `entry` 字段同形.
+ */
+export interface HistoryPendingOpener {
+  id: string
+  opener_ts: string | null
+  user_summary: string
+}
+
 // ── SSE envelope events (GET /api/sessions/:id/events) ───────────────────────
 // Each SSE frame's data is a JSON object with an `event` discriminator.
 export type SseEvent =
   | { event: 'subscribed'; session: Session }
   | { event: 'history'; messages: any[]; total?: number }
-  | { event: 'jsonl_meta'; session_id: string; total?: number; total_approximate?: number; tail_count?: number; jsonl_path?: string }
-  | { event: 'jsonl_history'; reset?: boolean; done?: boolean; chunk_index?: number; count?: number; entries: AnyEntry[] }
-  | { event: 'jsonl_entry'; session_id: string; entry: AnyEntry }
+  | { event: 'group_created'; session_id: string; group: HistoryGroup }
+  | { event: 'entries'; session_id: string; group_id: string; group_id_version: number; entries: AnyEntry[] }
   | { event: 'typing'; active: boolean }
   | { event: 'error'; message?: string; category?: string }
   | { event: 'server_error'; message?: string }