Execution Plans & Artifacts
Relevant source files
The following files were used as context for generating this wiki page:
Execution Plans and Artifacts represent the core visibility layer of the OpenWork system. A Plan is a structured, step-by-step sequence generated before and updated during task execution to provide users with transparency regarding the agent's intended actions. Artifacts are the tangible outputs resulting from these executions, such as files created, modified documents, or exported logs. Sources: PRODUCT.md:27-33, PRODUCT.md:47-51
This system ensures that agentic work moves away from opaque terminal-style interactions toward a "productized" experience where every decision and output is auditable and visible. Sources: README.md:14-18, ARCHITECTURE.md:46-51
Execution Plans & Step Tracking
Plans are first-class primitives in OpenWork. They are generated from user descriptions and stored as structured JSON artifacts attached to a session. This allows the UI to reconstruct the timeline of events even after a session has ended. Sources: PRODUCT.md:30-36, ARCHITECTURE.md:49-51
Plan Lifecycle & Components
The lifecycle of an execution plan involves a transition from a static "todo list" to a dynamic stream of events. Each plan consists of individual Steps, which primarily represent tool calls or reasoning segments. Sources: PRODUCT.md:33-45, ARCHITECTURE.md:52-59
| Component | Description | Data Origin |
|---|---|---|
| Step Row | A visual entry for a single tool call or reasoning block. | Part (SDK) |
| Tool Name | The specific function being invoked (e.g., bash, file_write). | part.tool |
| Permission State | Indicates if a step is pending, allowed, or denied. | permission.Service |
| Timestamps | Start and end times for latency tracking. | part.time |
| Output Preview | A truncated or full view of the tool's execution result. | part.state.output |
Sources: PRODUCT.md:39-45, packages/app/src/app/components/part-view.tsx:210-230
Data Flow for Execution Plans
OpenWork uses Server-Sent Events (SSE) to drive the real-time update of execution plans.
The UI subscribes to client.event.subscribe() to receive updates for streaming assistant responses, tool execution, and session lifecycle changes. Sources: ARCHITECTURE.md:76-83, packages/app/src/app/utils/index.ts:161-185
Artifacts Management
Artifacts are user-visible outputs generated during a run. These are primarily files but can also include generated spreadsheets or presentations. Sources: PRODUCT.md:47-51
Artifact Extraction Logic
OpenWork does not explicitly receive a list of artifacts from the server; instead, it derives them by scanning the MessageWithParts history of a session. It looks for tool parts that contain file paths or image data. Sources: packages/app/src/app/utils/index.ts:518-540
// packages/app/src/app/utils/index.ts:518-530
export function deriveArtifacts(list: MessageWithParts[]): ArtifactItem[] {
const results = new Map<string, ArtifactItem>();
list.forEach((message) => {
message.parts.forEach((part) => {
if (part.type !== "tool") return;
const state = (part as any).state ?? {};
// Scans state.path, state.file, and state.files for valid paths
// ... extraction logic ...
});
});
return Array.from(results.values());
}
Artifact Types & Visualization
Artifacts are categorized based on their source and intended display method within the PartView component. Sources: packages/app/src/app/components/part-view.tsx:135-165
- Files: Represented with filename, path, and MIME type. Users can "Open" or "Reveal" these in their local file manager. Sources: packages/app/src/app/components/part-view.tsx:293-315
- Diffs: Structured representations of file changes, often showing additions (+) and removals (-). Sources: packages/app/src/app/components/part-view.tsx:246-260
- Images: Rendered inline if they contain a base64 data URI or a valid URL. Sources: packages/app/src/app/components/part-view.tsx:278-291
- Diagnostics: Error or warning metadata provided by tools (e.g., linter errors). Sources: packages/app/src/app/components/part-view.tsx:232-244
Audit Logs
Every run provides an exportable audit log to ensure transparency. This is critical for administrative and power user personas who need to inspect exactly what happened during an agentic session. Sources: PRODUCT.md:53-58, packages/server/src/server.ts:163-171
The audit log includes:
- Prompts: Original user instructions.
- Plan: The structured sequence of steps.
- Tool Calls: Detailed arguments and outputs for every tool used.
- Permission Decisions: A record of which actions were allowed or denied and by whom.
- Outputs: Final results and generated artifacts.
Sources: PRODUCT.md:54-58, ARCHITECTURE.md:105-107
Audit Storage & Retrieval
Audit logs are stored relative to the workspace path. The server provides an endpoint to retrieve these entries. Sources: packages/server/src/server.ts:163-171
Summary
Execution Plans and Artifacts transform raw agentic processes into manageable, visual workflows. By leveraging real-time SSE streams and a derivation logic for artifacts, OpenWork provides a high-fidelity view of the agent's internal planning and the tangible results of its work, all while maintaining a comprehensive audit log for safety and transparency. Sources: PRODUCT.md:27-36, ARCHITECTURE.md:76-83, README.md:14-18