feat(session): implement codex-style steering and busy submit behavior

Author: adolago

packages/web/src/content/docs/config.mdx

@@ -175,7 +175,7 @@ Available options:
 - `scroll_speed` - Custom scroll speed multiplier (default: `3`, minimum: `1`). Ignored if `scroll_acceleration.enabled` is `true`.
 - `diff_style` - Control diff rendering. `"auto"` adapts to terminal width, `"stacked"` always shows single column.
 
-Note: If you submit a prompt while the session is already running, Zee will steer (interrupt) the active run.
+Note: While a session is running, `Enter` steers the active turn and `Tab` queues a message for the next turn.
 
 [Learn more about using the TUI here](/docs/tui).
 

packages/web/src/content/docs/keybinds.mdx

@@ -130,6 +130,15 @@ You can disable a keybind by adding the key to your config with a value of "none
 
 ---
 
+## Busy submit behavior
+
+When a session is running:
+
+- `Enter` steers the active turn immediately.
+- `Tab` queues your message to run after the current turn.
+
+---
+
 ## Desktop prompt shortcuts
 
 The OpenCode desktop app prompt input supports common Readline/Emacs-style shortcuts for editing text. These are built-in and currently not configurable via `opencode.json`.

packages/zee/src/cli/cmd/tui/component/prompt/busy-submit.ts

@@ -1,15 +1,22 @@
 export type BusySubmitDecision =
   | { submit: "prompt" }
   | { submit: "steer" }
+  | { submit: "queue" }
 
 export function decideBusySubmit(input: {
   sessionIsBusy: boolean
   hasSessionID: boolean
+  hasActiveTurn: boolean
+  trigger: "enter" | "tab"
 }): BusySubmitDecision {
   if (!input.sessionIsBusy) return { submit: "prompt" }
 
   // No active session to steer against (new session flow).
   if (!input.hasSessionID) return { submit: "prompt" }
 
+  // Session is busy, but no active assistant turn is steerable yet.
+  if (!input.hasActiveTurn) return { submit: "queue" }
+
+  if (input.trigger === "tab") return { submit: "queue" }
   return { submit: "steer" }
 }

packages/zee/src/cli/cmd/tui/component/prompt/index.tsx

@@ -69,6 +69,8 @@ export type PromptRef = {
   submit(): void
 }
 
+type SubmitTrigger = "enter" | "tab"
+
 
 function resolveHoldKeyNames(bindings: Keybind.Info[] | undefined): Set<string> {
   const names = new Set<string>()
@@ -99,26 +101,9 @@ export function Prompt(props: PromptProps) {
   const safeLayoutWidth = createMemo(() => Math.max(0, layoutWidth()))
   const borderFill = createMemo(() => "─".repeat(safeLayoutWidth()))
   const status = createMemo(() => sync.data.session_status?.[props.sessionID ?? ""] ?? { type: "idle" })
-  // Extended type to include new fields until SDK is regenerated
-  type StreamHealthExtended = {
-    isStalled: boolean
-    isThinking?: boolean
-    timeSinceLastEventMs: number
-    timeSinceContentMs?: number
-    eventsReceived: number
-    stallWarnings: number
-    phase?: "starting" | "thinking" | "tool_calling" | "generating"
-    charsReceived?: number
-    estimatedTokens?: number
-    requestCount?: number
-    embeddingConfig?: {
-      model: string
-      maxContext: number
-    }
-  }
-  const streamHealth = createMemo((): StreamHealthExtended | undefined => {
+  const streamHealth = createMemo(() => {
     const s = status()
-    return s.type === "busy" ? (s.streamHealth as StreamHealthExtended | undefined) : undefined
+    return s.type === "busy" ? s.streamHealth : undefined
   })
   // Session for token counter
   const session = createMemo(() => props.sessionID ? sync.session.get(props.sessionID) : undefined)
@@ -674,7 +659,7 @@ export function Prompt(props: PromptProps) {
       insertDictationText(transcript)
       setDictationState("idle")
       if (config.autoSubmit) {
-        setTimeout(() => submit(), 0)
+        setTimeout(() => submit("enter"), 0)
       }
     } catch (error) {
       toast.show({
@@ -1227,7 +1212,7 @@ export function Prompt(props: PromptProps) {
       setStore("extmarkToPartIndex", new Map())
     },
     submit() {
-      submit()
+      submit("enter")
     },
   }
 
@@ -1392,7 +1377,7 @@ export function Prompt(props: PromptProps) {
     },
   ])
 
-  async function submit() {
+  async function submit(trigger: SubmitTrigger = "enter") {
     if (props.disabled) return
     if (autocomplete?.visible) return
     if (!store.prompt.input) return
@@ -1477,9 +1462,13 @@ export function Prompt(props: PromptProps) {
     // Capture mode before it gets reset
     const currentMode = store.mode
     const variant = local.model.variant.current()
+    const sessionStatus = status()
+    const activeTurnID = sessionStatus.type === "busy" ? sessionStatus.activeTurnID : undefined
     const busyDecision = decideBusySubmit({
-      sessionIsBusy: status().type !== "idle",
+      sessionIsBusy: sessionStatus.type !== "idle",
       hasSessionID: Boolean(props.sessionID),
+      hasActiveTurn: Boolean(activeTurnID),
+      trigger,
     })
 
     // Tool permissions based on mode
@@ -1617,9 +1606,41 @@ export function Prompt(props: PromptProps) {
         ],
       } satisfies Parameters<typeof sdk.client.session.prompt>[0]
 
+      const queuePrompt = async () => {
+        try {
+          await sdk.client.session.prompt(
+            {
+              ...promptPayload,
+              noReply: true,
+            },
+            { throwOnError: true },
+          )
+          toast.show({
+            message: "Message queued.",
+            variant: "info",
+            duration: 2000,
+          })
+        } catch (error) {
+          restoreInput()
+          toast.show({
+            message: `Failed to queue message: ${formatSubmitError(error)}`,
+            variant: "error",
+            duration: 7000,
+          })
+        }
+      }
+
       if (busyDecision.submit === "steer") {
+        if (!activeTurnID) {
+          await queuePrompt()
+          return
+        }
         try {
-          await sdk.client.session.steer(promptPayload, { throwOnError: true })
+          const steerPayload = {
+            ...promptPayload,
+            expectedTurnID: activeTurnID,
+          } satisfies Parameters<typeof sdk.client.session.steer>[0]
+          await sdk.client.session.steer(steerPayload, { throwOnError: true })
           toast.show({
             message: "Steering message sent.",
             variant: "info",
@@ -1636,6 +1657,11 @@ export function Prompt(props: PromptProps) {
         return
       }
 
+      if (busyDecision.submit === "queue") {
+        await queuePrompt()
+        return
+      }
+
       try {
         await sdk.client.session.prompt(promptPayload, { throwOnError: true })
       } catch (error) {
@@ -2054,6 +2080,20 @@ export function Prompt(props: PromptProps) {
                 }
                 if (store.mode === "normal") autocomplete.onKeyDown(e)
                 if (!autocomplete.visible) {
+                  if (
+                    e.name === "tab" &&
+                    !e.ctrl &&
+                    !e.meta &&
+                    !e.shift &&
+                    !keybind.leader &&
+                    store.mode !== "shell" &&
+                    !input.plainText.trimStart().startsWith("!")
+                  ) {
+                    e.preventDefault()
+                    await submit("tab")
+                    return
+                  }
+
                   if (
                     (keybind.match("history_previous", e) && input.cursorOffset === 0) ||
                     (keybind.match("history_next", e) && input.cursorOffset === input.plainText.length)
@@ -2078,7 +2118,7 @@ export function Prompt(props: PromptProps) {
                     input.cursorOffset = input.plainText.length
                 }
               }}
-              onSubmit={submit}
+              onSubmit={() => submit("enter")}
               onPaste={async (event: PasteEvent) => {
                 if (props.disabled) {
                   event.preventDefault()

packages/zee/src/gateway/embedded-gateway.ts

@@ -28,10 +28,10 @@ async function resolvePersonaGateway() {
   _resolveAttempted = true
   try {
     const [configMod, authMod, serverMod, lockMod] = await Promise.all([
-      importUnchecked("../../Swabble/src/config/config"),
-      importUnchecked("../../Swabble/src/gateway/auth"),
-      importUnchecked("../../Swabble/src/gateway/server"),
-      importUnchecked("../../Swabble/src/infra/gateway-lock"),
+      importUnchecked("../../../Swabble/src/config/config"),
+      importUnchecked("../../../Swabble/src/gateway/auth"),
+      importUnchecked("../../../Swabble/src/gateway/server"),
+      importUnchecked("../../../Swabble/src/infra/gateway-lock"),
     ])
     _resolved = {
       loadConfig: configMod.loadConfig,

packages/zee/src/mcp/index.ts

@@ -460,6 +460,18 @@ export namespace MCP {
     })
   }
 
+  function resolveRuntimeMcpConfig(name: string, config: McpConfigMap): Config.Mcp | undefined {
+    const fromConfig = resolveMcpConfigEntry(name, config[name])
+    if (fromConfig) return fromConfig
+
+    const persona = (personaServers as Record<string, PersonaServerConfig>)[name]
+    if (!persona) return undefined
+    return forceMcpEnabled(name, {
+      type: persona.type,
+      command: Array.from(persona.command),
+    })
+  }
+
   function isLocalServer(name: string, config: McpConfigMap): boolean {
     const configured = resolveMcpConfigEntry(name, config[name])
     if (configured) return configured.type === "local"
@@ -1014,16 +1026,10 @@ export namespace MCP {
     // Use mutex to prevent concurrent state mutations for the same server
     return withServerMutex(name, async () => {
       const cfg = await Config.get()
-      const config = cfg.mcp ?? {}
-      const mcp = config[name]
-      if (!mcp) {
-        log.error("MCP config not found", { name })
-        return
-      }
-
-      const resolved = resolveMcpConfigEntry(name, mcp)
+      const config: McpConfigMap = (cfg.mcp ?? {}) as McpConfigMap
+      const resolved = resolveRuntimeMcpConfig(name, config)
       if (!resolved) {
-        log.error("Ignoring MCP connect request for config without type", { name })
+        log.error("MCP config not found", { name })
         return
       }
 
@@ -1103,19 +1109,13 @@ export namespace MCP {
     // Use mutex to prevent concurrent state mutations for the same server
     return withServerMutex(name, async () => {
       const cfg = await Config.get()
-      const mcpConfig = cfg.mcp?.[name]
-
-      if (!mcpConfig) {
+      const config: McpConfigMap = (cfg.mcp ?? {}) as McpConfigMap
+      const resolved = resolveRuntimeMcpConfig(name, config)
+      if (!resolved) {
         log.error("MCP config not found for reconnect", { name })
         return { status: "failed", error: "MCP config not found" }
       }
 
-      const resolved = resolveMcpConfigEntry(name, mcpConfig)
-      if (!resolved) {
-        log.error("MCP config invalid for reconnect", { name })
-        return { status: "failed", error: "Invalid MCP configuration" }
-      }
-
       // Close existing client if any
       const s = await state()
       const existingClient = s.clients[name]

packages/zee/src/pkg/sdk/gen/types.gen.ts

@@ -472,6 +472,7 @@ export type SessionStatus =
     }
   | {
       type: "busy"
+      activeTurnID?: string
       streamHealth?: {
         isStalled: boolean
         isThinking?: boolean
@@ -481,6 +482,12 @@ export type SessionStatus =
         stallWarnings: number
         phase?: "starting" | "thinking" | "tool_calling" | "generating"
         charsReceived?: number
+        estimatedTokens?: number
+        requestCount?: number
+        embeddingConfig?: {
+          model: string
+          maxContext: number
+        }
       }
     }
 

packages/zee/src/pkg/sdk/v2/client.ts

@@ -441,30 +441,14 @@ class ExtendedSession extends GeneratedSession {
     })
   }
 
-  // Steer a running session by injecting a user message at the next tool-call boundary
-  steer<ThrowOnError extends boolean = false>(
-    parameters: {
-      sessionID: string
-      parts: Array<{ id?: string; type: "text"; text: string } | { id?: string; type: string; [key: string]: any }>
-      model?: { providerID: string; modelID: string }
-      agent?: string
-      variant?: string
-      tools?: { [key: string]: boolean }
-      options?: { [key: string]: unknown }
-      directory?: string
-    },
+  // Steer a running session by injecting a user message into the active turn.
+  // expectedTurnID must match the current active turn.
+  override steer<ThrowOnError extends boolean = false>(
+    parameters: Parameters<GeneratedSession["steer"]>[0] & { directory?: string },
     options?: Options<never, ThrowOnError>
   ) {
-    const { directory: _, sessionID, ...body } = parameters
-    return (options?.client ?? this.client).post<void, unknown, ThrowOnError>({
-      url: `/session/${sessionID}/steer`,
-      body,
-      ...options,
-      headers: {
-        "Content-Type": "application/json",
-        ...options?.headers,
-      },
-    })
+    const { directory: _, ...rest } = parameters
+    return super.steer<ThrowOnError>(rest as Parameters<GeneratedSession["steer"]>[0], options)
   }
 }