[upstream-sync] Port session filesystem provider support (upstream PR #917)

[github-actions]

Summary

This PR ports the session filesystem provider feature from upstream github/copilot-sdk PR #917, which adds support for virtualizing the per-session storage that the underlying runtime uses (event log, large output handling, etc.) through custom client callbacks.

Upstream Changes Ported

PR #917 — Support sessionFs in Node SDK

Adds a mechanism for SDK clients to intercept file I/O that the runtime performs on a per-session basis, routing it through user-provided callbacks instead of the server's default local filesystem.

API additions:

• :session-fs new option in create-client — takes a SessionFsConfig map:

  • :initial-cwd — initial working directory for sessions
  • :session-state-path — path within each session's SessionFs where the runtime stores files
  • :conventions — path conventions: "windows" or "posix"
  • On start!, sends sessionFs.setProvider RPC to register as the filesystem provider

• :create-session-fs-handler new option in create-session / resume-session — required when :session-fs is set. A factory (fn [session] -> handler-map) called once per session that returns a map implementing the file operations:

  • :read-file, :write-file, :append-file, :exists, :stat
  • :mkdir, :readdir, :readdir-with-types, :rm, :rename
  • Handler functions receive normalized (kebab-case) params and may return values directly or via core.async channels

Event changes (also in PR #917):

• session.task_complete data now has optional :aborted? boolean (true when cancelled via abort signal)
• MCP server status enum extended with "needs-auth" value

Changes Skipped

• PR #967 — "Create README.md for GitHub Copilot SDK for Java" — Java documentation only, not relevant to Clojure port.

Implementation Notes

The SessionFsHandler TypeScript interface is represented in Clojure as a plain map of functions (idiomatic Clojure, no protocol needed). Incoming sessionFs.* RPC calls from the server are dispatched via handle-session-fs-request!, which converts the camelCase operation name to a kebab-case keyword using camel-snake-kebab to look up the handler function. Handler return values are normalized through the existing protocol clj->wire layer.

Files Changed

• src/github/copilot_sdk/client.clj — new handle-session-fs-request!, updated setup-request-handler!, start!, pre-register-session, docstrings
• src/github/copilot_sdk/session.clj — :session-fs-handler added to session state, new set-session-fs-handler!
• src/github/copilot_sdk/specs.clj — new specs: ::session-fs-config, ::session-fs, ::create-session-fs-handler, ::aborted; updated ::session-config, ::resume-session-config, ::join-session-config, ::client-options, ::session.task_complete-data
• doc/reference/API.md — documented :session-fs and :create-session-fs-handler
• CHANGELOG.md — added entries under [Unreleased]

Testing

Tests could not be run in this environment due to Maven dependency cache unavailability (network download failure). Please run bb test locally to verify.

The implementation follows the same patterns used by existing request handlers (hooks.invoke, systemMessage.transform) and is structurally consistent with how the Node.js SDK routes sessionFs calls.

Generated by Upstream Sync Agent · ◷

• expires on Apr 8, 2026, 2:43 PM UTC