Lightpanda: the headless browser designed for AI and automation
tools: trim the download tool's docs and comments, report the wire status text
coolswood6f35d309884b
diff --git a/src/browser/tools.zig b/src/browser/tools.zigindex b1d097186..bcd6793a4 100644--- a/src/browser/tools.zig+++ b/src/browser/tools.zig@@ -70,9 +70,6 @@ pub const driver_guidance =\\ `goto` then `markdown` — a standalone `goto` is an extra page load and\\ an extra round-trip for no added information. (`extract` reads the\\ current page only, so navigate with one of the above first.)- \\- `download {url, path}` → save a response body to a file with the- \\ session's cookies. The way to get binary or oversized content (PDF,- \\ spreadsheet, archive) out of the browser — text tools can't return it.\\\\Workflow:\\- Inspect before interacting (tree / interactiveElements /@@ -392,7 +389,7 @@ pub const Tool = enum {.click, .fill, .scroll, .hover, .press, .selectOption, .setChecked => .interaction,.waitForSelector, .waitForScript, .waitForState => .waiting,.getUrl, .getCookies, .getEnv, .consoleLogs => .state,- .download => .downloading,+ .download => .navigation,};}@@ -403,7 +400,6 @@ pub const Tool = enum {interaction,waiting,state,- downloading,};/// Per-tool LLM-facing metadata. Tool identity (name + predicates) lives@@ -812,7 +808,7 @@ pub const Tool = enum {),},.download => .{- .description = "Fetch a URL and save the response body to a local file, sending the session's cookies so authenticated sites work. The way to get a binary or large document (PDF, spreadsheet, archive) out of the browser: text tools can't return it, and `evaluate`'s in-page fetch cannot read cross-origin responses. The request goes through the same pipeline as a page load — redirects, `--http-proxy`, TLS and `--block-urls` settings all apply, cookies attach per hop from the session's jar, and Set-Cookie from every response (redirect steps included) updates it. SameSite is judged from the current page, so downloading from the site the session is logged into carries its session cookies; from an unrelated origin, per cookie rules, it may not. Nothing is written for a non-2xx response — a file already at `path` survives a failed download — and the failure reports the HTTP status. The result line names the saved file's absolute path, byte size and content type.",+ .description = "Fetch a URL and save the response body to a local file, sending the session's cookies so authenticated sites work. The way to get a binary or large document (PDF, spreadsheet, archive) out of the browser. Nothing is saved for a non-2xx response. Requires a loaded page — it fails before the first `goto`.",.summary = "Fetch a URL with the session's cookies into a file",.input_schema = minify(\\{@@ -2688,9 +2684,7 @@ fn execGetCookies(arena: std.mem.Allocator, session: *lp.Session, arguments: ?st}/// Generous, unlike the read tools' 10s: the body is the payload, and a slow-/// multi-megabyte PDF is a successful download, not a timeout. The cap rides-/// the transfer (curl's overall timeout), and since the body is buffered-/// before the file is written, a timed-out download leaves nothing behind.+/// multi-megabyte PDF is a successful download, not a timeout.const default_download_timeout_ms: u32 = 120_000;const DownloadParams = struct {@@ -2702,15 +2696,12 @@ fn execDownload(arena: std.mem.Allocator, session: *lp.Session, arguments: ?std.const args = try parseArgs(DownloadParams, arena, arguments);if (!isPathSafe(args.path)) return .{ .text = unsafe_path_message, .is_error = true };- // Like `search`: refuse up front what the browser would refuse anyway —- // the pipeline would too, but with a bare UrlBlocked error.if (session.browser.http_client.blocksUrl(args.url)) {return .{ .text = "url is refused by --block-urls", .is_error = true };}- // The frame owns the transfer: it attributes the request to the page for- // CDP, and its scope supplies the cookie jar the download authenticates- // with. The current page is also what SameSite judges the request by.+ // Nothing renders, but the frame owns the cookie jar the download+ // authenticates with, and attributes the request to the page for CDP.const frame = try requireFrame(session);const transfer = frame.newRequest(.{@@ -2733,18 +2724,16 @@ fn execDownload(arena: std.mem.Allocator, session: *lp.Session, arguments: ?std.},};{- // The transfer dies inside submitSync, one way or the other: on the- // early-bail paths it deinits itself, and once submitted the client- // deinits it at delivery. Only a failure before the submit is ours.+ // Only a pre-submit failure is ours: past the submit, the client+ // deinits the transfer at delivery.errdefer transfer.deinit();try transfer.setHeader("Accept", lp.Config.HttpHeaders.navigation_accept, .{});// A Referer from the current page, like a download launched from it.try frame.headersForRequest(transfer, .{});}- // Pumps the session inline. Other transfers' callbacks for this frame are- // held back until the fetch settles, so nothing runs JS under us; a page- // or session teardown mid-fetch surfaces as an error here.+ // Pumps the session inline: other transfers' callbacks for this frame are+ // held back until the fetch settles, so nothing runs JS under us.var response = transfer.submitSync(.{}) catch |err| switch (err) {error.OutOfMemory => return error.OutOfMemory,error.ClientDisconnected, error.SyncWaitInterrupted => return error.Cancelled,@@ -2762,7 +2751,7 @@ fn execDownload(arena: std.mem.Allocator, session: *lp.Session, arguments: ?std.return .{.text = arena.print("HTTP {d} {s}; nothing saved", .{response.status,- statusPhrase(response.status),+ response.status_text.get() orelse "",}) catch return ToolError.OutOfMemory,.is_error = true,};@@ -2784,16 +2773,6 @@ fn execDownload(arena: std.mem.Allocator, session: *lp.Session, arguments: ?std.};}-/// The standard reason phrase for the code. The wire's own phrase isn't-/// plumbed into a sync response, and the LLM-facing line only needs to say-/// what the status means.-fn statusPhrase(status: u16) []const u8 {- if (status <= 599) {- return @as(std.http.Status, @fromBackingInt(@intCast(status))).phrase() orelse "";- }- return "";-}-fn writeFile(path: []const u8, bytes: []const u8) !void {const file = try std.Io.Dir.cwd().createFile(lp.io, path, .{ .truncate = true });defer file.close(lp.io);@@ -3924,7 +3903,6 @@ test "download: session cookies ride along and Set-Cookie lands in the jar" {const path = try testing.tmpPath(&tmp, "headers.txt");const aa = testing.arena_allocator;- // First: the response's Set-Cookie must land in the session jar.var args = try std.json.parseFromSliceLeaky(std.json.Value, aa, try aa.print("{{\"url\":\"http://127.0.0.1:9582/download_tool/set_cookie\",\"path\":\"{s}\"}}",.{path},@@ -3939,8 +3917,6 @@ test "download: session cookies ride along and Set-Cookie lands in the jar" {}try std.testing.expect(in_jar);- // Second: the jar must send the cookie, like a page load would, and the- // result must name the saved file.const echo_path = try testing.tmpPath(&tmp, "echo.txt");args = try std.json.parseFromSliceLeaky(std.json.Value, aa, try aa.print("{{\"url\":\"http://127.0.0.1:9582/download_tool/echo_headers\",\"path\":\"{s}\"}}",@@ -3953,7 +3929,6 @@ test "download: session cookies ride along and Set-Cookie lands in the jar" {const body = try std.Io.Dir.cwd().readFileAlloc(lp.io, echo_path, aa, .limited(8192));try std.testing.expect(std.mem.find(u8, body, "lp_download=1") != null);- // The session's User-Agent, not a client default.try std.testing.expect(std.mem.find(u8, body, "Lightpanda/") != null);}@@ -3976,12 +3951,8 @@ test "download: a redirect's Set-Cookie lands in the jar and the next hop carrie), .{});const r = try call(aa, session, ®istry, "download", args, .{ .source = .user });try std.testing.expect(r.is_error == false);- // The response the tool reports is the final hop's: only a 2xx is saved,- // and the body is the endpoint the redirect followed.try std.testing.expect(std.mem.startsWith(u8, r.text, "saved "));- // The cookie set on the 302 was stored, and the redirected hop re-derived- // it from the jar for the final URL: the echo endpoint saw it.const body = try std.Io.Dir.cwd().readFileAlloc(lp.io, path, aa, .limited(8192));try std.testing.expect(std.mem.find(u8, body, "lp_redirect=1") != null);}diff --git a/src/docs.zig b/src/docs.zigindex e92991b27..b43ffa37e 100644--- a/src/docs.zig+++ b/src/docs.zig@@ -206,13 +206,12 @@ fn hasRecorded(g: Tool.Group) bool {fn writeGroupHeading(w: *Writer, g: Tool.Group, noun: []const u8, table_head: []const u8) Writer.Error!void {const title, const scope = switch (g) {- .navigation => .{ "Navigation and search", "bring a page into the browser" },+ .navigation => .{ "Navigation and search", "bring a page into the browser, or save a URL to a file" },.reading => .{ "Reading the page", "read the loaded page without modifying it" },.extraction => .{ "Data extraction and scripting", "return structured results from the loaded page" },.interaction => .{ "Interacting with the page", "dispatch real DOM events on the page" },.waiting => .{ "Waiting", "block until the page reaches a condition" },.state => .{ "State and debugging", "inspect browser state outside the DOM" },- .downloading => .{ "Downloading files", "save a URL's response body to a local file" },};try w.print("## {s}\n\nThese {s} {s}.\n\n{s}", .{ title, noun, scope, table_head });}diff --git a/src/test_routes.zig b/src/test_routes.zigindex b372f6511..0003327bb 100644--- a/src/test_routes.zig+++ b/src/test_routes.zig@@ -1044,7 +1044,6 @@ pub fn handle(req: *std.http.Server.Request) !void {}if (std.mem.eql(u8, path, "/download_tool/redirect")) {- // The 302 sets a cookie that the followed hop must carry.return req.respond("", .{.status = .found,.extra_headers = &.{