@rubytech/create-maxy-code 0.1.185 → 0.1.187

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.185",
+  "version": "0.1.187",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/plugins/admin/hooks/__tests__/prompt-optimiser-directive.test.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Regression test for prompt-optimiser-directive.sh.
+#
+# Covers:
+#   1. Valid UserPromptSubmit stdin  -> exit 0, stdout is valid JSON,
+#      hookEventName == "UserPromptSubmit", additionalContext non-empty.
+#   2. Empty / garbage stdin         -> exit 0, still valid JSON (the hook
+#      ignores the prompt text; the directive is standing).
+#   3. python3 unavailable on PATH   -> exit 0, empty stdout (fail-open).
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/prompt-optimiser-directive.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+
+# Assert: hook on $1 (stdin) exits 0 and stdout is JSON with a non-empty
+# additionalContext and the correct hookEventName.
+assert_valid_injection() {
+  local name="$1" stdin="$2" out actual_exit
+  out=$(printf '%s' "$stdin" | bash "$HOOK" 2>/dev/null)
+  actual_exit=$?
+  if [[ "$actual_exit" -ne 0 ]]; then
+    echo "FAIL: $name (expected exit=0, got=$actual_exit)" >&2; FAIL=$((FAIL+1)); return
+  fi
+  if printf '%s' "$out" | python3 -c '
+import json, sys
+d = json.load(sys.stdin)
+h = d["hookSpecificOutput"]
+assert h["hookEventName"] == "UserPromptSubmit", "wrong hookEventName"
+assert isinstance(h["additionalContext"], str) and len(h["additionalContext"]) > 0, "empty additionalContext"
+' 2>/dev/null; then
+    echo "PASS: $name"; PASS=$((PASS+1))
+  else
+    echo "FAIL: $name (stdout not valid directive JSON: $out)" >&2; FAIL=$((FAIL+1))
+  fi
+}
+
+# Case 1 — valid UserPromptSubmit envelope.
+assert_valid_injection "valid UserPromptSubmit stdin -> directive JSON" \
+  '{"hook_event_name":"UserPromptSubmit","prompt":"fix the thing","session_id":"abc"}'
+
+# Case 2 — garbage stdin still yields the standing directive.
+assert_valid_injection "garbage stdin -> still directive JSON" \
+  'not json at all'
+
+# Case 3 — fail-open when python3 is absent from PATH.
+FAKEBIN=$(mktemp -d)
+# A minimal PATH containing the core utils the hook needs (cat, printf, env,
+# command) but NOT python3. Resolve their real dir(s) and symlink them in.
+for util in cat printf env bash; do
+  src=$(command -v "$util" 2>/dev/null) && ln -sf "$src" "$FAKEBIN/$util" 2>/dev/null
+done
+nopy_out=$(printf '%s' '{"prompt":"x"}' | PATH="$FAKEBIN" bash "$HOOK" 2>/dev/null)
+nopy_exit=$?
+if [[ "$nopy_exit" -eq 0 && -z "$nopy_out" ]]; then
+  echo "PASS: python3 absent -> exit 0, empty stdout (fail-open)"; PASS=$((PASS+1))
+else
+  echo "FAIL: python3 absent (expected exit=0 + empty stdout, got exit=$nopy_exit stdout=$nopy_out)" >&2; FAIL=$((FAIL+1))
+fi
+rm -rf "$FAKEBIN"
+
+echo "----"
+echo "PASS=$PASS FAIL=$FAIL"
+[[ "$FAIL" -eq 0 ]]

package/payload/platform/plugins/admin/hooks/prompt-optimiser-directive.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook: inject the standing prompt-optimiser directive as
+# additionalContext on every turn, so the agent restates each non-trivial
+# prompt via the prompt-optimiser skill before acting on it. Mirrors
+# doctrine.sh: emit hookSpecificOutput.additionalContext via python3,
+# fail-open with exit 0.
+#
+# Compliance is behavioural, not deterministic. A hook cannot force a skill
+# call; the directive steers the agent, it does not gate the turn. The raw
+# prompt always still reaches the model (UserPromptSubmit output is ADDED to
+# the prompt, never substituted), so "the restatement governs" is an
+# instruction to the agent, not a removal of the original text.
+#
+# Input  (stdin, UserPromptSubmit contract): { "prompt": "...", ... } — drained
+#         and ignored; the directive is standing and prompt-independent.
+# Output (stdout JSON):
+#   { "hookSpecificOutput": { "hookEventName": "UserPromptSubmit",
+#                             "additionalContext": "<directive>" } }
+#
+# Fail-open: if python3 is unavailable or JSON encoding fails, exit 0 with no
+# stdout. The hook must never block or corrupt a turn.
+
+set -uo pipefail
+
+# Drain stdin; the directive does not depend on the prompt text.
+cat >/dev/null 2>&1 || true
+
+# Fail-open if the JSON encoder is unavailable.
+command -v python3 >/dev/null 2>&1 || exit 0
+
+DIRECTIVE=$(cat <<'DIRECTIVE_EOF'
+PROMPT-OPTIMISER DIRECTIVE (standing)
+Before acting on this turn's request, run the prompt-optimiser skill on the user's raw prompt in its in-session restatement mode, then treat the restated task as the authoritative statement of what was asked and proceed from it. Set aside your own first reading of the raw wording; the restatement governs. The raw prompt stays in context for reference only.
+Skip the restatement when the prompt is a one-word confirmation, a slash-command invocation, or a direct continuation of the immediately preceding turn; restatement adds nothing in those cases.
+DIRECTIVE_EOF
+)
+
+OUT=$(printf '%s' "$DIRECTIVE" | python3 -c '
+import json, sys
+ctx = sys.stdin.read()
+print(json.dumps({
+    "hookSpecificOutput": {
+        "hookEventName": "UserPromptSubmit",
+        "additionalContext": ctx,
+    }
+}))
+' 2>/dev/null) || exit 0
+
+[ -n "$OUT" ] || exit 0
+printf '%s\n' "$OUT"
+echo "[prompt-optimiser-directive] injected len=${#DIRECTIVE}" >&2
+exit 0

package/payload/platform/plugins/admin/skills/a4-print-documents/SKILL.md

@@ -2,8 +2,8 @@
 name: a4-print-documents
 description: >
   Constraints for producing print-quality A4 HTML documents intended for PDF output
-  via browser_pdf_save. Use when creating or modifying any HTML document that will be
-  saved as PDF, uses A4 page dimensions, or contains glassmorphism/backdrop-filter effects
+  via the on-device browser-pdf-save tool. Use when creating or modifying any HTML document
+  that will be saved as PDF, uses A4 page dimensions, or contains glassmorphism/backdrop-filter effects
   that must survive print. Trigger phrases: "PDF", "print to PDF", "download PDF",
   "one-pager", "A4", "brochure", "executive document", "market analysis", or any request
   to generate a document for print or download.
@@ -11,11 +11,13 @@ description: >
 
 # A4 Print-Ready HTML Documents
 
-Constraints for producing HTML documents that render correctly when saved as PDF via the personal-assistant's `browser_pdf_save` tool. Every rule exists because violating it caused a visible problem in production documents.
+Constraints for producing HTML documents that render correctly when saved as PDF via the on-device `browser-pdf-save` tool. Every rule exists because violating it caused a visible problem in production documents.
 
 ## Rendering path
 
-Generate the HTML document, then delegate to the personal-assistant to save it as PDF using `browser_pdf_save`. The personal-assistant controls Playwright — you compose the delegation brief describing what to render and any pre-render steps (like glassmorphism screenshot capture).
+Generate the HTML document, then save it as PDF with the on-device browser tools (no Playwright). The order is: capture any glassmorphism print-fallback images first (see below), then `browser-navigate` to the served HTML and `browser-pdf-save` to the output path. `browser-pdf-save` uses Chromium's print pipeline, so `@page` rules, page breaks, and `print-color-adjust` all apply and backgrounds are printed.
+
+Serve the HTML over `http://127.0.0.1:<port>` and navigate to that URL — open it from a local server rather than relying on a `file://` path. `browser-navigate` keeps the page alive so a screenshot pass and the PDF pass act on the same rendered document.
 
 ## Glassmorphism does not survive print
 
@@ -50,19 +52,17 @@ This pattern applies to every full-bleed glassmorphism section (cover pages, bac
 
 ### Capturing the print image
 
-Each glassmorphism section needs its own screenshot — you cannot reuse a print image from a different document or a differently-sized section.
-
-Delegate to the personal-assistant with a brief that includes:
+Each glassmorphism section needs its own screenshot — you cannot reuse a print image from a different document or a differently-sized section. Capture it with the on-device browser tools against the served HTML:
 
-1. **Serve the HTML over HTTP** — `file://` protocol is blocked by Playwright. The specialist should start a local server.
-2. **Set the viewport** to match the element's rendered size. Measure the element's bounding box first, then resize the viewport to `Math.ceil(width) + 1` by `Math.ceil(height) + 1` to eliminate scrollbars.
-3. **Hide UI chrome** (download buttons, navigation overlays) and set `document.body.style.overflow = 'hidden'` to suppress body-level scrollbars.
-4. **Screenshot the specific element** (e.g. `.cover`, `.backpage`) using element-level screenshot — not a full-page or viewport screenshot.
+1. **Serve the HTML over HTTP** and `browser-navigate` to `http://127.0.0.1:<port>/...` — open it from a local server, not a `file://` path.
+2. **Match the viewport to the element.** Read the element's bounding box with `browser-evaluate` (`document.querySelector('.cover').getBoundingClientRect()`), then `browser-resize` to `Math.ceil(width) + 1` by `Math.ceil(height) + 1` to eliminate scrollbars.
+3. **Hide UI chrome** with `browser-evaluate` — hide download buttons and navigation overlays and set `document.body.style.overflow = 'hidden'` to suppress body-level scrollbars.
+4. **Capture the specific element** with `browser-screenshot` passing the element's CSS selector (e.g. `.cover`, `.backpage`) — the selector clips to that element, not the full page.
 5. **Save the PNG** alongside the HTML, named for the section it replaces (e.g. `cover-print.png`, `backpage-print.png`).
-6. **Restore** hidden elements and overflow after capture.
+6. **Restore** hidden elements and overflow with `browser-evaluate` after capture.
 7. **Verify** the saved PNG visually — confirm no scrollbars, no UI chrome, correct dimensions.
 
-After capturing all print images, delegate a second task to save the final PDF via `browser_pdf_save`.
+After capturing all print images, save the final PDF with `browser-pdf-save` to the output path.
 
 ## Page margins, page numbers, and running footers
 
@@ -211,7 +211,7 @@ Multi-page documents follow this structure:
 </div>
 ```
 
-The backpage print image is captured via the same personal-assistant delegation process as the cover — element-level screenshot with UI chrome hidden.
+The backpage print image is captured the same way as the cover — `browser-screenshot` with the element selector, UI chrome hidden via `browser-evaluate`.
 
 ## Single-page documents
 

package/payload/platform/plugins/admin/skills/deck-pages/SKILL.md

@@ -17,7 +17,7 @@ Constraints for producing HTML slide decks that render correctly on screen and e
 
 ## How this differs from A4 print documents
 
-A4 documents use the browser's native print pipeline (`@page` rules, Playwright `browser_pdf_save`). Deck pages bypass print entirely — each slide is rasterized to a canvas and composited into a PDF on the client. This means:
+A4 documents use the browser's native print pipeline (`@page` rules, the on-device `browser-pdf-save` tool). Deck pages bypass print entirely — each slide is rasterized to a canvas and composited into a PDF on the client. This means:
 
 - Glassmorphism and `backdrop-filter` render correctly (no PNG fallbacks needed).
 - Text in the PDF is raster, not vector — so the canvas `scale` factor matters for sharpness.
@@ -29,7 +29,7 @@ Print styles are still included as a fallback for users who Cmd+P, but they are
 
 1. Build the HTML deck with fixed-dimension `.slide` containers.
 2. Add a client-side download button that uses `html2canvas-pro` + `jsPDF`.
-3. Verify each slide visually using Playwright snapshots before declaring the deck complete.
+3. Verify each slide visually using `browser-screenshot` before declaring the deck complete.
 
 ## Slide dimensions
 
@@ -316,25 +316,17 @@ Slides use a compressed typography scale that fits content within the fixed 210m
 
 These sizes are calibrated for 297mm × 210mm at `scale: 2` — they produce readable text in the exported PDF. Smaller sizes become illegible; larger sizes cause overflow.
 
-## Verifying slides with Playwright snapshots
+## Verifying slides with on-device screenshots
 
-Before declaring a deck complete, verify that every slide renders correctly by taking Playwright screenshots. This catches problems that are invisible in the dev server but appear in the PDF: clipped content, broken images, font loading failures, and layout overflow.
+Before declaring a deck complete, verify that every slide renders correctly by taking screenshots with `browser-screenshot`. This catches problems that are invisible in the dev server but appear in the PDF: clipped content, broken images, font loading failures, and layout overflow.
 
 ### Verification process
 
 1. **Start a local server** — the deck must be served over HTTP. `file://` protocol blocks font loading and CORS resources. If Next.js, run `npm run dev` and wait for the ready signal before navigating.
 
-2. **Navigate to the deck page** and wait for fonts and images to load. Use `browser_wait_for` or `browser_evaluate` with `document.fonts.ready` to ensure custom fonts are loaded — otherwise screenshots capture system-font fallbacks that look correct in dev but produce the wrong PDF.
+2. **Navigate to the deck page** with `browser-navigate` and wait for fonts and images to load. Use `browser-wait-for` or `browser-evaluate` with `document.fonts.ready` to ensure custom fonts are loaded — otherwise screenshots capture system-font fallbacks that look correct in dev but produce the wrong PDF.
 
-3. **Screenshot each slide individually** — take an element-level screenshot of each `.slide` div, not a full-page screenshot. Full-page screenshots compress the entire deck into one image and hide per-slide problems.
-
-   Pseudocode for the Playwright loop:
-   ```
-   slides = page.locator(".slide").all()
-   for i, slide in enumerate(slides):
-     slide.scroll_into_view_if_needed()
-     slide.screenshot(path=f"slide-{i+1}.png")
-   ```
+3. **Screenshot each slide individually** — call `browser-screenshot` with each `.slide` element's CSS selector, not a full-page screenshot. Full-page screenshots compress the entire deck into one image and hide per-slide problems. Read the slide selectors from `browser-snapshot` (or compute `.slide:nth-of-type(n)`), and capture each to its own `slide-<n>.png`.
 
 4. **Verify each screenshot against these checks:**
    - Content fits within the slide bounds (no clipping at edges).
@@ -345,15 +337,9 @@ Before declaring a deck complete, verify that every slide renders correctly by t
    - No unexpected scrollbars or overflow indicators.
    - Card grids and tables are evenly spaced.
 
-5. **Test the PDF download** — click the download button via Playwright and verify the generated PDF:
-   ```
-   page.click("button:has-text('Download PDF')")
-   download = page.wait_for_event("download")
-   download.save_as("deck.pdf")
-   ```
-   Then open the PDF and confirm page count matches slide count and no pages are blank.
+5. **Test the PDF download** — `browser-click` the download button, then open the generated PDF and confirm the page count matches the slide count and no pages are blank.
 
-### Common rendering failures caught by snapshots
+### Common rendering failures caught by screenshots
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
@@ -413,6 +399,6 @@ A complete working deck lives at `/Users/neo/capacity-derivatives/app/deck/` —
 - [ ] Download button is outside `.slide` containers (in a fixed overlay).
 - [ ] Dark slides use `backgroundColor: null` in html2canvas config.
 - [ ] Print fallback styles included (`@page`, `@media print`).
-- [ ] Playwright screenshots taken of every slide — content verified.
+- [ ] `browser-screenshot` taken of every slide — content verified.
 - [ ] PDF download tested — correct number of pages, no blank pages.
 - [ ] Fonts loaded before any screenshot or export (check `document.fonts.ready`).

package/payload/platform/plugins/admin/skills/professional-document/SKILL.md

@@ -141,7 +141,7 @@ Before saving the PDF, ask the operator where they want it saved. The operator n
 
 ### 9. Save the PDF
 
-Use `browser_pdf_save` to write the HTML to the operator-named path.
+`browser-navigate` to the served HTML, then `browser-pdf-save` to write the PDF to the operator-named path (on-device Chromium print pipeline; no Playwright).
 
 Emit `[professional-document] pdf-saved path=<operator-named-path> bytes=<n>`.
 

package/payload/platform/plugins/admin/skills/skill-builder/SKILL.md

@@ -46,7 +46,7 @@ Ask what rules the agent should follow when using this skill:
 
 Not every skill needs all of these. Only include what's relevant.
 
-If the skill involves generating PDFs or print-ready documents, load `references/pdf-generation.md` for the constraints on HTML layout and the `browser_pdf_save` rendering path.
+If the skill involves generating PDFs or print-ready documents, load `references/pdf-generation.md` for the constraints on HTML layout and the `browser-pdf-save` rendering path.
 
 ## Step 4: Decide on References
 

package/payload/platform/plugins/admin/skills/skill-builder/references/pdf-generation.md

@@ -1,15 +1,15 @@
 # PDF Generation in Skills
 
-When a skill needs to produce a PDF, the output is always a two-stage process: the skill authors the HTML, and the personal-assistant renders it to PDF via the `browser_pdf_save` MCP tool.
+When a skill needs to produce a PDF, the output is always a two-stage process: the skill authors the HTML, and the agent renders it to PDF with the on-device `browser-pdf-save` tool.
 
 ## The rule
 
-Never instruct the agent to write or execute raw Node.js scripts (e.g. `require('playwright')`, `page.pdf()`, `npx playwright`). Playwright is not in the Node.js module path — these scripts fail with MODULE_NOT_FOUND, waste tool calls searching the filesystem, and produce hardcoded paths that break on reinstall.
+Never instruct the agent to write or execute raw Node.js scripts (e.g. `require('playwright')`, `page.pdf()`, `npx playwright`). Playwright is not on device — these scripts fail with MODULE_NOT_FOUND, waste tool calls searching the filesystem, and produce hardcoded paths that break on reinstall.
 
 Instead, skills that produce PDFs should:
 
 1. **Build the HTML** — the skill's behaviour section describes what the document contains and how it's structured. The agent writes the HTML file using standard file tools.
-2. **Delegate rendering to personal-assistant** — the agent asks the personal-assistant to navigate to the HTML file and call `browser_pdf_save` to produce the PDF. The specialist has Playwright access through governed MCP tools; the admin agent does not.
+2. **Render with `browser-pdf-save`** — serve the HTML over `http://127.0.0.1:<port>`, `browser-navigate` to it, then `browser-pdf-save` to the output path. The tool drives the device's Chromium over CDP (honours `@page`/print CSS, prints backgrounds); no Playwright is involved.
 
 ## Print-ready HTML constraints
 
@@ -27,4 +27,4 @@ HTML intended for PDF output must follow print-ready layout patterns. The most c
 
 ## What the skill file should contain
 
-The skill's SKILL.md describes the document's purpose and structure. A `references/` file holds the HTML template or content specification. The skill should state that PDF rendering is delegated to personal-assistant — it should not contain Playwright code, npm commands, or file path assumptions about the Playwright installation.
+The skill's SKILL.md describes the document's purpose and structure. A `references/` file holds the HTML template or content specification. The skill should state that PDF rendering goes through `browser-pdf-save` — it should not contain Playwright code, npm commands, or file path assumptions about any Playwright installation.

package/payload/platform/plugins/browser/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "browser",
-  "description": "Headless browser rendering for JavaScript-heavy pages. Provides browser-render, which drives the device's existing Chromium over the Chrome DevTools Protocol and returns a page's fully rendered DOM (HTML + visible text). This is the JS-rendering leg of the three-tool retrieval story: WebFetch (lossy summary) / url-get (verbatim, server-rendered) / browser-render (JS-rendered). Use it for client-rendered SPAs and pages that WebFetch or url-get return empty or as a shell.",
+  "description": "Drives the device's existing Chromium over the Chrome DevTools Protocol for both retrieval and interactive automation. browser-render reads a JS-rendered page's DOM (the JS-rendering leg of WebFetch / url-get / browser-render retrieval). The browser-navigate family keeps one page alive across calls for click/fill/snapshot automation, and browser-pdf-save / browser-screenshot turn the rendered page into PDF or PNG files on device. Use it for client-rendered SPAs, form automation, and generating A4 PDFs.",
   "version": "0.1.0",
   "author": {
     "name": "Rubytech LLC"

package/payload/platform/plugins/browser/PLUGIN.md

@@ -1,10 +1,61 @@
 ---
 name: browser
-description: "Headless browser rendering for JavaScript-heavy pages. Provides browser-render, which drives the device's existing Chromium over the Chrome DevTools Protocol and returns a page's fully rendered DOM (HTML + visible text). This is the JS-rendering leg of the three-tool retrieval story: WebFetch (lossy summary) / url-get (verbatim, server-rendered) / browser-render (JS-rendered). Use it for client-rendered SPAs and pages that WebFetch or url-get return empty or as a shell."
+description: "Drives the device's existing Chromium over the Chrome DevTools Protocol for both retrieval and interactive automation. browser-render reads a JS-rendered page's DOM (the JS-rendering leg of WebFetch / url-get / browser-render retrieval). The browser-navigate family keeps one page alive across calls for click/fill/snapshot automation, and browser-pdf-save / browser-screenshot turn the rendered page into PDF or PNG files on device. Use it for client-rendered SPAs, form automation, and generating A4 PDFs."
 tools:
   - name: browser-render
     publicAllowlist: false
     adminAllowlist: true
+  - name: browser-navigate
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: browser-snapshot
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: browser-click
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: browser-fill
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: browser-fill-form
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: browser-type
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: browser-press-key
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: browser-hover
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: browser-select-option
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: browser-wait-for
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: browser-handle-dialog
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: browser-evaluate
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: browser-console-messages
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: browser-tabs
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: browser-pdf-save
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: browser-screenshot
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: browser-resize
+    publicAllowlist: false
+    adminAllowlist: true
 always: true
 embed: false
 metadata: {"platform":{}}
@@ -23,22 +74,41 @@ mcp-manifest: auto
 
 # Browser
 
-Renders JavaScript-heavy web pages and returns the rendered DOM, so the agent can read content that only exists after the page's scripts run.
+Drives the device's Chromium over the Chrome DevTools Protocol for three things: reading JS-rendered pages, automating a page (click/fill/snapshot), and turning a page into a PDF or PNG file on device.
 
 ## Why it exists
 
-`WebFetch` summarises and refuses verbatim output; `url-get` returns the verbatim source but does not execute JavaScript. Client-rendered pages (SPAs, content injected by in-page scripts) come back from both as an empty shell. `browser-render` is the only retrieval path that runs the page's JavaScript and reads the resulting DOM.
+`WebFetch` summarises and refuses verbatim output; `url-get` returns the verbatim source but does not execute JavaScript. Client-rendered pages come back from both as an empty shell. `browser-render` runs the page's JavaScript and reads the resulting DOM. The automation and output tools exist because the specialists previously named a Playwright tool surface (interaction + `browser_pdf_save`) that never actually shipped on a Pi — these tools provide the same capabilities backed by the on-device CDP connection instead.
 
 ## How it works
 
-The device already runs a per-brand Chromium for the VNC surface, launched by `platform/scripts/vnc.sh` with `--remote-debugging-port=${CDP_PORT}`. `browser-render` attaches to that running browser over the Chrome DevTools Protocol — it never launches its own browser, so nothing extra ships on device and there is no on-demand download.
+The device already runs a per-brand Chromium for the VNC surface, launched by `platform/scripts/vnc.sh` with `--remote-debugging-port=${CDP_PORT}`. Every tool attaches to that running browser over the Chrome DevTools Protocol — it never launches its own browser, so nothing extra ships on device and there is no on-demand download. The brand's CDP port reaches this server through the `CDP_PORT` spawn placeholder.
+
+`browser-render` is **stateless**: each call opens a fresh background target, navigates, reads the DOM, and closes it. The automation tools share **one persistent page**: `browser-navigate` creates (or reuses) a single live target, and the action tools drive it across calls. If that page dies (operator closes the tab, crash, browser restart) the action tools return `session-lost` and the agent calls `browser-navigate` again — only navigate re-attaches, so a dead page is never silently replaced mid-action. `browser-tabs` opens/switches/closes pages.
+
+## Tools
+
+Retrieval (stateless):
+- `browser-render` — `url`, optional `loadTimeoutMs`. Returns rendered HTML + visible text.
 
-For each call it opens a fresh background target, navigates to the URL, waits for the page load event, reads `document.documentElement.outerHTML` and the visible `body.innerText`, then closes the target. The brand's CDP port reaches this server through the `CDP_PORT` spawn placeholder.
+Automation (shared persistent page; selectors come from `browser-snapshot`):
+- `browser-navigate` — open a URL and keep the page alive. Entry point for automation.
+- `browser-snapshot` — accessibility snapshot: each interactive/landmark node as role, name, and a unique CSS selector to use with click/fill/hover.
+- `browser-click`, `browser-fill`, `browser-fill-form`, `browser-hover`, `browser-select-option` — act on a CSS selector.
+- `browser-type`, `browser-press-key` — real keyboard input (`Input.*`).
+- `browser-wait-for` — wait for a selector or text to appear.
+- `browser-handle-dialog` — pre-arm how the next JS dialog(s) are answered (CDP dialogs block, so policy must be set before the triggering action).
+- `browser-evaluate` — run a JS expression in the page and return its value.
+- `browser-console-messages` — drain buffered console output + uncaught errors.
+- `browser-tabs` — list / new / select / close pages.
 
-## Tool
+Output (to a file on device):
+- `browser-pdf-save` — `Page.printToPDF` of the current page; the on-device replacement for the old Playwright `browser_pdf_save`.
+- `browser-screenshot` — PNG of the page or one element (CSS selector clip), e.g. glassmorphism print-fallback images.
+- `browser-resize` — set the viewport size.
 
-- `browser-render` — input: `url` (absolute http(s)), optional `loadTimeoutMs`. Returns the rendered HTML and visible text, or a structured failure (`cdp-unreachable`, `navigate-failed`, `load-timeout`, `evaluate-failed`, `websocket-unavailable`). Admin-allowlisted; not exposed to public chat.
+All tools are admin-allowlisted; none are exposed to public chat.
 
 ## Observability
 
-A successful render emits `[browser-render] url=… rendered=true domBytes=…` on the server's stderr (captured by the mcp-spawn-tee log). Failures emit `rendered=false outcome=… detail=…`. On a device with no running Chromium (e.g. a laptop native-display install with no VNC browser) the tool returns `cdp-unreachable` rather than hanging.
+A successful render emits `[browser-render] url=… rendered=true domBytes=…` on the server's stderr (captured by the mcp-spawn-tee log). Every other tool returns a structured outcome: `ok`, or one of `cdp-unreachable`, `session-lost`, `selector-not-found`, `option-not-found`, `wait-timeout`, `navigate-failed`, `load-timeout`, `evaluate-failed`, `command-timeout`, `pdf-failed`, `screenshot-failed`, `unsupported-key`. On a device with no running Chromium (e.g. a laptop native-display install with no VNC browser) the tools return `cdp-unreachable` rather than hanging.

package/payload/platform/plugins/browser/mcp/dist/index.js

@@ -4,7 +4,10 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { eagerTool } from "../../../../lib/mcp-eager/dist/index.js";
 import { z } from "zod";
+import { writeFile } from "node:fs/promises";
 import { renderPage } from "./lib/cdp-render.js";
+import { BrowserSession, DEFAULT_COMMAND_TIMEOUT_MS, DEFAULT_LOAD_TIMEOUT_MS, } from "./lib/cdp-session.js";
+import * as actions from "./lib/cdp-actions.js";
 // Cast to `any` to avoid TS2589 the same way the other plugin servers do.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const server = new McpServer({ name: "maxy-browser", version: "0.1.0" });
@@ -14,6 +17,9 @@ const cdpPortRaw = process.env.CDP_PORT ?? "";
 const cdpPort = Number.parseInt(cdpPortRaw, 10);
 process.stderr.write(`[browser] boot cdpPort=${cdpPortRaw || "-"}\n`);
 const log = (line) => process.stderr.write(`${line}\n`);
+const WebSocketImpl = typeof WebSocket !== "undefined"
+    ? WebSocket
+    : undefined;
 // Cap what we hand back to the model so a large SPA cannot blow the agent's
 // context window. domBytes in the header always reports the true size.
 const MAX_TEXT_CHARS = 200_000;
@@ -27,13 +33,7 @@ eagerTool(server, "browser-render", "Render a JavaScript-heavy web page in the d
     url: z.string().url().describe("Absolute http(s) URL to render"),
     loadTimeoutMs: z.number().int().positive().optional().describe("Max wait for the page load event (default 30000)"),
 }, async (params) => {
-    const result = await renderPage(params.url, { loadTimeoutMs: params.loadTimeoutMs }, {
-        fetchImpl: fetch,
-        WebSocketImpl: typeof WebSocket !== "undefined" ? WebSocket : undefined,
-        cdpHost: "127.0.0.1",
-        cdpPort,
-        log,
-    });
+    const result = await renderPage(params.url, { loadTimeoutMs: params.loadTimeoutMs }, { fetchImpl: fetch, WebSocketImpl, cdpHost: "127.0.0.1", cdpPort, log });
     if (!result.rendered) {
         return {
             content: [{
@@ -55,6 +55,110 @@ eagerTool(server, "browser-render", "Render a JavaScript-heavy web page in the d
             }],
     };
 });
+// ── Interactive automation + output tools ────────────────────────────────────
+//
+// All of these drive ONE persistent page held in `browserSession`, against the
+// same device Chromium over CDP. The page is created by browser-navigate and
+// reused across calls; browser-tabs opens/switches/closes pages. A dead page
+// (operator closed the tab, crash, browser restart) yields a `session-lost`
+// outcome telling the agent to navigate again — only navigate re-attaches.
+const cdpDeps = { fetchImpl: fetch, WebSocketImpl, cdpHost: "127.0.0.1", cdpPort, log };
+const browserSession = new BrowserSession(cdpDeps);
+const actionCtx = {
+    deps: cdpDeps,
+    commandTimeoutMs: DEFAULT_COMMAND_TIMEOUT_MS,
+    loadTimeoutMs: DEFAULT_LOAD_TIMEOUT_MS,
+    writeFile: (path, data) => writeFile(path, data),
+};
+function reply(label, r, successText) {
+    if (!r.ok) {
+        return {
+            content: [{ type: "text", text: `${label} failed: ${r.outcome}${r.detail ? ` — ${r.detail}` : ""}` }],
+            isError: true,
+        };
+    }
+    return { content: [{ type: "text", text: successText ?? `${label}: ok` }] };
+}
+eagerTool(server, "browser-navigate", "Open a URL in the device's Chromium and keep the page alive for follow-up automation (click, fill, snapshot, pdf-save, screenshot). This is the entry point for interactive browser work — call it before any other browser-* automation tool. Reuses the one live automation page; use browser-tabs to open a separate page. For one-shot read-only retrieval of a JS page use browser-render instead.", {
+    url: z.string().url().describe("Absolute http(s) URL to open"),
+    loadTimeoutMs: z.number().int().positive().optional().describe("Max wait for the page load event (default 30000)"),
+}, async (params) => reply("browser-navigate", await actions.navigate(browserSession, params, actionCtx), `Navigated to ${params.url}`));
+eagerTool(server, "browser-snapshot", "Return an accessibility snapshot of the current page: each interactive or landmark element as role, accessible name, and a unique CSS selector. Use the returned selector verbatim with browser-click / browser-fill / browser-hover — it targets exactly the element you saw. Call this after browser-navigate (or after an action changes the page) to know what is on the page.", {}, async () => {
+    const r = await actions.snapshot(browserSession, {}, actionCtx);
+    return reply("browser-snapshot", r, r.data?.text);
+});
+eagerTool(server, "browser-click", "Click the element matching a CSS selector on the current page. Use a selector from browser-snapshot. Returns selector-not-found if nothing matches.", { selector: z.string().describe("CSS selector of the element to click") }, async (params) => reply("browser-click", await actions.click(browserSession, params, actionCtx), `Clicked ${params.selector}`));
+eagerTool(server, "browser-fill", "Set the value of one input, textarea, or contenteditable matching a CSS selector, firing input/change events. For multiple fields in one call use browser-fill-form.", {
+    selector: z.string().describe("CSS selector of the field"),
+    value: z.string().describe("Value to set"),
+}, async (params) => reply("browser-fill", await actions.fill(browserSession, params, actionCtx), `Filled ${params.selector}`));
+eagerTool(server, "browser-fill-form", "Fill several fields in one call. Each field is a CSS selector and the value to set. Reports every selector that matched nothing.", {
+    fields: z.array(z.object({
+        selector: z.string().describe("CSS selector of the field"),
+        value: z.string().describe("Value to set"),
+    })).describe("Fields to fill"),
+}, async (params) => reply("browser-fill-form", await actions.fillForm(browserSession, params, actionCtx), `Filled ${params.fields.length} field(s)`));
+eagerTool(server, "browser-type", "Type text into the focused element via real keyboard input. Pass a selector to focus that element first. Use this when setting value directly (browser-fill) does not trigger the page's keystroke handlers (autocompletes, rich editors).", {
+    text: z.string().describe("Text to type"),
+    selector: z.string().optional().describe("Optional CSS selector to focus before typing"),
+}, async (params) => reply("browser-type", await actions.type(browserSession, params, actionCtx), "Typed text"));
+eagerTool(server, "browser-press-key", "Press a single key on the focused element (Enter, Tab, Escape, Backspace, Delete, Arrow keys, Home, End, PageUp, PageDown, Space, or a single character). Use for submitting forms (Enter) or keyboard navigation.", { key: z.string().describe("Key name or single character") }, async (params) => reply("browser-press-key", await actions.pressKey(browserSession, params, actionCtx), `Pressed ${params.key}`));
+eagerTool(server, "browser-hover", "Hover the pointer over the element matching a CSS selector, firing pointer/mouse-over events. Use to reveal hover menus or tooltips before reading or clicking.", { selector: z.string().describe("CSS selector of the element to hover") }, async (params) => reply("browser-hover", await actions.hover(browserSession, params, actionCtx), `Hovered ${params.selector}`));
+eagerTool(server, "browser-select-option", "Choose an option in a <select> dropdown by option value or visible label, firing a change event.", {
+    selector: z.string().describe("CSS selector of the <select>"),
+    value: z.string().optional().describe("Option value to select"),
+    label: z.string().optional().describe("Option visible text/label to select"),
+}, async (params) => reply("browser-select-option", await actions.selectOption(browserSession, params, actionCtx), `Selected option in ${params.selector}`));
+eagerTool(server, "browser-wait-for", "Wait until an element (CSS selector) appears or some text is present on the page, up to a timeout. Use after an action that loads content asynchronously, before reading or interacting.", {
+    selector: z.string().optional().describe("CSS selector to wait for"),
+    text: z.string().optional().describe("Visible text to wait for"),
+    timeoutMs: z.number().int().positive().optional().describe("Max wait (default 30000)"),
+}, async (params) => reply("browser-wait-for", await actions.waitFor(browserSession, params, actionCtx), "Condition met"));
+eagerTool(server, "browser-handle-dialog", "Arm how the next JavaScript dialog(s) — alert, confirm, prompt — on the current page are answered. Set this BEFORE the action that triggers the dialog, because dialogs block the page and cannot be answered after the fact. The policy stands until changed. Unarmed dialogs are auto-dismissed and reported by browser-console-messages.", {
+    accept: z.boolean().describe("true to accept/OK, false to dismiss/Cancel"),
+    promptText: z.string().optional().describe("Text to enter into a prompt() dialog when accepting"),
+}, async (params) => reply("browser-handle-dialog", actions.handleDialog(browserSession, params), `Dialog policy armed: accept=${params.accept}`));
+eagerTool(server, "browser-evaluate", "Run a JavaScript expression in the current page and return its value (awaits a returned promise). Use for reading page state or driving behaviour that no other tool covers. The expression runs in the page, not in Node.", { expression: z.string().describe("JavaScript expression to evaluate in the page") }, async (params) => {
+    const r = await actions.evaluate(browserSession, params, actionCtx);
+    return reply("browser-evaluate", r, `Result: ${JSON.stringify(r.data?.value ?? null)}`);
+});
+eagerTool(server, "browser-console-messages", "Return and clear the buffered console output and uncaught errors from the current page (captured since navigation). Use to debug why a page or interaction did not behave as expected.", {}, async () => {
+    const r = actions.consoleMessages(browserSession);
+    return reply("browser-console-messages", r, r.data?.text);
+});
+eagerTool(server, "browser-tabs", "Manage browser tabs/pages: list open pages, open a new page (optionally at a URL and switch to it), select an existing page by id, or close a page by id. Use 'new' or 'select' to get a fresh page so stale state from a prior task does not leak in.", {
+    action: z.enum(["list", "new", "select", "close"]).describe("Tab action"),
+    id: z.string().optional().describe("Target id (required for select/close)"),
+    url: z.string().optional().describe("URL to open (optional for new)"),
+}, async (params) => {
+    const r = await actions.tabs(browserSession, params, actionCtx);
+    const text = params.action === "list"
+        ? "Tabs:\n" + (r.data?.tabs ?? [])
+            .map((t) => `${t.active ? "* " : "  "}${t.id} — ${t.title || "(untitled)"} — ${t.url}`).join("\n")
+        : `tabs ${params.action}: ok`;
+    return reply("browser-tabs", r, text);
+});
+eagerTool(server, "browser-pdf-save", "Render the current page to a PDF file on the device using Chromium's print pipeline (honours @page/@media print CSS, prints backgrounds). Pass an absolute output path. This is the on-device replacement for the old Playwright browser_pdf_save: navigate to the HTML (served over http, or a file path the browser can open), then call this.", {
+    path: z.string().describe("Absolute output path for the .pdf file"),
+    landscape: z.boolean().optional().describe("Landscape orientation (default false)"),
+    scale: z.number().optional().describe("Scale of the page rendering (default 1)"),
+    printBackground: z.boolean().optional().describe("Print background graphics (default true)"),
+}, async (params) => {
+    const r = await actions.pdfSave(browserSession, params, actionCtx);
+    return reply("browser-pdf-save", r, `Saved PDF to ${params.path} (${r.data?.bytes ?? 0} bytes)`);
+});
+eagerTool(server, "browser-screenshot", "Capture a PNG of the current page (or one element, via a CSS selector clip) to a file on the device. Pass an absolute output path. Use selector clips to capture glassmorphism/blur sections as print fallback images for A4 PDFs.", {
+    path: z.string().describe("Absolute output path for the .png file"),
+    selector: z.string().optional().describe("CSS selector to clip to a single element"),
+    fullPage: z.boolean().optional().describe("Capture beyond the viewport (default false)"),
+}, async (params) => {
+    const r = await actions.screenshot(browserSession, params, actionCtx);
+    return reply("browser-screenshot", r, `Saved screenshot to ${params.path} (${r.data?.bytes ?? 0} bytes)`);
+});
+eagerTool(server, "browser-resize", "Set the current page's viewport size in CSS pixels. Use before a screenshot to control the rendered dimensions (e.g. match an element's measured size to avoid scrollbars).", {
+    width: z.number().int().positive().describe("Viewport width in CSS pixels"),
+    height: z.number().int().positive().describe("Viewport height in CSS pixels"),
+}, async (params) => reply("browser-resize", await actions.resize(browserSession, params, actionCtx), `Resized to ${params.width}x${params.height}`));
 process.on("SIGINT", () => process.exit(0));
 const transport = new StdioServerTransport();
 await server.connect(transport);