Lightpanda: the headless browser designed for AI and automation
search: trim comments to the non-obvious why
Adrià Arrufatc8534b7afa71
diff --git a/src/browser/tools.zig b/src/browser/tools.zigindex 9eca88aff..5d55440db 100644--- a/src/browser/tools.zig+++ b/src/browser/tools.zig@@ -979,15 +979,15 @@ pub const SearchParams = struct {timeout: ?u32 = null,};-/// Bounds one search request once its connection is up (the search clients-/// have no connect timeout); the `search` schema advertises this default.+/// Advertised by the `search` schema. The search clients have no connect+/// timeout, so this only starts once connected.const default_search_timeout_ms: u32 = 10_000;pub const SearchEngine = enum { auto, brave, tavily, exa, keenable };/// Only the agent REPL's `/searchEngine` mutates this.pub var search_engine: SearchEngine = .auto;-// One entry per API engine, in `.auto` preference order.+// In `.auto` preference order.const api_engines = .{.{.tag = SearchEngine.brave,@@ -1028,8 +1028,7 @@ const api_engines = .{},};-/// A client whose `api_key` is optional also works with no API key: a-/// `null` key routes it to the provider's public endpoint.+/// A `null` key routes an optional-key client to its public endpoint.fn isKeyless(comptime Client: type) bool {return @typeInfo(@FieldType(Client, "api_key")) == .optional;}@@ -1057,13 +1056,12 @@ fn joinEngines(comptime field: enum { tag, env_var }, comptime last_sep: []const}}-/// The `.auto` cascade in one sentence, shared by the `search` tool-/// description and the `/searchEngine` help. Engine order and env vars come-/// from the table; the keyless clause is the one hand-written part.+/// Shared by the `search` tool description and the `/searchEngine` help;+/// the keyless clause is the one part not generated from the table.pub const search_cascade_prose = "tries " ++ joinEngines(.tag, ", then ") ++ " in order, each when its API key (" ++ joinEngines(.env_var, " or ") ++ ") is set; keenable also works without a key through its public endpoint (rate-limited per client IP)";-/// The key `engine` uses right now: the exported value, `null` for a keyless-/// engine's public endpoint, or `MissingApiKey`.+/// The key `engine` uses right now; `null` selects a keyless engine's+/// public endpoint.fn engineKey(comptime engine: anytype) error{MissingApiKey}!?[]const u8 {if (lp.environ().getPosix(engine.env_var)) |key| return key;return if (comptime isKeyless(engine.Client)) null else error.MissingApiKey;@@ -1095,9 +1093,8 @@ fn execSearch(arena: std.mem.Allocator, arguments: ?std.json.Value) ToolError!Tovar last_err: ?anyerror = null;inline for (api_engines) |engine| {if (engineKey(engine)) |api_key| {- // Any failure (network, non-2xx, parse) falls through to- // the next engine so a single outage doesn't kill a whole- // benchmark run.+ // Fall through on any failure so one outage doesn't kill+ // a whole benchmark run.if (apiSearch(engine, arena, api_key, timeout_ms, args.query)) |markdown_| {return .{ .text = markdown_ };} else |err| {@@ -1117,9 +1114,7 @@ fn execSearch(arena: std.mem.Allocator, arguments: ?std.json.Value) ToolError!To}}-/// Search with an explicitly selected engine — no fallback. A failed call-/// comes back as an error result, as does a missing key unless the engine-/// is keyless (it then uses its public endpoint).+/// No fallback: a failed call or a missing key is an error result.fn searchExplicit(arena: std.mem.Allocator, comptime engine: anytype, timeout_ms: u32, query: []const u8) ToolError!ToolResult {const label = @tagName(engine.tag);const api_key = engineKey(engine) catch return .{@@ -1138,9 +1133,7 @@ fn searchFailed(arena: std.mem.Allocator, comptime label: []const u8, err: anyer};}-/// `arena` owns the returned slice. `api_key` is `null` only for a keyless-/// engine's public endpoint. `timeout_ms` bounds the single attempt once the-/// connection is up.+/// `arena` owns the returned slice.fn apiSearch(comptime engine: anytype,arena: std.mem.Allocator,@@ -1149,9 +1142,8 @@ fn apiSearch(query: []const u8,) ![]const u8 {var init_options = engine.init_options;- // No HTTP-level retries: in `.auto` the next rung is the retry, and- // honoring a public endpoint's Retry-After (up to 60 s per sleep) would- // stall the tool on the shared browser thread instead.+ // The cascade (or the model) is the retry; honoring a Retry-After (60 s+ // per sleep on the public endpoint) would stall the shared browser thread.init_options.retry_policy = .disabled;init_options.request_timeout_ms = timeout_ms;var client: engine.Client = .init(@@ -1223,8 +1215,7 @@ fn formatKeenableMarkdown(w: *std.Io.Writer, resp: keenable.types.SearchResponse}}-/// Providers default a missing title to ""; the URL stands in rather than-/// rendering an empty bold run.+/// An empty title (providers default it to "") would render as `****`.fn writeResultItem(w: *std.Io.Writer, i: usize, title: []const u8, url: []const u8, snippet: []const u8) !void {try w.print("{d}. **", .{i + 1});try writeSingleLine(w, if (title.len == 0) url else title);