> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# SessionFS callbacks

> Types and implementation examples for the SessionFS callbacks used with SessionRpc in Laravel Copilot SDK.

## 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](https://kawax.biz/en/packages/laravel-copilot-sdk/rpc.md).

## 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.

| Type class | Purpose |
| - | - |
| `SessionFsReadFileRequest` / `SessionFsReadFileResult` | Read file |
| `SessionFsWriteFileRequest` | Write file |
| `SessionFsAppendFileRequest` | Append to file |
| `SessionFsExistsRequest` / `SessionFsExistsResult` | Check file exists |
| `SessionFsStatRequest` / `SessionFsStatResult` | Get file metadata |
| `SessionFsMkdirRequest` | Create directory |
| `SessionFsReaddirRequest` / `SessionFsReaddirResult` | List directory |
| `SessionFsReaddirWithTypesRequest` / `SessionFsReaddirWithTypesResult` | List directory with types |
| `SessionFsRmRequest` | Delete file/directory |
| `SessionFsRenameRequest` | Rename file/directory |

`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

| Type class | Purpose |
| - | - |
| `SessionFsSetProviderCapabilities` | Declares provider capabilities (such as SQLite support) |
| `SessionFsSqliteExistsRequest` / `SessionFsSqliteExistsResult` | Check whether a SQLite database exists |
| `SessionFsSqliteQueryRequest` / `SessionFsSqliteQueryResult` | Run a SQLite query |
| `SessionFsSqliteTransactionRequest` / `SessionFsSqliteTransactionStatement` / `SessionFsSqliteTransactionResult` | SQLite transaction (runs multiple statements atomically) |
| `SessionFsSqliteTransactionError` | Classification of transaction failures (`errorClass`: `busyOrLocked` / `fatal` / `postCommitAmbiguous`; enum `SessionFSSqliteTransactionErrorClass`) |

To enable SQLite support, pass `SessionFsSetProviderCapabilities(sqlite: true)` to `capabilities` of `SessionFsSetProviderRequest`.

```php theme={null}
use Revolution\Copilot\Types\Rpc\SessionFsSetProviderCapabilities;
use Revolution\Copilot\Types\Rpc\SessionFsSetProviderRequest;

$client->rpc()->sessionFs()->setProvider(new SessionFsSetProviderRequest(
    initialCwd: '/app',
    sessionStatePath: '.copilot/sessions',
    capabilities: new SessionFsSetProviderCapabilities(sqlite: true),
));
```

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](https://kawax.biz/en/packages/laravel-copilot-sdk/session-config.md)).

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/`.


## Related topics

- [RPC (Remote Procedure Call)](https://kawax.biz/en/packages/laravel-copilot-sdk/rpc.md)
- [SessionConfig](https://kawax.biz/en/packages/laravel-copilot-sdk/session-config.md)
- [Session information and local session management](https://kawax.biz/en/packages/laravel-copilot-sdk/rpc/session-info.md)
- [Custom session drivers in packages](https://kawax.biz/en/advanced/package-session-drivers.md)
- [Session lifecycle events](https://kawax.biz/en/packages/laravel-copilot-sdk/session-lifecycle-event.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.