Artifacts & Previews
Relevant source files
The following files were used as context for generating this wiki page:
Artifacts and Previews represent the system within OpenWork that allows users to interact with, view, and edit files generated or referenced during agentic sessions. This system provides specialized renderers for various file formats—such as Markdown, spreadsheets, and HTML—enabling a seamless transition from agent-generated data to human-readable deliverables.
The architecture relies on the extraction of "Open Targets" from session transcripts and tool outputs. Once a file or URL is identified and verified by the OpenWork server, it is surfaced in the UI through an "Openable items" strip or the command palette. This ensures that only valid, existing workspace files are presented as interactive artifacts.
Sources: evals/react-session-flows.md:76-80, apps/app/src/react-app/domains/session/artifacts/artifact-panel.tsx:80-95
System Architecture
The Artifacts system operates by deriving potential targets from transcript messages and tool states. These targets are classified into different preview types based on their file extensions or URI schemes.
Data Flow for Artifact Resolution
The following diagram illustrates how a file mention in a transcript becomes a viewable artifact in the side panel.
The client extracts paths from tool outputs (e.g., write, apply_patch) and prose. It then sends a POST /workspace/:id/artifacts/resolve request to the server to verify existence and determine the appropriate preview mode.
Sources: apps/server/src/artifact-files.e2e.test.ts:74-90, apps/app/src/app/utils/index.ts:770-800, apps/app/scripts/open-target.test.ts:160-165
Artifact Classification & Types
Files are classified into ArtifactType categories based on their extensions. This classification dictates which preview component is used in the ArtifactPanel.
| Artifact Type | Supported Extensions | UI Preview Component |
|---|---|---|
| Markdown | .md, .markdown, .mdx | MarkdownPreview / ArtifactTextEditor |
| Sheet | .csv, .tsv, .xlsx, .xls, .ods | ArtifactSpreadsheetEditor |
| HTML | .html, .htm | HTMLPreview (Sandboxed) |
| Image | .png, .jpg, .jpeg, .gif, .webp, .svg | ImagePreview |
.pdf | HTMLPreview (Binary URL) | |
| Text | .txt, .json, .ts, .py, .sh, etc. | PlainText / ArtifactTextEditor |
Sources: apps/app/src/lib/artifacts.ts:28-85, apps/app/src/react-app/domains/session/artifacts/artifact-panel.tsx:216-235
Core Components
ArtifactPanel
The primary container for artifact visualization. It manages the lifecycle of fetching file content or downloading binary data from the OpenWork server. It uses useQuery to handle state and Suspense for lazy-loaded editors.
- Editing Support: For Markdown and Text types, it provides a
draftstate and asavefunction that callsclient.writeWorkspaceFile. - Download/External Actions: Provides buttons to download the file directly or open it in the system's default application (for local workspaces) using
openDesktopPath.
Sources: apps/app/src/react-app/domains/session/artifacts/artifact-panel.tsx:110-185
Artifact Extraction Logic
The system scans message parts for relevant paths. Specifically, it looks at:
- Tool Metadata: Input
filePathorpathfromwriteandedittools. - Patch Content: Files mentioned in
apply_patchmarkers (e.g.,*** Add File: path/to/file). - Regex Scanning: Prose mentions matching standard path patterns, though tool-based metadata is given higher confidence (95%).
Sources: apps/app/src/lib/artifacts.ts:182-210, apps/app/src/app/utils/index.ts:800-830, apps/app/scripts/open-target.test.ts:45-55
Interaction Lifecycle
When an agent completes a task, the following sequence occurs to update the artifacts:
The "Openable items" strip appears directly below the assistant message that introduced the files.
Sources: evals/openable-items-flow.md:18-35, evals/react-session-flows.md:545-560
Editing and Persistence
OpenWork supports direct editing of certain artifacts.
- Spreadsheet Editing: Users can edit cells in
.csvor.xlsxfiles. The system handles binary data conversion for Excel files and raw text for CSVs. - Markdown/Text Editing: Uses a dedicated
ArtifactTextEditor(lazy-loaded). Users can toggle "Edit" mode, modify the content, and save. - Conflict Prevention: The save mutation includes a
baseUpdatedAttimestamp to ensure that edits are based on the latest version of the file known to the client.
Sources: apps/app/src/react-app/domains/session/artifacts/artifact-panel.tsx:185-210, apps/server/src/artifact-files.e2e.test.ts:100-110
Browser Previews vs. Artifacts
A distinction is made between file-based artifacts and browser-based previews:
- Localhost URLs: Detected (e.g.,
http://localhost:3000) and opened in the Browser Pane using an ElectronWebContentsViewoverlay. - Socket Hints: WebSocket URLs (
ws://...) are extracted but classified as diagnostic hints; clicking them typically opens the corresponding HTTP URL in browser mode. - HTML Artifacts: While they can be rendered in the artifact pane, local dev servers are preferred for dynamic "web previews."
Sources: evals/react-session-flows.md:120-135, apps/app/scripts/open-target.test.ts:25-35
Conclusion
The Artifacts & Previews system provides a robust framework for managing deliverables within OpenWork. By combining automated extraction from agent activities with server-side verification and specialized editors, it transforms raw file system changes into an interactive workspace experience. Its ability to handle diverse formats—from rendered Markdown to editable Excel sheets—makes it a critical tool for verifying and refining agentic work.