golem-file-io-scala

name	golem-file-io-scala
description	Reading and writing files from a Scala Golem agent. Use when the user asks to read files, write files, or do filesystem operations from agent code in Scala.

File I/O in Scala Golem Agents

Overview

Golem Scala agents are compiled to JavaScript via Scala.js and run in a QuickJS-based WASM runtime. The runtime provides node:fs for filesystem operations, accessible via Scala.js JavaScript interop. Standard JVM file I/O (java.io.File, java.nio.file.*) is not available.

To provision files into an agent's filesystem, load the golem-add-initial-files skill. To understand the full runtime environment, load the golem-js-runtime skill.

Setting Up the node:fs Facade

Define a Scala.js facade object for the node:fs module:

import scala.scalajs.js
import scala.scalajs.js.annotation.JSImport

@js.native
@JSImport("node:fs", JSImport.Namespace)
private object Fs extends js.Object {
  def readFileSync(path: String, encoding: String): String = js.native
  def readFileSync(path: String): js.typedarray.Uint8Array = js.native
  def writeFileSync(path: String, data: String): Unit = js.native
  def existsSync(path: String): Boolean = js.native
  def readdirSync(path: String): js.Array[String] = js.native
  def appendFileSync(path: String, data: String): Unit = js.native
  def mkdirSync(path: String, options: js.Object): Unit = js.native
}

Important: WASI modules like node:fs are not available during the build-time pre-initialization (wizer) phase — they are only available at runtime. Use lazy val to defer initialization:

// ✅ CORRECT — lazy val defers import to first runtime use
private lazy val fs: Fs.type = Fs

// ❌ WRONG — top-level val triggers import during pre-initialization and fails
private val fs: Fs.type = Fs