Port upstream PR #960: ElicitationContext single-arg handler

[krukow]

Summary

Ports upstream PR #960 (Close Language Gaps for Commands + Dialogs/Elicitations) — the cross-SDK consistency change that merges the elicitation handler's two arguments into a single ElicitationContext.

Upstream Changes Ported

PR #960 — ElicitationRequest → ElicitationContext

BREAKING: The elicitation handler signature changes from 2-arg to single-arg:

;; Before (PR #81)
:on-elicitation-request (fn [request {:keys [session-id]}] ...)

;; After (this PR)
:on-elicitation-request (fn [{:keys [session-id message requested-schema mode elicitation-source url]}] ...)

The ElicitationContext map includes :session-id alongside the request fields, matching the CommandContext pattern used by command handlers.

Changes

File	Description
src/github/copilot_sdk/specs.clj	::elicitation-request → ::elicitation-context, added :session-id to required keys
src/github/copilot_sdk/client.clj	Build context with :session-id included, updated docstrings
src/github/copilot_sdk/session.clj	Handler called with single arg instead of (handler request {:session-id ...})
test/.../integration_test.clj	All 3 elicitation tests updated to single-arg handler
examples/elicitation_provider.clj	Example handler updated to destructure context
doc/reference/API.md	Elicitation Provider section and config table updated
CHANGELOG.md	Breaking change documented

Upstream Changes Skipped

PR	Reason
#996	README badge update only
#992	GitHub Actions workflow config
#951	AI issue triage system (CI tooling)
#983	Cross-SDK reviewer fix (CI tooling)
#978	Runtime version bump + test re-enable (no SDK API change)

Testing

• 114 tests, 366 assertions, 0 failures
• 12 doc files valid, 0 warnings
• All 3 elicitation integration tests updated and passing

[Copilot]

Pull request overview

Ports upstream PR #960 to align elicitation handling with other cross-SDK “context map” patterns by switching :on-elicitation-request from a 2-arg handler to a single ElicitationContext argument that includes :session-id.

Changes:

• Renames/spec-updates inbound elicitation payload spec from ::elicitation-request to ::elicitation-context and requires :session-id.
• Updates v3 broadcast routing + session handler invocation to call elicitation handler with a single context map.
• Updates integration tests, example, API reference docs, and changelog for the breaking signature change.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/github/copilot_sdk/specs.clj	Renames/adjusts spec to ::elicitation-context including required :session-id.
src/github/copilot_sdk/client.clj	Builds ElicitationContext in v3 handler and updates create-session docs to single-arg signature.
src/github/copilot_sdk/session.clj	Calls elicitation handler with a single context argument.
test/github/copilot_sdk/integration_test.clj	Updates elicitation provider tests to use the single-arg handler and asserts context contents.
examples/elicitation_provider.clj	Updates example handler to destructure the single context map.
doc/reference/API.md	Updates API docs to describe ElicitationContext single-arg handler.
CHANGELOG.md	Documents breaking change in [Unreleased].

[Copilot]

When building context, optional fields are always assoc’d even when missing in data (so :requested-schema, :elicitation-source, :url may be present with nil). That makes it impossible to distinguish “absent” vs “explicitly nil”, and it would fail ::elicitation-context if you ever validate it (those opt-un keys require non-nil values when present). Consider only assoc’ing these keys when non-nil (e.g., cond-> / merge with select-keys + keep).

Suggested change

	(let [context {:session-id session-id
	:message (:message data)
	:requested-schema (:requested-schema data)
	:mode (:mode data)
	:elicitation-source (:elicitation-source data)
	:url (:url data)}
	(let [requested-schema (:requested-schema data)
	elicitation-source (:elicitation-source data)
	url (:url data)
	context (cond-> {:session-id session-id
	:message (:message data)
	:mode (:mode data)}
	(some? requested-schema) (assoc :requested-schema requested-schema)
	(some? elicitation-source) (assoc :elicitation-source elicitation-source)
	(some? url) (assoc :url url))

[Copilot]

The create-session docstring was updated to describe the new single-arg :on-elicitation-request handler, but the resume-session docstring later in this file still references elicitation as “upstream PR #908” without clarifying the new signature/context shape. Please update the resume-session docs too so both entry points describe the same breaking API.

[krukow]

Addressing Copilot Code Review (2 comments)

Fixed in 2adfd4b:

1. Optional nil fields in context map (client.clj:372)
✅ Now uses cond-> to only assoc optional fields when non-nil. This prevents absent keys from appearing as nil and keeps the map clean for spec validation.

2. resume-session docstring outdated (client.clj:1445)
✅ Updated to describe the new single-arg ElicitationContext signature, matching create-session.