mirror of
https://github.com/Twigpine/zero.git
synced 2026-11-10 13:11:31 -10:00
Vasanth TandClaude Opus 5
cd0eb194e4
* feat(tools): give tool results an image channel and add view_image Closes #824. tools.Result carried only text, so no tool could hand the model a picture. The sharpest edge was our own capture tooling: browser_screenshot, desktop_screenshot and browser_pdf wrote a PNG, set Meta["artifact_path"] and returned "Artifact captured: <path>". Nothing read that path afterwards, so the model asked for a screenshot, was told one existed, and could not look at it. Zero was never image-blind on the way in — zeroruntime.ImageBlock, Message.Images and internal/imageinput are mature. What was missing is the model-initiated leg. Result.Images is delivered as a following USER message, not on the tool result itself. Every provider drops images on a tool-role message: Anthropic maps a tool result to a tool_result block whose content is a string, Gemini to a functionResponse, and OpenAI guards its image content-parts to the user role with an explicit comment saying so. Attaching them to the tool result would have plumbed the whole path and delivered nothing. A separate message also keeps one tool result per tool call, which the providers validate. Blocks with no data, or a media type outside the provider allow-list, are dropped rather than sent — a rejected image would fail the whole turn, and the tool's text still stands on its own. The message names the tool, since the images arrive detached from their result and nothing else says which call produced them when several ran in one turn. view_image resolves through resolveScopedReadPath before imageinput.LoadFile. That scoping is load-bearing: LoadFile joins a relative path to the workspace root and otherwise takes the path as given, so without it the tool would read anywhere on disk. It is registered with the other scoped readers and declared read-only and thread-safe, matching read_file. The capture tools now attach what they wrote. A PDF or an unreadable file yields no image and the text stands alone, so a capture is never failed over its attachment. Co-Authored-By: Claude Opus 5 <[email protected]> * fix(agent): keep tool results contiguous when a tool returns an image The image messages are user-role, and the first version appended each one immediately after its own tool result. With two tool calls in a turn that produces tool_result, user, tool_result — and a user message between two tool results breaks strict provider replay. Anthropic makes it concrete. appendUserBlocks coalesces consecutive user content into one block list, and tool_result blocks must come first in that message, so the interleaved shape maps to: [tool_result, text, image, tool_result] which the API rejects. loop.go already documents this exact rule three lines below the change, for the self-correction feedback it defers for the same reason. Images are now collected during the tool loop and appended once every tool_result is recorded — including the aborted placeholders on the abort, stop-reason and repeated-failure paths, so an early exit cannot strand them mid-sequence either. The original test used a single tool call, which cannot exhibit the bug. The new one runs two calls where the first returns an image and asserts the image message does not fall between the first and last tool result. Also from review: view_image joins the "execute" tool category, which grants read_file but not view_image, so a specialist declared with tools: [execute] could not look at a screenshot it had just captured. Covered by a test that holds for every category granting read_file rather than naming one. And the core read-only set is now asserted by tool name, not only by count — a count still passes when one reader is swapped for another. Co-Authored-By: Claude Opus 5 <[email protected]> * test(agent): pin the tool-result/image ordering contract The assertions only tracked the first and last tool-result index, so four distinct broken orderings passed: a message wedged between the two tool results, a duplicated image flush, a duplicated tool result, and both results answering the same tool_call_id. Mutation-testing each of those against the real loop confirmed the old assertions were green on all four. Now it collects every tool-result index and id and requires exactly two, in c1-then-c2 order, at adjacent indexes, with the image following the last one and delivered exactly once. Adjacency is the assertion that carries the contract: Anthropic needs every tool_result block ahead of any other block in the user message they coalesce into, so anything between the two results is the 400 this change exists to avoid. The image is deliberately NOT pinned to exactly last+1. appendUserBlocks merges consecutive user-role content, so [tool_result, tool_result, text, image] maps to tool_result blocks first and replays fine; pinning would fail that valid shape while killing nothing the adjacency and count assertions do not already catch. messageShape reports the actual role ordering on failure, and the loop uses two ifs rather than a switch so an image left on a tool-role message is reported as the misplacement it is instead of "the image never reached the model". --------- Co-authored-by: Claude Opus 5 <[email protected]>
81 lines
3.1 KiB
Go
81 lines
3.1 KiB
Go
package tools
|
|
|
|
import (
|
|
"context"
|
|
|
|
"github.com/Gitlawb/zero/internal/imageinput"
|
|
"github.com/Gitlawb/zero/internal/zeroruntime"
|
|
)
|
|
|
|
// ViewImageToolName is the canonical registry name of the image viewer.
|
|
const ViewImageToolName = "view_image"
|
|
|
|
// NewViewImageTool builds the workspace-scoped image viewer.
|
|
func NewViewImageTool(workspaceRoot string) Tool {
|
|
return NewScopedViewImageTool(workspaceRoot, nil)
|
|
}
|
|
|
|
// NewScopedViewImageTool builds the image viewer bound to a path scope.
|
|
//
|
|
// The scope is not optional decoration. imageinput.LoadFile resolves a relative
|
|
// path by joining it to the workspace root and otherwise takes the path as
|
|
// given, so on its own it would happily read outside the workspace. Every path
|
|
// goes through resolveScopedReadPath first, exactly like read_file, so this tool
|
|
// grants no reach that read_file does not already have.
|
|
func NewScopedViewImageTool(workspaceRoot string, scope PathScope) Tool {
|
|
return viewImageTool{
|
|
baseTool: baseTool{
|
|
name: ViewImageToolName,
|
|
description: "Look at an image file. Use this to see a screenshot, diagram, mockup or photo " +
|
|
"the user mentioned but did not attach, or one a previous tool wrote to disk. " +
|
|
"Accepts PNG, JPEG, GIF and WebP up to 10 MiB.",
|
|
parameters: Schema{
|
|
Type: "object",
|
|
Properties: map[string]PropertySchema{
|
|
"path": {Type: "string", Description: "Path of the image to look at."},
|
|
},
|
|
Required: []string{"path"},
|
|
AdditionalProperties: false,
|
|
},
|
|
safety: readOnlySafety("Reads an image file without modifying anything."),
|
|
// Same shape as read_file: reads one file, mutates nothing, and is
|
|
// safe to run concurrently.
|
|
capabilities: ToolCapabilities{Effect: EffectReadOnly, ThreadSafe: true, ResourceKeys: fileResourceKeys},
|
|
},
|
|
workspaceRoot: workspaceRoot,
|
|
scope: scope,
|
|
}
|
|
}
|
|
|
|
type viewImageTool struct {
|
|
baseTool
|
|
workspaceRoot string
|
|
scope PathScope
|
|
}
|
|
|
|
func (tool viewImageTool) Run(_ context.Context, args map[string]any) Result {
|
|
requestedPath, err := aliasedStringArg(args, []string{"path", "file", "file_path", "filepath", "filename", "image"}, "", true, false)
|
|
if err != nil {
|
|
return errorResult("Error: Invalid arguments for " + ViewImageToolName + ": " + err.Error())
|
|
}
|
|
absolutePath, relativePath, err := resolveScopedReadPath(tool.workspaceRoot, tool.scope, requestedPath)
|
|
if err != nil {
|
|
return errorResult("Error: " + err.Error())
|
|
}
|
|
image, err := imageinput.LoadFile(absolutePath, tool.workspaceRoot)
|
|
if err != nil {
|
|
// LoadFile's errors already name the problem (missing, too large,
|
|
// unsupported type) and are safe to show: they carry the path the caller
|
|
// asked for, which it already knows.
|
|
return errorResult("Error viewing " + relativePath + ": " + err.Error())
|
|
}
|
|
return Result{
|
|
Status: StatusOK,
|
|
// The text says what arrived; the image itself reaches the model through
|
|
// the agent loop, which delivers Images on a following user message.
|
|
Output: "Viewing " + relativePath + " (" + image.MediaType + ").",
|
|
Images: []zeroruntime.ImageBlock{image},
|
|
Meta: map[string]string{"media_type": image.MediaType},
|
|
}
|
|
}
|