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.uploads manages the lifecycle of file attachments before they are sent to the agent. Files are staged in a temporary pending directory, then either finalized (moved to the durable session artifact store) when the message is sent, or deleted individually when the user removes them from the message composer. All file access is mediated through the main process — the renderer never receives raw filesystem access.

​
Staging lifecycle

User picks / pastes files
         │
         ▼
  stageFiles()         ──► UploadedAttachment[] (sessionId = '.pending')
         │
    User sends message
         │
         ▼
  finalizeSession()    ──► UploadedAttachment[] (sessionId = real ACP session ID)
         │
    Agent receives attachments with durable paths
If the user removes an attachment from the composer before sending, call deleteUpload() to clean up the staged file.

​
Methods

​
stageFiles(request)

Copies one or more files into the app-managed upload staging area. Returns an UploadedAttachment for each file with a temporary sessionId of '.pending' until the session is finalized. The content field of each StageUploadFile must be a base64-encoded string of the file’s bytes.
​
request
StageUploadFilesRequest
required
Returns: Promise<UploadedAttachment[]>

​
deleteUpload(request)

Deletes a single staged upload file from the staging area. Call this when the user removes an attachment chip from the composer before sending the message.
​
request
DeleteUploadRequest
required
Returns: Promise<void>

​
finalizeSession(request)

Moves pending staged uploads into the durable session directory once an ACP session ID exists. Call this after window.api.acp.createSession() returns a sessionId and before (or alongside) sendPrompt. The returned attachments have their sessionId updated to the real session ID and their path updated to the durable location.
​
request
FinalizeUploadSessionRequest
required
Returns: Promise<UploadedAttachment[]> — the same attachments with updated sessionId and path fields.

​
readPreview(request)

Reads a bounded preview of a staged upload file. Uses the same ArtifactPreviewResult shape as window.api.artifacts.readPreview so preview components can handle both artifact and upload previews uniformly.
​
request
ReadArtifactPreviewRequest
required
Returns: Promise<ArtifactPreviewResult>
​
content
string
required
File content encoded as specified.
​
encoding
'utf8' | 'base64'
required
Encoding used.
​
size
number
required
Total file size in bytes.
​
truncated
boolean
required
true when content is shorter than the full file.

​
Type reference

​
UploadedAttachment

The record returned by stageFiles and finalizeSession. Pass this directly to AcpPromptRequest.attachments.
FieldTypeDescription
idstringUnique attachment identifier
sessionIdstring'.pending' before finalization; real ACP session ID after
namestringSafe filename used in storage
originalNamestringOriginal filename as provided by the user
pathstringAbsolute path to the file on disk
mimeTypestring | undefinedMIME type when provided
sizenumberFile size in bytes
Use the exported getUploadedAttachmentName helper from src/shared/uploads to display the best available filename — it returns originalName if present, falling back to name for older records.

​
Usage example

import type { UploadedAttachment } from '../../../../shared/uploads'

async function attachAndSend(
  sessionId: string,
  fileBytes: ArrayBuffer,
  fileName: string
) {
  // 1. Encode file as base64
  const base64 = btoa(
    String.fromCharCode(...new Uint8Array(fileBytes))
  )

  // 2. Stage the file before the session exists (or early in the compose flow)
  const staged: UploadedAttachment[] = await window.api.uploads.stageFiles({
    files: [{ name: fileName, content: base64, mimeType: 'text/csv' }]
  })
  console.log('Staged:', staged[0].path)

  // 3. Preview the staged file in the composer
  const preview = await window.api.uploads.readPreview({
    path: staged[0].path,
    maxBytes: 4096,
    encoding: 'utf8'
  })
  console.log('Preview:', preview.content)

  // 4. Finalize once the session ID is known
  const finalized: UploadedAttachment[] = await window.api.uploads.finalizeSession({
    sessionId,
    attachments: staged
  })
  console.log('Finalized session ID:', finalized[0].sessionId) // real sessionId

  // 5. Send the prompt with attachments
  await window.api.acp.sendPrompt({
    sessionId,
    text: 'Please analyse the attached CSV and summarise the key findings.',
    attachments: finalized
  })
}

// Removing an attachment from the composer before sending:
async function removeAttachment(attachment: UploadedAttachment) {
  await window.api.uploads.deleteUpload({ path: attachment.path })
}

Build docs developers (and LLMs) love

Get started for freeTalk to us