🤖 Stateless /compact UX with structured metadata

[ammar-agent]

Overview

Replace localStorage-based compaction state tracking with structured metadata embedded in messages. Four critical bugs discovered after initial implementation were fixed through systematic improvements to the replay and metadata flow architecture.

Key insight: Embed structured metadata directly in the user's compaction request message. The backend stores it as a black-box, and the frontend queries it when needed—no localStorage, no callback chains, no event systems.

What Changed

Architecture

Before (localStorage-based):

User types /compact -c msg → ChatInput → onCompactStart callback → App → localStorage
Backend compacts → useAutoCompactContinue reads localStorage → sends continue message

After (metadata-based):

User types /compact -c msg → ChatInput creates cmuxMetadata: { type: "compaction-request", parsed: { continueMessage } }
Backend stores metadata as-is (black-box) → useAutoCompactContinue queries messages → sends continue message

Key Improvements

1. Metadata Flow: compaction-request → backend black-box → compaction-result in summary
2. Stream Event Buffering: All stream events buffered until caught-up to ensure aggregator has full historical context
3. Single Source of Truth: cmuxMetadata drives all compaction detection, display, and continuation logic
4. Type Safety: Discriminated unions with proper narrowing throughout

Bugs Fixed

Issue #1: Continue Message Lost After Edit ✅

Problem: Editing /compact -c "msg" lost the continue message.

Root Cause: When compaction completed, history was replaced with just the summary. The original compaction-request message (containing continueMessage) was deleted. useAutoCompactContinue looked for it and found nothing.

Solution: Extract continueMessage from request before history replacement and store it in summary metadata as compaction-result. Hook now reads from summary, not request.

// In WorkspaceStore during compaction completion:
const continueMessage = compactRequestMsg?.metadata?.cmuxMetadata?.parsed.continueMessage;
const summaryMessage = createCmuxMessage(/*...*/,  {
  cmuxMetadata: continueMessage 
    ? { type: "compaction-result", continueMessage } 
    : { type: "normal" },
});

Issue #2: "streaming..." Instead of "compacting..." After Reload ✅

Problem: After page reload during active compaction, StreamingBarrier showed "streaming..." instead of "compacting...".

Root Cause: Replay timing issue. When stream-start arrived during replay, aggregator's message cache was still empty (messages buffered separately), so isCompacting check failed.

Solution: Buffer all stream events (start/delta/end/abort/tool calls) until caught-up message arrives. Process them only after historical messages are loaded. This ensures aggregator always has full context when detecting compaction state.

// In WorkspaceStore:
if (!isCaughtUp && this.isStreamEvent(data)) {
  const pending = this.pendingStreamEvents.get(workspaceId) ?? [];
  pending.push(data);
  return; // Don't process yet
}

if (isCaughtUpMessage(data)) {
  aggregator.loadHistoricalMessages(historicalMsgs);
  // NOW process buffered events with full context
  for (const event of pendingEvents) {
    this.processStreamEvent(workspaceId, aggregator, event);
  }
}

Benefits:

• Eliminates entire class of replay timing bugs
• Works for all stream events (not just compaction detection)
• No special cases or optional parameters

Issue #3: Edit Button Active During Compaction ✅

Problem: Clicking "Edit" during compaction created a stuck state—input populated but disabled, user couldn't type or cancel.

Solution: Disable Edit button during compaction with helpful tooltip explaining how to cancel first. Prevents user from entering broken state.

// In UserMessage:
{
  label: "Edit",
  onClick: handleEdit,
  disabled: isCompacting,
  tooltip: isCompacting
    ? `Cannot edit while compacting (press ${formatKeybind(KEYBINDS.INTERRUPT_STREAM)} to cancel)`
    : undefined,
}

Issue #4: Duplicate Messages When Editing Compaction ✅

Problem: Editing a compaction message created duplicates instead of replacing.

Root Cause: Compaction command path didn't pass editMessageId.

Solution: Pass editMessageId through compaction path and clear editing state on success.

Files Changed

Deleted

• src/components/Messages/PendingUserDraft.tsx (84 lines)
• src/components/Messages/ChatBarrier/CompactionBarrier.tsx (37 lines)

Modified

• src/stores/WorkspaceStore.ts - Stream event buffering until caught-up, extract continueMessage before replacement
• src/hooks/useAutoCompactContinue.ts - Query compaction-result from summary instead of request
• src/utils/messages/StreamingMessageAggregator.ts - Use cmuxMetadata for isCompacting detection
• src/components/ChatInput.tsx - Create metadata on send, regenerate on edit
• src/components/AIView.tsx - Pass isCompacting to MessageRenderer
• src/components/Messages/MessageRenderer.tsx - Pass isCompacting to UserMessage
• src/components/Messages/UserMessage.tsx - Disable edit button during compaction
• src/types/message.ts - Add CmuxFrontendMetadata discriminated union
• src/types/ipc.ts - Add cmuxMetadata to SendMessageOptions
• src/services/agentSession.ts - Pass through metadata as black-box

Added

• tests/ipcMain/sendMessage.test.ts - Integration test verifying metadata round-trip

Benefits

1. Type-safe - Discriminated unions enforce correct structure at compile time
2. Single source of truth - Message metadata is authoritative, no synchronization issues
3. No string parsing on read - Data is already structured from send
4. Queryable - Easy to find compaction messages with .find()
5. Editable - Re-parses edited commands automatically
6. Stateless - No localStorage or callback chains
7. Simpler - Removed 2 components, ~105 net LoC reduction
8. Tested - Integration test verifies metadata round-trip through IPC
9. Robust - Stream event buffering eliminates replay timing bugs

Testing

• ✅ TypeScript compilation passes (both renderer and main)
• ✅ Integration test passes (metadata round-trip)
• ✅ All type constraints satisfied
• ✅ No breaking changes to existing APIs
• ✅ Static checks passing (lint, fmt, typecheck)

Manual testing recommended:

• /compact without continue message
• /compact -c "message" with auto-continue
• Edit compaction message after completion
• Reload during compaction (verify "compacting..." barrier)
• Click Edit button during compaction (verify disabled with tooltip)

Generated with cmux

[ammario]

Manual merging due to flake