Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/aipoch/open-science/llms.txt

Use this file to discover all available pages before exploring further.

window.api.artifacts manages the lifecycle of research outputs produced by the agent. Artifacts are files written during a run — plots, datasets, reports, generated scripts — stored under the project’s artifact directory. All file access goes through main-process path validation so the renderer never receives raw filesystem permissions.

​
Methods

​
finalizeRunArtifacts(request)

Moves pending run files from temporary run storage into the durable, message-owned artifact directory. Call this once the renderer has assigned a messageId to the response that produced the files. The method is idempotent for the same (claimId, messageId) pair — safe to retry on duplicate event delivery.
​
request
FinalizeRunArtifactsRequest
required
Returns: Promise<ArtifactFile[]> — the finalized list of artifact files.
Calling finalizeRunArtifacts with the same claimId but a different messageId throws an error. A claim can only be finalized for one message.

​
openFile(request)

Opens an artifact file in the operating system’s default application for its MIME type (e.g., a PDF viewer for reports, the default image viewer for plots). The path is verified against the managed artifact store before shell.openPath is called — unmanaged paths are rejected.
​
request
OpenArtifactFileRequest
required
Returns: Promise<void>

​
readPreview(request)

Reads up to maxBytes of an artifact file for inline display in the preview panel. Returns the content encoded as UTF-8 text or base64, a truncated flag, and the total file size so the UI can show a “file too large” notice without reading the whole file.
​
request
ReadArtifactPreviewRequest
required
Returns: Promise<ArtifactPreviewResult>
​
content
string
required
The file content, encoded as specified by encoding.
​
encoding
'utf8' | 'base64'
required
The encoding used for content.
​
size
number
required
Total file size in bytes (not the length of content).
​
truncated
boolean
required
true when content is shorter than the full file because maxBytes was reached.

​
Type reference

​
ArtifactFile

A renderer-safe description of one generated file. File bytes are never embedded — only metadata and a path are included.
FieldTypeDescription
idstringUnique artifact identifier
projectNamestringLogical project bucket that owns this file
sessionIdstringSession that produced this artifact
messageIdstring | undefinedMessage the artifact is associated with (set after finalization)
runIdstring | undefinedRuntime run that wrote this file
namestringDisplay filename
pathstringAbsolute path on disk
fileUrlstringfile:// URL for use in <img> and <iframe> tags
mimeTypestring | undefinedMIME type when known
sizenumberFile size in bytes
mtimeMsnumberLast-modified time (epoch milliseconds)

​
ArtifactWriteEncoding

type ArtifactWriteEncoding = 'utf8' | 'base64'
Use 'utf8' for text-based artifacts (CSV, JSON, Markdown, Python scripts) and 'base64' for binary artifacts (PNG, PDF, Parquet).

​
Usage example

import type { ArtifactFile, ArtifactPreviewResult } from '../../../../shared/artifacts'

// After receiving an 'artifact' event with kind === 'stop',
// finalize the run to associate files with the message:
async function finalizeAndPreview(claimId: string, messageId: string) {
  const files: ArtifactFile[] = await window.api.artifacts.finalizeRunArtifacts({
    claimId,
    messageId
  })

  console.log(`Finalized ${files.length} artifact(s)`)

  for (const file of files) {
    console.log(`${file.name} — ${file.size} bytes at ${file.path}`)
  }

  // Read a text preview of the first file
  if (files.length > 0) {
    const preview: ArtifactPreviewResult = await window.api.artifacts.readPreview({
      path: files[0].path,
      maxBytes: 8192,
      encoding: 'utf8'
    })

    if (preview.truncated) {
      console.log(`Preview (${preview.size} bytes total, truncated):`)
    }
    console.log(preview.content)
  }
}

// Open a file in the OS default viewer
async function openArtifact(file: ArtifactFile) {
  await window.api.artifacts.openFile({ path: file.path })
}

Build docs developers (and LLMs) love

Get started for freeTalk to us