feat: add Steer and Queue follow-up modes alongside Chat/Plan

[Fanzzzd]

Right now T3 Code appears to only model default and plan interaction modes. I’d like to request support for Steer and Queue style follow-up behavior while a run is already active.

Why

When the agent is already working, users often want two different behaviors:

• Steer: inject immediate guidance into the active run
• Queue: save the follow-up so it runs after the current work settles

This is a meaningful UX distinction and avoids forcing users into interrupt-or-wait behavior only.

Settings ask

It would be even better if this can be configured in Settings, for example:

• default follow-up behavior while a run is active
• whether the composer shows Steer / Queue explicitly
• an optional shortcut for sending the non-default behavior once

Suggested acceptance criteria

• The composer exposes both follow-up modes when a run is active.
• The selected mode is visible and predictable.
• Users can configure the default active-run follow-up behavior in Settings.
• Queued follow-ups survive reconnects/reloads.
• Steering a run does not silently discard already queued follow-ups.

Relevant code context

• packages/contracts/src/orchestration.ts
• apps/web/src/components/ChatView.tsx
• apps/server/src/orchestration/Layers/ProviderCommandReactor.ts

Reference implementation ideas

• CodexMonitor already exposes configurable follow-up behavior with Queue vs Steer while a run is active.

[MatejSkarka]

+1 for this, for sure for "Steer". This is very usefull function in Codex.

[CanRau]

@MatejSkarka You can already steer by just adding messages, so basically only queueing is missing with clear UI, from my understanding

[juliusmarminge]

yes it's all steer now. we'll add queinig!

[aashishsingla567]

+1 Queue is very important

[FleetAdmiralJakob]

This is a big one and super important for me

[SOUMITRO-SAHA]

PRD: Steer & Queue Interaction Model

1. Objective

To transition the interaction model from a synchronous "wait-and-reply" system to an asynchronous "task-pipeline" system. This allows users to stack instructions while a run is active and selectively "promote" urgent guidance to the active run (Steering).

2. Current State Analysis

2.1 Existing Flow (Synchronous)

The current implementation follows a strict synchronous message flow:

[User sends message]
       ↓
ThreadTurnStartCommand dispatched
       ↓
┌─────────────────────────────────────┐
│  thread.message-sent event          │  ← User message stored
│  thread.turn-start-requested event  │  ← AI turn starts immediately
└─────────────────────────────────────┘
       ↓
Provider session activated (Codex app-server)
       ↓
[AI processes and responds]
       ↓
thread.turn-diff-complete event
       ↓
[Session returns to idle state]

Key Characteristics:

• No buffering: Messages dispatch immediately, triggering a new turn.
• Blocking behavior: While session.status === "running", users must wait or interrupt.
• Destructive interrupt: ThreadTurnInterruptCommand stops the current turn entirely.

2.2 Current Schemas (Relevant Excerpts)

// OrchestrationThread - current structure
const OrchestrationThread = Schema.Struct({
  id: Schema.String,
  projectId: Schema.String,
  title: Schema.String.pipe(Schema.optional),
  model: Schema.String.pipe(Schema.optional),
  runtimeMode: RuntimeMode,
  interactionMode: ProviderInteractionMode,
  branch: Schema.String.pipe(Schema.optional),
  worktreePath: Schema.String.pipe(Schema.optional),
  latestTurn: OrchestrationLatestTurn.pipe(Schema.optional),
  messages: Schema.Array(OrchestrationMessage),
  proposedPlans: Schema.Array(OrchestrationProposedPlan),
  activities: Schema.Array(OrchestrationThreadActivity),
  checkpoints: Schema.Array(OrchestrationCheckpointSummary),
  session: OrchestrationSession.pipe(Schema.optional),
  // ... timestamps
});

// OrchestrationSession - tracks active provider state
const OrchestrationSession = Schema.Struct({
  threadId: Schema.String,
  status: OrchestrationSessionStatus, // "idle" | "running" | "error"
  providerName: Schema.String.pipe(Schema.optional),
  runtimeMode: RuntimeMode,
  activeTurnId: Schema.String.pipe(Schema.optional),
  lastError: Schema.String.pipe(Schema.optional),
  updatedAt: Schema.String,
});

// OrchestrationLatestTurn - turn lifecycle state
const OrchestrationLatestTurn = Schema.Struct({
  turnId: Schema.String,
  state: OrchestrationLatestTurnState, // "requested" | "running" | "completed"
  requestedAt: Schema.String,
  startedAt: Schema.String.pipe(Schema.optional),
  completedAt: Schema.String.pipe(Schema.optional),
  assistantMessageId: Schema.String.pipe(Schema.optional),
});

2.3 Existing Commands

Command	Purpose	Behavior
ThreadTurnStartCommand	Send message + start turn	Creates message-sent and turn-start-requested events synchronously
ThreadTurnInterruptCommand	Stop active turn	Emits turn-interrupt-requested, terminates provider session
ThreadSessionStopCommand	Stop session	Emits session-stop-requested

3. User Problems

• Context Loss: Users think of a fix while the AI is mid-generation but have to wait to type it, often forgetting the nuance.
• Interruption Friction: "Interrupting" a run feels destructive. "Queuing" feels constructive.
• Visibility: Current systems don't show the user what is "pending," leading to duplicate prompts.
• Workflow Disruption: Users lose momentum when forced to wait for completion.

4. Proposed Features & Logic

4.1 The Follow-Up Queue

• Any message sent while session.status === "running" is automatically pushed to a Follow-Up Queue.
• Queue Limit: Maximum of 10 queued items per thread. Attempts to add beyond this limit are rejected with a user-friendly error.
• The AI finishes Turn A, then automatically pops the next item from the queue and starts Turn B.

                    ┌─────────────────────────────────┐
                    │   session.status === "running"  │
                    └─────────────────────────────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    ▼                             ▼
           [User sends message]          [Turn completes]
                    │                             │
                    ▼                             ▼
        ┌───────────────────────┐      ┌─────────────────────┐
        │ queuedFollowUps.push()│      │ Check queue length  │
        │ (if < 10 items)       │      │                     │
        └───────────────────────┘      └──────────┬──────────┘
                                                  │
                                   ┌──────────────┴──────────────┐
                                   ▼                             ▼
                          [Queue empty]                  [Queue has items]
                                   │                             │
                                   ▼                             ▼
                          [Session → idle]             [Dequeue first item]
                                                                 │
                                                                 ▼
                                                       [Auto-start next turn]

4.2 The "Steer" Promotion

• Each item in the queue has a "Promote to Steer" action.
• Action: Injects the message directly into the current turn context without stopping file-writing.
• Implementation: Uses ThreadTurnSteerCommand (new) to send mid-turn guidance.
• Note: Steer is only available when provider supports mid-turn injection (Codex supports this via send_turn with a running session).

4.3 Queue Operations

Operation	Command	Event Emitted	Behavior
Queue item	ThreadFollowUpQueueCommand	thread.follow-up-queued	Appends to queuedFollowUps if < 10 items
Dequeue item	ThreadFollowUpDequeueCommand	thread.follow-up-dequeued	Removes from queue (FIFO or by index)
Steer item	ThreadTurnSteerCommand	thread.turn-steered	Injects into active turn, removes from queue

4.4 Settings Integration

// New settings schema
const FollowUpModeSettings = Schema.Struct({
  followUpMode: Schema.Literal("queue", "steer"), // Default: "queue"
  showFollowUpModeInComposer: Schema.Boolean, // Default: true
});

• followUpMode: Determines default behavior when sending during active turn.
  • "queue": Add to queue (default)
  • "steer": Immediately inject into active turn
• showFollowUpModeInComposer: Toggle UI indicator in composer footer.

---

5. UI/UX Design

The UI sits directly above the Composer to indicate "input-ready" but "pending-execution."

5.1 UI Layout Example

----------------------------------------------------------------------
[ QUEUE ]  3 pending                            ( ⚡ Steer All ) [⌘⇧↵]
----------------------------------------------------------------------
[ 1 ] Refactor the CSS to use Tailwind vars...       [⚡]  [⌘⇧1] [ x ]
[ 2 ] Also check the types in orchestration.ts...    [⚡]  [⌘⇧2] [ x ]
[ 3 ] Add unit tests for the decider...              [⚡]  [⌘⇧3] [ x ]
----------------------------------------------------------------------
[ Queue limit: 3/10 ]                                                ]
----------------------------------------------------------------------
[ ⌨️ Type a follow-up or instruction...                              ]
----------------------------------------------------------------------

5.2 Composer Footer States

┌────────────────────────────────────────────────────────────────────┐
│  [Queue: 3 pending] [Mode: Queue ▾]      │  ⚡ Steer All (⌘⇧↵)     │
└───────────────────────────────────────────────────────────────────-┘

When session idle:
┌─────────────────────────────────────────────────────────────────────┐
│  [Ready] [Mode: Queue ▾]                                            │
└─────────────────────────────────────────────────────────────────────┘

When queue full (10 items):
┌─────────────────────────────────────────────────────────────────────┐
│  [Queue Full: 10/10] [Mode: Queue ▾]                                │
└─────────────────────────────────────────────────────────────────────┘

5.3 Component Breakdown

Element	Function	Shortcut
Queue Item	Displays truncated preview of pending prompt	N/A
Steer Button (⚡)	Injects that specific prompt into the active run	Cmd + Shift + [Index]
Steer All	Merges all queue items and sends as a single steer update	Cmd + Shift + Enter
Cancel (x)	Removes item from queue	N/A
Mode Selector	Switches between Queue and Steer modes	N/A

---

6. Technical Requirements

6.1 Schema Changes (packages/contracts/src/orchestration.ts)

// Add to OrchestrationThread
const OrchestrationQueuedFollowUp = Schema.Struct({
  id: Schema.String,
  message: Schema.Struct({
    text: Schema.String,
    attachments: Schema.Array(ChatAttachment).pipe(Schema.optional),
  }),
  queuedAt: Schema.String,
  mode: Schema.Literal("queue", "steer"),
});

// Updated OrchestrationThread
const OrchestrationThread = Schema.Struct({
  // ... existing fields ...
  queuedFollowUps: Schema.Array(OrchestrationQueuedFollowUp), // NEW
});

// New Commands
const ThreadFollowUpQueueCommand = Schema.Struct({
  type: Schema.Literal("thread.follow-up.queue"),
  commandId: Schema.String,
  threadId: Schema.String,
  message: Schema.Struct({
    text: Schema.String,
    attachments: Schema.Array(ChatAttachment).pipe(Schema.optional),
  }),
  mode: Schema.Literal("queue", "steer").pipe(Schema.optional),
  createdAt: Schema.String,
});

const ThreadFollowUpDequeueCommand = Schema.Struct({
  type: Schema.Literal("thread.follow-up.dequeue"),
  commandId: Schema.String,
  threadId: Schema.String,
  followUpId: Schema.String.pipe(Schema.optional), // If omitted, dequeues first (FIFO)
  createdAt: Schema.String,
});

const ThreadTurnSteerCommand = Schema.Struct({
  type: Schema.Literal("thread.turn.steer"),
  commandId: Schema.String,
  threadId: Schema.String,
  turnId: Schema.String,
  message: Schema.Struct({
    text: Schema.String,
    attachments: Schema.Array(ChatAttachment).pipe(Schema.optional),
  }),
  createdAt: Schema.String,
});

// New Events
const ThreadFollowUpQueuedPayload = Schema.Struct({
  threadId: Schema.String,
  followUp: OrchestrationQueuedFollowUp,
});

const ThreadFollowUpDequeuedPayload = Schema.Struct({
  threadId: Schema.String,
  followUpId: Schema.String,
});

const ThreadTurnSteeredPayload = Schema.Struct({
  threadId: Schema.String,
  turnId: Schema.String,
  followUpId: Schema.String.pipe(Schema.optional),
  messageText: Schema.String,
});

6.2 Queue Limits (Constants)

// packages/contracts/src/orchestration.ts
export const MAX_QUEUED_FOLLOW_UPS = 10;

6.3 Server-Side Implementation (apps/server/src/orchestration/decider.ts)

New command handlers in decideOrchestrationCommand:

1. thread.follow-up.queue

   • Validate queuedFollowUps.length < MAX_QUEUED_FOLLOW_UPS
   • If limit reached, return error event
   • Otherwise, emit thread.follow-up-queued event

2. thread.follow-up.dequeue

   • Validate follow-up exists
   • Emit thread.follow-up-dequeued event

3. thread.turn.steer

   • Validate session is running
   • Emit thread.turn-steered event
   • Remove from queue if followUpId provided

6.4 Reactor Logic (apps/server/src/orchestration/Layers/ProviderCommandReactor.ts)

On thread.turn-diff-complete event:

// After turn completion, check for queued follow-ups
if (readModel.threads.find((t) => t.id === threadId)?.queuedFollowUps.length > 0) {
  // Dequeue first item
  const nextFollowUp = thread.queuedFollowUps[0];

  // Dispatch ThreadTurnStartCommand with the queued message
  await dispatchCommand({
    type: "thread.turn-start",
    threadId,
    message: {
      messageId: generateId(),
      role: "user",
      text: nextFollowUp.message.text,
      attachments: nextFollowUp.message.attachments,
    },
    // ... other fields
  });
}

6.5 Frontend State Management (apps/web/src)

// apps/web/src/state/threadStore.ts
interface ThreadState {
  // ... existing fields
  queuedFollowUps: OrchestrationQueuedFollowUp[];
}

// Selectors
const selectQueuedFollowUps = (threadId: string) => (state) =>
  state.threads[threadId]?.queuedFollowUps ?? [];

const selectQueueCount = (threadId: string) => (state) =>
  state.threads[threadId]?.queuedFollowUps.length ?? 0;

const selectCanQueue = (threadId: string) => (state) =>
  (state.threads[threadId]?.queuedFollowUps.length ?? 0) < 10;

6.6 WebSocket Integration

Queue operations use the existing dispatchCommand RPC method:

// Client dispatches
ws.dispatchCommand({
  type: "thread.follow-up.queue",
  threadId: "thread-123",
  message: { text: "Also fix the tests" },
});

// Server pushes domain events
ws.push("orchestration.domainEvent", {
  type: "thread.follow-up-queued",
  payload: { threadId: "thread-123", followUp: {...} },
});

---

7. Persistence & Recovery

7.1 Event Sourcing

• queuedFollowUps is derived from thread.follow-up-queued and thread.follow-up-dequeued events.
• Queue state survives:
  • Browser refresh (via WebSocket resync)
  • Server restart (via event replay)
  • Page navigation (via global state)

7.2 Thread Snapshot

• queuedFollowUps included in OrchestrationReadModel snapshot.
• On WebSocket reconnect, client receives full snapshot via getSnapshot RPC.

---

8. Acceptance Criteria

8.1 Core Functionality

• Sending a message while session.status === "running" adds it to queuedFollowUps instead of blocking.
• Queue rejects additions when at 10 items, showing user-friendly error.
• Queue indicator displays correct count (e.g., "Queue: 3/10").
• When a turn completes, the first queued item is automatically dequeued and processed.
• "Steer" button injects message into active turn without interrupting.
• "Steer All" merges all queued items into single steer command.
• Deleting a queue item removes it from both state and UI.

8.2 State Synchronization

• Queue state persists across browser refresh.
• Queue state syncs on WebSocket reconnect.
• Queue state survives server restart (via event store).

8.3 Keyboard Shortcuts

• Enter (while running): Add to queue.
• Cmd + Enter (while running): Force steer (bypass queue).
• Cmd + Shift + Enter: Steer all queued items.
• Cmd + Shift + 1-9: Steer specific queue item by index.

8.4 Error Handling

• Attempting to queue beyond 10 items shows: "Queue is full (10/10). Please wait for items to process."
• Attempting to steer when session is not running shows: "Cannot steer: no active turn."
• Network errors during queue operations show retry option.

[SOUMITRO-SAHA]

Hi @juliusmarminge @maria-rcks ,

I have written a short PRD for this task and shared my thoughts on how the feature could be implemented. Could you please review it and let me know what you think?

If the proposal looks good to you, I would be happy to take ownership of the implementation. Please feel free to assign this task to me.

[ranvier2d2]

Hi @SOUMITRO-SAHA

I'm not a maintainer, but I did implement and validate a local version of this flow, and found a few semantics that may be worth making explicit in the PRD:

1. A queued follow-up should remain only in the queue UI while pending, and should not be inserted into the chat timeline until drain dispatch actually begins.
2. queuedAt and dispatch time should be treated differently. I hit a real ordering bug where a drained queued message rendered above assistant output that had actually occurred earlier because the optimistic message reused the original enqueue timestamp.
3. Failed local drain dispatches likely need explicit rollback semantics. If the client dequeues an item, inserts an optimistic user message, and local thread.turn.start dispatch fails before server acceptance, the optimistic message should be removed and the queued item restored to the front of the queue.

I only caught this in real-browser validation, so I’m attaching a couple of short GIFs in case they help make the interaction clearer:

Queued item stays pending, then appears only after drain.

Queue default + immediate "Send now" override in the same run.

Not trying to push a different architecture, just sharing a few implementation details that turned out to matter a lot for the UI.

[cafeai]

+1 for queue support please...
i typically queue a significant amount of things up when i know i'll be away from the computer

[tiagonrodrigues]

+1! Is this WIP?