feat: relay streamed reasoning, render tool params, add execute tool #34
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!34
Loading…
Reference in a new issue
No description provided.
Delete branch "aquatic-shark"
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?
Fixes three operator-visible gaps in brainless:
Read params were invisible in the timeline. The ACP tool-call payload carried the model's
head/tailargs and{"output": ...}results, but clients render a read fromrawInput.offset/limitand result text from acontentkey, so the Paseo timeline showed a barereadwith no line range and no content. Built-in read calls now mirror head/tail as offset/limit (plus the standard locations entry) and all built-in tool results carry acontentkey alongsideoutput. Model-facing schemas are unchanged.Reasoning blocks never rendered.
Promptskipped every partial event, and reasoning models (melious's Responses path) deliver thinking only as streamed deltas — the terminal response omits it — so reasoning was dropped entirely. Thought deltas are now relayed live asagent_thought_chunkupdates (Paseo coalesces consecutive chunks into one block). Answer-text deltas stay buffered until the round's final event confirms the turn survived, preserving the budget-crossing guarantee (no partially delivered answer marked cancelled).No built-in command tool. Added an always-visible
execute(command, cwd?, timeout?)tool: runssh -cin the session working directory, returns combined output + exit code as data, caps output at 100 KiB, and bounds runtime (default 30s, max 300s) by killing the whole process group so orphaned grandchildren can't holdWaitopen.Tests: new e2e coverage for streamed reasoning (
TestACPPromptStreamsReasoningDeltas) and read param rendering (TestACPToolCallReadParamsRenderable), plus an execute-tool suite.go test -race ./...andgolangci-lint runare clean.Known limitation (deliberately out of scope): the chat-completions fallback path still cannot surface reasoning — ADK's openaimodel reads chat-completions responses for text/refusals/tool calls only, and
reasoning_contentisn't in openai-go's types. The primary Responses path is fixed.AI code review of PR #34 (feat: relay streamed reasoning, render tool params, add execute tool), head
7a8ed6d.Verified in this session (checkout at head, Go 1.27.1):
go build ./...,go vet ./...,go test ./...,go test -race ./internal/tools ./internal/harness, andgolangci-lint run ./internal/tools ./internal/harness(0 issues) are all clean — the PR's test claims hold. New coverage is good:TestACPPromptStreamsReasoningDeltas,TestACPToolCallReadParamsRenderable, and the execute-tool suite exercise the new paths with real servers.No blocking security/safety/concurrency findings. Claims I checked and cleared rather than trusting memory:
cappedBufferbetweencmd.Stdout/cmd.Stderris NOT a data race: os/exec documents "If Stdout and Stderr are the same writer ... at most one goroutine at a time will call Write" (/usr/local/go/src/os/exec/exec.go:233), and a-racerun of a command hammering both pipes concurrently is clean.errors.AsType[*exec.ExitError]andacp.ToolKindExecuteare valid for this module (go 1.27.1, acp-go-sdk v0.13.5).WithUpdateRawOutputoptions innotifyToolCallsare safe: acp-go-sdk applies options in order and each sets the field (last wins).Findings (1 IMPORTANT + 3 SUGGESTION, all in new code):
internal/tools/exec.go:206: truncation note is skipped when the output cap is filled exactly and more bytes arrive (reproduced with a failing test).internal/tools/exec.go:108: timeout duration overflows for absurdtimeoutvalues (>= ~292 years), killing the command instantly.internal/harness/harness.go:1089:bufferedTextis write-only dead state — written and reset, never read.internal/tools/exec.go:115:executeinherits the full process environment (model can read every env var); informational under the documented trusted-ACP posture.Dependency note: no
go.mod/go.sumchanges in this PR.govulncheck ./...reports 9 stdlib vulnerabilities, but all are pre-existing on base main (call stacks areatomic_file.go,mcp.go,uuid— none in the new code). Not introduced here; worth a separate cleanup.Requesting changes for the verified truncation defect; the suggestion items are optional improvements.
@ -1006,0 +1086,4 @@}if text != "" {_, _ = bufferedText.WriteString(text)SUGGESTION —
bufferedTextis write-only dead state: it is written here andReset()in three places (lines 816, 870, 881) but never read — the client's answer text comes from the final event'seventText, not from the buffer (verified by grep: noString()/Len()call on it). The comment ("Answer text was buffered ... so the final event carries it whole") describes a mechanism that does not exist; behavior is still correct because the deltas are simply discarded. Either drop the parameter and its writes, or actually consult the buffer (e.g. apply the same prefix-extension dedupunstreameddoes for thoughts) so the code matches the comment.@ -0,0 +105,4 @@timeout := execTimeoutif args.Timeout > 0 {timeout = min(time.Duration(args.Timeout)*time.Second, maxExecTimeout)SUGGESTION —
time.Duration(args.Timeout)*time.Secondoverflows fortimeout>= 9_223_372_037 seconds (~292 years): the product wraps negative,minkeeps the negative duration, andcontext.WithTimeoutwith a negative duration is already expired — the command is killed immediately instead of running. Verified withgo run:Timeout=9223372037 -> -2562047h47m16.709551616s. Not exploitable (a model asking for 292-year timeouts is already broken), but the clamp is cheaper in seconds:timeout = min(time.Duration(args.Timeout), maxExecTimeout/time.Second) * time.Second.@ -0,0 +112,4 @@defer cancel()//nolint:gosec // G204: this tool's entire purpose is running the model's command for the operator's own agent.cmd := exec.Command("sh", "-c", args.Command)SUGGESTION —
cmd.Envis unset, soshinherits the harness's full process environment (go doc os/exec.Cmd.Env: "If Env is nil, the new process uses the current process's environment"). The model can now read every env var (provider keys, tokens) viaenv— a capability the previous built-in set (file/fetch/memory) did not have. Consistent with the documented trusted-ACP posture (README "It can reach anything the paseo user can"), so informational: consider filteringcmd.Envor adding a config toggle for lower-trust deployments, and acknowledge env disclosure in the README's trust section.@ -0,0 +203,4 @@// close the pipe on the child, killing it with SIGPIPE.written := len(data)if n := w.cap - w.buf.Len(); n > 0 {IMPORTANT — the truncation note is skipped when the cap is reached by an exact fill and more bytes arrive.
w.truncated = trueis only set inside then > 0branch (if len(data) > n), so oncecap - buf.Len() == 0the tail is dropped without setting the flag;String()then returns output without the[... output truncated ...]marker. Reproduced this session withgo test -run TestTruncReproExactFillThenTail ./internal/tools/on acappedBuffer{cap: 100}written with 100 bytes then "tail": FAIL — "missing truncation note". Condition: combined stdout+stderr output >= 100 KiB where no single write straddles the boundary (common with fixed-size chunked writers, e.g.dd bs=1k count=100+ a trailing write). The model then treats truncated output as complete, and the README's "Output is capped at 100 KiB with a truncation note" contract is violated. Fix: setw.truncated = truewhenever bytes are dropped, including then <= 0case (guardingwritten > 0so zero-length writes don't flag).Submitting with REQUEST_CHANGES: one verified IMPORTANT correctness defect in the new execute tool's truncation reporting (reproduced with a failing test under
go test -race; no blocking security/safety/concurrency issues found). The three SUGGESTION items are optional.@ -1006,0 +1086,4 @@}if text != "" {_, _ = bufferedText.WriteString(text)SUGGESTION —
bufferedTextis write-only dead state: it is written here andReset()in three places (lines 816, 870, 881) but never read — the client's answer text comes from the final event'seventText, not from the buffer (verified by grep: noString()/Len()call on it). The comment ("Answer text was buffered ... so the final event carries it whole") describes a mechanism that does not exist; behavior is still correct because the deltas are simply discarded. Either drop the parameter and its writes, or actually consult the buffer (e.g. apply the same prefix-extension dedupunstreameddoes for thoughts) so the code matches the comment.@ -0,0 +105,4 @@timeout := execTimeoutif args.Timeout > 0 {timeout = min(time.Duration(args.Timeout)*time.Second, maxExecTimeout)SUGGESTION —
time.Duration(args.Timeout)*time.Secondoverflows fortimeout>= 9_223_372_037 seconds (~292 years): the product wraps negative,minkeeps the negative duration, andcontext.WithTimeoutwith a negative duration is already expired — the command is killed immediately instead of running. Verified withgo run:Timeout=9223372037 -> -2562047h47m16.709551616s. Not exploitable (a model asking for 292-year timeouts is already broken), but the clamp is cheaper in seconds:timeout = min(time.Duration(args.Timeout), maxExecTimeout/time.Second) * time.Second.@ -0,0 +112,4 @@defer cancel()//nolint:gosec // G204: this tool's entire purpose is running the model's command for the operator's own agent.cmd := exec.Command("sh", "-c", args.Command)SUGGESTION —
cmd.Envis unset, soshinherits the harness's full process environment (go doc os/exec.Cmd.Env: "If Env is nil, the new process uses the current process's environment"). The model can now read every env var (provider keys, tokens) viaenv— a capability the previous built-in set (file/fetch/memory) did not have. Consistent with the documented trusted-ACP posture (README "It can reach anything the paseo user can"), so informational: consider filteringcmd.Envor adding a config toggle for lower-trust deployments, and acknowledge env disclosure in the README's trust section.@ -0,0 +203,4 @@// close the pipe on the child, killing it with SIGPIPE.written := len(data)if n := w.cap - w.buf.Len(); n > 0 {IMPORTANT — the truncation note is skipped when the cap is reached by an exact fill and more bytes arrive.
w.truncated = trueis only set inside then > 0branch (if len(data) > n), so oncecap - buf.Len() == 0the tail is dropped without setting the flag;String()then returns output without the[... output truncated ...]marker. Reproduced this session withgo test -run TestTruncReproExactFillThenTail ./internal/tools/on acappedBuffer{cap: 100}written with 100 bytes then "tail": FAIL — "missing truncation note". Condition: combined stdout+stderr output >= 100 KiB where no single write straddles the boundary (common with fixed-size chunked writers, e.g.dd bs=1k count=100+ a trailing write). The model then treats truncated output as complete, and the README's "Output is capped at 100 KiB with a truncation note" contract is violated. Fix: setw.truncated = truewhenever bytes are dropped, including then <= 0case (guardingwritten > 0so zero-length writes don't flag).Review findings resolved in
2d5571c:cappedBuffer.Writenow flagstruncatedwhen a write is dropped because the cap was already full, so an exact fill + trailing write always yields the[... output truncated ...]marker. Regression test:TestCappedBufferFlagsTruncationOnExactFill.min(args.Timeout, maxExecTimeout/time.Second)) before converting totime.Duration, so huge ints can't wrap negative into an already-expired context. Regression test:TestExecClampsHugeTimeout.bufferedText) — removed the write-only buffer and its resets; comments now state that answer-text deltas are dropped and the round's final event carries the whole answer. No behavior change (deltas were already discarded).go test -race ./...(both packages) andgolangci-lint runare clean (0 issues).Superseded by #35 (same commits, conventional head branch
feat/relay-streamed-reasoning). Review comments from this PR remain here for reference; all findings are resolved in2d5571c.Pull request closed