Action Runner System
Relevant source files
The following files were used as context for generating this wiki page:
The Action Runner System is a core architectural component of the Bolt platform designed to execute side effects generated by the AI assistant. It bridges the gap between structured AI responses—parsed from specialized XML-like tags—and the actual execution environment provided by StackBlitz WebContainers. The system handles tasks such as manipulating the filesystem and executing shell commands directly in the browser.
This system ensures that operations like file creation and command execution are handled sequentially, reliably, and with full observability within the user interface. It is managed primarily through the WorkbenchStore, which orchestrates the lifecycle of "Artifacts" and their constituent actions.
Sources: README.md, app/lib/runtime/action-runner.ts:1-20, app/lib/stores/workbench.ts:25-45
Core Architecture and Components
The system is built on a reactive architecture using nanostores for state management. It consists of three primary layers: parsing, orchestration, and execution.
The Action Runner Class
The ActionRunner is the primary engine for executing tasks. Each artifact (a logical grouping of actions) is assigned its own ActionRunner instance. It manages a queue of actions using a promise chain to ensure sequential execution.
Sources: app/lib/runtime/action-runner.ts:40-60, app/lib/stores/workbench.ts:225-235
Interaction Flow
The following diagram illustrates how a message from the AI is transformed into executable actions through the system.
The flow starts with the StreamingMessageParser detecting tags like <boltArtifact> and <boltAction>, which triggers callbacks in the WorkbenchStore to initialize and then execute the runner.
Sources: app/lib/runtime/message-parser.ts:50-100, app/lib/stores/workbench.ts:220-255
Action Lifecycle and States
Actions move through a specific set of states to provide feedback to the UI. The ActionStatus type defines these phases: pending, running, complete, aborted, and failed.
Status Definitions
| Status | Description |
|---|---|
pending | The action has been discovered and added to the runner but hasn't started yet. |
running | The action is currently being executed (e.g., shell command is active). |
complete | The action finished successfully. |
aborted | The action was cancelled via an AbortController. |
failed | An error occurred during execution. |
Sources: app/lib/runtime/action-runner.ts:10-25
Execution Logic
The runner utilizes an internal #currentExecutionPromise to chain actions. This ensures that even if multiple actions are received in a stream, they do not overlap, which is critical for filesystem integrity and shell command order.
Action Types and Implementation
The system currently supports two primary types of actions defined in app/types/actions.ts.
1. Shell Actions
Shell actions allow the AI to run commands in a terminal environment.
- Implementation: Uses
webcontainer.spawn('jsh', ['-c', action.content]). - Environment: Automatically sets
npm_config_yes: trueto bypass prompts during package installations. - Output: Pipes the process output to the browser console.
Sources: app/lib/runtime/action-runner.ts:125-155
2. File Actions
File actions manage the creation and modification of project files.
- Implementation: Uses
webcontainer.fs.writeFile. - Directory Handling: Automatically creates parent directories using
mkdirwith{ recursive: true }if they don't exist. - Local Sync: The
WorkbenchStoreadditionally attempts to mirror these changes to the local filesystem viaapp/lib/persistence/fileSystem.ts.
Sources: app/lib/runtime/action-runner.ts:157-185, app/lib/persistence/fileSystem.ts:105-130
Integration with UI (Artifacts)
The Artifact component serves as the visual representation of the Action Runner System. It provides a real-time list of actions and their statuses.
// From app/components/chat/Artifact.tsx
const actions = useStore(
computed(artifact.runner.actions, (actions) => {
return Object.values(actions);
}),
);
The UI subscribes to the actions store of the runner. It renders specific icons based on the status (e.g., a spinner for running, a checkmark for complete). For shell actions, it uses shiki to highlight the command content.
Sources: app/components/chat/Artifact.tsx:35-55, app/components/chat/Artifact.tsx:145-180
Summary
The Action Runner System provides a robust framework for browser-based development by abstracting the complexities of WebContainer interactions. By maintaining a strict sequential execution model and a clear state machine, it allows the AI assistant to perform complex software engineering tasks—like scaffolding projects and running build scripts—while keeping the user informed through a reactive interface.