fix: surface tool calls and interleaved text in the ACP timeline #19
No reviewers
Labels
No labels
code-review
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
sam/brainless!19
Loading…
Reference in a new issue
No description provided.
Delete branch "fix/acp-tool-call-surfacing"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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 fromsnapshot.kind ?? snapshot.titleand shows no summary for theotherkind. 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:
notifyToolCallssentacp.WithStartKind(acp.ToolKindOther)for every function call. The ACP SDK definesread/edit/delete/move/search/execute/think/fetch/switch_modekinds, and Paseo renders each as a recognizable Read / Edit / Search / Shell / Fetch row.eventText/eventThoughtgated onev.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.rawOutputinto the row for known kinds; forotherthe detail becomesunknownwith no summary.Fix
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/eventThoughtno 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.Tests
TestACPToolCallsStreamKindAndNarrative) drives a real tool-calling turn through the Responses-API mock and asserts the start kind, the completed update, and the interleaved prose.TestToolKind).go test ./...andracedetector test ./internal/harness/pass.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.
toolKindis well-documented, the classifier order is deliberate (Execute before Search/Fetch/Read/Edit) and pinned by tests.hasToolPartsand theeventTextdoc 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.Content.Role: "user"with FunctionResponse parts (internal/llminternal/base_flow.go), sohasToolPartscorrectly distinguishes them from the user's own text.StartToolCallwithoutWithStartKindleavesKindempty and the wire field isjson:"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 run0 issues,go test ./internal/harness/passes,racedetector test ./internal/harness/finds no data races.Pass 3 — Security / dependencies
No dependency changes (
go.mod/go.sumidentical to base).govulncheck ./internal/harness/→ 0 reachable vulnerabilities. Pre-existing (not introduced by this PR): indirectgolang.org/x/crypto@v0.55.0carries 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:
TestACPToolCallsStreamKindAndNarrativedrives a realistic two-request tool-calling turn (message + function_call in one response, matching ADK'sPopulateClientFunctionCallIDid substitution) and asserts kind, completed update, and interleaved prose;TestToolKindpins the classifier. No perf concerns (toolKindruns 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) {🟡 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" withrunOptions.yieldUserMessagedefaulting to false), andPromptcallsrunner.Runwithout 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 wirerunner.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.ToolKindReadcase strings.Contains(lower, "create"), strings.Contains(lower, "write"), strings.Contains(lower, "insert"),strings.Contains(lower, "update"), strings.Contains(lower, "delete"), strings.Contains(lower, "move"),🟡 SUGGESTION —
deleteandmoveare collapsed intoacp.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:Also add
{"delete", acp.ToolKindDelete}and{"move", acp.ToolKindMove}rows toTestToolKind(harness_test.go) to pin the mapping.Review suggestions resolved in
21f9e87:toolKindnow mapsdelete→ToolKindDeleteandmove/rename→ToolKindMove(dedicated ACP kinds), withTestToolKindrows pinning all three.runner.WithYieldUserMessage()is ever enabled) and trimmed its comment to state it only fires under that option;Promptdoes 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 ./...andgolangci-lint runpass on the new head.