fix: surface tool calls and interleaved text in the ACP timeline #19

Merged
sam merged 2 commits from fix/acp-tool-call-surfacing into main 2026-10-03 11:35:15 +00:00
Collaborator

Problem

Every tool call brainless streams over ACP was labeled kind=other, so in Paseo's timeline the agent's activity rendered as a wall of anonymous Other rows: Paseo names the row from snapshot.kind ?? snapshot.title and shows no summary for the other kind. The model's prose between tool calls never appeared either, and results were not surfaced.

Three root causes, all confirmed against the ACP SDK and Paseo's server:

  1. Hardcoded kind — notifyToolCalls sent acp.WithStartKind(acp.ToolKindOther) for every function call. The ACP SDK defines read / edit / delete / move / search / execute / think / fetch / switch_mode kinds, and Paseo renders each as a recognizable Read / Edit / Search / Shell / Fetch row.
  2. Interleaved text dropped — eventText/eventThought gated on ev.IsFinalResponse(), which ADK defines as false for any event carrying function calls (session.go). A model response that says "Let me check X" and calls a tool is a single event, so the prose was discarded.
  3. Results not surfaced — same kind problem: Paseo only pulls rawOutput into the row for known kinds; for other the detail becomes unknown with no summary.

Fix

  • New toolKind(name) maps tool names to ACP kinds: exact for the built-in file tools (read, create, edit, insert), name-shape for MCP tools (terminal/exec/run → execute, search/grep/query → search, fetch/http/url → fetch, read/get/list/inspect/capture → read, write verbs → edit). Unknown tools carry no kind, so Paseo falls back to the humanized tool name ("List providers") instead of "Other".
  • eventText/eventThought no longer require a final response, so a tool-calling turn's narrative streams to the client. The live loop skips only text-only user events — ADK stamps tool-response events with the user role, so a bare role check would drop their completed updates.
  • Session replay benefits too: stored intermediate model responses now re-stream their prose.

Tests

  • New e2e test (TestACPToolCallsStreamKindAndNarrative) drives a real tool-calling turn through the Responses-API mock and asserts the start kind, the completed update, and the interleaved prose.
  • Table test pins the classifier (TestToolKind).

go test ./... and racedetector test ./internal/harness/ pass.

## Problem Every tool call brainless streams over ACP was labeled `kind=other`, so in Paseo's timeline the agent's activity rendered as a wall of anonymous **Other** rows: Paseo names the row from `snapshot.kind ?? snapshot.title` and shows no summary for the `other` kind. The model's prose between tool calls never appeared either, and results were not surfaced. Three root causes, all confirmed against the ACP SDK and Paseo's server: 1. **Hardcoded kind** — `notifyToolCalls` sent `acp.WithStartKind(acp.ToolKindOther)` for every function call. The ACP SDK defines `read` / `edit` / `delete` / `move` / `search` / `execute` / `think` / `fetch` / `switch_mode` kinds, and Paseo renders each as a recognizable Read / Edit / Search / Shell / Fetch row. 2. **Interleaved text dropped** — `eventText`/`eventThought` gated on `ev.IsFinalResponse()`, which ADK defines as **false for any event carrying function calls** (`session.go`). A model response that says "Let me check X" *and* calls a tool is a single event, so the prose was discarded. 3. **Results not surfaced** — same kind problem: Paseo only pulls `rawOutput` into the row for known kinds; for `other` the detail becomes `unknown` with no summary. ## Fix - New `toolKind(name)` maps tool names to ACP kinds: exact for the built-in file tools (`read`, `create`, `edit`, `insert`), name-shape for MCP tools (terminal/exec/run → execute, search/grep/query → search, fetch/http/url → fetch, read/get/list/inspect/capture → read, write verbs → edit). Unknown tools carry **no kind**, so Paseo falls back to the humanized tool name ("List providers") instead of "Other". - `eventText`/`eventThought` no longer require a final response, so a tool-calling turn's narrative streams to the client. The live loop skips only text-only user events — ADK stamps tool-response events with the user role, so a bare role check would drop their completed updates. - Session replay benefits too: stored intermediate model responses now re-stream their prose. ## Tests - New e2e test (`TestACPToolCallsStreamKindAndNarrative`) drives a real tool-calling turn through the Responses-API mock and asserts the start kind, the completed update, and the interleaved prose. - Table test pins the classifier (`TestToolKind`). `go test ./...` and `racedetector test ./internal/harness/` pass.
fix: surface tool calls and interleaved text in the ACP timeline
All checks were successful
code-review / Agent review (pull_request) Successful in 8s
ab18424786
Every function call was streamed to the client (Paseo) with kind
"other", so the timeline rendered a wall of anonymous "Other" rows:
Paseo names the row from snapshot.kind and renders no summary for the
"other" kind. Map tool names to ACP kinds instead - exact for the
built-in file tools (read/create/edit/insert), name-shape for MCP
tools (terminal/exec -> execute, search/grep/query -> search,
fetch/http/url -> fetch, read/get/list/inspect/capture -> read, write
verbs -> edit) - and omit the kind for unknown tools so the client
falls back to the tool name instead of "other".

The model's prose between tool calls never reached the client either:
eventText/eventThought gated on IsFinalResponse, which ADK defines as
false for any event carrying function calls, so the text from a
tool-calling turn was dropped. Stream text and thought from every
model event, skipping only text-only user events (ADK stamps
tool-response events with the user role, so a bare role check would
drop their completed updates).

Tests: e2e tool-call turn asserting the start kind, the completed
update, and the interleaved prose; table test pinning the classifier.
pi-reviewer left a comment

Review: fix: surface tool calls and interleaved text in the ACP timeline

Reviewed against the actual dependency sources (ADK v2.4.0, acp-go-sdk v0.13.5) in this session, not from memory. All claims below were verified by running commands in a worktree at head ab18424.

Pass 1 — Style / naming / docs

Clean. toolKind is well-documented, the classifier order is deliberate (Execute before Search/Fetch/Read/Edit) and pinned by tests. hasToolParts and the eventText doc update are accurate.

Pass 2 — Correctness / safety / error handling / concurrency

Root causes verified against ADK source:

  • session.Event.IsFinalResponse() (session/session.go:218) is !hasFunctionCalls && !hasFunctionResponses && !Partial && !hasTrailingCodeExecutionResult — confirmed the old gate dropped every tool-calling turn's prose.
  • Tool-response events are stamped Content.Role: "user" with FunctionResponse parts (internal/llminternal/base_flow.go), so hasToolParts correctly distinguishes them from the user's own text.
  • Instrumented the live run stream: exactly 3 events — model(text+function_call), user-role tool response, final model text — matching the new skip logic's expectations.
  • StartToolCall without WithStartKind leaves Kind empty and the wire field is json:"kind,omitempty", so the "no kind → client falls back to tool name" design is sound.

No blocking issues. go vet ./internal/harness/ clean, golangci-lint run 0 issues, go test ./internal/harness/ passes, racedetector test ./internal/harness/ finds no data races.

Pass 3 — Security / dependencies

No dependency changes (go.mod/go.sum identical to base). govulncheck ./internal/harness/ → 0 reachable vulnerabilities. Pre-existing (not introduced by this PR): indirect golang.org/x/crypto@v0.55.0 carries 3 module-level advisories — GO-2026-6355 and GO-2026-6354 (fixed in v0.56.0) and GO-2026-5932 (unmaintained openpgp) — none reachable from this code. Worth a separate dependency-bump PR.

Pass 4 — Tests / performance / observability

Tests are the strength of this PR: TestACPToolCallsStreamKindAndNarrative drives a realistic two-request tool-calling turn (message + function_call in one response, matching ADK's PopulateClientFunctionCallID id substitution) and asserts kind, completed update, and interleaved prose; TestToolKind pins the classifier. No perf concerns (toolKind runs once per function-call part).

Verdict: APPROVED

Two optional suggestions attached (delete/move → dedicated ACP kinds; the user-message skip guard is currently untriggered dead code). Neither blocks merge.

## Review: fix: surface tool calls and interleaved text in the ACP timeline Reviewed against the actual dependency sources (ADK v2.4.0, acp-go-sdk v0.13.5) in this session, not from memory. All claims below were verified by running commands in a worktree at head ab18424. ### Pass 1 — Style / naming / docs Clean. `toolKind` is well-documented, the classifier order is deliberate (Execute before Search/Fetch/Read/Edit) and pinned by tests. `hasToolParts` and the `eventText` doc update are accurate. ### Pass 2 — Correctness / safety / error handling / concurrency Root causes verified against ADK source: - `session.Event.IsFinalResponse()` (`session/session.go:218`) is `!hasFunctionCalls && !hasFunctionResponses && !Partial && !hasTrailingCodeExecutionResult` — confirmed the old gate dropped every tool-calling turn's prose. - Tool-response events are stamped `Content.Role: "user"` with FunctionResponse parts (`internal/llminternal/base_flow.go`), so `hasToolParts` correctly distinguishes them from the user's own text. - Instrumented the live run stream: exactly 3 events — model(text+function_call), user-role tool response, final model text — matching the new skip logic's expectations. - `StartToolCall` without `WithStartKind` leaves `Kind` empty and the wire field is `json:"kind,omitempty"`, so the "no kind → client falls back to tool name" design is sound. No blocking issues. `go vet ./internal/harness/` clean, `golangci-lint run` 0 issues, `go test ./internal/harness/` passes, `racedetector test ./internal/harness/` finds no data races. ### Pass 3 — Security / dependencies No dependency changes (`go.mod`/`go.sum` identical to base). `govulncheck ./internal/harness/` → 0 reachable vulnerabilities. Pre-existing (not introduced by this PR): indirect `golang.org/x/crypto@v0.55.0` carries 3 module-level advisories — GO-2026-6355 and GO-2026-6354 (fixed in v0.56.0) and GO-2026-5932 (unmaintained openpgp) — none reachable from this code. Worth a separate dependency-bump PR. ### Pass 4 — Tests / performance / observability Tests are the strength of this PR: `TestACPToolCallsStreamKindAndNarrative` drives a realistic two-request tool-calling turn (message + function_call in one response, matching ADK's `PopulateClientFunctionCallID` id substitution) and asserts kind, completed update, and interleaved prose; `TestToolKind` pins the classifier. No perf concerns (`toolKind` runs once per function-call part). ### Verdict: APPROVED Two optional suggestions attached (delete/move → dedicated ACP kinds; the user-message skip guard is currently untriggered dead code). Neither blocks merge.
@ -377,0 +379,4 @@
// echoed as an agent message. ADK also stamps tool-response events with
// the user role, so only text-only user events are skipped: tool
// responses carry function parts and must still reach notifyToolCalls.
if ev.Content != nil && ev.Content.Role == genai.RoleUser && !hasToolParts(ev.Content) {
Collaborator

🟡 SUGGESTION — this guard never fires in the current configuration. The ADK runner yields the user's own message only when runner.WithYieldUserMessage() is passed (verified in ADK v2.4.0: runner/run_node.go "if opts.yieldUserMessage && userEvent != nil" with runOptions.yieldUserMessage defaulting to false), and Prompt calls runner.Run without it. I instrumented the live stream for this exact turn: 3 events — model(text+function_call), user-role tool response, final model text — no user-message event. The guard is correct and cheap to keep (it prevents echo if the option is ever enabled), but today it is untested: the new e2e test passes identically without it. Either wire runner.WithYieldUserMessage() and assert the echo is suppressed, or trim the comment to state the guard only matters under that option.

🟡 SUGGESTION — this guard never fires in the current configuration. The ADK runner yields the user's own message only when `runner.WithYieldUserMessage()` is passed (verified in ADK v2.4.0: `runner/run_node.go` "if opts.yieldUserMessage && userEvent != nil" with `runOptions.yieldUserMessage` defaulting to false), and `Prompt` calls `runner.Run` without it. I instrumented the live stream for this exact turn: 3 events — model(text+function_call), user-role tool response, final model text — no user-message event. The guard is correct and cheap to keep (it prevents echo if the option is ever enabled), but today it is untested: the new e2e test passes identically without it. Either wire `runner.WithYieldUserMessage()` and assert the echo is suppressed, or trim the comment to state the guard only matters under that option.
@ -617,0 +649,4 @@
strings.Contains(lower, "inspect"), strings.Contains(lower, "capture"):
return acp.ToolKindRead
case strings.Contains(lower, "create"), strings.Contains(lower, "write"), strings.Contains(lower, "insert"),
strings.Contains(lower, "update"), strings.Contains(lower, "delete"), strings.Contains(lower, "move"),
Collaborator

🟡 SUGGESTION — delete and move are collapsed into acp.ToolKindEdit, but the ACP SDK defines dedicated kinds for exactly these verbs. Verified this session: go doc -all github.com/coder/acp-go-sdk.ToolKind → "const ( ToolKindRead ToolKind = "read" ... ToolKindDelete ToolKind = "delete" ToolKindMove ToolKind = "move" ... )". Returning the dedicated kinds costs nothing and gives Paseo distinct Delete/Move rows instead of folding them into Edit. Fix:

case strings.Contains(lower, "delete"):
    return acp.ToolKindDelete
case strings.Contains(lower, "move"), strings.Contains(lower, "rename"):
    return acp.ToolKindMove

Also add {"delete", acp.ToolKindDelete} and {"move", acp.ToolKindMove} rows to TestToolKind (harness_test.go) to pin the mapping.

🟡 SUGGESTION — `delete` and `move` are collapsed into `acp.ToolKindEdit`, but the ACP SDK defines dedicated kinds for exactly these verbs. Verified this session: `go doc -all github.com/coder/acp-go-sdk.ToolKind` → "const ( ToolKindRead ToolKind = "read" ... ToolKindDelete ToolKind = "delete" ToolKindMove ToolKind = "move" ... )". Returning the dedicated kinds costs nothing and gives Paseo distinct Delete/Move rows instead of folding them into Edit. Fix: ```go case strings.Contains(lower, "delete"): return acp.ToolKindDelete case strings.Contains(lower, "move"), strings.Contains(lower, "rename"): return acp.ToolKindMove ``` Also add `{"delete", acp.ToolKindDelete}` and `{"move", acp.ToolKindMove}` rows to `TestToolKind` (harness_test.go) to pin the mapping.
Addresses PR #19 review: the ACP SDK defines ToolKindDelete and
ToolKindMove, so folding them into ToolKindEdit threw away distinct
Delete/Move rows in the client timeline. delete -> delete; move and
rename -> move. Test rows pin the mapping.
Author
Collaborator

Review suggestions resolved in 21f9e87:

  • Comment 700 (delete/move kinds) — toolKind now maps delete → ToolKindDelete and move/rename → ToolKindMove (dedicated ACP kinds), with TestToolKind rows pinning all three.
  • Comment 701 (user-message skip guard) — kept the guard (prevents a prompt echo if runner.WithYieldUserMessage() is ever enabled) and trimmed its comment to state it only fires under that option; Prompt does not pass it today.

Both threads auto-mark stale on the head change; there is no resolve-comment API route on this Forgejo (POST/PUT /repos/sam/brainless/pulls/comments/{id}/resolve → 405), so this comment is the resolution record. go test ./... and golangci-lint run pass on the new head.

Review suggestions resolved in 21f9e87: - **Comment 700 (delete/move kinds)** — `toolKind` now maps `delete` → `ToolKindDelete` and `move`/`rename` → `ToolKindMove` (dedicated ACP kinds), with `TestToolKind` rows pinning all three. - **Comment 701 (user-message skip guard)** — kept the guard (prevents a prompt echo if `runner.WithYieldUserMessage()` is ever enabled) and trimmed its comment to state it only fires under that option; `Prompt` does not pass it today. Both threads auto-mark stale on the head change; there is no resolve-comment API route on this Forgejo (POST/PUT `/repos/sam/brainless/pulls/comments/{id}/resolve` → 405), so this comment is the resolution record. `go test ./...` and `golangci-lint run` pass on the new head.
sam merged commit a642512b91 into main 2026-10-03 11:35:15 +00:00
sam deleted branch fix/acp-tool-call-surfacing 2026-10-03 11:35:15 +00:00
Sign in to join this conversation.
No reviewers
No labels
code-review
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
sam/brainless!19
No description provided.