Action Runner

Relevant source files

The following files were used as context for generating this wiki page:

• app/lib/runtime/action-runner.ts
• app/lib/runtime/message-parser.ts
• app/lib/stores/workbench.ts
• app/components/chat/Artifact.tsx
• app/lib/runtime/message-parser.spec.ts

The Action Runner is a core runtime component responsible for executing side effects generated by the AI assistant. It operates within a sandboxed environment provided by the WebContainer API, allowing the application to safely run shell commands and perform filesystem operations directly in the browser.

The runner acts as the execution engine for "Actions" (such as creating files or running terminal commands) that are contained within "Artifacts." It manages the lifecycle of these actions—including queuing, execution, status tracking, and cancellation—ensuring that the generated code is correctly applied to the local project environment.
Sources: app/lib/runtime/action-runner.ts:1-20, CONTRIBUTING.md:14-25

Core Architecture and Lifecycle

The Action Runner is designed around a sequential execution model. It receives action data parsed from the AI's streaming response and coordinates with the WebContainer to perform the requested tasks.

Execution Flow

Actions follow a strict state machine from discovery to completion. When a message parser identifies an action tag (e.g., <boltAction>), it notifies the WorkbenchStore, which in turn interacts with the ActionRunner assigned to that specific artifact.

The diagram above illustrates the transition of an action from the initial parsing stage through to final execution in the WebContainer.
Sources: app/lib/runtime/action-runner.ts:46-95, app/lib/runtime/message-parser.ts:85-110

Action States

Every action managed by the runner is tracked via a status property.

Status	Description
pending	The action has been added to the runner but has not started execution.
running	The action is currently being executed by the WebContainer.
complete	The action finished successfully.
aborted	The action was manually cancelled by the user or system via an AbortController.
failed	The execution encountered an error, which is stored in the error property.

Sources: app/lib/runtime/action-runner.ts:10-25

Supported Action Types

The Action Runner currently handles two primary types of operations: filesystem modifications and terminal command execution.

File Actions

File actions write content to specific paths within the WebContainer's virtual filesystem. The runner automatically ensures that parent directories exist before attempting to write the file.

• Logic: Uses nodePath.dirname to identify the target folder and webcontainer.fs.mkdir with { recursive: true } to prepare the path.
• Execution: Calls webcontainer.fs.writeFile to commit the content.
  Sources: app/lib/runtime/action-runner.ts:137-160

Shell Actions

Shell actions execute commands within a virtualized terminal (JSH).

• Logic: Spawns a jsh process via the WebContainer API.
• Environment: Sets npm_config_yes: true to bypass prompts during package installations.
• Cancellation: Listens to the abortSignal and calls process.kill() if the action is aborted.
  Sources: app/lib/runtime/action-runner.ts:114-135

Implementation Details

The ActionRunner Class

The ActionRunner class encapsulates the logic for managing a collection of actions associated with a single artifact.

export class ActionRunner {
  #webcontainer: Promise<WebContainer>;
  #currentExecutionPromise: Promise<void> = Promise.resolve();

  actions: ActionsMap = map({});

  constructor(webcontainerPromise: Promise<WebContainer>) {
    this.#webcontainer = webcontainerPromise;
  }
  // ... methods for addAction and runAction
}

• Sequential Queue: Uses #currentExecutionPromise as a chain to ensure actions within the same runner are executed one after another, preventing race conditions in the filesystem.
• State Management: Uses nanostores (ActionsMap) to provide reactive updates to the UI, allowing components like the Artifact view to show real-time progress.
  Sources: app/lib/runtime/action-runner.ts:33-44, app/lib/stores/workbench.ts:241-260

Integration with Workbench

The WorkbenchStore acts as the orchestrator between the UI components and the Action Runner.

Interaction with Message Parser

The Action Runner relies on the StreamingMessageParser to feed it structured data from the AI's LLM stream. The parser identifies <boltAction> tags and extracts attributes like type and filePath.

• Opening Actions: onActionOpen is triggered when the start tag is found, allowing the UI to show a "pending" indicator immediately.
• Closing Actions: onActionClose is triggered when the end tag is found, signaling that the full content of the action (e.g., the entire file code) is available for execution.
  Sources: app/lib/runtime/message-parser.ts:80-120, app/lib/runtime/message-parser.spec.ts:105-120

Summary

The Action Runner is the primary bridge between the AI's textual instructions and the actual project state. By utilizing the WebContainer API, it enables a "prompt-to-code" workflow where the runner handles the technical complexities of filesystem management and process execution, providing a reactive and safe environment for rapid development.
Sources: app/lib/runtime/action-runner.ts:1-160, README.md:10-20