Skip to content

Lightpanda: the headless browser designed for AI and automation

agent: Improve save prompt (#2691)

Francis Bouvier7e9acec50fb9
diff --git a/src/agent/Agent.zig b/src/agent/Agent.zig
index b8f9eb5d1..227cec140 100644
--- a/src/agent/Agent.zig
+++ b/src/agent/Agent.zig
@@ -77,6 +77,100 @@ const default_system_prompt = browser_tools.driver_guidance ++
\\ the Credentials section above) before reporting unavailable.
;
+/// Skill-like documentation for writing Lightpanda agent script
+/// Used in the system prompt of the `/save` command.
+const script_skill =
+ \\# Writing Lightpanda agent scripts
+ \\
+ \\Run with:
+ \\
+ \\```console
+ \\./lightpanda agent script.js
+ \\```
+ \\
+ \\## Mental model (get this right first)
+ \\
+ \\The script runs in its **own V8 context** — neither the page nor Node.js:
+ \\
+ \\- No `window`, `document`, DOM, `localStorage` — read pages with `extract(...)`, run page-side JS only via `evaluate("...")`.
+ \\- No `require`, `process`, `fs`, npm. Standard ECMAScript built-ins only (`JSON`, `Map`, template literals, …).
+ \\- All primitives are **synchronous and blocking**. Never wrap them in `async`/`await`/`.then` — `const data = extract({...})`, not `await extract(...)`. Top-level `await` is a `SyntaxError` (classic script); promise callbacks only run after the script body ends.
+ \\- Page `evaluate("...")` cannot see script variables — interpolate values into the string. Script code cannot see page variables.
+ \\- Variables persist across navigations within one run, so cross-page aggregation is plain JS.
+ \\- The **last top-level expression is the script's output**, printed automatically (objects/arrays as JSON). End with the bare result: `extract({...});` or `results;`. No `console.log(JSON.stringify(...))`, no top-level `return` (illegal).
+ \\
+ \\## Primitives
+ \\
+ \\| Call | Notes |
+ \\|------|-------|
+ \\| `goto(url[, { timeout }])` | Returns at `load`. Default timeout 10000 ms. Throws on failure; a **timeout does NOT throw** — it returns a "did not finish loading" status string. |
+ \\| `extract(schema)` | The only primitive returning a real JS value (object/array). See schema below. |
+ \\| `evaluate(script[, { url, timeout, save }])` | Page-side JS escape hatch; returns text (JSON for objects/arrays). |
+ \\| `click(sel)` / `hover(sel)` | |
+ \\| `fill(sel, value)` / `selectOption(sel, value)` | |
+ \\| `setChecked(sel[, checked])` | `checked` defaults to `true`. |
+ \\| `press(sel, key)` / `press(null, key)` / `press({ key })` | Selector first! `press("Enter")` binds "Enter" to `selector` and fails. |
+ \\| `scroll()` / `scroll({ x, y })` | |
+ \\| `waitForSelector(sel[, { timeout }])` | `waitFor*` default timeout 5000 ms. |
+ \\| `waitForScript(js[, { timeout }])` | Re-evaluates page JS until truthy. |
+ \\| `waitForState(state[, { timeout }])` | `"load"`, `"domcontentloaded"`, `"networkalmostidle"`, `"networkidle"`, `"done"`. |
+ \\
+ \\Calling convention: leading positionals + optional trailing options object, or one object with everything (`waitForSelector("#row", { timeout: 2000 })` ≡ `waitForSelector({ selector: "#row", timeout: 2000 })`). A bare option positional (`waitForSelector("#row", 2000)`) and a field passed both ways are `invalid arguments`. `null` skips a positional. Arguments must be JSON-serializable.
+ \\
+ \\CSS selectors only — `backendNodeId`s don't exist here. Standard CSS only: no jQuery `:contains()` or Playwright `:has-text()`.
+ \\
+ \\## extract schema
+ \\
+ \\Keys = output field names; values pick what to lift (not a JSON Schema):
+ \\
+ \\```js
+ \\const { stories } = extract({
+ \\ stories: [{
+ \\ selector: "tr.athing", // one record per match
+ \\ limit: 5,
+ \\ fields: { // resolved relative to each match
+ \\ title: ".titleline > a", // first match's text (null if missing)
+ \\ url: { selector: ".titleline > a", attr: "href" },
+ \\ text: "" // "" = the matched element's own text
+ \\ }
+ \\ }]
+ \\});
+ \\```
+ \\
+ \\- `"sel"` → first match's text; `["sel"]` → all matches' text; `{ selector, attr }` / `[{ selector, attr }]` → attribute(s); `limit: N` caps any array form.
+ \\- Every value is a string or null — parse numbers in script logic.
+ \\- Empty arrays are valid results; if **every** field misses, extract throws ("no schema selector matched any element") → your selectors are wrong, not the page empty.
+ \\- An object schema always returns an object (destructure it); a bare array schema returns the array directly.
+ \\- No `save:` option in scripts — keep results in variables.
+ \\
+ \\## Best practices
+ \\
+ \\1. **Navigate, settle, read.** After `goto` on a dynamic page (feeds, search results, comment threads), call `waitForState("networkidle")` or `waitForSelector(...)` before extracting. Most static pages are complete at `load` — don't wait blindly.
+ \\2. **Check `goto` when completeness matters** — it returns a status string instead of throwing on timeout.
+ \\3. **Aggregate in the script, not the page.** List-to-detail: extract the list, then loop `goto`/`extract` per item, assembling plain JS objects.
+ \\4. **Prefer `extract` over `evaluate`.** `evaluate` is for page behavior extraction can't express, not a default.
+ \\5. **Credentials via `$LP_*` placeholders** in any string argument (`fill("#pw", "$LP_HN_PASSWORD")`). Never inline a real secret; placeholders resolve inside the Lightpanda process.
+ \\6. **Unique selectors.** Disambiguate with attributes/position: `input[type="submit"][value="login"]`, not `input[type="submit"]`.
+ \\7. **Let failures fail.** Primitives throw on error and stop the script — only `try/catch` where you have a real fallback (e.g. optional cookie banner: `try { click("#accept") } catch {}`).
+ \\8. **End with the bare result expression.** `console.log` is for debug output only and doesn't JSON-format objects.
+ \\9. Modern, readable JS: `const`/`let`, `for (const x of xs)`, template literals, destructuring, 2-space indent.
+ \\
+ \\## Common errors
+ \\
+ \\| Error | Cause / fix |
+ \\|-------|-------------|
+ \\| `document is not defined` | DOM API in script context → use `extract` or `evaluate` |
+ \\| `require is not defined` | Not Node.js |
+ \\| `no page loaded - run goto(url) first` | Page primitive before navigation |
+ \\| `invalid arguments` | Wrong arity/shape, non-JSON value, or a field set both positionally and in options |
+ \\| `extract: no schema selector matched any element` | All schema fields missed → fix selectors |
+ \\| `press` fails with one string arg | Selector-first: use `press(null, "Enter")` or `press({ key: "Enter" })` |
+;
+
+// Sytem prompt of the `/save` command
+// With the save instructions and the skill-like agent script documentation.
+const save_system_prompt = browser_tools.save_synthesis_prompt ++ "\n" ++ script_skill;
+
const synthesis_prompt =
\\You have used your tool budget or cannot finish the exploration.
\\Give your best final answer NOW based ONLY on what you actually observed
@@ -899,6 +993,13 @@ fn synthesizeSave(self: *Agent, arena: std.mem.Allocator, filename: ?[]const u8,
self.conversation.ensureSystemPrompt() catch return self.failSave("out of memory");
+ // Swap the dedicated save_system_prompt in as the system prompt for this one turn;
+ // regular turns keep the driver prompt. (`messages[0]` is the system
+ // message — rollback and prune never touch it.)
+ const plain_system = self.conversation.messages.items[0].content;
+ self.conversation.messages.items[0].content = save_system_prompt;
+ defer self.conversation.messages.items[0].content = plain_system;
+
const ma = self.conversation.arena.allocator();
const baseline = self.conversation.messages.items.len;
@@ -972,9 +1073,6 @@ fn rememberSavePath(self: *Agent, path: []const u8) void {
fn buildSaveSynthesisMessage(self: *Agent, arena: std.mem.Allocator, prompt: ?[]const u8) ![]const u8 {
var out: std.Io.Writer.Allocating = .init(arena);
const w = &out.writer;
- try w.writeAll(browser_tools.save_synthesis_prompt);
- try w.writeAll("\n\nBuiltin functions to prefer (call them as JS functions):\n");
- try save.renderBuiltinCatalog(w);
const recorded = self.save_buffer.bytes();
if (recorded.len > 0) {
try w.writeAll("\nCommands and JS that actually ran this session:\n");
diff --git a/src/agent/save.zig b/src/agent/save.zig
index a986ef48b..852ea1691 100644
--- a/src/agent/save.zig
+++ b/src/agent/save.zig
@@ -93,22 +93,6 @@ pub fn writeContentFile(path: []const u8, content: []const u8, mode: Mode) !void
if (content.len > 0 and content[content.len - 1] != '\n') try file.writeAll("\n");
}
-/// Document the recorded browser tools — the subset callable from a saved
-/// script — with full descriptions, so the model gets each function's argument
-/// dialect (e.g. `extract`'s schema format) without the tool schemas a no-tools
-/// synthesis turn omits.
-pub fn renderBuiltinCatalog(w: *std.Io.Writer) !void {
- for (Schema.all()) |s| {
- if (!s.tool.isRecorded()) continue;
- try w.print("\n{s}(", .{s.tool_name});
- for (s.required, 0..) |req, i| {
- if (i != 0) try w.writeAll(", ");
- try w.writeAll(req);
- }
- try w.print("):\n{s}\n", .{s.description});
- }
-}
-
/// Strip a surrounding ```` ```lang … ``` ```` markdown fence if the model
/// wrapped its output in one despite being told not to.
pub fn stripCodeFence(text: []const u8) []const u8 {
@@ -156,19 +140,6 @@ test "parseCommand: rejects path-like filenames" {
try std.testing.expectError(error.UnterminatedQuote, parseCommand("\"unclosed.js"));
}
-test "renderBuiltinCatalog: lists recorded tools, omits read-only ones" {
- var out: std.Io.Writer.Allocating = .init(std.testing.allocator);
- defer out.deinit();
- try renderBuiltinCatalog(&out.writer);
- const text = out.written();
- try std.testing.expect(std.mem.indexOf(u8, text, "goto(") != null);
- try std.testing.expect(std.mem.indexOf(u8, text, "extract(") != null);
- try std.testing.expect(std.mem.indexOf(u8, text, "click(") != null);
- // tree/markdown are read-only and not callable from a saved script.
- try std.testing.expect(std.mem.indexOf(u8, text, "tree(") == null);
- try std.testing.expect(std.mem.indexOf(u8, text, "markdown(") == null);
-}
-
test "stripCodeFence: unwraps a fenced block and passes plain text through" {
try std.testing.expectEqualStrings("goto(\"x\");", stripCodeFence("```js\ngoto(\"x\");\n```"));
try std.testing.expectEqualStrings("goto(\"x\");", stripCodeFence("goto(\"x\");"));