plan runs several input actions that one observation already decided, then returns
the synchronized state. Filling a form or setting a report's filters takes one model
turn instead of one per action.
| Entry point | Name |
|---|---|
| CLI | bsk plan |
| MCP | bsk_plan |
| Wire protocol | None; the client sends each step's existing tool.* request |
bsk plan --session abcd --context CURRENT --until-visible '#summary' --steps '[
{"action":"select","ref":"@e45","values":["east"]},
{"action":"select","ref":"@e46","values":["done"]},
{"action":"click","ref":"@e49"}
]'A step is an action beside the fields that action's bsk step --params takes, and
optional expect. Actions are click, fill, select, press, hover, scroll-to,
wheel and drag, plus wait-for-element (ref or selector, state, timeout_ms)
for a condition that later steps need. _ and - are interchangeable in these names.
A plan holds 1 to 20 steps.
bsk plan and bsk_plan are available by default. In MCP, call bsk_plan directly:
{"session":"abcd","context":"CURRENT","steps":[
{"action":"fill","ref":"@e3","value":"Ada"},
{"action":"select","ref":"@e4","values":["CN"]}
]}Use context and, for an untargeted first step, observation on the outer bsk_plan
call. Steps use protocol names such as ref and timeout_ms; put expect on the
step it protects. until_visible, wait_timeout_ms, and max_tokens (--max-tokens
on CLI) work on bsk_plan as with bsk_interact; --save-full and --baseline are
CLI options on bsk plan.
{"ok":false,"completed":1,"total":3,
"stopped":{"index":1,"action":"select","effect_state":"none","error":{"message":"..."}},
"not_run":[2],"post":{"context_id":"...","observation":{"text":"..."}},"elapsed_ms":412}completedcounts the steps that finished, always the first ones in order.stoppednames the step that ended the plan.effect_stateisnone,committedorunknown, and isunknownwhenever the failure carries no evidence that nothing was sent.notesholds receipt details the final state cannot show, such as handled dialogs.postis the same read-only sync asbsk step. It also follows a refused or failed step, so the caller can replan without another call. It is omitted after a stop request, a native dialog, a timeout or a lost connection, and a human hold returns no context.readinessholds the--until-visiblewait, which runs only after every step completed. Exit status andisErrorfollowok.
The client sends the same request each step's own command would, so the extension checks
control, the target and expect immediately before every input. Human input between two
steps refuses the next step. All steps stay on the plan's tab, even if a click opens another.
A plan is not a transaction. Completed steps stay done, and nothing is retried or rolled
back. It removes the model between actions, so it must not be used where a later action
depends on what an earlier one reveals. An irreversible action such as submit or pay
belongs in its own call after reading the state, unless expect protects its facts.
- Steps share one control context, which requires target policy and daemon protocol 1.8. Under strict policy a context authorizes one action, so a plan stops after its first step.
- A strict observation authorizes one action on the page as observed, so only the first
step may be untargeted, and it needs
--observation. navigateandevaluaterun on their own: navigation retires the context, and a script's result usually decides what comes next.- The 120-second budget is checked between steps. A step in flight finishes under its own timeout, because cutting it short would turn a clean result into an unknown effect.