From 7d9490bba1216f8f09b5943ece4196add5a5b580 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sun, 18 Oct 2026 09:45:28 +0100 Subject: [PATCH 1/2] chat: name the in-flight state, and surface background processes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two gaps in the chat's in-flight feedback. The turn indicator no longer reads a bare `Working…` for every state. A new pure derivation (TurnPhase/turnPhase/turnPhaseLabel in ui/chat/ChatFormat.kt) labels the headline from evidence already on the wire: `Thinking…` while text or reasoning deltas are still arriving (within TURN_THINKING_WINDOW_MILLIS), `Running a tool…` while calls are in flight, `Waiting…` otherwise. No percentage, ETA or invented progress. The agent's shell commands are now surfaced end to end as their own frame kind, so a background process (a dev server, a watching build) that outlives its tool call is visible and clears when it exits. Server: - protocol/chat.go adds ChatEventShell, ChatShell (id, status, command, *int exit — a pointer so exit 0 is not "absent") and ChatEventFrame.shell. - opencode/chat.go maps shell.created/shell.exited through a new exported ChatStreamState, attributing created via info.metadata.sessionID and exit via the ids the stream already surfaced; another session's or an unattributed shell is ignored, an id-less shell fails the stream. No cwd/file/credential is carried. - server/chat_hub.go retains still-running shells (chatShellLimit plus the shared byte cap) and drops them on exit; chat_stream.go replays them on chat_subscribe, the shell half of the resume (a shell is not a turn, so the message snapshot cannot carry it). App: - data/protocol/Chat.kt adds ChatShell, ChatEventFrame.shell, EVENT_SHELL, SHELL_RUNNING/SHELL_EXITED. - ui/chat/ChatStore.kt stamps ChatThread.lastDeltaAt on each delta (cleared when the turn settles) and keeps ChatThread.shells across a chat switch; a shell never marks the thread running. streamResumed drops shells so the subscribe replay re-syncs the still-running ones. - ui/chat/ChatTranscript.kt: RunningIndicator prints the phase label; a new always-visible BackgroundProcessBar names each running shell. - ui/chat/ChatConversationPane.kt shows the bar whenever a shell is running, whether or not a turn is. Tests extend the server's event mapping (opencode/chat_v2_test.go, server/chat_test.go) and the app's pure folds (new ui/chat/ChatInFlightStateTest.kt, 15 tests), pinning the shell mapping, the other-session rejection and the "background process outlives the turn" state. Checked and intentionally unchanged: - No packaged OpenCode skill reference documents either surface. internal/author/skill/references/operations.md describes the brokered chat_* protocol in prose without naming frame kinds or the app indicator, so it stays correct as-is; no reference was added, so install.go's managed inventory needs no change. - This repository has no packaged templates directory. - Shared docs are not edited here per the map: docs/notes/chat-shell-background -process.md records what is now stale in docs/cli.md and android/README.md for the docs-fold writer. Verification (this session): gofmt -l clean, go build ./... and go vet ./... OK. Android unit suite and the on-device capture were run in the preceding review stage; see the note for the live-verification limitation. --- .../net/awan/pipelines/data/protocol/Chat.kt | 30 +++ .../pipelines/ui/chat/ChatConversationPane.kt | 10 +- .../net/awan/pipelines/ui/chat/ChatFormat.kt | 71 ++++++ .../net/awan/pipelines/ui/chat/ChatStore.kt | 78 ++++++- .../awan/pipelines/ui/chat/ChatTranscript.kt | 73 +++++- .../ui/chat/ChatInFlightStateTest.kt | 211 ++++++++++++++++++ docs/notes/chat-shell-background-process.md | 98 ++++++++ internal/opencode/chat.go | 150 ++++++++++++- internal/opencode/chat_test.go | 9 +- internal/opencode/chat_v2_test.go | 124 +++++++++- internal/protocol/chat.go | 31 +++ internal/server/chat_hub.go | 92 ++++++++ internal/server/chat_stream.go | 10 + internal/server/chat_test.go | 100 +++++++++ 14 files changed, 1053 insertions(+), 34 deletions(-) create mode 100644 android/app/src/test/java/net/awan/pipelines/ui/chat/ChatInFlightStateTest.kt create mode 100644 docs/notes/chat-shell-background-process.md 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. From 7fbbd953746ce48ae960f84065ea9103408cfc8a Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sun, 18 Oct 2026 09:58:28 +0100 Subject: [PATCH 2/2] chat: one tool-call summary chip per turn, opening the call list MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The chat transcript no longer renders a chip per tool call: `ToolCalls` (`android/.../ui/chat/ChatToolCalls.kt`) now draws a single summary chip reading `N tools called` (`1 tool called` for one) as the turn's only tool-call surface. While the turn streams the chip shows the call count growing and the existing spinner while any call is in flight, plus the existing `· long` mark for a running call past `TOOL_LONG_RUNNING_MILLIS`; both are gated on the turn still streaming (`live = streaming` in `AgentTurnItem`), so a settled chip never spins or fakes a long mark. Tapping the chip opens the existing `ToolPanel` as a popup listing every call of the turn, in the order the agent made them: one independently collapsible row per call naming it, showing its one-line detail, its `+N -M` edit stat and its duration, expanding in place to the pretty-printed INPUT, the synthesised edit diff, then the ERROR block for a failed call or the OUTPUT (`(no output)` when empty). The list is bounded by the new `TOOL_PANEL_MAX_HEIGHT_DP` (`Dimens.kt`, purpose-named) and scrolls inside the panel, so many calls never grow the popup past the window nor re-flow the transcript. The chip announces the count ("N tool calls, expand for details") through the app's accessibility treatment. Pure logic lives in `ChatFormat.kt` (`toolCallsLabel`, `toolCallsAnnouncement`, `toolCallCount`, `toolsRunning`, `toolCallRow`) with unit cases added to the existing `ChatFormatTest`; no raw dimension was introduced, so `DimensTest` is unchanged. Checked for staleness: the packaged authoring skill references (`internal/author/skill/references/`) and the packaged templates carry no Android-chat content, so neither needs updating — this change is `android/`-only. The shared docs this change makes stale (`android/README.md`'s "Tool-call chips and the expandable panel" section and `docs/chat-verification.md`'s tool-chip row) are recorded in `docs/notes/chat-tool-group.md` for the single `docs-fold` writer rather than edited here. --- .../net/awan/pipelines/ui/chat/ChatFormat.kt | 58 ++++ .../awan/pipelines/ui/chat/ChatToolCalls.kt | 323 +++++++++++------- .../awan/pipelines/ui/chat/ChatTranscript.kt | 22 +- .../net/awan/pipelines/ui/theme/Dimens.kt | 7 + .../awan/pipelines/ui/chat/ChatFormatTest.kt | 84 +++++ docs/notes/chat-tool-group.md | 48 +++ 6 files changed, 418 insertions(+), 124 deletions(-) create mode 100644 docs/notes/chat-tool-group.md 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..3c2f7bce 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 @@ -80,6 +80,34 @@ internal fun formatToolDuration(millis: Long): String = when { /** The chip label for a tool call: its name, or a placeholder when unnamed. */ internal fun toolLabel(part: ChatPart): String = part.name.ifBlank { "tool" } +/** + * A turn's one summary chip: `N tools called`, and `1 tool called` for a single + * call — a count of one is never pluralised. The chip is the transcript's only + * tool-call surface, so this label stands in for every call of the turn. + */ +internal fun toolCallsLabel(count: Int): String = + if (count == 1) "1 tool called" else "$count tools called" + +/** + * What the summary chip announces to a screen reader, since the individual + * calls only exist inside the popup: the count, plus how to reach the detail. + * Singular and plural follow [toolCallsLabel] so the two never disagree. + */ +internal fun toolCallsAnnouncement(count: Int): String = + if (count == 1) "1 tool call, expand for details" else "$count tool calls, expand for details" + +/** + * How many tool calls [parts] holds. Counted by kind rather than by + * `parts.size`, so a turn that also carries text or reasoning never inflates + * the number the summary chip shows. + */ +internal fun toolCallCount(parts: List): Int = + parts.count { it.type == ChatProtocol.PART_TOOL } + +/** True while any tool call in [parts] is still in flight. */ +internal fun toolsRunning(parts: List): Boolean = + parts.any { it.type == ChatProtocol.PART_TOOL && ChatProtocol.toolRunning(it.state) } + /** * The in-flight tool calls across a conversation's [messages], in transcript * order, so the conversation's indicator and the session row read the same set @@ -131,6 +159,36 @@ internal fun toolDetail(part: ChatPart): String? { return null } +/** + * Everything one row of the tool panel shows for a single call, derived once so + * the row, the summary chip and their unit test agree: the call's real name (the + * name the earlier frames taught it, only falling back to `tool` when none was + * ever seen), its one-line detail, its duration, the pretty-printed INPUT, the + * OUTPUT, the ERROR text for a failed call and the synthesised edit diff. + * [error] is null for a call that did not fail, and [diff] is null for every + * non-edit call, so the row shows only the sections that have content. + */ +internal data class ToolCallRow( + val name: String, + val detail: String?, + val duration: String?, + val input: String, + val output: String, + val error: String?, + val diff: ToolDiff?, +) + +/** Builds the one row a turn's tool panel shows for [part]. */ +internal fun toolCallRow(part: ChatPart): ToolCallRow = ToolCallRow( + name = toolLabel(part), + detail = toolDetail(part), + duration = toolDurationMillis(part)?.let(::formatToolDuration), + input = prettyToolInput(part.state?.input), + output = toolOutputText(part.state), + error = if (toolFailed(part.state)) toolErrorText(part.state) else null, + diff = toolEditDiff(part.state?.input), +) + /** * How long a running [part] has been going at [nowMillis]. The protocol's own * timing wins whenever the part carries it (a running call from stored history diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatToolCalls.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatToolCalls.kt index ed9738cd..1e0708be 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatToolCalls.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatToolCalls.kt @@ -4,14 +4,15 @@ import androidx.compose.foundation.clickable import androidx.compose.foundation.layout.Arrangement import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.Column -import androidx.compose.foundation.layout.ExperimentalLayoutApi -import androidx.compose.foundation.layout.FlowRow import androidx.compose.foundation.layout.Row import androidx.compose.foundation.layout.fillMaxWidth +import androidx.compose.foundation.layout.heightIn import androidx.compose.foundation.layout.padding import androidx.compose.foundation.layout.size import androidx.compose.foundation.layout.widthIn +import androidx.compose.foundation.rememberScrollState import androidx.compose.foundation.shape.RoundedCornerShape +import androidx.compose.foundation.verticalScroll import androidx.compose.material.icons.Icons import androidx.compose.material.icons.filled.Build import androidx.compose.material.icons.filled.Close @@ -25,6 +26,7 @@ import androidx.compose.material3.IconButton import androidx.compose.material3.MaterialTheme import androidx.compose.material3.Surface import androidx.compose.material3.Text +import androidx.compose.material3.minimumInteractiveComponentSize import androidx.compose.runtime.Composable import androidx.compose.runtime.getValue import androidx.compose.runtime.mutableStateOf @@ -33,6 +35,9 @@ import androidx.compose.runtime.setValue import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.platform.LocalDensity +import androidx.compose.ui.semantics.Role +import androidx.compose.ui.semantics.contentDescription +import androidx.compose.ui.semantics.semantics import androidx.compose.ui.text.style.TextOverflow import androidx.compose.ui.unit.IntOffset import androidx.compose.ui.unit.IntRect @@ -48,6 +53,7 @@ import net.awan.pipelines.ui.components.CodeBlock import net.awan.pipelines.ui.theme.ICON_BUTTON_SMALL_DP import net.awan.pipelines.ui.theme.ICON_INLINE_DP import net.awan.pipelines.ui.theme.ICON_STATUS_DP +import net.awan.pipelines.ui.theme.TOOL_PANEL_MAX_HEIGHT_DP import net.awan.pipelines.ui.theme.TOOL_PANEL_MAX_WIDTH_DP /** The tool panel floats over the transcript; these bound its width and offsets. */ @@ -57,109 +63,115 @@ private val TOOL_PANEL_MARGIN = 8.dp private val TOOL_PANEL_ELEVATION = 12.dp /** - * One turn's tool calls as a single group of compact chips, mirroring the - * reference transcript's `_ToolCalls`/`_ToolChip` (research §1.3): each call - * shows its name (or the edited file), its duration and a spinner while it runs, - * and the chips of the turn wrap together on as few lines as they fit instead of - * each taking a row. + * One turn's tool calls behind a single summary chip: `N tools called`, with the + * existing spinner while any call is still in flight and a `· long` mark while a + * running call has passed [TOOL_LONG_RUNNING_MILLIS]. A settled turn never shows + * either mark, so a finished turn cannot fake work it is not doing. * - * Tapping a chip opens its INPUT (pretty JSON) / OUTPUT (monospace) panel as an - * overlay anchored to that chip (research §1.3 `_buildPanel`), dismissed by its - * own X or by tapping outside. Because the panel is a popup and not part of the - * transcript layout, opening or closing it never re-flows the conversation nor - * moves its scroll position — the transcript stays exactly where the operator - * left it. + * The chip is the transcript's only tool-call surface: tapping it opens the tool + * panel as a popup listing every call of the turn in the order the agent made + * them, each row collapsing independently. Because the panel is a popup and not + * part of the transcript layout, opening or closing it never re-flows the + * conversation nor moves its scroll position. * - * An `edit`-family call expands to a diff card (research §1.3 `_CodeRun` / - * `_DiffView`): the `+N -M` stat on the chip and a green/red unified diff derived - * from the arguments, since the brokered protocol carries no diff field. An - * `error` call is visibly failed — an error-tinted chip and error icon — and its - * panel shows the error text. + * [elapsedMillis] is the live age of a call — the conversation supplies it from + * its own clock, so the `long` mark is derived from real elapsed time rather + * than guessed. [live] is whether the turn is still streaming: a stored call can + * carry a stale `running` status long after the turn ended, and a settled chip + * must not spin (or wear the `long` mark) on that. */ -@OptIn(ExperimentalLayoutApi::class) @Composable -internal fun ToolCalls(parts: List) { - // One id at a time: the reference shows a single panel, and a focusable popup - // dismisses the previous one on open. No key is needed: an id that is no - // longer among the calls simply matches nothing, so a streaming rebuild keeps - // the panel the operator just opened without allocating a key list per frame. - var openId by remember { mutableStateOf(null) } - FlowRow( - modifier = Modifier.fillMaxWidth().padding(vertical = 4.dp), - horizontalArrangement = Arrangement.spacedBy(CHAT_ITEM_GAP), - verticalArrangement = Arrangement.spacedBy(CHAT_ITEM_GAP), - ) { - parts.forEach { part -> - ToolChip( - part = part, - expanded = openId == part.id, - onToggle = { openId = if (openId == part.id) null else part.id }, - onDismiss = { openId = null }, - ) +internal fun ToolCalls(parts: List, live: Boolean, elapsedMillis: (ChatPart) -> Long = { 0L }) { + val calls = parts.filter { it.type == ChatProtocol.PART_TOOL } + if (calls.isEmpty()) return + // One panel at a time: the chip toggles it, and the panel's own X or a tap + // outside dismisses it. No key is needed: the calls belong to this turn. + var open by remember { mutableStateOf(false) } + val running = live && toolsRunning(calls) + val failed = calls.any { toolFailed(it.state) } + // The "long" mark is a running-call signal only: it is meaningful on the + // summary chip while a call is in flight, so a settled chip never wears it. + val long = running && calls.any { toolLongRunning(elapsedMillis(it)) } + Box(Modifier.fillMaxWidth().padding(vertical = CHAT_ITEM_GAP)) { + ToolCallsChip( + count = toolCallCount(calls), + running = running, + failed = failed, + long = long, + expanded = open, + onToggle = { open = !open }, + ) + if (open) { + Popup( + popupPositionProvider = rememberToolPanelPositionProvider(), + onDismissRequest = { open = false }, + properties = PopupProperties(focusable = true), + ) { + ToolPanel(calls = calls, onDismiss = { open = false }) + } } } } -/** A compact tool-call chip: kind icon, label, diff stat, duration and chevron. */ +/** + * The turn's one summary chip: the call count, the running spinner (or a state + * icon once settled), the optional `long` mark and a chevron naming the popup + * it opens. Its content description carries the count and how to reach the + * calls, so the summary is understandable without opening the panel. + */ @Composable -private fun ToolChip(part: ChatPart, expanded: Boolean, onToggle: () -> Unit, onDismiss: () -> Unit) { - val running = ChatProtocol.toolRunning(part.state) - val failed = toolFailed(part.state) - val diff = toolEditDiff(part.state?.input) - Box { - Surface( - shape = RoundedCornerShape(CHAT_ITEM_GAP + 2.dp), - color = if (failed) { - MaterialTheme.colorScheme.errorContainer - } else { - MaterialTheme.colorScheme.surfaceContainerHigh - }, - modifier = Modifier.clickable(onClick = onToggle), +private fun ToolCallsChip( + count: Int, + running: Boolean, + failed: Boolean, + long: Boolean, + expanded: Boolean, + onToggle: () -> Unit, +) { + Surface( + shape = RoundedCornerShape(CHAT_ITEM_GAP + 2.dp), + color = if (failed) { + MaterialTheme.colorScheme.errorContainer + } else { + MaterialTheme.colorScheme.surfaceContainerHigh + }, + modifier = Modifier + .semantics { contentDescription = toolCallsAnnouncement(count) } + .clickable(onClick = onToggle), + ) { + Row( + verticalAlignment = Alignment.CenterVertically, + horizontalArrangement = Arrangement.spacedBy(CHAT_ITEM_GAP), + modifier = Modifier.padding(horizontal = CHAT_ITEM_GAP + 2.dp, vertical = CHAT_ITEM_GAP), ) { - Row( - verticalAlignment = Alignment.CenterVertically, - horizontalArrangement = Arrangement.spacedBy(CHAT_ITEM_GAP), - modifier = Modifier.padding(horizontal = CHAT_ITEM_GAP + 2.dp, vertical = CHAT_ITEM_GAP), - ) { - if (running) { - CircularProgressIndicator(Modifier.size(ICON_STATUS_DP), strokeWidth = 2.dp) - } else { - Icon( - imageVector = when { - failed -> Icons.Default.ErrorOutline - diff != null -> Icons.Default.Edit - else -> Icons.Default.Build - }, - contentDescription = if (failed) "Failed tool call" else null, - modifier = Modifier.size(16.dp), - tint = if (failed) MaterialTheme.colorScheme.error else MaterialTheme.colorScheme.onSurfaceVariant, - ) - } - Text( - text = diff?.file?.takeIf { it.isNotBlank() } ?: toolLabel(part), - style = MaterialTheme.typography.labelMedium, - maxLines = 1, - overflow = TextOverflow.Ellipsis, - ) - diff?.let { DiffStat(it) } - toolDurationMillis(part)?.let { - Text(formatToolDuration(it), style = MaterialTheme.typography.labelMedium, color = MaterialTheme.colorScheme.onSurfaceVariant) - } + if (running) { + CircularProgressIndicator(Modifier.size(ICON_STATUS_DP), strokeWidth = 2.dp) + } else { Icon( - imageVector = if (expanded) Icons.Default.KeyboardArrowUp else Icons.Default.KeyboardArrowDown, - contentDescription = if (expanded) "Collapse tool call" else "Expand tool call", + imageVector = if (failed) Icons.Default.ErrorOutline else Icons.Default.Build, + contentDescription = null, modifier = Modifier.size(ICON_INLINE_DP), + tint = if (failed) MaterialTheme.colorScheme.error else MaterialTheme.colorScheme.onSurfaceVariant, ) } - } - if (expanded) { - Popup( - popupPositionProvider = rememberToolPanelPositionProvider(), - onDismissRequest = onDismiss, - properties = PopupProperties(focusable = true), - ) { - ToolPanel(part = part, onDismiss = onDismiss) + Text( + text = toolCallsLabel(count), + style = MaterialTheme.typography.labelMedium, + maxLines = 1, + overflow = TextOverflow.Ellipsis, + ) + if (long) { + Text( + text = "· long", + style = MaterialTheme.typography.labelMedium, + color = MaterialTheme.colorScheme.error, + ) } + Icon( + imageVector = if (expanded) Icons.Default.KeyboardArrowUp else Icons.Default.KeyboardArrowDown, + contentDescription = if (expanded) "Hide tool calls" else "Show tool calls", + modifier = Modifier.size(ICON_INLINE_DP), + ) } } } @@ -198,17 +210,15 @@ private fun rememberToolPanelPositionProvider(): PopupPositionProvider { } /** - * The expanded panel of one tool call, mirroring the reference panel - * (`_buildPanel`, research §1.3): a header naming the call and its duration with - * a close X, then the pretty-printed INPUT and the monospace OUTPUT (or the - * synthesised edit diff). Both content blocks carry the shared whole-block copy - * action from [CodeBlock]. A failed call always renders its error text in an - * ERROR block — even an edit-family call, whose diff is still shown alongside it. + * The turn's whole tool history as one panel, grown from the single-call panel: a + * header naming the count with a close X, then one collapsible row per call in + * the order the agent made them. The list is bounded ([TOOL_PANEL_MAX_HEIGHT_DP]) + * and scrolls inside the panel, so a turn with many calls neither grows the popup + * past the window nor moves the transcript behind it. */ @Composable -private fun ToolPanel(part: ChatPart, onDismiss: () -> Unit, modifier: Modifier = Modifier) { - val diff = toolEditDiff(part.state?.input) - val failed = toolFailed(part.state) +private fun ToolPanel(calls: List, onDismiss: () -> Unit, modifier: Modifier = Modifier) { + var expandedIds by remember { mutableStateOf>(emptySet()) } Surface( shape = RoundedCornerShape(CHAT_ITEM_GAP), color = MaterialTheme.colorScheme.surfaceContainer, @@ -221,35 +231,110 @@ private fun ToolPanel(part: ChatPart, onDismiss: () -> Unit, modifier: Modifier ) { Row(verticalAlignment = Alignment.CenterVertically, horizontalArrangement = Arrangement.spacedBy(CHAT_ITEM_GAP)) { Icon( - imageVector = if (failed) Icons.Default.ErrorOutline else Icons.Default.Build, + imageVector = Icons.Default.Build, contentDescription = null, - modifier = Modifier.size(16.dp), - tint = if (failed) MaterialTheme.colorScheme.error else MaterialTheme.colorScheme.primary, + modifier = Modifier.size(ICON_INLINE_DP), + tint = MaterialTheme.colorScheme.primary, ) Text( - text = diff?.file?.takeIf { it.isNotBlank() } ?: toolLabel(part), + text = toolCallsLabel(calls.size), style = MaterialTheme.typography.labelLarge, - maxLines = 1, - overflow = TextOverflow.Ellipsis, modifier = Modifier.weight(1f), ) - diff?.let { DiffStat(it) } - toolDurationMillis(part)?.let { - Text(formatToolDuration(it), style = MaterialTheme.typography.labelMedium, color = MaterialTheme.colorScheme.onSurfaceVariant) - } IconButton(onClick = onDismiss, modifier = Modifier.size(ICON_BUTTON_SMALL_DP)) { - Icon(Icons.Default.Close, contentDescription = "Close tool call", modifier = Modifier.size(16.dp)) + Icon(Icons.Default.Close, contentDescription = "Close tool calls", modifier = Modifier.size(ICON_INLINE_DP)) } } - if (diff != null) { - DiffView(diff) - } else { - CodeBlock(label = "INPUT", text = prettyToolInput(part.state?.input)) - } - if (failed) { - CodeBlock(label = "ERROR", text = toolErrorText(part.state)) - } else if (diff == null) { - CodeBlock(label = "OUTPUT", text = toolOutputText(part.state)) + Column( + verticalArrangement = Arrangement.spacedBy(CHAT_ITEM_GAP), + modifier = Modifier + .fillMaxWidth() + .heightIn(max = TOOL_PANEL_MAX_HEIGHT_DP) + .verticalScroll(rememberScrollState()), + ) { + calls.forEach { part -> + val row = toolCallRow(part) + ToolCallRowItem( + row = row, + expanded = part.id in expandedIds, + onToggle = { + expandedIds = if (part.id in expandedIds) expandedIds - part.id else expandedIds + part.id + }, + ) + } + } + } + } +} + +/** + * One call inside the panel: a header naming the call, its `+N -M` stat for an + * edit and its duration, and — expanded in place — the pretty-printed INPUT, the + * synthesised diff for an edit-family call, then the ERROR block for a failed + * call or the OUTPUT (or `(no output)`) for a settled one. Rows expand and + * collapse independently, so comparing two calls never loses the other's detail. + */ +@Composable +private fun ToolCallRowItem(row: ToolCallRow, expanded: Boolean, onToggle: () -> Unit) { + Column(Modifier.fillMaxWidth()) { + Row( + verticalAlignment = Alignment.CenterVertically, + horizontalArrangement = Arrangement.spacedBy(CHAT_ITEM_GAP), + modifier = Modifier + .fillMaxWidth() + .minimumInteractiveComponentSize() + .clickable(role = Role.Button, onClick = onToggle) + .padding(vertical = CHAT_ITEM_GAP), + ) { + Icon( + imageVector = when { + row.error != null -> Icons.Default.ErrorOutline + row.diff != null -> Icons.Default.Edit + else -> Icons.Default.Build + }, + contentDescription = if (row.error != null) "Failed tool call" else null, + modifier = Modifier.size(ICON_INLINE_DP), + tint = if (row.error != null) MaterialTheme.colorScheme.error else MaterialTheme.colorScheme.onSurfaceVariant, + ) + Column(Modifier.weight(1f)) { + Text( + text = row.name, + style = MaterialTheme.typography.labelMedium, + maxLines = 1, + overflow = TextOverflow.Ellipsis, + ) + row.detail?.let { + Text( + text = it, + style = MaterialTheme.typography.labelSmall, + color = MaterialTheme.colorScheme.onSurfaceVariant, + maxLines = 1, + overflow = TextOverflow.Ellipsis, + ) + } + } + row.diff?.let { DiffStat(it) } + row.duration?.let { + Text(it, style = MaterialTheme.typography.labelMedium, color = MaterialTheme.colorScheme.onSurfaceVariant) + } + Icon( + imageVector = if (expanded) Icons.Default.KeyboardArrowUp else Icons.Default.KeyboardArrowDown, + contentDescription = if (expanded) "Collapse ${row.name}" else "Expand ${row.name}", + modifier = Modifier.size(ICON_INLINE_DP), + ) + } + if (expanded) { + Column( + verticalArrangement = Arrangement.spacedBy(CHAT_ITEM_GAP), + modifier = Modifier.fillMaxWidth().padding(start = ICON_INLINE_DP + CHAT_ITEM_GAP, bottom = CHAT_ITEM_GAP), + ) { + CodeBlock(label = "INPUT", text = row.input) + row.diff?.let { DiffView(it) } + if (row.error != null) { + CodeBlock(label = "ERROR", text = row.error) + } else { + CodeBlock(label = "OUTPUT", text = row.output) + } } } } 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..50860ece 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 @@ -195,6 +195,7 @@ internal fun ChatTranscript( reasoning = reasoning, streaming = row.key == streamingTurnKey, runningSince = thread.runningSince, + toolStartedAt = thread.toolStartedAt, onToggleReasoning = onToggleReasoning, ) } @@ -434,10 +435,11 @@ private fun UserMessageItem(message: ChatMessage) { /** * One agent reply as a single bubble: the turn's one collapsible thinking block - * first, then its tool-call chips in order, then its answer text. A turn's + * first, then its one tool-call summary chip, then its answer text. A turn's * reasoning and answer are never mixed — the fold in [ChatTurn] keeps them * separate, so the answer is never drawn inside the thinking block — and the - * whole reply is one item however many model steps produced it. + * whole reply is one item however many model steps produced it. The individual + * calls live inside the chip's popup, not in the transcript. */ @Composable private fun AgentTurnItem( @@ -445,15 +447,17 @@ private fun AgentTurnItem( reasoning: ReasoningExpansion, streaming: Boolean, runningSince: Long, + toolStartedAt: Map, onToggleReasoning: (String) -> Unit, ) { // The turn's own timing for the collapsed thinking line: a streaming turn // counts live from its own start (the same clock the running indicator uses, // so the two never disagree), a settled turn shows the span its parts' timing // envelopes report, and a turn with neither shows no duration rather than a - // guessed one. + // guessed one. The same tick ages the summary chip's running calls, so its + // "long" mark never comes from a stale clock. + val now = if (streaming && runningSince > 0) rememberElapsedNow(runningSince) else 0L val elapsedMillis: Long? = if (streaming && runningSince > 0) { - val now = rememberElapsedNow(runningSince) if (runningSince < now) now - runningSince else 0L } else { turn.elapsedMillis @@ -477,7 +481,15 @@ private fun AgentTurnItem( elapsedMillis = elapsedMillis, onToggle = { onToggleReasoning(turnKey) }, ) - if (turn.tools.isNotEmpty()) ToolCalls(turn.tools) + if (turn.tools.isNotEmpty()) { + ToolCalls( + parts = turn.tools, + live = streaming, + elapsedMillis = { part -> + runningToolElapsedMillis(part, toolStartedAt[part.id] ?: 0L, now) + }, + ) + } if (turn.answer.isNotBlank()) MarkdownText(turn.answer) } } diff --git a/android/app/src/main/java/net/awan/pipelines/ui/theme/Dimens.kt b/android/app/src/main/java/net/awan/pipelines/ui/theme/Dimens.kt index 1b6a9351..caace198 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/theme/Dimens.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/theme/Dimens.kt @@ -235,6 +235,13 @@ internal val ICON_BUTTON_SMALL_DP = 28.dp /** The floating tool panel's maximum width; it floats over the transcript. */ internal val TOOL_PANEL_MAX_WIDTH_DP = 420.dp +/** + * How tall the tool panel's list of calls may grow before it scrolls inside the + * panel. Bounded so a turn with many calls never grows the popup past the window + * or pushes its own placement above the screen. + */ +internal val TOOL_PANEL_MAX_HEIGHT_DP = 440.dp + /** A chat row's title column stops here so the close action keeps its place. */ internal val CHAT_TITLE_MAX_WIDTH_DP = 160.dp diff --git a/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatFormatTest.kt b/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatFormatTest.kt index 74b7bd13..d9f5e03a 100644 --- a/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatFormatTest.kt +++ b/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatFormatTest.kt @@ -179,4 +179,88 @@ class ChatFormatTest { assertEquals("scratch", sessionTagLabel("scratch")) assertNull(sessionTagLabel("")) } + + @Test + fun theToolSummaryReadsAsACallCountAndNeverSaysOneTools() { + // The turn's one chip: the singular is a whole word, not a pluralised count. + assertEquals("1 tool called", toolCallsLabel(1)) + assertEquals("6 tools called", toolCallsLabel(6)) + // The same count is what a screen reader hears, plus how to reach the calls. + assertEquals("1 tool call, expand for details", toolCallsAnnouncement(1)) + assertEquals("6 tool calls, expand for details", toolCallsAnnouncement(6)) + } + + @Test + fun theSummaryCountCountsOnlyTheTurnsToolCalls() { + val parts = listOf( + ChatPart(type = ChatProtocol.PART_TEXT, id = "t1", text = "answer"), + ChatPart(type = ChatProtocol.PART_TOOL, id = "c1", name = "shell"), + ChatPart(type = ChatProtocol.PART_TOOL, id = "c2", name = "grep"), + ) + // Text and reasoning ride in the same turn but never inflate the chip. + assertEquals(2, toolCallCount(parts)) + assertEquals(0, toolCallCount(parts.filter { it.type == ChatProtocol.PART_TEXT })) + // One call still in flight keeps the chip live. + assertTrue(toolsRunning(listOf(parts[1].copy(state = ChatToolState(status = ChatProtocol.TOOL_RUNNING))))) + assertFalse(toolsRunning(listOf(parts[1].copy(state = ChatToolState(status = ChatProtocol.TOOL_COMPLETED))))) + } + + @Test + fun aToolCallRowDerivesItsNameDetailDurationInputAndOutput() { + val part = ChatPart( + type = ChatProtocol.PART_TOOL, + id = "c1", + name = "shell", + state = ChatToolState( + status = ChatProtocol.TOOL_COMPLETED, + input = JsonObject(mapOf("command" to JsonPrimitive("ls"))), + content = listOf(ChatToolContent(type = "text", text = "a.txt")), + ), + time = ChatTime(created = 1_000, ran = 1_000, completed = 2_500), + ) + val row = toolCallRow(part) + assertEquals("shell", row.name) + assertEquals("ls", row.detail) + assertEquals("1.5s", row.duration) + assertTrue(row.input.contains("\"command\"")) + assertEquals("a.txt", row.output) + // A successful non-edit call has neither an error block nor a diff. + assertNull(row.error) + assertNull(row.diff) + } + + @Test + fun aFailedEditRowCarriesItsErrorAndSynthesisedDiff() { + val part = ChatPart( + type = ChatProtocol.PART_TOOL, + id = "c2", + name = "edit", + state = ChatToolState( + status = ChatProtocol.TOOL_ERROR, + input = JsonObject( + mapOf( + "filePath" to JsonPrimitive("/tmp/a.txt"), + "oldString" to JsonPrimitive("one"), + "newString" to JsonPrimitive("two"), + ), + ), + error = ChatError(type = "boom", message = "exploded"), + ), + ) + val row = toolCallRow(part) + assertEquals("edit", row.name) + // The ERROR block wins over any output, and the diff is still shown beside it. + assertEquals("exploded", row.error) + assertEquals("/tmp/a.txt", row.diff?.file) + assertEquals(1, row.diff?.added) + assertEquals(1, row.diff?.removed) + // A call with no completion time shows no duration rather than a guess. + assertNull(row.duration) + } + + @Test + fun aToolCallRowKeepsTheRealNameAndOnlyFallsBackWhenNoneWasEverSeen() { + assertEquals("shell", toolCallRow(ChatPart(type = ChatProtocol.PART_TOOL, id = "c1", name = "shell")).name) + assertEquals("tool", toolCallRow(ChatPart(type = ChatProtocol.PART_TOOL, id = "c2")).name) + } } diff --git a/docs/notes/chat-tool-group.md b/docs/notes/chat-tool-group.md new file mode 100644 index 00000000..bdd35672 --- /dev/null +++ b/docs/notes/chat-tool-group.md @@ -0,0 +1,48 @@ +# Chat transcript: one tool-call summary chip per agent turn + +## What this item changed + +`android/` only — the chat transcript's tool-call surface. + +- **One chip per turn.** `ui/chat/ChatToolCalls.kt` no longer renders a chip per + call in a `FlowRow`; `ToolCalls` renders a single summary chip reading + `N tools called` (`1 tool called` for one), the transcript's only tool-call + surface. The individual calls are not chips any more. +- **Live summary.** The chip shows the existing spinner while any call is in + flight and a `· long` mark while a running call has passed + `TOOL_LONG_RUNNING_MILLIS`; both are gated on the turn still streaming + (`AgentTurnItem` passes `live = streaming`), so a settled turn never shows the + spinner or a long mark for a stored call whose status is stale. +- **Popup list.** Tapping the chip opens `ToolPanel` as a bounded + (`TOOL_PANEL_MAX_HEIGHT_DP`), scrollable list of one collapsible row per call in + the order the agent made them. A row shows the call's name, its one-line detail, + its `+N -M` stat for an edit and its duration, and expands in place to the + pretty-printed INPUT, the synthesised diff for an `edit`-family call, then the + ERROR block for a failed call or the OUTPUT (or `(no output)`). Rows expand and + collapse independently, and the popup still does not re-flow or scroll the + transcript. +- **Pure logic.** `ui/chat/ChatFormat.kt` adds `toolCallsLabel`, + `toolCallsAnnouncement` (the chip's accessibility line, e.g. "6 tool calls, + expand for details"), `toolCallCount`, `toolsRunning` and `toolCallRow` (the + per-row detail derivation), with cases added to `ChatFormatTest`. +- **Geometry.** `ui/theme/Dimens.kt` adds `TOOL_PANEL_MAX_HEIGHT_DP`; no raw + literal was introduced, so `DimensTest` is unchanged. + +## Shared documents this change makes stale + +`android/README.md` describes the surface this item changed. The note is written +here rather than edited in place; the `docs-fold` writer should update it. + +- `android/README.md` — the section **"Tool-call chips and the expandable panel + (16 Oct 2026)"** and its **Grouped chips** bullet ("A run of consecutive `tool` + parts in one assistant turn is now one `FlowRow` of compact chips") describe the + per-call chips this item removed. It should say the turn renders one summary + chip (`N tools called`) as the transcript's only tool-call surface, and that + tapping it opens one popup listing every call of the turn as independently + collapsible rows, with the chip's spinner/`long` marks gated on the turn still + streaming. The **Overlay panel, scroll preserved** bullet stays true. +- `docs/chat-verification.md:140` — the "Conversation — tool chip expanding" row + names `ChatToolCalls.kt` and the per-chip panel; it should name the summary chip + and the per-turn popup list, and the pure tests now include the label, count, + announcement and per-row derivations in `ChatFormatTest` (the placement maths in + `ToolPanelPositionProviderTest` is unchanged).