diff --git a/android/app/src/main/java/net/awan/pipelines/data/protocol/Chat.kt b/android/app/src/main/java/net/awan/pipelines/data/protocol/Chat.kt index b4d84acd..b912191f 100644 --- a/android/app/src/main/java/net/awan/pipelines/data/protocol/Chat.kt +++ b/android/app/src/main/java/net/awan/pipelines/data/protocol/Chat.kt @@ -165,11 +165,31 @@ data class ChatEventFrame( val part: ChatPart? = null, val step: ChatStep? = null, val usage: ChatUsage? = null, + // The payload of a `shell` frame: the lifecycle of one shell the agent + // started. Nil on every other kind. A shell carries no message id, because a + // background process outlives the tool call (and the turn) that started it. + val shell: ChatShell? = null, // The sending device's label on a `user` frame (another client's prompt), so // the transcript can say who sent it. Empty on the agent's own frames. val client: String = "", ) +/** + * The state of one shell command the agent started, mirroring + * `internal/protocol/chat.go`'s ChatShell. [id] is stable across the created and + * exited frames so a running process is keyed by it; [status] is one of + * [ChatProtocol.SHELL_RUNNING]/[ChatProtocol.SHELL_EXITED]; [command] is the + * command line the shell was given (present on the created frame); [exit] is the + * process exit code and is non-null only once the shell has exited. + */ +@Serializable +data class ChatShell( + val id: String = "", + val status: String = "", + val command: String = "", + val exit: Int? = null, +) + @Serializable data class ChatStep( val status: String = "", @@ -242,6 +262,16 @@ object ChatProtocol { const val EVENT_STEP = "step" const val EVENT_USAGE = "usage" + /** + * The lifecycle of one shell the agent started. It carries a [ChatShell], + * no message id and no [ChatPart]: a background process can outlive the turn + * that started it, so it is a frame of its own and never a tool part. + */ + const val EVENT_SHELL = "shell" + + const val SHELL_RUNNING = "running" + const val SHELL_EXITED = "exited" + /** * A prompt another client sent, echoed live to this client so it appears in * the transcript attributed to the sending device. The sender never receives diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatConversationPane.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatConversationPane.kt index 9789c597..beafb699 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatConversationPane.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatConversationPane.kt @@ -215,7 +215,8 @@ internal fun ChatConversationPane( message = thread.error, onRetry = { vm.loadChatHistory(thread.sessionId) }, ) - thread.messages.isEmpty() && thread.notices.isEmpty() && !thread.running && approval == null -> + thread.messages.isEmpty() && thread.notices.isEmpty() && !thread.running && + approval == null && thread.runningShells.isEmpty() -> EmptyState( message = "This chat has no messages yet. Ask something below.", ) @@ -237,6 +238,13 @@ internal fun ChatConversationPane( ) } } + // The background processes still running, shown whether or not a turn + // is: a shell can outlive the turn that started it, so this is a strip + // of its own rather than part of the turn indicator, and it clears the + // moment each shell exits. + if (thread.runningShells.isNotEmpty()) { + BackgroundProcessBar(thread.runningShells) + } if (thread.error != null && thread.loaded) { Text( text = thread.error, diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatFormat.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatFormat.kt index 1df0166c..d4edd4c1 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatFormat.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatFormat.kt @@ -10,6 +10,7 @@ import net.awan.pipelines.data.protocol.ChatPermissionFrame import net.awan.pipelines.data.protocol.ChatMessage import net.awan.pipelines.data.protocol.ChatProtocol import net.awan.pipelines.data.protocol.ChatSession +import net.awan.pipelines.data.protocol.ChatShell import net.awan.pipelines.data.protocol.ChatToolState import net.awan.pipelines.ui.humanBytes @@ -157,6 +158,76 @@ internal const val TOOL_LONG_RUNNING_MILLIS: Long = 60_000L /** Whether a running call has been going long enough to be marked as unusual. */ internal fun toolLongRunning(elapsedMillis: Long): Boolean = elapsedMillis >= TOOL_LONG_RUNNING_MILLIS +/** + * How recently a text or reasoning delta must have arrived for a turn to read as + * still thinking. Long enough that the once-a-second tick the indicator runs on + * cannot flicker between thinking and waiting on a steady stream, short enough + * that a stalled turn starts reading as waiting while the operator still wonders. + */ +internal const val TURN_THINKING_WINDOW_MILLIS: Long = 2_500L + +/** + * What an in-flight turn is actually doing, from evidence already on the wire. + * It is the one derivation the running indicator and its unit test share, so the + * headline never disagrees with the tool lines under it: + * + * - [THINKING] while text or reasoning deltas are still arriving (within + * [TURN_THINKING_WINDOW_MILLIS] of the last one); + * - [TOOL] while one or more tool calls are in flight, which the indicator names + * separately; + * - [WAITING] otherwise — the turn is running but nothing is arriving and no + * tool is running, for example while the model is awaited between steps. + * + * No percentage, ETA or progress is ever invented: the only inputs are the calls + * the stream reported and the time since the last delta. + */ +internal enum class TurnPhase { THINKING, TOOL, WAITING } + +/** + * The [TurnPhase] of a turn in flight. [runningTools] are the calls the stream + * reports as still running; [silentMillis] is how long ago the last text or + * reasoning delta arrived, or null when none has (a turn that has not streamed + * yet reads as waiting rather than inventing thinking). + */ +internal fun turnPhase(runningTools: List, silentMillis: Long?): TurnPhase = when { + runningTools.isNotEmpty() -> TurnPhase.TOOL + silentMillis != null && silentMillis in 0 until TURN_THINKING_WINDOW_MILLIS -> TurnPhase.THINKING + else -> TurnPhase.WAITING +} + +/** The running indicator's headline for [phase], naming what is happening. */ +internal fun turnPhaseLabel(phase: TurnPhase): String = when (phase) { + TurnPhase.THINKING -> "Thinking…" + TurnPhase.TOOL -> "Running a tool…" + TurnPhase.WAITING -> "Waiting…" +} + +/** + * The background processes still running for a session, in the order they + * started, from the shells the server reported and the session retains. A shell + * that has exited is never listed — that is what clears the indicator — and the + * set is independent of the turn, because a background process outlives the tool + * call (and often the turn) that started it. + */ +internal fun runningBackgroundShells(shells: Map): List = + shells.values.filter { it.id.isNotBlank() && it.status == ChatProtocol.SHELL_RUNNING } + +/** + * The one-line command a background process is running, collapsed to a single + * line and elided past [TOOL_DETAIL_MAX_LENGTH] like a tool call's detail, so a + * long command line cannot flood the indicator. A shell that reported no command + * reads as a generic `background process` rather than a blank line. + */ +internal fun shellCommandSummary(command: String): String { + val text = command.trim().replace(TOOL_DETAIL_WHITESPACE, " ") + if (text.isEmpty()) return "background process" + return if (text.length <= TOOL_DETAIL_MAX_LENGTH) { + text + } else { + text.take(TOOL_DETAIL_MAX_LENGTH - 1).trimEnd() + "…" + } +} + /** * The running-tool start stamps after a thread's [messages] changed: every tool * part in flight keeps the stamp it already had, or is stamped with [now] when it diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatStore.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatStore.kt index 7b109b34..8a53ea64 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatStore.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatStore.kt @@ -9,6 +9,7 @@ import net.awan.pipelines.data.protocol.ChatPart import net.awan.pipelines.data.protocol.ChatPermissionFrame import net.awan.pipelines.data.protocol.ChatProtocol import net.awan.pipelines.data.protocol.ChatSession +import net.awan.pipelines.data.protocol.ChatShell /** * A saved scroll position inside one conversation. Kept as Android-free @@ -99,6 +100,23 @@ data class ChatThread( * [runningSince] does for the turn. */ val toolStartedAt: Map = emptyMap(), + /** + * Wall-clock epoch millis the last text or reasoning delta of the in-flight + * turn arrived, or 0 when none has. Kept on the thread so the running + * indicator can tell "thinking" (deltas still arriving) from "waiting" + * (nothing arriving) without guessing, and so it survives a chat switch like + * [runningSince]. Cleared the moment the turn settles. + */ + val lastDeltaAt: Long = 0, + /** + * The agent's shell commands still running for this session, keyed by the + * shell id the server reported and in the order they started. A background + * process can outlive the tool call (and the turn) that started it, so this is + * thread state of its own rather than part of the turn: it keeps showing after + * the turn's indicator has gone, and a shell leaves the map the moment its + * exited frame arrives. Kept on the thread so it survives a chat switch. + */ + val shells: Map = emptyMap(), /** The unsent composer text for this chat. */ val draft: String = "", /** @@ -175,6 +193,20 @@ data class ChatThread( */ fun toolElapsedMillis(part: ChatPart, nowMillis: Long): Long = runningToolElapsedMillis(part, toolStartedAt[part.id] ?: 0L, nowMillis) + + /** + * The background processes this session is still running, in start order, so + * a conversation shows what is running even when no turn is. + */ + val runningShells: List get() = runningBackgroundShells(shells) + + /** + * What the in-flight turn is doing at [nowMillis] (see [turnPhase]): its + * running tool calls, and how long ago the last delta arrived. Pure, so the + * indicator and its unit test share the one derivation. + */ + internal fun phase(nowMillis: Long): TurnPhase = + turnPhase(runningTools, lastDeltaAt.takeIf { it in 1 until nowMillis }?.let { nowMillis - it }) } /** @@ -777,7 +809,14 @@ class ChatStore( if (ids.isEmpty()) return ids _state.value = _state.value.copy( open = _state.value.open.map { - if (it.running) it.copy(running = false, runningSince = 0, toolStartedAt = emptyMap()) else it + if (it.running || it.shells.isNotEmpty()) { + // A shell's exit may have been swallowed by the gap too, so the + // retained shells are dropped as well and re-learned from the + // re-subscribe's replay of the ones still running. + it.copy(running = false, runningSince = 0, toolStartedAt = emptyMap(), lastDeltaAt = 0, shells = emptyMap()) + } else { + it + } }, ) return ids @@ -887,6 +926,7 @@ class ChatStore( ChatProtocol.EVENT_USER -> applyRemoteUser(frame) ChatProtocol.PART_TEXT, ChatProtocol.PART_REASONING -> applyDelta(frame) ChatProtocol.PART_TOOL -> applyTool(frame) + ChatProtocol.EVENT_SHELL -> applyShell(frame) ChatProtocol.EVENT_STEP -> { val started = frame.step?.status != ChatProtocol.STEP_ENDED update(frame.sessionId) { setRunning(it, started) } @@ -895,6 +935,27 @@ class ChatStore( } } + /** + * Folds one shell frame: a running shell joins the thread's background + * processes, keyed by its id and kept in start order, and an exited one leaves + * — which is what clears the indicator the moment the shell exits. It never + * marks the thread running, because a background process is not the turn: a + * shell that outlives the turn keeps showing after the turn's own indicator + * has gone, which is the one state it exists to make visible. + */ + private fun applyShell(frame: ChatEventFrame) { + val shell = frame.shell ?: return + if (shell.id.isBlank()) return + update(frame.sessionId) { thread -> + val shells = if (shell.status == ChatProtocol.SHELL_EXITED) { + thread.shells - shell.id + } else { + thread.shells + (shell.id to shell) + } + if (shells == thread.shells) thread else thread.copy(shells = shells) + } + } + /** * Folds a user turn another client sent into the transcript, in place, once. * The server never echoes this client's own prompts, so the sender's own @@ -941,7 +1002,9 @@ class ChatStore( val rawId = frame.part?.id.orEmpty() if (rawId.isEmpty() || frame.delta.isEmpty()) return val kind = frame.kind - upsertParts(frame) { parts -> + // A delta just arrived, so the turn is thinking right now: stamp the + // arrival so the indicator can tell thinking from waiting. + upsertParts(frame, deltaArrivedAt = now()) { parts -> val id = deltaPartId(parts, kind, rawId) val index = parts.indexOfFirst { it.id == id } if (index < 0) { @@ -970,7 +1033,11 @@ class ChatStore( * parts with [upsert]'s result, then marks the thread running. The text and * reasoning delta fold and the tool upsert share this so the two cannot drift. */ - private fun upsertParts(frame: ChatEventFrame, upsert: (List) -> List) { + private fun upsertParts( + frame: ChatEventFrame, + deltaArrivedAt: Long? = null, + upsert: (List) -> List, + ) { update(frame.sessionId) { thread -> val messages = thread.messages.toMutableList() val index = messages.indexOfLast { it.id == frame.messageId } @@ -989,7 +1056,8 @@ class ChatStore( val message = messages[resolvedIndex] messages[resolvedIndex] = message.copy(parts = upsert(message.parts)) val stamped = runningToolStamps(thread.toolStartedAt, messages, now()) - setRunning(thread.copy(messages = messages, toolStartedAt = stamped), true) + val running = setRunning(thread.copy(messages = messages, toolStartedAt = stamped), true) + if (deltaArrivedAt == null) running else running.copy(lastDeltaAt = deltaArrivedAt) } } @@ -1002,7 +1070,7 @@ class ChatStore( private fun setRunning(thread: ChatThread, running: Boolean): ChatThread = when { running && !thread.running -> thread.copy(running = true, runningSince = now()) running -> thread - else -> thread.copy(running = false, runningSince = 0, toolStartedAt = emptyMap()) + else -> thread.copy(running = false, runningSince = 0, toolStartedAt = emptyMap(), lastDeltaAt = 0) } private fun update(sessionId: String, block: (ChatThread) -> ChatThread) { diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatTranscript.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatTranscript.kt index 0434bb23..1cd82743 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatTranscript.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatTranscript.kt @@ -23,6 +23,7 @@ import androidx.compose.material.icons.Icons import androidx.compose.material.icons.filled.Build import androidx.compose.material.icons.filled.KeyboardArrowDown import androidx.compose.material.icons.filled.KeyboardArrowUp +import androidx.compose.material.icons.filled.PlayArrow import androidx.compose.material.icons.filled.Psychology import androidx.compose.material3.CircularProgressIndicator import androidx.compose.material3.Icon @@ -56,6 +57,7 @@ import kotlinx.coroutines.launch import net.awan.pipelines.data.protocol.ChatMessage import net.awan.pipelines.data.protocol.ChatPart import net.awan.pipelines.data.protocol.ChatProtocol +import net.awan.pipelines.data.protocol.ChatShell import net.awan.pipelines.ui.formatDuration import net.awan.pipelines.ui.theme.CHAT_BUBBLE_MAX_WIDTH_DP import net.awan.pipelines.ui.theme.CHAT_FOLLOW_THRESHOLD_DP @@ -293,15 +295,16 @@ private fun LazyListState.bottomDistancePx(itemCount: Int): Int? { } /** - * The in-flight turn indicator: a spinner, `Working…` and the turn's live elapsed - * time, then one compact line for each tool call in flight — its name, the - * command or description the part carries, and how long that call has been - * running. The elapsed values are derived from the turn's own start - * ([ChatThread.elapsedMillis]) and each call's own start + * The in-flight turn indicator: a spinner, the turn's actual state (see + * [TurnPhase] — `Thinking…` while deltas arrive, `Running a tool…` while calls are + * in flight, `Waiting…` otherwise) and its live elapsed time, then one compact + * line for each tool call in flight — its name, the command or description the + * part carries, and how long that call has been running. The headline is derived + * from [ChatThread.phase] so the operator can tell generating from waiting on a + * command instead of watching a bare `Working…`; the elapsed values come from the + * turn's own start ([ChatThread.elapsedMillis]) and each call's own start * ([ChatThread.toolElapsedMillis]), so they keep counting across a chat switch, - * and the tick loop stops the moment the turn settles. This is what makes the - * otherwise-silent part of a turn legible: the operator can tell `working on X` - * from `waiting on something` instead of watching a bare `Running`. + * and the tick loop stops the moment the turn settles. */ @Composable private fun RunningIndicator(thread: ChatThread) { @@ -317,7 +320,7 @@ private fun RunningIndicator(thread: ChatThread) { horizontalArrangement = Arrangement.spacedBy(CHAT_ITEM_GAP), ) { CircularProgressIndicator(Modifier.size(16.dp), strokeWidth = 2.dp) - Text("Working…", style = MaterialTheme.typography.bodySmall, color = MaterialTheme.colorScheme.onSurfaceVariant) + Text(turnPhaseLabel(thread.phase(now)), style = MaterialTheme.typography.bodySmall, color = MaterialTheme.colorScheme.onSurfaceVariant) Text( text = "· ${formatDuration(elapsedMillis / 1_000)}", style = MaterialTheme.typography.bodySmall, @@ -382,6 +385,58 @@ private fun RunningToolLine(part: ChatPart, elapsedMillis: Long) { } } +/** + * The always-visible indicator that the agent has a background process running — + * a dev server, a watching build, a sleep whose tool call has already returned. + * It is deliberately separate from the turn's spinner: a background process can + * outlive the turn, so this is shown whenever a shell is running, whether or not + * a turn is, and each line names the command the way the running-tool line names + * a call. It clears the moment the shell exits, because the exited frame removes + * it from the thread's shells. It survives a chat switch like the other live + * state, since it is read from the thread rather than held here. + */ +@Composable +internal fun BackgroundProcessBar(shells: List, modifier: Modifier = Modifier) { + Column( + verticalArrangement = Arrangement.spacedBy(SPACING_XS), + modifier = modifier.fillMaxWidth().padding(horizontal = CHAT_GUTTER, vertical = 4.dp), + ) { + shells.forEach { shell -> + key(shell.id) { BackgroundProcessLine(shell) } + } + } +} + +/** One background process: a distinct glyph, a `Background process` label and its command. */ +@Composable +private fun BackgroundProcessLine(shell: ChatShell) { + Row( + verticalAlignment = Alignment.CenterVertically, + horizontalArrangement = Arrangement.spacedBy(CHAT_ITEM_GAP), + modifier = Modifier.fillMaxWidth(), + ) { + Icon( + Icons.Default.PlayArrow, + contentDescription = null, + tint = MaterialTheme.colorScheme.tertiary, + modifier = Modifier.size(ICON_STATUS_DP), + ) + Text( + text = "Background process", + style = MaterialTheme.typography.labelMedium, + color = MaterialTheme.colorScheme.tertiary, + ) + Text( + text = shellCommandSummary(shell.command), + style = MaterialTheme.typography.labelMedium, + color = MaterialTheme.colorScheme.onSurfaceVariant, + maxLines = 1, + overflow = TextOverflow.Ellipsis, + modifier = Modifier.weight(1f), + ) + } +} + /** * The wall clock, re-read once a second while a turn is in flight, so the * indicator derives the elapsed time with [ChatThread.elapsedMillis] — the one diff --git a/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatInFlightStateTest.kt b/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatInFlightStateTest.kt new file mode 100644 index 00000000..d3c21330 --- /dev/null +++ b/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatInFlightStateTest.kt @@ -0,0 +1,211 @@ +package net.awan.pipelines.ui.chat + +import net.awan.pipelines.data.protocol.ChatEventFrame +import net.awan.pipelines.data.protocol.ChatPart +import net.awan.pipelines.data.protocol.ChatProtocol +import net.awan.pipelines.data.protocol.ChatSession +import net.awan.pipelines.data.protocol.ChatShell +import net.awan.pipelines.data.protocol.ChatStep +import net.awan.pipelines.data.protocol.ChatToolState +import org.junit.Assert.assertEquals +import org.junit.Assert.assertFalse +import org.junit.Assert.assertTrue +import org.junit.Test + +/** + * The two in-flight states a conversation now names: what a running turn is + * actually doing (thinking, running a tool or waiting) and whether a background + * process is still running. Both are derived from evidence already on the wire + * (the tool calls and delta timing the stream reports, and the shell frames), so + * they are tested as pure folds and against [ChatStore] with an injected clock — + * no device, server or Compose runtime. + */ +class ChatInFlightStateTest { + + private fun tool(id: String, status: String) = ChatPart( + type = ChatProtocol.PART_TOOL, + id = id, + name = "shell", + state = ChatToolState(status = status), + ) + + private fun deltaFrame(sessionId: String, text: String = "hi") = ChatEventFrame( + sessionId = sessionId, + messageId = "m1", + kind = ChatProtocol.PART_TEXT, + delta = text, + part = ChatPart(type = ChatProtocol.PART_TEXT, id = "m1#text#0"), + ) + + private fun toolFrame(sessionId: String, part: ChatPart) = + ChatEventFrame(sessionId = sessionId, messageId = "m1", kind = ChatProtocol.PART_TOOL, part = part) + + private fun stepFrame(sessionId: String, status: String) = + ChatEventFrame(sessionId = sessionId, kind = ChatProtocol.EVENT_STEP, step = ChatStep(status = status)) + + private fun shellFrame( + sessionId: String, + id: String, + status: String, + command: String = "", + exit: Int? = null, + ) = ChatEventFrame( + sessionId = sessionId, + kind = ChatProtocol.EVENT_SHELL, + shell = ChatShell(id = id, status = status, command = command, exit = exit), + ) + + // ---- Part 1: the turn's phase -------------------------------------------- + + @Test + fun aToolInFlightOutranksThinking() { + // A running call is named separately by the tool lines, so it is the + // phase even while deltas are still arriving. + assertEquals(TurnPhase.TOOL, turnPhase(listOf(tool("c1", ChatProtocol.TOOL_RUNNING)), silentMillis = 100L)) + } + + @Test + fun aRecentDeltaReadsAsThinking() { + assertEquals(TurnPhase.THINKING, turnPhase(emptyList(), silentMillis = 0L)) + assertEquals(TurnPhase.THINKING, turnPhase(emptyList(), silentMillis = TURN_THINKING_WINDOW_MILLIS - 1)) + } + + @Test + fun silenceAndANeverStreamedTurnReadAsWaiting() { + // At the window boundary the turn has stopped arriving: waiting. + assertEquals(TurnPhase.WAITING, turnPhase(emptyList(), silentMillis = TURN_THINKING_WINDOW_MILLIS)) + assertEquals(TurnPhase.WAITING, turnPhase(emptyList(), silentMillis = 10_000L)) + // No delta has arrived at all: waiting, never an invented "thinking". + assertEquals(TurnPhase.WAITING, turnPhase(emptyList(), silentMillis = null)) + } + + @Test + fun thePhaseNamesItself() { + assertEquals("Thinking…", turnPhaseLabel(TurnPhase.THINKING)) + assertEquals("Running a tool…", turnPhaseLabel(TurnPhase.TOOL)) + assertEquals("Waiting…", turnPhaseLabel(TurnPhase.WAITING)) + } + + @Test + fun theStoreDerivesThinkingThenWaitingFromDeltaTiming() { + var clock = 1_000L + val store = ChatStore(now = { clock }) + store.open(ChatSession(id = "s", title = "s")) + + store.event(deltaFrame("s")) + val thread = store.value.thread("s")!! + // The delta arrived at 1_000; 500ms later the turn is still thinking. + assertEquals(TurnPhase.THINKING, thread.phase(1_500L)) + // Past the window with no new delta the same turn reads as waiting. + clock = 5_000L + assertEquals(TurnPhase.WAITING, store.value.thread("s")!!.phase(5_000L)) + } + + @Test + fun aToolFrameMakesTheTurnReadAsRunningATool() { + val store = ChatStore(now = { 1_000L }) + store.open(ChatSession(id = "s", title = "s")) + store.event(deltaFrame("s")) + store.event(toolFrame("s", tool("c1", ChatProtocol.TOOL_RUNNING))) + assertEquals(TurnPhase.TOOL, store.value.thread("s")!!.phase(1_100L)) + } + + @Test + fun aSettledTurnClearsTheDeltaStamp() { + val store = ChatStore(now = { 1_000L }) + store.open(ChatSession(id = "s", title = "s")) + store.event(deltaFrame("s")) + store.event(stepFrame("s", ChatProtocol.STEP_ENDED)) + val thread = store.value.thread("s")!! + assertFalse(thread.running) + assertEquals(0L, thread.lastDeltaAt) + } + + // ---- Part 2: the background process -------------------------------------- + + @Test + fun onlyRunningShellsAreListed() { + val shells = mapOf( + "sh_1" to ChatShell(id = "sh_1", status = ChatProtocol.SHELL_RUNNING, command = "npm run dev"), + "sh_2" to ChatShell(id = "sh_2", status = ChatProtocol.SHELL_EXITED, command = "ls", exit = 0), + ) + assertEquals(listOf("sh_1"), runningBackgroundShells(shells).map { it.id }) + } + + @Test + fun aCommandIsCollapsedElidedAndNeverBlank() { + assertEquals("npm run dev", shellCommandSummary(" npm run \n dev ")) + val long = shellCommandSummary("x".repeat(500)) + assertTrue(long.length < 500) + assertTrue(long.endsWith("…")) + assertEquals("background process", shellCommandSummary(" ")) + } + + @Test + fun aRunningShellIsShownAndClearedOnExit() { + val store = ChatStore(now = { 1_000L }) + store.open(ChatSession(id = "s", title = "s")) + store.event(shellFrame("s", "sh_1", ChatProtocol.SHELL_RUNNING, command = "npm run dev")) + + val running = store.value.thread("s")!!.runningShells + assertEquals(listOf("sh_1"), running.map { it.id }) + assertEquals("npm run dev", running.single().command) + + store.event(shellFrame("s", "sh_1", ChatProtocol.SHELL_EXITED, exit = 0)) + assertTrue(store.value.thread("s")!!.runningShells.isEmpty()) + } + + @Test + fun aBackgroundProcessOutlivesTheTurnItStartedIn() { + val store = ChatStore(now = { 1_000L }) + store.open(ChatSession(id = "s", title = "s")) + store.event(deltaFrame("s")) + store.event(shellFrame("s", "sh_1", ChatProtocol.SHELL_RUNNING, command = "sleep 120")) + assertTrue(store.value.thread("s")!!.running) + + // The turn settles while the shell keeps running: the spinner is gone but + // the background process is still shown rather than assumed finished. + store.event(stepFrame("s", ChatProtocol.STEP_ENDED)) + val settled = store.value.thread("s")!! + assertFalse(settled.running) + assertEquals(listOf("sh_1"), settled.runningShells.map { it.id }) + } + + @Test + fun aBackgroundProcessSurvivesAChatSwitch() { + val store = ChatStore(now = { 1_000L }) + store.open(ChatSession(id = "a", title = "a")) + store.event(shellFrame("a", "sh_1", ChatProtocol.SHELL_RUNNING, command = "npm run dev")) + store.open(ChatSession(id = "b", title = "b")) + store.activate("a") + assertEquals(listOf("sh_1"), store.value.thread("a")!!.runningShells.map { it.id }) + } + + @Test + fun theSameShellRepeatedDoesNotDuplicateAndAForeignOneIsKeyedApart() { + val store = ChatStore(now = { 1_000L }) + store.open(ChatSession(id = "s", title = "s")) + store.event(shellFrame("s", "sh_1", ChatProtocol.SHELL_RUNNING, command = "a")) + store.event(shellFrame("s", "sh_1", ChatProtocol.SHELL_RUNNING, command = "a")) + store.event(shellFrame("s", "sh_2", ChatProtocol.SHELL_RUNNING, command = "b")) + assertEquals(listOf("sh_1", "sh_2"), store.value.thread("s")!!.runningShells.map { it.id }) + } + + @Test + fun aShellFrameWithNoIdentityIsIgnored() { + val store = ChatStore(now = { 1_000L }) + store.open(ChatSession(id = "s", title = "s")) + store.event(ChatEventFrame(sessionId = "s", kind = ChatProtocol.EVENT_SHELL, shell = null)) + store.event(shellFrame("s", "", ChatProtocol.SHELL_RUNNING, command = "x")) + assertTrue(store.value.thread("s")!!.runningShells.isEmpty()) + } + + @Test + fun resumingClearsShellsSoTheReplayCanResyncThem() { + val store = ChatStore(now = { 1_000L }) + store.open(ChatSession(id = "s", title = "s")) + store.event(shellFrame("s", "sh_1", ChatProtocol.SHELL_RUNNING, command = "npm run dev")) + assertEquals(listOf("s"), store.streamResumed()) + assertTrue(store.value.thread("s")!!.runningShells.isEmpty()) + } +} diff --git a/docs/notes/chat-shell-background-process.md b/docs/notes/chat-shell-background-process.md new file mode 100644 index 00000000..f56a813a --- /dev/null +++ b/docs/notes/chat-shell-background-process.md @@ -0,0 +1,98 @@ +# Chat: an honest in-flight state and background processes + +## What this item changed + +Both areas, the chat's in-flight feedback. + +**Server (`internal/`).** + +- `protocol/chat.go` adds the `shell` frame kind (`ChatEventShell`), the + `ChatShell` payload (`id`, `status`, `command`, optional `exit` — a pointer so + exit `0` is not "absent"), the `ChatShellRunning`/`ChatShellExited` statuses and + the `ChatEventFrame.shell` field. +- `opencode/chat.go` maps the location-scoped `shell.created`/`shell.exited` + firehose events onto that frame. A shell belongs to the session that started it + only through `data.info.metadata.sessionID` (the agent's shell tool sets it); + the exit event carries no session at all, so it is emitted only for a shell id + the stream already surfaced. Another session's shell, and a shell with no + attributed session, are ignored; a shell event with no id fails the stream. + `NormalizeChatEvent` now folds a `ChatStreamState` (the retained last message id + plus the session's running shell ids) across frames instead of a bare + `*string`. +- `server/chat_hub.go` retains each session's still-running shells (bounded by + `chatShellLimit` and the per-session byte cap) and clears them on exit; + `server/chat_stream.go` replays them on `chat_subscribe`, the shell half of the + resume (the message snapshot cannot carry a shell, because a shell is not a + turn). + +**App (`android/`).** + +- `data/protocol/Chat.kt` adds `ChatShell`, `ChatEventFrame.shell`, `EVENT_SHELL`, + `SHELL_RUNNING`/`SHELL_EXITED`. +- `ui/chat/ChatFormat.kt` adds the one pure derivation of a running turn's phase + (`TurnPhase` + `turnPhase` + `turnPhaseLabel` + `TURN_THINKING_WINDOW_MILLIS`) + and of the background processes (`runningBackgroundShells`, + `shellCommandSummary`). +- `ui/chat/ChatStore.kt`: `ChatThread.lastDeltaAt` (stamped on every text/reasoning + delta, cleared when the turn settles) and `ChatThread.shells` (a shell joins on + its running frame and leaves on its exited frame, never marking the thread + running); `thread.phase(now)` and `thread.runningShells`; `streamResumed` drops + shells so the subscribe replay re-syncs the ones still running. +- `ui/chat/ChatTranscript.kt`: `RunningIndicator`'s headline is the phase label + (was the bare `Working…`); a new `BackgroundProcessBar` names each running + shell. +- `ui/chat/ChatConversationPane.kt` shows the bar whenever a shell is running, + whether or not a turn is. + +No percentage, ETA or progress bar is invented on either side. + +## Shared documents this change makes stale + +`docs/cli.md` and `android/README.md`. The note is written here rather than edited +in place; the `docs-fold` writer should update them. + +- `docs/cli.md`, the `chat_subscribe` bullet ("`chat_subscribe` attaches a + connection to one session's shared live stream (body `session_id`) and replays + the session's still-pending approval requests…") is now incomplete: attaching + also replays the session's still-running shell commands as `chat_event` frames + of the new kind `shell`, so a device that attaches after a background process + started is shown it. +- `docs/cli.md`, the chat-protocol type list, should name the new `chat_event` + kind `shell`: its payload carries the shell's `id`, `status` + (`running`/`exited`), the `command` it is running and, once it has exited, its + `exit` code. It carries no message id, because a background process outlives the + turn that started it. +- `android/README.md:4719` — the **Running indicator** bullet reads "The + transcript's indicator shows the spinner, `Working…` and the live elapsed + time…". It should say the headline is the turn's actual state — `Thinking…` + while text/reasoning deltas are still arriving, `Running a tool…` while calls + are in flight, `Waiting…` otherwise — derived purely from the tool calls and the + time since the last delta, never an invented percentage/ETA (the one-second + tick, the elapsed living on the thread, and the tool lines below it are still + true). +- `android/README.md` should also record the new always-visible background-process + strip: whenever a shell the agent started is still running it names the + command, it is independent of the turn (a background process can outlive the + turn and is shown then), it survives a chat switch, and it clears the moment the + shell exits. + +Dates, counts and capture names in the dated README records are past evidence and +stay as they are; only the behaviour statements above are now stale. + +## Not stale + +- No packaged OpenCode skill reference documents either surface. The chat + references in `internal/author/skill/references/` document the server's + brokered `chat_*` protocol at a level this change extends additively; nothing + there names the frame kinds or the app indicator. +- `android/AGENTS.md` and `internal/server/AGENTS.md` already list the files + touched, so they need no change. + +## Not verified live + +The end-to-end behaviour on the operator's phone against a **changed** server was +not captured: the deployed server (`0.0.0.0:8080`) predates the shell mapping, and +redeploying it is forbidden while runs are in flight. The shell mapping itself was +checked against the installed OpenCode 2.0.20 service's own event stream (a +`shell.created` carries `metadata.sessionID`, a `shell.exited` carries only +`id`/`exit`/`status`); the app path is covered by unit tests only. diff --git a/internal/opencode/chat.go b/internal/opencode/chat.go index eda1ec3a..40adc005 100644 --- a/internal/opencode/chat.go +++ b/internal/opencode/chat.go @@ -325,7 +325,7 @@ func (c *Chat) Stream(ctx context.Context, id string, ready func(), emit func(pr func scanChatEvents(ctx context.Context, body io.Reader, sessionID string, emit func(protocol.ChatEventFrame) error) error { scanner := bufio.NewScanner(body) scanner.Buffer(make([]byte, 0, 64<<10), MaxResponse) - lastMessageID := "" + state := &ChatStreamState{} for scanner.Scan() { if err := ctx.Err(); err != nil { return err @@ -338,7 +338,7 @@ func scanChatEvents(ctx context.Context, body io.Reader, sessionID string, emit if len(payload) == 0 { continue } - frame, ok, err := NormalizeChatEvent(payload, sessionID, &lastMessageID) + frame, ok, err := NormalizeChatEvent(payload, sessionID, state) if err != nil { return err } @@ -346,7 +346,7 @@ func scanChatEvents(ctx context.Context, body io.Reader, sessionID string, emit continue } if frame.MessageID != "" { - lastMessageID = frame.MessageID + state.LastMessageID = frame.MessageID } if err := emit(frame); err != nil { return err @@ -372,7 +372,8 @@ func isChatEventType(t string) bool { "session.usage.updated", "session.tool.input.started", "session.tool.input.ended", "session.tool.called", "session.tool.progress", - "session.tool.success", "session.tool.failed": + "session.tool.success", "session.tool.failed", + "shell.created", "shell.exited": return true } return false @@ -403,13 +404,92 @@ type chatEvent struct { Input int `json:"input"` Output int `json:"output"` } `json:"tokens"` + // The shell family. shell.created nests the started command under info; + // shell.exited carries the id, the final status and the exit code at the top + // level. Exit is a pointer so an exit of 0 is distinguishable from absent. + Status string `json:"status"` + Exit *int `json:"exit"` + Info *chatShellInfo `json:"info"` +} + +// chatShellInfo is the Shell.Info envelope a shell.created event nests under +// "info". The session that started the shell is reported in metadata.sessionID +// (the agent's shell tool sets it); only the fields the protocol surfaces are +// read, and the shell's cwd/file are deliberately not carried so no path or +// credential leaks into a frame. +type chatShellInfo struct { + ID string `json:"id"` + Status string `json:"status"` + Command string `json:"command"` + Metadata map[string]any `json:"metadata"` +} + +// shellSessionID reads the session that started a shell from the created event's +// metadata, or "" when the event carries none. The agent's shell tool sets +// metadata.sessionID; a shell started by anything else is unattributed and is +// ignored, so a shell that cannot be shown to belong to this session never +// becomes one of its frames. +func (i *chatShellInfo) shellSessionID() string { + if i == nil || i.Metadata == nil { + return "" + } + id, _ := i.Metadata["sessionID"].(string) + return id +} + +// ChatStreamState is the per-session memory one event stream folds across its +// frames, so a frame that omits context can still be attributed. It is the +// single state NormalizeChatEvent reads and writes; a caller that maps a lone +// event passes an empty state (or nil when it needs no attribution). +// +// - LastMessageID is the most recent assistant message id, so a later tool or +// step event that omits it still attributes every frame to a stable message. +// - Shells holds the ids of the shells this session has started and not yet +// seen exit. shell.exited carries no session id, so the id remembered here is +// what attributes the exit to its session: another session's shell is an +// unknown id and is ignored. +type ChatStreamState struct { + LastMessageID string + Shells map[string]struct{} +} + +// knowsShell reports whether id is a shell this stream has already surfaced for +// the session, and so is one this stream may now report the exit of. +func (s *ChatStreamState) knowsShell(id string) bool { + if s == nil || id == "" { + return false + } + _, ok := s.Shells[id] + return ok +} + +// markShell remembers id as a shell of this session. +func (s *ChatStreamState) markShell(id string) { + if s == nil || id == "" { + return + } + if s.Shells == nil { + s.Shells = map[string]struct{}{} + } + s.Shells[id] = struct{}{} +} + +// forgetShell drops id once its exit has been surfaced. +func (s *ChatStreamState) forgetShell(id string) { + if s == nil || s.Shells == nil { + return + } + delete(s.Shells, id) } // NormalizeChatEvent maps one OpenCode firehose `data:` payload to a -// protocol.ChatEventFrame. ok is false for an event type this adapter does not +// protocol.ChatEventFrame, folding the small per-session context ([stream]) it +// needs across frames. ok is false for an event type this adapter does not // surface or one belonging to a different session, so the caller can skip it // without emitting a frame. Malformed JSON returns an error and never a frame. -func NormalizeChatEvent(payload []byte, sessionID string, lastMessageID *string) (protocol.ChatEventFrame, bool, error) { +// stream may be nil when the caller maps a lone event and needs no attribution; +// a nil stream simply means no inherited message id and no remembered shell. +func NormalizeChatEvent(payload []byte, sessionID string, stream *ChatStreamState) (protocol.ChatEventFrame, bool, error) { var outer struct { Type string `json:"type"` Data json.RawMessage `json:"data"` @@ -432,6 +512,14 @@ func NormalizeChatEvent(payload []byte, sessionID string, lastMessageID *string) if err := json.Unmarshal(outer.Data, &data); err != nil { return protocol.ChatEventFrame{}, false, fmt.Errorf("malformed OpenCode event data: %w", err) } + // The shell events are location-scoped, not session-scoped: the session that + // started a shell is reported in the created event's metadata, and the exit + // names no session at all, so it is attributed through the ids this stream + // already surfaced. They are mapped before the session check the other events + // use, which their absent data.sessionID could never pass. + if outer.Type == "shell.created" || outer.Type == "shell.exited" { + return normalizeShellEvent(outer.Type, data, sessionID, stream) + } if data.SessionID != sessionID { return protocol.ChatEventFrame{}, false, nil } @@ -439,8 +527,8 @@ func NormalizeChatEvent(payload []byte, sessionID string, lastMessageID *string) if messageID == "" { messageID = data.MessageIDAlt } - if messageID == "" && lastMessageID != nil { - messageID = *lastMessageID + if messageID == "" && stream != nil { + messageID = stream.LastMessageID } // Every pushed frame must carry a stable message id so the client can // attribute it; without one this is not a chat frame. @@ -481,6 +569,52 @@ func NormalizeChatEvent(payload []byte, sessionID string, lastMessageID *string) return frame, true, nil } +// normalizeShellEvent maps one shell.created/shell.exited payload onto a +// protocol.ChatEventShell frame. A shell belongs to the session whose id the +// created event carries in info.metadata.sessionID, so a shell started by any +// other session is ignored (ok=false) rather than shown in this session. The +// exit event carries no session at all, so it is emitted only for a shell id +// this stream already surfaced for the session; any other id is another +// session's and is ignored. An event that carries no shell id at all cannot be +// keyed by the client and is malformed, so it fails the stream instead of +// producing a frame the client cannot attribute. +func normalizeShellEvent(eventType string, data chatEvent, sessionID string, stream *ChatStreamState) (protocol.ChatEventFrame, bool, error) { + if eventType == "shell.created" { + if data.Info == nil || data.Info.ID == "" { + return protocol.ChatEventFrame{}, false, fmt.Errorf("malformed OpenCode shell.created event") + } + if data.Info.shellSessionID() != sessionID { + return protocol.ChatEventFrame{}, false, nil + } + status := data.Info.Status + if status == "" { + status = protocol.ChatShellRunning + } + stream.markShell(data.Info.ID) + return protocol.ChatEventFrame{ + SessionID: sessionID, + Kind: protocol.ChatEventShell, + Shell: &protocol.ChatShell{ID: data.Info.ID, Status: status, Command: data.Info.Command}, + }, true, nil + } + if data.ID == "" { + return protocol.ChatEventFrame{}, false, fmt.Errorf("malformed OpenCode shell.exited event") + } + if !stream.knowsShell(data.ID) { + return protocol.ChatEventFrame{}, false, nil + } + stream.forgetShell(data.ID) + status := data.Status + if status == "" { + status = protocol.ChatShellExited + } + return protocol.ChatEventFrame{ + SessionID: sessionID, + Kind: protocol.ChatEventShell, + Shell: &protocol.ChatShell{ID: data.ID, Status: status, Exit: data.Exit}, + }, true, nil +} + // toolInput picks a tool call's arguments from whichever frame carries them: // session.tool.called carries the parsed `input` object, session.tool.input.ended // carries the same arguments as a `text` JSON string, and progress/success carry diff --git a/internal/opencode/chat_test.go b/internal/opencode/chat_test.go index 1efaa12d..2aab9b59 100644 --- a/internal/opencode/chat_test.go +++ b/internal/opencode/chat_test.go @@ -17,11 +17,11 @@ import ( ) func TestNormalizeChatEvent(t *testing.T) { - last := "msg_prev" + prior := &ChatStreamState{LastMessageID: "msg_prev"} cases := []struct { name string payload string - last *string + state *ChatStreamState wantOK bool wantKind string wantMsg string @@ -38,14 +38,13 @@ func TestNormalizeChatEvent(t *testing.T) { {name: "tool completed", payload: `{"type":"session.tool.success","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","id":"call_1","name":"shell","content":[{"type":"text","text":"ok"}]}}`, wantOK: true, wantKind: protocol.ChatEventTool, wantStatus: protocol.ChatToolCompleted}, {name: "tool failed", payload: `{"type":"session.tool.failed","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","id":"call_1","name":"shell","error":{"type":"tool","message":"boom"}}}`, wantOK: true, wantKind: protocol.ChatEventTool, wantStatus: protocol.ChatToolError}, {name: "usage", payload: `{"type":"session.usage.updated","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","tokens":{"input":12,"output":34},"cost":0.001}}`, wantOK: true, wantKind: protocol.ChatEventUsage, wantUsage: &protocol.ChatUsage{InputTokens: 12, OutputTokens: 34, Cost: 0.001}}, - {name: "message id fallback", payload: `{"type":"session.step.started","data":{"sessionID":"ses_1","index":1}}`, last: &last, wantOK: true, wantKind: protocol.ChatEventStep, wantMsg: "msg_prev", wantStep: protocol.ChatStepStarted}, + {name: "message id fallback", payload: `{"type":"session.step.started","data":{"sessionID":"ses_1","index":1}}`, state: prior, wantOK: true, wantKind: protocol.ChatEventStep, wantMsg: "msg_prev", wantStep: protocol.ChatStepStarted}, {name: "foreign session skipped", payload: `{"type":"session.text.delta","data":{"sessionID":"ses_other","delta":"x"}}`, wantOK: false}, {name: "unknown type skipped", payload: `{"type":"session.created","data":{"sessionID":"ses_1"}}`, wantOK: false}, } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { - lastID := tc.last - frame, ok, err := NormalizeChatEvent([]byte(tc.payload), "ses_1", lastID) + frame, ok, err := NormalizeChatEvent([]byte(tc.payload), "ses_1", tc.state) if err != nil { t.Fatalf("unexpected error: %v", err) } diff --git a/internal/opencode/chat_v2_test.go b/internal/opencode/chat_v2_test.go index 4e76d7d3..00cb2242 100644 --- a/internal/opencode/chat_v2_test.go +++ b/internal/opencode/chat_v2_test.go @@ -137,8 +137,7 @@ func TestChatDeltaPartIDsNeverCollide(t *testing.T) { } ids := map[string]string{} for kind, payload := range payloads { - last := "" - frame, ok, err := NormalizeChatEvent([]byte(payload), "ses_1", &last) + frame, ok, err := NormalizeChatEvent([]byte(payload), "ses_1", &ChatStreamState{}) if err != nil || !ok { t.Fatalf("%s delta: ok=%v err=%v", kind, ok, err) } @@ -205,8 +204,7 @@ func TestChatToolLifecycleCarriesNameAndInput(t *testing.T) { } for _, tc := range frames { t.Run(tc.name, func(t *testing.T) { - last := "" - frame, ok, err := NormalizeChatEvent([]byte(tc.payload), "ses_1", &last) + frame, ok, err := NormalizeChatEvent([]byte(tc.payload), "ses_1", &ChatStreamState{}) if err != nil || !ok { t.Fatalf("ok=%v err=%v", ok, err) } @@ -246,8 +244,7 @@ func TestChatToolLifecycleCarriesNameAndInput(t *testing.T) { // that is not yet a complete JSON value must still surface, carried as a JSON // string so the frame stays valid and the client can show the partial arguments. func TestChatToolInputFromPartialText(t *testing.T) { - last := "" - frame, ok, err := NormalizeChatEvent([]byte(`{"type":"session.tool.input.ended","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","id":"call_1","text":"{\"command\":\"l"}}`), "ses_1", &last) + frame, ok, err := NormalizeChatEvent([]byte(`{"type":"session.tool.input.ended","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","id":"call_1","text":"{\"command\":\"l"}}`), "ses_1", &ChatStreamState{}) if err != nil || !ok { t.Fatalf("ok=%v err=%v", ok, err) } @@ -266,6 +263,121 @@ func TestChatToolInputFromPartialText(t *testing.T) { } } +// TestChatShellEventMapping pins the shell mapping: a shell.created belonging to +// the session surfaces a ChatEventShell frame carrying the shell's id, status and +// command, and the matching shell.exited carries its id, status and exit code. +// The frames carry no message id (a shell outlives the tool call that started +// it), and the exit is a pointer so an exit of 0 is not mistaken for "absent". +func TestChatShellEventMapping(t *testing.T) { + state := &ChatStreamState{} + created, ok, err := NormalizeChatEvent([]byte(`{"type":"shell.created","data":{"info":{"id":"sh_1","status":"running","command":"npm run dev","cwd":"/work","metadata":{"sessionID":"ses_1"}}}}`), "ses_1", state) + if err != nil || !ok { + t.Fatalf("shell.created: ok=%v err=%v", ok, err) + } + if created.Kind != protocol.ChatEventShell || created.Shell == nil { + t.Fatalf("created frame = %+v", created) + } + if created.MessageID != "" { + t.Fatalf("shell frame carried a message id: %q", created.MessageID) + } + if created.Shell.ID != "sh_1" || created.Shell.Status != protocol.ChatShellRunning || created.Shell.Command != "npm run dev" { + t.Fatalf("created shell = %+v", created.Shell) + } + exited, ok, err := NormalizeChatEvent([]byte(`{"type":"shell.exited","data":{"id":"sh_1","exit":0,"status":"exited"}}`), "ses_1", state) + if err != nil || !ok { + t.Fatalf("shell.exited: ok=%v err=%v", ok, err) + } + if exited.Shell == nil || exited.Shell.ID != "sh_1" || exited.Shell.Status != protocol.ChatShellExited { + t.Fatalf("exited shell = %+v", exited.Shell) + } + if exited.Shell.Exit == nil || *exited.Shell.Exit != 0 { + t.Fatalf("exit code = %v, want a present 0", exited.Shell.Exit) + } + // A second exit for the same shell is not this session's any more: the id was + // forgotten once its exit surfaced. + if _, ok, err := NormalizeChatEvent([]byte(`{"type":"shell.exited","data":{"id":"sh_1","exit":0,"status":"exited"}}`), "ses_1", state); err != nil || ok { + t.Fatalf("repeated exit produced a frame: ok=%v err=%v", ok, err) + } +} + +// TestChatShellEventForeignSessionIgnored pins the session scoping the shell +// events need: they are location-scoped, so the session that started a shell is +// named only in the created event's metadata. A shell started by another session +// is ignored, and its exit — which names no session at all — is ignored too, +// because the id was never remembered for this session. +func TestChatShellEventForeignSessionIgnored(t *testing.T) { + state := &ChatStreamState{} + foreign := `{"type":"shell.created","data":{"info":{"id":"sh_foreign","status":"running","command":"sleep 120","metadata":{"sessionID":"ses_other"}}}}` + if frame, ok, err := NormalizeChatEvent([]byte(foreign), "ses_1", state); err != nil || ok { + t.Fatalf("another session's shell produced a frame: %+v ok=%v err=%v", frame, ok, err) + } + if _, ok, err := NormalizeChatEvent([]byte(`{"type":"shell.exited","data":{"id":"sh_foreign","exit":0,"status":"exited"}}`), "ses_1", state); err != nil || ok { + t.Fatalf("another session's shell exit produced a frame: ok=%v err=%v", ok, err) + } + // An unattributed shell (no metadata.sessionID) is not this session's either. + unattributed := `{"type":"shell.created","data":{"info":{"id":"sh_anon","status":"running","command":"ls","metadata":{}}}}` + if _, ok, err := NormalizeChatEvent([]byte(unattributed), "ses_1", state); err != nil || ok { + t.Fatalf("unattributed shell produced a frame: ok=%v err=%v", ok, err) + } +} + +// TestChatMalformedShellEventFailsStream pins that a shell event which cannot be +// keyed (no shell id) fails the stream instead of producing a frame the client +// cannot attribute. +func TestChatMalformedShellEventFailsStream(t *testing.T) { + cases := []string{ + `{"type":"shell.created","data":{"info":{"status":"running","metadata":{"sessionID":"ses_1"}}}}`, + `{"type":"shell.exited","data":{"exit":0,"status":"exited"}}`, + } + for _, payload := range cases { + if _, ok, err := NormalizeChatEvent([]byte(payload), "ses_1", &ChatStreamState{}); err == nil || ok { + t.Fatalf("malformed shell event %s: ok=%v err=%v", payload, ok, err) + } + } +} + +// TestChatStreamSurfacesShellLifecycle drives the whole mapping through the SSE +// read loop: a shell started for the session surfaces as a shell frame, a shell +// started by another session is dropped, and the matching exit is surfaced only +// for the session's own shell. It pins that the shell context the exit needs is +// carried across frames by the stream's retained state, not by one payload. +func TestChatStreamSurfacesShellLifecycle(t *testing.T) { + frames := []string{ + `{"id":"evt_1","type":"shell.created","data":{"info":{"id":"sh_1","status":"running","command":"npm run dev","metadata":{"sessionID":"ses_1"}}}}`, + `{"id":"evt_2","type":"shell.created","data":{"info":{"id":"sh_other","status":"running","command":"sleep 120","metadata":{"sessionID":"ses_other"}}}}`, + `{"id":"evt_3","type":"session.text.delta","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","ordinal":0,"delta":"hi"}}`, + `{"id":"evt_4","type":"shell.exited","data":{"id":"sh_other","exit":0,"status":"exited"}}`, + `{"id":"evt_5","type":"shell.exited","data":{"id":"sh_1","exit":0,"status":"exited"}}`, + } + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "text/event-stream") + for _, frame := range frames { + _, _ = w.Write([]byte("data: " + frame + "\n\n")) + } + })) + defer srv.Close() + + chat := NewChat(&Connection{Backend: "v2", URL: srv.URL}) + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + var got []protocol.ChatEventFrame + if err := chat.Stream(ctx, "ses_1", nil, func(frame protocol.ChatEventFrame) error { + got = append(got, frame) + return nil + }); err != nil { + t.Fatalf("stream: %v", err) + } + var shellIDs []string + for _, frame := range got { + if frame.Kind == protocol.ChatEventShell && frame.Shell != nil { + shellIDs = append(shellIDs, frame.Shell.ID+":"+frame.Shell.Status) + } + } + if len(shellIDs) != 2 || shellIDs[0] != "sh_1:running" || shellIDs[1] != "sh_1:exited" { + t.Fatalf("shell frames = %v, want only this session's created and exited", shellIDs) + } +} + // TestOpenStreamRejectsUnknownBackend pins that the shared construction path // validates the backend before any process is started, so OpenStream never // launches a serve for an unknown backend. diff --git a/internal/protocol/chat.go b/internal/protocol/chat.go index 2fdeaaf5..70138e91 100644 --- a/internal/protocol/chat.go +++ b/internal/protocol/chat.go @@ -80,6 +80,17 @@ const ( ChatEventStep = "step" ChatEventUsage = "usage" ChatEventUser = "user" + // ChatEventShell reports the lifecycle of one shell the agent started. It + // carries no ChatPart and no message id: a shell can outlive the tool call + // that started it, so it is a frame of its own rather than a tool part. + ChatEventShell = "shell" +) + +// ChatShell.Status values, mirroring the OpenCode shell events. A running shell +// is one whose command has started and not yet exited; exited is final. +const ( + ChatShellRunning = "running" + ChatShellExited = "exited" ) // ChatStep.Status values, mirroring the OpenCode session.step events. @@ -292,6 +303,10 @@ type ChatEventFrame struct { Part *ChatPart `json:"part,omitempty"` Step *ChatStep `json:"step,omitempty"` Usage *ChatUsage `json:"usage,omitempty"` + // Shell is the payload of a ChatEventShell frame: the shell's id, its + // status, the command it is running and (once it has exited) its exit code. + // It is nil on every other kind. + Shell *ChatShell `json:"shell,omitempty"` // Client is the sending device's label on a user frame (ChatEventUser), so a // transcript can say who sent the message. It is empty on assistant frames. Client string `json:"client,omitempty"` @@ -310,6 +325,22 @@ type ChatUsage struct { Cost float64 `json:"cost,omitempty"` } +// ChatShell is the state of one shell command the agent started, carried by a +// ChatEventShell frame. ID is the OpenCode shell id and is stable across its +// created and exited events, so a client keys a running process by it. Status is +// ChatShellRunning or ChatShellExited; Command is the command line the shell was +// given (present on the created event); Exit is the process exit code and is +// present only once the shell has exited — it is a pointer so an exit of 0 is +// distinguishable from "not exited yet". No credential, environment or output is +// carried: the command line is the only text, and only so the operator can name +// what is running. +type ChatShell struct { + ID string `json:"id"` + Status string `json:"status,omitempty"` + Command string `json:"command,omitempty"` + Exit *int `json:"exit,omitempty"` +} + // ChatPermissionFrame is the server-pushed chat_permission payload: one pending // OpenCode permission request the phone must approve or reject. It is a distinct // Message field (like ChatEvent) rather than a ChatEvent.Kind, so it does not diff --git a/internal/server/chat_hub.go b/internal/server/chat_hub.go index fdc14b3b..134e3fd6 100644 --- a/internal/server/chat_hub.go +++ b/internal/server/chat_hub.go @@ -21,6 +21,11 @@ const chatRetainedLimit = opencode.MaxResponse // least-recently-updated turn is evicted once the cap is exceeded. const chatMaxTurns = 128 +// chatShellLimit bounds how many running shells one session retains for replay +// to a client that reattaches, so a runaway turn cannot grow the retained state +// without limit. It matches the approval-replay bound. +const chatShellLimit = 16 + // chatHub retains the accumulated turn state per session, independently of any // single connection, so a reconnecting client can re-sync what it missed. State // is keyed by session and then by message id (a session holds many turns), and @@ -77,6 +82,14 @@ type chatTurn struct { // chatPermissionRetainedLimit like the dedup set above. resolutions map[string]*chatResolution resolutionOrder []string + // shells holds the session's still-running shell commands, keyed by the + // shell id the stream gave them, so a client that reattaches can be re-synced + // the background processes it cannot have seen. shellOrder preserves start + // order and bounds the retained set to chatShellLimit; a turn that has + // finished retains nothing here, so a background process surviving the turn + // is never mistaken for the turn still running. + shells map[string]protocol.ChatShell + shellOrder []string } // chatResolution is the shared answer to one permission request. answered is @@ -128,6 +141,11 @@ func (h *chatHub) apply(frame protocol.ChatEventFrame) { case protocol.ChatEventUsage: turn.usage = frame.Usage return + case protocol.ChatEventShell: + // A shell frame carries no message id (it outlives the tool call that + // started it), so it is folded before the message-id gate below. + turn.applyShell(frame.Shell) + return } if frame.MessageID == "" { return @@ -210,6 +228,58 @@ func (h *chatHub) apply(frame protocol.ChatEventFrame) { } } +// applyShell folds one shell frame into the session's retained shells. A running +// shell is upserted (keyed by its id) so a client that reattaches can be +// re-synced the processes still running; an exited shell is dropped, which is +// what clears the indicator. The retained set is bounded both by count +// (chatShellLimit) and by the same per-session byte cap the other retained state +// uses, so a long turn with many shells cannot grow it without limit. A shell +// exit for a shell the session never retained is ignored, so a frame that is not +// this session's cannot clear another session's process. +func (t *chatTurn) applyShell(shell *protocol.ChatShell) { + if shell == nil || shell.ID == "" { + return + } + if shell.Status == protocol.ChatShellExited { + old, ok := t.shells[shell.ID] + if !ok { + return + } + t.shellOrder = removeShellID(t.shellOrder, shell.ID) + delete(t.shells, shell.ID) + t.shrink(len(old.Command)) + return + } + if t.shells == nil { + t.shells = map[string]protocol.ChatShell{} + } + if _, ok := t.shells[shell.ID]; !ok { + if !t.retain(len(shell.Command)) { + return + } + t.shellOrder = append(t.shellOrder, shell.ID) + } + t.shells[shell.ID] = *shell + for len(t.shellOrder) > chatShellLimit { + id := t.shellOrder[0] + t.shellOrder = t.shellOrder[1:] + if dropped, ok := t.shells[id]; ok { + delete(t.shells, id) + t.shrink(len(dropped.Command)) + } + } +} + +// removeShellID drops id from order, preserving the order of the rest. +func removeShellID(order []string, id string) []string { + for i, existing := range order { + if existing == id { + return append(order[:i:i], order[i+1:]...) + } + } + return order +} + // mergeChatToolPart folds one tool frame onto the part retained from the frames // before it. A tool call is reported across several frames that each carry only // part of it — input.started the name, input.ended the arguments as text, called @@ -379,3 +449,25 @@ func (h *chatHub) snapshot(sessionID string) []protocol.ChatMessage { } return messages } + +// shellSnapshot returns the session's still-running shells, in the order they +// started, so a client attaching to the session's stream can be re-synced the +// background processes it cannot have seen. It is the shell half of the resume +// path — the message snapshot cannot carry a shell, because a shell is not a +// turn — and returns nil when the session has none running. A shell that has +// exited is not retained, so a stale process is never replayed. +func (h *chatHub) shellSnapshot(sessionID string) []protocol.ChatShell { + h.mu.Lock() + defer h.mu.Unlock() + turn := h.turns[sessionID] + if turn == nil || len(turn.shells) == 0 { + return nil + } + shells := make([]protocol.ChatShell, 0, len(turn.shells)) + for _, id := range turn.shellOrder { + if shell, ok := turn.shells[id]; ok { + shells = append(shells, shell) + } + } + return shells +} diff --git a/internal/server/chat_stream.go b/internal/server/chat_stream.go index da9f9cb3..76c175e6 100644 --- a/internal/server/chat_stream.go +++ b/internal/server/chat_stream.go @@ -119,4 +119,14 @@ func handleChatSubscribe(request protocol.Message, broker chatBroker, hub *chatH frame := pending sub.send(protocol.Message{Type: protocol.ChatPermission, ChatPermission: &frame}) } + // Replay the background processes still running, so a device that attaches + // after they started (a reconnect, or a chat opened from another device) + // shows them rather than nothing until they exit. The message snapshot cannot + // carry a shell — a shell outlives the turn and is not a turn — so this is the + // shell half of the resume. + for _, shell := range hub.shellSnapshot(query.SessionID) { + running := shell + frame := protocol.ChatEventFrame{SessionID: query.SessionID, Kind: protocol.ChatEventShell, Shell: &running} + sub.send(protocol.Message{Type: protocol.ChatEvent, ChatEvent: &frame}) + } } diff --git a/internal/server/chat_test.go b/internal/server/chat_test.go index bf19de7f..29dbc4bb 100644 --- a/internal/server/chat_test.go +++ b/internal/server/chat_test.go @@ -939,6 +939,106 @@ func TestChatHubRetainsToolNameAndInputAcrossLifecycle(t *testing.T) { } } +// TestChatHubRetainsShellOutlivingTurn pins the background-process state: a shell +// the agent started survives the turn that started it, so a client re-syncing the +// session still sees the process running, and its exit clears it. An exit for a +// shell the session never retained (another session's) clears nothing. +func TestChatHubRetainsShellOutlivingTurn(t *testing.T) { + hub := newChatHub() + hub.apply(protocol.ChatEventFrame{SessionID: "ses_1", Kind: protocol.ChatEventShell, Shell: &protocol.ChatShell{ID: "sh_1", Status: protocol.ChatShellRunning, Command: "npm run dev"}}) + // The turn that started the shell finishes while the shell keeps running. + hub.apply(protocol.ChatEventFrame{SessionID: "ses_1", MessageID: "msg_1", Kind: protocol.ChatEventStep, Step: &protocol.ChatStep{Status: protocol.ChatStepEnded}}) + shells := hub.shellSnapshot("ses_1") + if len(shells) != 1 || shells[0].ID != "sh_1" || shells[0].Command != "npm run dev" || shells[0].Status != protocol.ChatShellRunning { + t.Fatalf("running shell not retained past the turn: %+v", shells) + } + // An exit for a shell this session never started is not this session's. + hub.apply(protocol.ChatEventFrame{SessionID: "ses_1", Kind: protocol.ChatEventShell, Shell: &protocol.ChatShell{ID: "sh_other", Status: protocol.ChatShellExited}}) + if shells := hub.shellSnapshot("ses_1"); len(shells) != 1 { + t.Fatalf("foreign exit cleared the running shell: %+v", shells) + } + exit := 0 + hub.apply(protocol.ChatEventFrame{SessionID: "ses_1", Kind: protocol.ChatEventShell, Shell: &protocol.ChatShell{ID: "sh_1", Status: protocol.ChatShellExited, Exit: &exit}}) + if shells := hub.shellSnapshot("ses_1"); shells != nil { + t.Fatalf("exited shell still retained: %+v", shells) + } +} + +// TestChatPromptStreamsShellFrame pins that a shell frame reaches the watching +// client like every other frame kind, carrying its payload and no message id. +func TestChatPromptStreamsShellFrame(t *testing.T) { + broker := scriptedChat() + broker.script = append([]protocol.ChatEventFrame{ + {SessionID: "ses_1", Kind: protocol.ChatEventShell, Shell: &protocol.ChatShell{ID: "sh_1", Status: protocol.ChatShellRunning, Command: "sleep 120"}}, + }, broker.script...) + ctx, _, conn := dialChat(t, broker) + if err := wsjson.Write(ctx, conn, protocol.Message{Type: protocol.ChatPrompt, ID: "r1", ChatPrompt: &protocol.ChatPromptRequest{SessionID: "ses_1", Text: "hi"}}); err != nil { + t.Fatal(err) + } + var ack protocol.Message + if err := wsjson.Read(ctx, conn, &ack); err != nil { + t.Fatal(err) + } + frames := readChatTurn(t, ctx, conn) + if len(frames) == 0 || frames[0].Kind != protocol.ChatEventShell { + t.Fatalf("first frame = %+v, want the shell frame", frames) + } + shell := frames[0] + if shell.MessageID != "" || shell.Shell == nil || shell.Shell.ID != "sh_1" || shell.Shell.Command != "sleep 120" || shell.Shell.Status != protocol.ChatShellRunning { + t.Fatalf("shell frame = %+v", shell) + } +} + +// TestChatSubscribeReplaysRunningShell pins the shell half of the resume: a +// client attaching to a session's stream after a shell started is replayed the +// still-running shell, so a reconnect (or a chat opened from another device) +// shows the background process instead of nothing until it exits. +func TestChatSubscribeReplaysRunningShell(t *testing.T) { + broker := scriptedChat() + broker.script = append([]protocol.ChatEventFrame{ + {SessionID: "ses_1", Kind: protocol.ChatEventShell, Shell: &protocol.ChatShell{ID: "sh_1", Status: protocol.ChatShellRunning, Command: "sleep 120"}}, + }, broker.script...) + ctx, _, conns := dialChatConns(t, Options{Chat: broker}, 2) + if err := wsjson.Write(ctx, conns[0], protocol.Message{Type: protocol.ChatPrompt, ID: "r1", ChatPrompt: &protocol.ChatPromptRequest{SessionID: "ses_1", Text: "hi"}}); err != nil { + t.Fatal(err) + } + var ack protocol.Message + if err := wsjson.Read(ctx, conns[0], &ack); err != nil { + t.Fatal(err) + } + frames := readChatTurn(t, ctx, conns[0]) + sawShell := false + for _, frame := range frames { + if frame.Kind == protocol.ChatEventShell && frame.Shell != nil && frame.Shell.ID == "sh_1" { + sawShell = true + } + } + if !sawShell { + t.Fatalf("shell frame not fanned out: %+v", frames) + } + // The second client attaches only now; the running shell must be replayed. + if err := wsjson.Write(ctx, conns[1], protocol.Message{Type: protocol.ChatSubscribe, ID: "sub1", ChatSubscribe: &protocol.ChatQuery{SessionID: "ses_1"}}); err != nil { + t.Fatal(err) + } + var subscription protocol.Message + if err := wsjson.Read(ctx, conns[1], &subscription); err != nil { + t.Fatal(err) + } + if subscription.Type != protocol.ChatSubscribe || subscription.ID != "sub1" { + t.Fatalf("subscribe ack = %+v", subscription) + } + var replayed protocol.Message + if err := wsjson.Read(ctx, conns[1], &replayed); err != nil { + t.Fatal(err) + } + if replayed.Type != protocol.ChatEvent || replayed.ChatEvent == nil || replayed.ChatEvent.Kind != protocol.ChatEventShell { + t.Fatalf("replay frame = %+v", replayed) + } + if replayed.ChatEvent.Shell == nil || replayed.ChatEvent.Shell.ID != "sh_1" || replayed.ChatEvent.Shell.Status != protocol.ChatShellRunning { + t.Fatalf("replayed shell = %+v", replayed.ChatEvent.Shell) + } +} + // TestChatPromptSubscribesBeforePrompt pins the subscribe-before-prompt order: // the firehose has no replay cursor, so the subscription must be attached before // the prompt is posted or deltas emitted in between are lost.