Skip to content

saved flows

Dr K edited this page Nov 14, 2026 · 5 revisions

Saved flows

A flow is a named YAML document of steps, each one a tool call. run_flow runs every step on the server, in order, in the browser the caller already holds, so a sequence somebody got right is replayed in one call. This area covers what a document is, where documents live and who may write them, how a flow says where it applies and how a page names the flows that fit it, saving, running, and the resources and routes that serve them.

Use cases

  • An agent saves a sign-in as login with sites and paths, and every later session that lands on that page is told login exists.
  • An agent runs a flow an operator shared in global and reads a line per step. A mistake in step nine is refused at save, with every other mistake, before a browser moves.
  • An admin edits a flow's YAML with its comments kept and moves it into global.

Neighbours

FLOW-1. The workspace and its browser are in workspaces-and-sessions.md; the token the routes sit behind in auth-and-roles.md; tools, routes and error statuses in surfaces.md; what each action a step names does in browser-actions.md; binding a secret and every scrub in secrets-and-scope.md; the history a run adds to in site-data.md; a person holding the browser in live-view-and-control.md; the Flows tab in admin-ui.md.

The document

FLOW-2. A flow document is a YAML mapping with the keys name, description, sites, paths, parameters, timeout and steps. name and steps are required. A caller sets the other six.

FLOW-3. description is a string. sites and paths are lists of strings, each a place (FLOW-19 to FLOW-24). parameters is a JSON Schema object whose properties are the parameters and whose required lists the ones every run must supply (FLOW-8). timeout is a whole number of seconds, at least 1 (FLOW-33). steps is a non-empty list.

FLOW-4. The file name is the flow's identity: a stored flow is read with its name set to the file's, whatever the YAML says. A name is 1 to 64 characters of letters, digits, dots, dashes and underscores, starting with a letter or digit; surrounding whitespace is trimmed and any other name is refused, never rewritten. A document is at most 1 MiB of YAML, else a flow is limited to 1 MiB of YAML, a 413.

FLOW-5. The document's shape is served at flow://schema and GET /schemas/flow, built once from the live tool schemas: each document key, each step key, x-step-params (every tool a step may name, session_id removed), x-parameters and x-secret.

Steps

FLOW-6. A step is an object with tool and args, and may carry id, onError, return and note. Any other key is refused, naming the keys a step takes. timeout is not a step key. args holds exactly the arguments the named tool takes when called directly. id and note are strings, and id is unique in the flow. return is a boolean: true puts the step's full result in the report (FLOW-35). onError is abort (the default) or continue (FLOW-32).

FLOW-7. A step names any browser action in the capability table, including save_site_data, screenshot and keep_file. It may not name open_session, end_browser, await_control, outline or network_body, and each refusal says why: a flow runs in the browser the caller holds, a person cannot be waited for inside a run, and the last two are for working a flow out. run_flow, save_flow and the resource tools are not steps, and args may not name session_id.

Parameters

FLOW-8. A parameter is declared under parameters.properties, one JSON Schema per name, and is written ${name} in a step's args. A name in required that is not in properties is refused. A parameter marked writeOnly is refused: a parameter is text and may appear in a report, and a value nobody may see is a secret (FLOW-10).

FLOW-9. ${name} may sit in any string in args, at any depth, and inside a longer string. An argument that is exactly one reference takes the value with its type kept; elsewhere the value is written into the text. $${ is a literal ${. Substitution is one pass, so a supplied value is never scanned again. At run time a reference to a name the run was not given stays as written, which keeps a JavaScript template literal in a script argument intact.

FLOW-10. A secret is not a parameter. A step types one with write's secret argument, and no other tool takes one. SEC-17, SEC-18 and SEC-25 give the rules, which saving and running enforce.

FLOW-11. A parameter's default is used when a run omits it, and does not satisfy required. A run that omits a required name, or passes one the flow does not declare, is refused before step one with <flow> needs <names>: pass them in params or <flow> does not take <names>. Takes: <declared>. It is a 400, not a report.

Where flows live

FLOW-12. Saved flows are on only when data.dir is set. With it unset every flow resource, tool and route answers saved flows are not enabled on this server: it was started with no DATA_DIR, so there is nowhere to keep them.

FLOW-13. A workspace's flows are the files <data.dir>/workspaces/<workspace>/flows/<name>.yaml, its library. The library global is shared: every workspace reads and runs its flows. The stdio transport has its own library, stdio.

FLOW-14. A caller's library is its workspace name, or global when it named none, which it may read and may not write. global and stdio cannot be chosen as a workspace name.

FLOW-15. A name defined in both a workspace and global resolves to the workspace's, in a listing, a read and a run. A run's report says which library the flow came from in workspace.

FLOW-16. An agent writes only its own library. save_flow and delete_flow by a caller with no workspace name are refused: the shared 'global' library is read-only: every workspace can list and run what is in it, so a flow you changed or deleted would change or vanish under another workspace mid-run, and the refusal says to name a workspace. Saving a name that was read from global writes a copy into the caller's own library. Only the admin writes global (FLOW-45 to FLOW-47).

FLOW-17. A listing (flow://flows, GET /flows) is {workspace, count, flows}: the caller's flows and global's, by name. Each entry has name, workspace, description, parameters, step_count and shared, and sites and paths when readable. It never holds steps. shared says which directory holds the flow, so a caller whose library is global sees shared: true.

FLOW-18. A read of one flow (flow://flows/{name}, GET /flows/{name}) returns the document with its steps, workspace (the library it came from) and shared. A name in neither library is no flow called '<name>' in <workspace> or the shared library. flow://flows lists what there is., a 400.

FLOW-54. A flow document is parsed with the safe YAML loader, libyaml when PyYAML has it. The parsed document is cached by its text, one entry per distinct text, so a save, a hand edit or a coarse clock cannot serve a stale flow. The cache holds 4 MiB of YAML plus 1,024 bytes per entry, least recently used out first, and a document larger than the whole cache is parsed and not kept. A caller gets a copy of what it reads. A save writes keys in the order given, width 100, with non-ASCII characters kept, because a person reads this text in the admin editor.

Placing a flow

FLOW-19. sites and paths say where a flow applies. They are for finding a flow and never restrict a run: a flow is listed and runnable wherever the browser is. They are unrelated to a secret's leash (SEC-9). A flow with neither is never named in flows_here, and save_flow's description says so; with only paths it applies on every site, and with only sites on every path of those sites.

FLOW-20. A site is a host with an optional port. A site with a port matches only that port; one without matches any. The scheme is ignored. A URL's port is its explicit port or its scheme's default, so example.com:443 matches https://example.com/. Hosts compare without case and as IDNA, and an IPv6 host is written in brackets. *. in front matches a subdomain of any depth and never the apex: *.example.com matches a.b.example.com and not example.com.

FLOW-21. A path is exact, compared with case and without a trailing /. * matches any run of characters inside one segment. ** as a whole segment matches zero or more segments, so /docs/** matches /docs and /docs/a/b. The query is ignored.

FLOW-22. A path entry that contains # also names a hash route, matched as a second path with the same * and **: /#/auth/* or /app/#/settings/**. An entry without # matches any route, so / covers every screen of a hash-routed app.

FLOW-23. A route is a fragment that starts with / or !/. Its !, its own query and a trailing / are dropped, so #!/a and #/a are one route. #/ is the root route, which differs from no route. Any other fragment (#top, #access_token=...) is ignored. An entry with # never matches a URL with no route, and /#/ matches the root route only. A URL that is not http or https, or has no host, matches nothing, so a cleared page (about:blank) names no flow.

FLOW-24. Saving refuses a bad place and names what to write. sites and paths, when given, are non-empty lists of strings (sites is empty: leave it out to match any site).

  • A site is refused for a scheme, a user name, a path, ? or #, a bare *, a * other than the leading *., a non-host, and a port outside 1 to 65535.
  • A path is refused when it does not start with / (a lone #route is told to write /#route), has two #, a fragment that is not a route, a query, ** inside a segment, or //.
  • A duplicate entry is kept.

A stored flow whose places cannot be read is listed without them, never named in flows_here, and still runs; the log names it, never a value.

Which flows a page names

FLOW-25. flows_here(workspace, url) returns the flows that apply to url: the workspace's own first, then global's, each in name order, at most 10. A global flow is left out when the workspace has a flow of that name at all, placed or not, because a run by that name runs the workspace's. The answer is cached per library under its revision (names, inodes, sizes and modification times), so a warm call stats the directory and reads no flow. The cache has no time limit.

FLOW-26. An entry is {name, uri, description, parameters, required} and, for a global flow, shared: true. uri is flow://flows/{name}. parameters and required are lists of names, not schemas. A caller gets a copy, and a hint put on a result has its description scrubbed for secrets as a resource read is.

FLOW-27. A call's result carries flows_here only when it left the browser on a different page from the record's, meaning a different host, port, path or route, and only when some flow applies. A change of query, scheme or non-route fragment is not a different page. The field is absent, never empty.

FLOW-28. open_session carries flows_here for the page it opened on every time, as does an open that lost a race and returned the other's browser. workspace://current carries it for the record's page, read from the record and never the Grid. A page withheld from the record (it carried a secret's value) never hints. A failure while hinting is logged and never fails the call.

FLOW-29. A flow step carries no hint. The run's report carries flows_here for the page the run ended on, compared with the page the record held before the run. The flow that just ran is not left out, and a report with url_redacted has none.

Running a flow

FLOW-30. run_flow(name, params, verbose) and POST /flows/{name}/runs (body params, verbose) run a flow in the caller's browser. The caller names a workspace, because a run drives a browser. With no open browser the run is refused with no session is open in workspace <name> yet before the flow is read, and a reaped browser is reopened first. The browser is resolved once.

FLOW-31. Steps run in order, once each, with no branching, loop or step reading another's output. Each step takes the browser's turn for its duration, so another call on the session runs between two steps, not after the whole run.

FLOW-32. A step that fails stops the run and status is failed. With onError: continue the run goes on and the step's line is ok: false; status stays ok when no other step stops the run. onError: continue is not honoured for an assert, for a step refused because a person holds the browser, or for a cancelled run.

FLOW-33. A run stops before a step when:

  • the budget has passed (the run passed its <n>s budget before this step);
  • the run was cancelled (the run was cancelled before this step), because the caller's call was cancelled or the browser ended;
  • the step's secret was refused;
  • a step's result could not be checked for secrets (the error is the fixed sentence this call's result could not be checked for secrets, so it is not returned), whatever onError says.

A step that has started is never interrupted: its own wait_timeout bounds it. The budget is the document's timeout, else 120, checked before each step.

FLOW-34. The report is {flow, workspace, status, steps_run, steps_total, steps} with status ok or failed, plus url and title of the last page a step reported, page when capture is on, flows_here (FLOW-29), reopened and site_data as any call carries them, and url_redacted: true when that page carried a guarded value, so url is scrubbed and is not an address to go back to.

FLOW-35. A step's line is {n, tool} plus the keys that apply: id, note, summary, ok, error, url (only when the step moved the page and the page is safe to show), file (when the step kept one) and result (only when the step says return: true or the run is verbose). Silence is information: a step with no url did not move the page.

FLOW-36. A result loses image and every guarded value, and a step's error is one line scrubbed of every value the run typed and every secret in scope where it ran (SEC-46). A summary is built from url, selector, to, action, key, filename and index only, and says text=<n> chars for typed text. A value typed from a secret shows as [secret:<name>/<key>].

FLOW-37. A failed run carries hint for its last step: {prompt: "repair_flow", arguments: {flow, step}}, and read and section naming a skill page (FLOWS.md or TROUBLESHOOTING.md) when the skill is served. The page is chosen by what failed: a budget stop, an assertion or a locator.

FLOW-38. A run is refused before step one, as a report with status: failed, steps_run: 0, a hint and one line giving the reason, when the stored document is malformed (this flow cannot be run as written), has a writeOnly parameter, has a bad timeout, or has a step in the old format (a params or valueFrom key: this flow was saved in an older format). A step naming a tool that is not runnable fails with there is no action called '<tool>'. A step that reads a kept file (upload_file) is answered from the caller's own library, whatever the document says.

FLOW-39. A run adds its pages to the workspace's history once, in order (steps that succeeded and moved, and the final page unless withheld), slides the record's idle time, writes a resize step's size to the record, and writes the pages reached so far before a save_site_data step.

FLOW-40. Over MCP a run reports progress while it works, step <n>/<total>: <summary> at each step and on a heartbeat inside a long one, to a client that sent a progress token. Cancelling the call stops the run at its next step.

Saving

FLOW-41. save_flow(name, steps, description, sites, paths, parameters, timeout) and PUT /flows/{name} create or replace one flow in the caller's own library. The document is validated before anything is written, and one that fails is refused with every reason at once: this flow cannot be saved: and one - line per problem, a 400.

FLOW-42. Saving checks each step against its tool's live schema, with the position in the message (step 3 (login)). It refuses:

  • an unknown tool (listing the available ones) and an unknown argument (listing the tool's);
  • a wrong JSON type, and a value outside a closed set (compared without case);
  • a missing required argument, and an argument that belongs inside selector (it goes inside selector);
  • a selector without exactly one of xpath and css;
  • an assert with onError: continue, since a run that goes on after a false assertion reports success it did not earn;
  • a write with neither text nor a secret;
  • an action that needs an element and names none;
  • a drag without exactly one destination (to, or by_x and by_y not both zero).

An argument that is exactly one reference is not type-checked, since the run supplies its value.

FLOW-43. A ${name} that is not declared is refused with the declared names listed and the $${ escape named. parameters written as a map of names ({email: string}, or with no properties, names the steps reference) instead of a schema is refused with the corrected properties object. A parameters that is not an object, properties that is not an object and required that is not a list of names are refused.

FLOW-44. null for timeout, sites or paths means unset, workspace and shared in the document are dropped and a timeout given as digits is stored as an integer. The file is written whole by renaming a temporary file over it, so a reader sees the old document or the new one.

A save returns {saved: true, workspace, name, ...the stored document}, checked for secrets as a resource is, with warnings when the first step acts on whatever page the browser is on (its tool is not navigate or assert and it has no url). The flow is kept either way.

Editing, moving and deleting

FLOW-45. The admin's save stores YAML text verbatim, comments and order kept, after validating the parsed document as a save does. It refuses text that is not YAML (the message gives a line and column, never the line), not a mapping, over 1 MiB, or whose name differs from the file's. It writes the flow where it lives, global included, and creates a new one in the workspace. It does not coerce timeout or return warnings.

FLOW-46. The admin moves a flow by writing it to the target library and then deleting it from the source, so a failure between the two leaves it in both. A move to the library it is in does nothing. The admin reads and deletes a flow in the library that holds it.

FLOW-47. delete_flow(name) and DELETE /flows/{name} remove one flow from the caller's own library and return {deleted, workspace, name}; a flow that is not there is deleted: false, not an error. Deleting from global is refused as FLOW-16 says.

FLOW-48. A flow file edited on disk is picked up by the next read. A file that is not YAML, not a mapping or not UTF-8 reads as absent and is logged; it never fails a listing. A file whose stem is not a usable flow name, a link or a hidden file is not a flow. Nothing validates a hand edit at read: the run's checks (FLOW-38) refuse a bad one.

Surfaces

FLOW-49. Reads are resources and writes are tools: flow://flows, flow://flows/{name} and flow://schema; save_flow, run_flow and delete_flow. run_flow and delete_flow are annotated destructive, save_flow and delete_flow idempotent. The HTTP routes are GET /flows, GET /flows/{name}, PUT /flows/{name}, DELETE /flows/{name}, POST /flows/{name}/runs and GET /schemas/flow, all behind the server's token and not rows of the capability table. An HTTP save takes the keys of FLOW-2 from the body and ignores any other; an HTTP run reads verbose as a boolean, so the string "false" is false.

Proposed: several sessions in a workspace

Not built. The reasoning, and the questions still open, are in the multiplayer design.

FLOW-50. (proposed) One run of a flow is one lane. run_flow takes session and transport (ACT-44), and every step runs in that session over that transport.

FLOW-51. (proposed) A step names no session, window or transport, so one flow never reaches across sessions or windows. Replaces, when built, FLOW-6's "args holds exactly the arguments the named tool takes when called directly" for session and transport. How save_flow refuses a step that names one, and whether a run may follow a popup window its own page opened, are open.

Proposed: tags

Not built. The reasoning, and the questions still open, are in the flow tags design.

FLOW-52. (proposed) A flow document has an optional key tags, a list of strings. What a tag may be is open.

FLOW-53. (proposed) A library listing carries each flow's tags. Tags group flows and never place them: which flows a page offers stays with sites and paths (FLOW-19).

Clone this wiki locally