From ce6999e0ee386785e7016e4681ffa70ebde11441 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Wed, 14 Oct 2026 10:29:58 +0000 Subject: [PATCH 1/2] [Automated] Draft docs (kagent): feat(sandbox): read_sandbox_file returns text pages and images Signed-off-by: GitHub Action --- .../1.x/about/substrate-runtime/standalone-sandboxes.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs-site/content/kagent/1.x/about/substrate-runtime/standalone-sandboxes.md b/docs-site/content/kagent/1.x/about/substrate-runtime/standalone-sandboxes.md index d562000b..4c532b10 100644 --- a/docs-site/content/kagent/1.x/about/substrate-runtime/standalone-sandboxes.md +++ b/docs-site/content/kagent/1.x/about/substrate-runtime/standalone-sandboxes.md @@ -165,7 +165,9 @@ tools: An agent that creates a Sandbox owns it under whatever identity the MCP connection authenticated, not under the identity of the person it is talking to. A Session share token grants no access to a Sandbox. To have an agent act for the person who invoked it, configure credential propagation. The Go kagent runtime reads `KAGENT_PROPAGATE_TOKEN=true` to pass the caller's credentials and identity to the MCP servers that you trust. -The MCP transfer limits are tighter than the command line's. A gRPC file transfer is bounded at 64 MiB. An MCP transfer or output read is bounded at 1 MiB, encodes bytes as base64, and returns a continuation offset for reading more. +The MCP transfer limits are tighter than the command line's. A gRPC file transfer is bounded at 64 MiB. `write_sandbox_file` and `read_sandbox_outputs` are bounded at 1 MiB and use base64. Output reads return continuation byte offsets. + +Use `read_sandbox_file` when an agent must inspect a result file. Unlike `write_sandbox_file` and `read_sandbox_outputs`, `read_sandbox_file` returns model-readable content instead of `data_base64`. Text comes back as numbered lines, with `offset` and `limit` for paging. By default, a text page contains 2000 lines and stops at 32 KiB. A line longer than 2000 bytes is cut. PNG, JPEG, and GIF files up to 10 MiB return as images that the Claude and Codex harnesses can pass to their models. Other file types return a description instead of bytes. ## Next steps From c45bd36d0e71ed2a9acb972302c0dc9bf13d4583 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Wed, 14 Oct 2026 10:17:40 -0500 Subject: [PATCH 2/2] Apply review fixes to the read_sandbox_file paragraph Verified every number against the merged kagent#3120: maxSandboxPageBytes, maxSandboxImageBytes, defaultSandboxReadLines, and maxSandboxLineBytes in go/core/internal/mcp/sandboxes.go. The draft's figures were right; its precision and coverage were not. - A page holds at most 2000 lines, not exactly 2000. The draft read as wrong for any file shorter than a page. - "A line longer than 2000 bytes is cut" left the reader unable to tell a dropped line from a truncated one. The code truncates to 2000 bytes and appends a [line cut] marker. - Paging was undocumented where it matters: offset is a 1-based line number, and a short page reports the offset to continue from. Naming offset and limit without either fact does not let a reader page. - An image over 10 MiB returns a message asking for a smaller copy. The draft's "other file types return a description" did not cover it. - Condition before command, per ste.md: the trailing "when" clause moves to the front of the sentence. - Dropped the "Unlike write_sandbox_file and read_sandbox_outputs" clause, which restated the contrast the preceding paragraph drew. - Split the seven-sentence block into three paragraphs, one per result shape. Added the three file tools to the tool-binding example above, which listed only lifecycle tools and so named none of the tools this section discusses. Co-Authored-By: Claude Opus 5 (1M context) Signed-off-by: Rachael Graham --- .../1.x/about/substrate-runtime/standalone-sandboxes.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs-site/content/kagent/1.x/about/substrate-runtime/standalone-sandboxes.md b/docs-site/content/kagent/1.x/about/substrate-runtime/standalone-sandboxes.md index 4c532b10..ee0dc1e2 100644 --- a/docs-site/content/kagent/1.x/about/substrate-runtime/standalone-sandboxes.md +++ b/docs-site/content/kagent/1.x/about/substrate-runtime/standalone-sandboxes.md @@ -161,13 +161,20 @@ tools: - list_sandbox_templates - create_sandbox - list_sandboxes + - write_sandbox_file + - read_sandbox_file + - read_sandbox_outputs ``` An agent that creates a Sandbox owns it under whatever identity the MCP connection authenticated, not under the identity of the person it is talking to. A Session share token grants no access to a Sandbox. To have an agent act for the person who invoked it, configure credential propagation. The Go kagent runtime reads `KAGENT_PROPAGATE_TOKEN=true` to pass the caller's credentials and identity to the MCP servers that you trust. The MCP transfer limits are tighter than the command line's. A gRPC file transfer is bounded at 64 MiB. `write_sandbox_file` and `read_sandbox_outputs` are bounded at 1 MiB and use base64. Output reads return continuation byte offsets. -Use `read_sandbox_file` when an agent must inspect a result file. Unlike `write_sandbox_file` and `read_sandbox_outputs`, `read_sandbox_file` returns model-readable content instead of `data_base64`. Text comes back as numbered lines, with `offset` and `limit` for paging. By default, a text page contains 2000 lines and stops at 32 KiB. A line longer than 2000 bytes is cut. PNG, JPEG, and GIF files up to 10 MiB return as images that the Claude and Codex harnesses can pass to their models. Other file types return a description instead of bytes. +When an agent must inspect a result file, use `read_sandbox_file`. The tool returns content that the model reads directly rather than `data_base64`, in one of three shapes. + +Text returns as numbered lines. `offset` takes the first line to read, counting from 1, and `limit` takes the number of lines, which defaults to 2000. A page also stops at 32 KiB, whichever bound it reaches first. A line longer than 2000 bytes is truncated to 2000 bytes and marked `[line cut]`. A page that stops before the end of the file reports the offset to continue from. + +A PNG, JPEG, or GIF file of at most 10 MiB returns as an image. The Claude and Codex harnesses resize those images for their models. A larger image returns a message asking the agent to write a smaller copy in the Sandbox. Every other file type returns a description of the file rather than its bytes. ## Next steps