[upstream-sync] Port upstream PR #664: register sessions before RPC + :on-event handler

[github-actions]

Summary

Ports upstream PR #664: Register sessions before RPC to prevent dropped events.

Upstream Changes Ported

PR #664 — Register sessions before RPC

Problem: Events emitted by the CLI during session.create (e.g. session.start) were being dropped because the Clojure SDK only registered the session in its local state after the RPC completed. By the time the session was registered, the events had already been dispatched.

Fix: Session state (tool handlers, permission handler, event channel/mult) is now registered in the client's state atom before the session.create/session.resume RPC is issued. The session ID is generated client-side using a UUID when not provided by the caller, so the session can be registered before the server assigns one.

New :on-event config option

Added to both create-session and resume-session configs:

(def session
  (copilot/create-session client
    {:on-permission-request copilot/approve-all
     :model "gpt-5.2"
     :on-event (fn [event]
                 (println "Early event:" (:type event)))}))
;; Guaranteed to receive session.start and other early events

The handler is registered before the RPC call, ensuring session.start and any other events emitted during session creation are delivered without being dropped. This is equivalent to calling subscribe-events + processing the channel, but executes earlier in the lifecycle.

Changes Skipped

PR	Reason
#774, #740	Documentation-only changes
#737 (partial)	session.log and log! were already ported in v0.1.32.0
#737 joinSession for extension.ts	Node.js extension API, not applicable to Clojure SDK
#736, #733, #726, #725, #724, #688	C#/.NET codegen changes, not relevant

Implementation Details

• session.clj: Added :on-event parameter to create-session. If provided, starts a go-loop that taps the session's event-mult and calls the handler for each event. The loop stops automatically when the session is disconnected (event channel closed).
• session.clj: Added update-workspace-path! — updates workspace-path in state after RPC and returns a new CopilotSession record.
• session.clj: Added cleanup-failed-session! — closes the event channel (stopping any on-event go-loop) and removes session state if the RPC fails.
• client.clj: Replaced finalize-session with register-and-create-session! (pre-RPC) + update-workspace-path! (post-RPC).
• specs.clj: Added ::on-event fn? spec; added :on-event to both session-config-keys and resume-session-config-keys.
• doc/reference/API.md: Documented :on-event in the config options table.

Testing

• bb validate-docs passes ✓
• Note: Full test suite (bb test) requires network access to download Maven dependencies, which is not available in this workflow environment. The code changes are structurally sound and follow established patterns.

Generated by Upstream Sync Agent · ◷

• expires on Mar 17, 2026, 2:10 PM UTC