Skip to content

Lightpanda: the headless browser designed for AI and automation

agent: better instructions not to use evaluate on /save

Francis Bouvierac34d2f9b779
diff --git a/src/agent/Agent.zig b/src/agent/Agent.zig
index d05168e42..2c6e3fdd1 100644
--- a/src/agent/Agent.zig
+++ b/src/agent/Agent.zig
@@ -148,7 +148,7 @@ const script_skill =
\\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.
+ \\4. **`evaluate` is a last resort, not a reading tool.** A `querySelectorAll`-and-parse `evaluate` block is always wrong: lift the raw strings with `extract`, then trim/split/parse them in top-level JS. Reserve `evaluate` for behavior that must run inside the page and no builtin covers — and remember its state dies on every `goto`/reload, while script variables persist.
\\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 {}`).
diff --git a/src/browser/tools.zig b/src/browser/tools.zig
index b9cceef16..35d7ab806 100644
--- a/src/browser/tools.zig
+++ b/src/browser/tools.zig
@@ -156,6 +156,13 @@ pub const save_synthesis_prompt =
\\- Reasoning you did between tool calls — comparing, filtering, picking,
\\ aggregating across pages — becomes plain top-level JavaScript, so the
\\ script reaches the result without you.
+ \\- Read pages with extract(schema): CSS selectors lift text and
+ \\ attributes as strings, and every trim/split/regex/parse/merge on
+ \\ those strings is top-level JavaScript. Do NOT write an evaluate(...)
+ \\ that querySelects the page and massages the result — that is
+ \\ extract + top-level JS. evaluate is ONLY for what must execute
+ \\ inside the page and no builtin can do. Top-level variables also
+ \\ persist across goto/reload; everything in the page context is wiped.
\\Stay faithful to the calls that worked: same arguments and options each
\\one actually used. Do NOT add a `timeout` (or any option) the session
\\didn't use. Never round-trip a result through `lp.*`, and never append
@@ -173,10 +180,13 @@ pub const save_script_rules =
\\- The builtins are synchronous and the file runs as a classic script:
\\ `const data = extract({...})` — never async/await/.then. Top-level
\\ `await` is a SyntaxError; top-level `return` is illegal.
- \\- Plain top-level JavaScript handles logic (loops, cross-page
- \\ aggregation, filtering); it runs in the script context, not the page.
- \\ evaluate(...) is the page-side escape hatch only — it cannot see
- \\ script variables, so interpolate values into its string.
+ \\- Read pages with extract(schema); all processing of the returned
+ \\ strings (trim, split, parse, merge, loops, cross-page aggregation)
+ \\ is plain top-level JavaScript in the script context. evaluate(...)
+ \\ is ONLY for JS that must run inside the page and no builtin covers —
+ \\ never a querySelector-and-parse block. It cannot see script
+ \\ variables (interpolate values into its string), and page state is
+ \\ wiped by every goto/reload while script variables persist.
\\- 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 or JSON.stringify.