Evaluate JS

Run small, bounded JavaScript evaluations for page introspection (read a counter, check a flag, verify a title) without dumping unbounded DOM back to the model.

This page covers:

• What “bounded output” means
• How to call evaluate-js directly (Python) or via Tool Registry (Python + TypeScript)
• When to use read() instead

Table of Contents

1. When to use it
2. Python: runtime evaluation
3. Tool Registry: evaluate_js tool
4. Examples

When to use it

Good fits:

• check document.title
• read a small counter (window.__APP_STATE__.count)
• check presence of a global flag

Avoid:

• extracting lists of products
• exporting DOM/HTML
• “scraping” via querySelectorAll dumps

CAPTCHA handlers and page-control

If you build a custom CAPTCHA solver, you can call a page-control JS hook from the handler to read or write small bits of page state in the same live session. Keep the JS bounded and focused on single values.

async def captcha_handler(ctx):
  # Small, bounded JS to read/patch the page
  challenge = await ctx.page_control.evaluate_js("/* read a token or sitekey */")
  await ctx.page_control.evaluate_js("/* inject a solution token */")
  return {"action": "wait_until_cleared"}

Python: runtime evaluation

Python runtime exposes a safe evaluate helper that returns a bounded, textual result.

from predicate.models import EvaluateJsRequest

result = await runtime.evaluate_js(EvaluateJsRequest(code="document.title"))
if result.ok:
    print(result.text)
else:
    print("error:", result.error)

Tool Registry: evaluate_js tool

Both SDKs include a default evaluate_js tool in their Tool Registry pack.

from predicate.tools import ToolRegistry, ToolContext, register_default_tools

registry = ToolRegistry()
register_default_tools(registry, runtime)

ctx = ToolContext(runtime)
out = await registry.execute(

Examples

Guard against a wrong page

from predicate.models import EvaluateJsRequest

title = await runtime.evaluate_js(EvaluateJsRequest(code="document.title"))
runtime.assert_(lambda _snap: bool(title.ok and title.text and "Checkout" in title.text), "title_contains_checkout")

Related topics

• Tool Registry — typed tools + tool_call trace events
• Content Reading — full text/markdown extraction