Skip to content

Lightpanda: the headless browser designed for AI and automation

agent: emit intent comments in saved scripts

Adrià Arrufat7547d3ac7214
diff --git a/src/agent/Agent.zig b/src/agent/Agent.zig
index 207d84699..b923aab14 100644
--- a/src/agent/Agent.zig
+++ b/src/agent/Agent.zig
@@ -171,6 +171,19 @@ const script_skill =
\\6. **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 { page.click("#accept") } catch {}`).
\\7. **End with `return <result>`.** `console.log` is for debug output only and doesn't JSON-format objects.
\\8. Modern, readable JS: `const`/`let`, `for (const x of xs)`, template literals, destructuring, 2-space indent.
+ \\9. **Comment the intent of each block.** Put a one-line `//` comment above each logical step describing what it accomplishes toward the goal (not restating the call). One comment per block, not per line — skip self-evident lines:
+ \\ ```js
+ \\ // Load the Hacker News front page
+ \\ const page = new Page();
+ \\ await page.goto("https://news.ycombinator.com");
+ \\
+ \\ // Pull the top 5 stories (title + link)
+ \\ const { stories } = page.extract({ stories: [{ selector: "tr.athing", limit: 5, fields: { title: ".titleline > a", url: { selector: ".titleline > a", attr: "href" } } }] });
+ \\
+ \\ // Open each story page in parallel and read its text
+ \\ const pages = stories.map(() => new Page());
+ \\ await Promise.all(pages.map((p, i) => p.goto(stories[i].url)));
+ \\ ```
\\
\\## Common errors
\\
diff --git a/src/browser/tools.zig b/src/browser/tools.zig
index f020a5fce..4812bf624 100644
--- a/src/browser/tools.zig
+++ b/src/browser/tools.zig
@@ -169,7 +169,14 @@ pub const save_synthesis_prompt =
\\didn't use. Never round-trip a result through `lp.*`, and never append
\\no-op page.extract(...) probes or `page.evaluate("return lp....")` tails to
\\surface output.
- \\Output ONLY JavaScript source — no markdown fences, no commentary.
+ \\Annotate the script with short `//` intent comments so a later reader grasps
+ \\it at a glance: one comment above each logical block (navigate, extract a
+ \\list, fan out to detail pages, aggregate, return) stating what that block
+ \\accomplishes toward the goal — NOT restating the API call. One comment per
+ \\step, not per line; skip self-evident lines.
+ \\Output ONLY JavaScript source — no markdown fences and no prose outside the
+ \\code, but DO annotate the script with the `//` intent comments described
+ \\above.
;
/// Script-language rules for consumers that never see the full