#2236

feat(flow): record a browser task once and replay its requests

DraftRaillywants to merge intofrom

Problem

An agent that repeats a browser task drives the page every time: open, snapshot, click, read. Most of that work only exists to reach data the page already fetches from its own API.

Changes

  • flow start <name> and flow save record a task and keep the first-party requests behind it: JSON API responses, and JSON that server-rendered pages embed (__NEXT_DATA__, JSON-LD, window.x = {...})
  • Cookies, authorization and token or CSRF headers are never saved; each run reads cookies from the live session
  • Params come from --param, from query values of the recorded page URL, and from values picked out of earlier responses; values copied from a single field are filled from that response on every run
  • flow run <name> --param k=v --where f=v --fields a,b --limit n replays the flow and returns only what the task needs
  • A run tries direct HTTP, then the same request from the page, then a replay of the recorded commands, and starts the next run at the tier that worked
  • Every tier checks the response against the recorded shape; a change marks the flow unverified, and a response that only lacks its lists counts as no results
  • Writes (anything but GET and GraphQL queries) need --allow-write, and a write the site accepted is never resent by a lower tier
  • A command replay needs --allow-write whenever the recording caused any write, since it repeats every recorded command
  • Every request and redirect follows the session's current domain allowlist
  • Values typed into password-like fields are not stored, auth and credential commands are not recorded, and flow files are owner-only
  • Saved flows use the shape of a WebMCP tool (name, description, inputSchema from the params); flow list returns it and webmcp list shows flows in it after the tools the page declares
  • After navigation, responses list the saved flows for the site; when the page declares WebMCP tools, those come first and the hint suggests them when one covers the task
  • MCP: flow_list, flow_run, flow_start and flow_save in the core profile
  • flow list, text output, core skill, commands reference, network docs page and README

Open questions:

  • command name: flow at the top level, or under network
  • a dedicated docs page needs the docs route suite to allow new pages, so this is a section of the network page for now

Visual proof

Recording on a local fixture shop:

A new session on a page that also declares a WebMCP tool: the declared tool comes first, webmcp list shows the saved flow in the same shape, and the flow runs with a new param:

Activity

26

This pull request is a draft

Merging is unavailable until it is marked ready for review.