FilesystemMiddlewareOptions

Backend instance or factory (default: StateBackend)

Optional descriptions for built-in filesystem tools.

Keys correspond to FsToolName. Descriptions for tools that are not enabled by the tools allowlist are ignored because those tools are not exposed to the model.

Default cap on the number of matches the grep tool returns (default: 1000).

When the cap is hit, the returned matches are flagged as truncated and a note tells the model to narrow the search. A per-call max_count tool argument overrides this default. Set to null to disable the cap.

Optional token limit before evicting a HumanMessage to the filesystem (default: 50000 tokens, ~200KB)

Keep binary read_file content and inline HumanMessage media out of message history (default: false).

Payloads are written to /blobs on the backend and state keeps a content-addressed reference instead; model requests are rehydrated from the backend. HumanMessage payloads added since the last model response are replaced starting at the next model call, so the original input write still lands in checkpoint history for that turn. Useful with sandbox backends. Has no effect when /blobs routes to a StateBackend, since that backend stores files as part of graph state — offloading there would just relocate the bytes to a different key within the same checkpoint, not out of it.

Filesystem permission rules enforced on every tool call.

Rules are evaluated in declaration order; first match wins; permissive default. Applies to ls, read_file, write_file, edit_file, glob, and grep.

Paths are canonicalized (. and empty segments dropped) before matching. With FilesystemBackend (or a CompositeBackend route to one), rules are also checked against the symlink-resolved target, and a deny on either form blocks the call — so allow rules must cover a symlink's target, not just the link.

Note on execute: permissions are not enforced on execute because shell commands can access any path regardless of path-based rules. Using permissions with an execution-capable backend (one where isSandboxBackend returns true) throws a ConfigurationError unless either:

• execute is disabled via tools, or
• the backend is a CompositeBackend and every permission path is scoped to a route prefix.

When omitted or empty, all filesystem operations are permitted.

Optional filesystem-specific usage guidance. Omitted by default because tool schemas provide it.

Allowlist of built-in filesystem tools to expose to the model.

• undefined, null, and "all" preserve the default behavior: every filesystem tool is registered, subject to backend capability filtering.
• Passing an array restricts the middleware to only those tool names.
• read_file must be included in every explicit array because it is used by normal file-inspection flows and by large-result recovery guidance.
• Backend capability checks still narrow the final visible tool set. For example, execute is removed when the resolved backend does not support command execution, even if it appears in this allowlist.
• User-provided non-filesystem tools are not affected by this allowlist.

Optional token limit before evicting a tool result to the filesystem (default: 20000 tokens, ~80KB)