Lightpanda: the headless browser designed for AI and automation
agent: treat first arg of /save as filename and append .js
Adrià Arrufatde7ad43bb918
diff --git a/docs/agent.md b/docs/agent.mdindex 45c8d2ab9..917680928 100644--- a/docs/agent.md+++ b/docs/agent.md@@ -55,10 +55,12 @@ Tell it what you want:```The agent navigates, extracts, prints the answer. When you're happy with-the result, save it:+the result, save it and replay it right away to check it holds up without+the LLM:```❯ /save hn-top-story.js+❯ /load hn-top-story.js❯ /quit```@@ -79,7 +81,7 @@ data across pages), see the [tutorial](agent-tutorial.md).# Force a specific provider, ignoring auto-detection./lightpanda agent --provider anthropic-# Slash-commands-only REPL, no LLM at all+# REPL without an LLM: /goto, /extract, ... work; plain English doesn't./lightpanda agent --no-llm# One-shot: ask a question, print the answer to stdout, exit@@ -96,9 +98,10 @@ The whole value of a saved script is that it keeps working after you walk away.for as an `extract()` call; vague prompts produce vague recordings.- **Be specific about the page.** "Go to news.ycombinator.com" is muchbetter than "find me what's on Hacker News".-- **Check the file with `cat your-script.js` before running it.** If the- extracted data isn't in the script, the recording missed something. Try- rewording your prompt.+- **Check the file with `cat your-script.js` before running it.** The+ script holds the *calls*, not the data, so look for an `extract(...)`+ whose schema covers the fields you asked for. If there isn't one, the+ recording missed something — try rewording your prompt.- **When the page changes and a saved script breaks**, re-run with the LLM,get an updated answer, save again. You only pay the LLM when somethinggenuinely changed.@@ -150,11 +153,12 @@ tokens.`--effort <none|minimal|low|medium|high|xhigh>` sets the per-turn reasoningbudget for thinking models. It maps to each provider's nativereasoning-effort knob and is ignored by non-thinking models. The REPL-defaults to `low` so turns stay snappy. `--task` and script runs default to-`medium` where answer quality matters more than per-turn latency. Higher+defaults to `low` so turns stay snappy. `--task` defaults to `medium`+where answer quality matters more than per-turn latency. Highereffort can mean fewer tool calls per task (the model plans better), so it'sa real tradeoff rather than a pure slowdown. Change it live in the REPL-with `/effort`; selection persists in `.lp-agent.zon`.+with `/effort`; selection persists in `.lp-agent.zon`. Script replay makes+no LLM calls, so effort doesn't apply there.The default depends on how you launched, which is easy to miss:@@ -162,28 +166,35 @@ The default depends on how you launched, which is easy to miss:|----------------|----------------|--------------------------------------|| REPL | `low` | Keeps turns snappy || `--task` | `medium` | Answer quality matters more |-| Script replay | `medium` | Same: correctness over latency |## Slash commandsThe REPL uses a small slash-command language for browser actions. Each line-is either a slash command, a `#` comment, a blank line, or (when an LLM is-configured) a natural-language prompt.+you type at the prompt is either a slash command, a `#` comment, a blank+line, or (when an LLM is configured) a natural-language prompt.Slash commands accept:- A single positional value, when the tool has exactly one required field.- `/goto 'https://example.com'`, `/extract '{"karma":"#karma"}'`.+ `/goto 'https://example.com'`. The value can itself be quoted JSON when+ that's what the field takes: `/extract '{"karma":"#karma"}'` passes the+ string to extract's one required field, `schema`.- `key=value` pairs. Values may be bare or quoted; strings with whitespace- must be quoted. `/fill selector='#email' value='[email protected]'`.+ must be quoted. `/fill selector='#email' value='[email protected]'`. A positional+ and `key=value` pairs can be mixed, but the positional must come first:+ `/extract '{"karma":"#karma"}' save=me`.- A raw `{json}` blob, handed straight to the tool.`/findElement {"role":"button"}`.Tools whose selector is optional (`/click`, `/hover`, `/findElement`) takeno positional and must use `key=value` form: `/click selector='a.login'`.+`/help <tool>` prints any tool's JSON schema — required fields, optional+fields, and types.Quoting is content-aware: `'…'`, `"…"`, and triple-quoted `'''…'''` /-`"""…"""` for values that mix quote styles or span multiple lines.+`"""…"""` for values that mix quote styles or span multiple lines. Paste a+multi-line command and the REPL keeps the whole paste as one input; typed+line by line, Enter submits at each newline.### LLM-driven helpers@@ -209,7 +220,7 @@ These don't drive the browser, they control the REPL itself:| `/effort <level>` | Sets reasoning budget. Saved to `.lp-agent.zon`. || `/verbosity <level>` | Tunes the log level. Levels: low, medium, high. || `/usage` | Prints cumulative token usage and cache hit rate. |-| `/save [file.js]` | Writes the session to a script. |+| `/save [file] [prompt]` | Writes the session to a script. `.js` is appended to the name if missing; trailing words guide the synthesizer.|| `/load <path>` | Runs a script from disk against the current session.|| `/clear` | Forgets the conversation (history, usage, recorded actions, node IDs); keeps the page and cookies.|| `/reset` | Full reset: everything `/clear` does, plus a fresh browser session, dropping the page, cookies, and storage.|@@ -229,9 +240,18 @@ a completely clean browser (no cookies, no current page, no storage).- **JS mode (`!`).** Type `!` on an empty prompt to toggle a scratchpadwhere the whole line runs as page-side JavaScript, same context as`/evaluate` so `document` and `window` are in scope. Handy for poking at- a page without wrapping every line in `/evaluate`. `$LP_*` refs are still- resolved at execution, console output is echoed back, and `Esc` exits.- JS-mode lines are not recorded.+ a page without wrapping every line in `/evaluate`:++ ```+ ❯ !+ ! ❯ document.title+ "Hacker News"+ ! ❯ document.querySelectorAll('tr.athing').length+ 30+ ```++ `$LP_*` refs are still resolved at execution, console output is echoed+ back, and `Esc` exits. JS-mode lines are not recorded.- **Tab completion** (case-insensitive). Cycles through `/<tool>` and metaslash commands. The dim grey suffix shown after the cursor is the firstmatch.@@ -247,16 +267,23 @@ a completely clean browser (no cookies, no current page, no storage).lift off the page. The result is printed to stdout as a single JSON object.```console-# Log into the demo and grab the dashboard title and visible cards.-# Site-scoped vars (LP_<SITE>_<FIELD>) avoid collisions when you have-# credentials for several sites; the unprefixed form is the fallback.-/goto 'https://demo-browser.lightpanda.io/'-/acceptCookies-/fill selector='#email' value='$LP_DEMO_USERNAME'-/fill selector='#password' value='$LP_DEMO_PASSWORD'-/click selector='button[type="submit"]'-/waitForSelector '.dashboard'-/extract '{"title": ".dashboard h1", "cards": [".dashboard .card .name"]}'+# The demo shop renders its product data with an XHR after the initial+# HTML, so wait for it to land before extracting.+/goto 'https://demo-browser.lightpanda.io/campfire-commerce/'+/waitForSelector '#product-features li'+/extract '{"name": "#product-name", "price": "#product-price", "related": [{"selector": "#product-related div", "fields": {"name": "h4", "price": "p"}}]}'+```++```json+{+ "name": "Outdoor Odyssey Nomad Backpack 60 liters",+ "price": "$244.99",+ "related": [+ { "name": "Outdoor Odyssey Hiking Poles", "price": "$79.99" },+ { "name": "Outdoor Odyssey Sleeping Bag", "price": "$129.99" },+ { "name": "Outdoor Odyssey Water Bottle", "price": "$19.99" }+ ]+}```Supported value forms:@@ -286,7 +313,7 @@ the `save=` modifier:```console/goto 'https://news.ycombinator.com/'-/extract save=front '''+/extract '''{"stories": [{"selector": "tr.athing",@@ -297,7 +324,7 @@ the `save=` modifier:}}]}-'''+''' save=front/evaluate '''console.log(lp.front.stories[0].title);@@ -351,7 +378,15 @@ See [agent-script.md](agent-script.md) for the full script format reference.`/save [file.js]` writes the current session to a `.js` file. `/load <path>`runs a script from disk against the current session.-`/save` works one of two ways:+`/save` arguments are positional: the first token is the filename (`.js`+is appended when missing, so `/save test` writes `test.js`; quote names+with spaces) and anything after it is passed to the synthesizer as+guidance — `/save hn.js keep only the extraction`. With no argument at+all, the file gets an auto-generated `session-*.js` name.++`/save` works one of two ways, decided by the session rather than by any+argument — if the REPL has an LLM you get synthesis, with `--no-llm` (or+no resolved provider) you get the deterministic transcription:- **With `--no-llm`** it transcribes the session deterministically.State-mutating commands (`/goto`, `/click`, `/fill`, `/scroll`, `/hover`,@@ -376,8 +411,19 @@ runs a script from disk against the current session.````--task` runs a single user turn, prints the final answer to stdout, and-exits. Combine with `-a <path>` / `--attach <path>` (repeatable) to feed-local files to providers that accept attachments. Text files are inlined+exits. On a TTY a spinner on stderr shows the tool currently running while+the agent works; raise `--verbosity` for the full `[tool/result]` trace.++Combine with `-a <path>` / `--attach <path>` (repeatable) to feed+local files to providers that accept attachments — for example, a list of+items to look up, or a document to cross-check against a live page:++```console+./lightpanda agent -a invoice.pdf \+ --task "open shop.example.com/orders/1042 and check the order total matches the attached invoice"+```++Text files are inlinedinto the prompt (max 512 KiB each); binary files (image, audio, pdf) arebase64-encoded inline (max 20 MiB each). Unsupported MIME types fail beforeany browser work runs.diff --git a/src/agent/Agent.zig b/src/agent/Agent.zigindex befd2a2a9..7fc3521b1 100644--- a/src/agent/Agent.zig+++ b/src/agent/Agent.zig@@ -912,11 +912,12 @@ fn resolveSavePathAndMode(self: *Agent, arena: std.mem.Allocator, filename: ?[]c}fn handleSave(self: *Agent, arena: std.mem.Allocator, rest: []const u8) void {- const parsed = save.parseCommand(rest) catch |err| {+ const parsed = save.parseCommand(arena, rest) catch |err| {const msg: []const u8 = switch (err) {error.UnterminatedQuote => "unterminated filename quote",error.EmptyFilename => "filename cannot be empty",error.InvalidFilename => "filename must be a local file name, not a path",+ error.OutOfMemory => "out of memory",};self.terminal.printError("{s}", .{msg});return;diff --git a/src/agent/save.zig b/src/agent/save.zigindex 852ea1691..1e2586ab9 100644--- a/src/agent/save.zig+++ b/src/agent/save.zig@@ -29,31 +29,32 @@ pub const Mode = enum { append, replace };pub const Command = struct { filename: ?[]const u8, prompt: ?[]const u8 };-/// Split `/save` arguments into an optional filename and an optional trailing-/// natural-language prompt. A quoted leading token is always a filename; an-/// unquoted one is a filename only if it ends in `.js` (else the whole argument-/// is the prompt, and a name is chosen automatically).-pub fn parseCommand(rest: []const u8) !Command {+/// Split `/save` arguments positionally: the first (optionally quoted) token+/// is the filename — `.js` is appended when missing — and everything after it+/// is a natural-language prompt for the synthesizer. The filename may alias+/// `rest` or be arena-allocated.+pub fn parseCommand(arena: std.mem.Allocator, rest: []const u8) !Command {const trimmed = std.mem.trim(u8, rest, &std.ascii.whitespace);if (trimmed.len == 0) return .{ .filename = null, .prompt = null };+ var name: []const u8 = undefined;+ var after: []const u8 = undefined;if (trimmed[0] == '\'' or trimmed[0] == '"') {const quote = trimmed[0];const end = std.mem.indexOfScalarPos(u8, trimmed, 1, quote) orelse return error.UnterminatedQuote;- const name = trimmed[1..end];- try validateFilename(name);- const rest_prompt = std.mem.trim(u8, trimmed[end + 1 ..], &std.ascii.whitespace);- return .{ .filename = name, .prompt = if (rest_prompt.len == 0) null else rest_prompt };+ name = trimmed[1..end];+ after = trimmed[end + 1 ..];+ } else {+ const tok_end = std.mem.indexOfAny(u8, trimmed, &std.ascii.whitespace) orelse trimmed.len;+ name = trimmed[0..tok_end];+ after = trimmed[tok_end..];}-- const tok_end = std.mem.indexOfAny(u8, trimmed, &std.ascii.whitespace) orelse trimmed.len;- const first = trimmed[0..tok_end];- if (std.mem.endsWith(u8, first, ".js")) {- try validateFilename(first);- const rest_prompt = std.mem.trim(u8, trimmed[tok_end..], &std.ascii.whitespace);- return .{ .filename = first, .prompt = if (rest_prompt.len == 0) null else rest_prompt };+ try validateFilename(name);+ if (!std.mem.endsWith(u8, name, ".js")) {+ name = try std.mem.concat(arena, u8, &.{ name, ".js" });}- return .{ .filename = null, .prompt = trimmed };+ const prompt = std.mem.trim(u8, after, &std.ascii.whitespace);+ return .{ .filename = name, .prompt = if (prompt.len == 0) null else prompt };}fn validateFilename(name: []const u8) !void {@@ -105,39 +106,68 @@ pub fn stripCodeFence(text: []const u8) []const u8 {}test "parseCommand: filename only" {- const r = try parseCommand("out.js");+ var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);+ defer arena.deinit();+ const r = try parseCommand(arena.allocator(), "out.js");try std.testing.expectEqualStrings("out.js", r.filename.?);try std.testing.expect(r.prompt == null);}test "parseCommand: filename and prompt" {- const r = try parseCommand("out.js summarize the login flow");+ var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);+ defer arena.deinit();+ const r = try parseCommand(arena.allocator(), "out.js summarize the login flow");try std.testing.expectEqualStrings("out.js", r.filename.?);try std.testing.expectEqualStrings("summarize the login flow", r.prompt.?);}test "parseCommand: quoted filename keeps trailing prompt" {- const r = try parseCommand("\"my flow.js\" do X");+ var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);+ defer arena.deinit();+ const r = try parseCommand(arena.allocator(), "\"my flow.js\" do X");try std.testing.expectEqualStrings("my flow.js", r.filename.?);try std.testing.expectEqualStrings("do X", r.prompt.?);}-test "parseCommand: prompt only when first token is not a .js name" {- const r = try parseCommand("make a login script");- try std.testing.expect(r.filename == null);- try std.testing.expectEqualStrings("make a login script", r.prompt.?);+test "parseCommand: appends .js to a bare name" {+ var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);+ defer arena.deinit();+ const r = try parseCommand(arena.allocator(), "test");+ try std.testing.expectEqualStrings("test.js", r.filename.?);+ try std.testing.expect(r.prompt == null);+}++test "parseCommand: appends .js and keeps trailing prompt" {+ var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);+ defer arena.deinit();+ const r = try parseCommand(arena.allocator(), "test keep only the extraction");+ try std.testing.expectEqualStrings("test.js", r.filename.?);+ try std.testing.expectEqualStrings("keep only the extraction", r.prompt.?);+}++test "parseCommand: appends .js to a quoted name" {+ var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);+ defer arena.deinit();+ const r = try parseCommand(arena.allocator(), "'my flow' do X");+ try std.testing.expectEqualStrings("my flow.js", r.filename.?);+ try std.testing.expectEqualStrings("do X", r.prompt.?);}test "parseCommand: empty is all null" {- const r = try parseCommand(" ");+ var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);+ defer arena.deinit();+ const r = try parseCommand(arena.allocator(), " ");try std.testing.expect(r.filename == null);try std.testing.expect(r.prompt == null);}test "parseCommand: rejects path-like filenames" {- try std.testing.expectError(error.InvalidFilename, parseCommand("../evil.js"));- try std.testing.expectError(error.InvalidFilename, parseCommand("/tmp/x.js"));- try std.testing.expectError(error.UnterminatedQuote, parseCommand("\"unclosed.js"));+ var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);+ defer arena.deinit();+ const aa = arena.allocator();+ try std.testing.expectError(error.InvalidFilename, parseCommand(aa, "../evil.js"));+ try std.testing.expectError(error.InvalidFilename, parseCommand(aa, "/tmp/x.js"));+ try std.testing.expectError(error.UnterminatedQuote, parseCommand(aa, "\"unclosed.js"));}test "stripCodeFence: unwraps a fenced block and passes plain text through" {