Electron Stagewrightdocs

ADR-026: Workflow composition without hidden tool calls

Context

Repeated Electron automation flows invite a “macro” feature: one call could launch an app, inspect it, interact, assert, and collect evidence. Fewer model turns can reduce latency and context use. The word macro, however, hides three materially different designs:

  1. a generic tool such as run_macro({ command, args }) or run_workflow({ steps });
  2. a named server-side tool whose handler re-dispatches a fixed sequence of other tools;
  3. a user-reviewed workflow artifact executed outside the model's interactive tool-selection loop.

The first design conflicts directly with ADR-007. Independent Electron MCP implementations moved away from nested command selectors because granular top-level tools materially improved model tool selection and argument accuracy. A generic step runner would reintroduce the same ambiguity under a new name.

The second design is typed and discoverable, but it cannot currently preserve every authorization and trace guarantee:

The third design already has a concrete foundation: ADR-009's promoted replay specifications are reviewable JSON, validate each fixed tool call through the dispatcher, preserve explicit checkpoints, and run headlessly in CI. They are automation artifacts rather than model-selected interactive macros.

MCP also distinguishes user-controlled prompts from model-controlled tools. A prompt or documented recipe can guide an interactive sequence while leaving every underlying tool call visible to the host. Experimental MCP tasks provide deferred execution and polling; they do not make nested tool authorization visible and therefore do not resolve this decision.

Decision

1. Do not add a generic macro or workflow-runner tool

Electron Stagewright will not ship a public tool whose input selects arbitrary commands, tool names, or step arrays. In particular, no electron_macro, run_macro, or run_workflow({ steps }) surface will be registered.

This preserves the granular tool-selection contract and prevents one broadly approved tool from becoming an unbounded proxy for the rest of the manifest.

2. Keep interactive composition host-visible

Interactive recipes remain sequences of ordinary top-level tool calls. They may be taught through server instructions, resources, documentation, or a future MCP prompt surface, but the recipe itself does not execute tools.

This means:

Prompts are optional guidance, not a prerequisite for using the server. A future prompt addition must be validated against at least two supported MCP hosts before public documentation depends on it.

3. Keep deterministic automation in reviewed replay specifications

Repeatable unattended workflows continue to use stagewright-replay specifications and the electron-stagewright-replay runner from ADR-009. The specification fixes tool names and arguments in a reviewable artifact; execution sends every step through the normal dispatcher.

The first eligible composition enhancement is parameterization of replay specifications, not a model-facing macro engine. It requires a separate ADR amendment and must satisfy all of these constraints:

4. Ship no server-side macro set under the current protocol contract

The canonical launch-then-snapshot flow and failure-diagnostics flow are useful recipes, but current evidence does not justify hiding their component calls from the host. They remain documented sequences until the revisit gates below are met.

A future server-side composition is eligible only when all of the following are true:

  1. The exact nested plan and its aggregate effects are visible to the host before execution, with an authorization mechanism stronger than advisory tool annotations.
  2. Dispatch records carry causal identity and the trace/replay format proves that a composed flow executes exactly once.
  3. A benchmark against the same granular sequence shows a material token or latency improvement without reducing task success or recovery quality.
  4. The first set consists of a small number of statically named, statically typed workflows; it excludes eval and destructive operations.
  5. Every workflow declares its leaf tools, failure policy, partial-effect behavior, timeout budget, and cleanup behavior in its public contract.

Rationale

This decision separates two goals that are easy to conflate:

Reducing turns is valuable only if it does not weaken authorization, repeat effects during replay, or recreate the nested-selector accuracy problem the project was designed to avoid. The existing replay-spec path already handles unattended, reviewable automation; it is the safer place to evolve parameterized composition when evidence requires it.

Alternatives considered

Consequences

References