Skip to main content

SessionFS callbacks

Scope: SessionRpc (per-session operations tied to a Session) For an overview of RPC and the list of all RPC pages, see RPC.

SessionFS callback types

Callback types (Request/Result) are defined for session-scoped file system operations. These are the request/response types used when the Copilot CLI calls back to the client. SessionFsStatResult, SessionFsReaddirResult, and SessionFsReaddirWithTypesResult have an optional error (SessionFsError) used on failure.

SessionFs handlers

The Client routes sessionFs.readFile / readFileBytes / writeFile / writeFileBytes requests, as well as appendFile, exists, stat, mkdir, readdir, readdirWithTypes, rm, rename, sqliteQuery, sqliteTransaction, and sqliteExists, to the Session’s provider. File operation failures are returned as an error of ENOENT (ENOENT or errno 2) or UNKNOWN. exists returns false on exception, and stat returns zero values plus an error on failure. Operations the provider doesn’t support result in an UNKNOWN error (a JSON-RPC error for SQLite operations). Exceptions from sqliteQuery/sqliteExists become JSON-RPC errors, and sqliteTransaction failures are returned as an error in the result (with errorClass). The provider-side interfaces (SessionFsFilesystemProvider, SessionFsSqliteCapableProvider, SessionFsSqliteProvider, SessionFsSqliteTransactionProvider) were added as separate interfaces so they don’t break the existing SessionFsProvider (two methods).

SQLite callback types

To enable SQLite support, pass SessionFsSetProviderCapabilities(sqlite: true) to capabilities of SessionFsSetProviderRequest.
Normally you don’t call this RPC directly. If you specify the Client option sessionFs (or session_fs in config/copilot.php), Client::start() sends sessionFs.setProvider only once. Sessions need createSessionFsProvider (see SessionConfig). The SessionFsSqliteQueryType enum (src/Enums/) represents the query type:
  • Exec: DDL/multiple statements (no result)
  • Query: SELECT (returns rows)
  • Run: INSERT/UPDATE/DELETE (returns rowsAffected)
These type classes are in src/Types/Rpc/.
Last modified on November 19, 2026