Skip to content

Lightpanda: the headless browser designed for AI and automation

agent: improve /save system prompt

Francis Bouvier9ca117a23595
diff --git a/src/agent/Agent.zig b/src/agent/Agent.zig
index befd2a2a9..d05168e42 100644
--- a/src/agent/Agent.zig
+++ b/src/agent/Agent.zig
@@ -169,7 +169,7 @@ const script_skill =
// 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 save_system_prompt = browser_tools.save_synthesis_prompt ++ "\n\n" ++ script_skill;
const synthesis_prompt =
\\You have used your tool budget or cannot finish the exploration.
diff --git a/src/browser/tools.zig b/src/browser/tools.zig
index e68b9edbc..b9cceef16 100644
--- a/src/browser/tools.zig
+++ b/src/browser/tools.zig
@@ -140,41 +140,50 @@ pub const driver_guidance =
\\
;
-/// Guidance for synthesizing a clean, replayable agent script from a session.
-/// Shared: the agent's `/save` feeds it to its own LLM; the MCP `save` tool
-/// hands it to the driving client as the tool description.
+/// Save-specific guidance: how to distill a finished session into a clean,
+/// replayable agent script. Deliberately free of script-language rules —
+/// the agent's `/save` pairs it with the full script-writing skill in its
+/// system prompt, and the MCP `save` tool appends `save_script_rules`.
pub const save_synthesis_prompt =
- \\Write a single Lightpanda agent script (.js) that reproduces what the user
- \\set out to do this session. Infer the goal from the whole conversation and
- \\keep only the steps a clean, repeatable script needs — drop failed attempts,
- \\retries, exploratory reads (tree/markdown/extract probes), and corrections.
- \\Pick the right layer for each step:
- \\- builtins (goto, click, fill, extract, …) for actions and for reading data;
- \\ extract is how you pull structured data out of a page.
- \\- plain top-level JavaScript for logic — loops, cross-page aggregation,
- \\ filtering, string building. It runs in the script, not the page.
- \\- evaluate(...) only for page-side JavaScript no builtin can express. It is
- \\ an escape hatch, not a default, and cannot see the script's variables —
- \\ interpolate any value into its string.
- \\Stay faithful to the recorded calls: same options each one actually used.
- \\Do NOT add a `timeout` to goto (or any tool) unless the session
- \\did. Never round-trip a result through `lp.*`, and never append no-op
- \\extract(...) probes or `evaluate("return lp....")` tails to surface output.
- \\The completion value — the last top-level expression — prints automatically
- \\(objects and arrays as JSON), so end with the bare result expression: a final
- \\`extract({...});`, or `results;` after an aggregation loop. No console.log,
- \\JSON.stringify, or `return` (illegal at top level) needed.
- \\Write modern, readable JavaScript: `for (const x of xs)`, `const`/`let` over
- \\`var`, template literals, destructuring, 2-space indent (including multi-line
- \\extract({...}) schemas).
- \\The script runs as a classic script, so top-level `await` is a syntax error.
- \\The builtins are synchronous — each returns its result directly, so never
- \\wrap them in async/await, .then, or Promises (`const data = extract(...)`,
- \\not `await extract(...)`). evaluate(...) may run async JS in the page, but
- \\the call itself returns synchronously.
+ \\Distill this session into ONE Lightpanda agent script (.js) that, run
+ \\later on its own, redoes what the user set out to accomplish. You are
+ \\reproducing the user's goal, not replaying the transcript:
+ \\- Infer the goal from the whole conversation, including corrections —
+ \\ the user's final intent wins over their first phrasing.
+ \\- Keep only the steps a clean re-run needs, in the order that worked.
+ \\ Drop failed attempts, retries, dead ends, and exploratory reads
+ \\ (tree/markdown/extract probes that only informed your next move).
+ \\- 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.
+ \\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
+ \\no-op extract(...) probes or `evaluate("return lp....")` tails to
+ \\surface output.
\\Output ONLY JavaScript source — no markdown fences, no commentary.
;
+/// Script-language rules for consumers that never see the full
+/// script-writing skill: appended to the MCP `save` tool description so a
+/// driving client that only knows the tool surface can still write a valid
+/// script. The agent's `/save` covers all of this via its skill doc instead.
+pub const save_script_rules =
+ \\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.
+ \\- 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.
+ \\- Modern, readable JS: `const`/`let`, `for (const x of xs)`, template
+ \\ literals, destructuring, 2-space indent.
+;
+
/// Reject paths that an untrusted MCP client could use to escape the
/// working directory: empty paths, absolute paths, and any path with a
/// `..` segment. Operator-controlled symlinks already inside CWD are out
diff --git a/src/mcp/tools.zig b/src/mcp/tools.zig
index bb492eee6..31764c1ea 100644
--- a/src/mcp/tools.zig
+++ b/src/mcp/tools.zig
@@ -39,7 +39,7 @@ const save_schema = browser_tools.minify(
const extra_tools = [_]McpTool{
.{
.name = "save",
- .description = "Save the session as a reusable Lightpanda agent script. You hold the conversation, so synthesize the `script` yourself — call the builtins you used as tools (goto, click, fill, extract, …) as JavaScript functions with the same object arguments. Keep `$LP_*` placeholders; never inline a resolved secret.\n\n" ++ browser_tools.save_synthesis_prompt,
+ .description = "Save the session as a reusable Lightpanda agent script. You hold the conversation, so synthesize the `script` yourself — call the builtins you used as tools (goto, click, fill, extract, …) as JavaScript functions with the same object arguments. Keep `$LP_*` placeholders; never inline a resolved secret.\n\n" ++ browser_tools.save_synthesis_prompt ++ "\n\n" ++ browser_tools.save_script_rules,
.inputSchema = save_schema,
},
};