Port blob attachments (#731), permission docs (#879), model refresh

[krukow]

Summary

Ports upstream Copilot SDK changes and refreshes documentation/examples.

Upstream Ports

PR #731 — Blob attachment outbound sending

(copilot/send! session
  {:prompt "Describe this image"
   :attachments [{:type :blob
                  :data "iVBORw0KGgoAAAANSUhEUg..."
                  :mime-type "image/png"
                  :display-name "screenshot.png"}]})

• specs.clj: Added :blob to outbound ::attachment spec
• util.clj: Added :blob case to attachment->wire
• 5 unit tests + 1 E2E test for blob attachment sending

PR #879 — Permission Handling README

• New "Permission Handling" section in README.md (deny-by-default, approve-all, custom handler)
• Aligned API reference permission section with join-session exception

Housekeeping

• Model refresh: gpt-5.2 → gpt-5.4 across all examples, docs, source docstrings, and tests
• BYOK codex model: gpt-5.3-codex (no 5.4-codex exists)
• session_resume example: "secret word" → "code word" (avoids model content filtering)
• MCP debugging docs: Added missing :on-permission-request to examples
• Codox HTML: Regenerated doc/api/ from updated source docstrings
• update-docs skill: Added Codox regeneration step (bb docs)

Verification

• ✅ bb validate-docs — 12 files, 0 warnings
• ✅ bb test — 98 tests, 311 assertions, 0 failures
• ✅ COPILOT_E2E_TESTS=true bb test — 98 tests, 338 assertions, 0 failures
• ✅ ./run-all-examples.sh — 15 examples, all clean

[Copilot]

Pull request overview

Ports upstream Copilot SDK changes to (1) support outbound :blob attachments (inline base64 data) and (2) expand README documentation around permission handling, keeping the Clojure SDK aligned with upstream behavior and docs.

Changes:

• Add outbound support for :blob attachments via specs + wire conversion.
• Add unit + E2E coverage for blob attachment sending.
• Update README/API reference/CHANGELOG documentation for blob attachments and permission handling.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/github/copilot_sdk/util.clj	Adds :blob case to attachment->wire for outbound encoding.
src/github/copilot_sdk/specs.clj	Extends outbound ::attachment spec to include :blob and clarifies inbound alias commentary.
test/github/copilot_sdk_test.clj	Adds unit tests for blob wire encoding + spec validity in send options.
test/github/copilot_sdk/e2e_test.clj	Adds an E2E test ensuring blob attachment sending succeeds end-to-end.
doc/reference/API.md	Documents :blob in attachment table and adds a “Blob Attachments” section.
README.md	Adds a “Permission Handling” section with examples and links.
CHANGELOG.md	Adds Unreleased entries for outbound :blob support and README permission docs.

[Copilot]

Pull request overview

Ports upstream support for outbound blob attachments and adds permission-handling documentation, aligning the Clojure SDK with upstream Copilot SDK behavior and guidance.

Changes:

• Add outbound :blob attachments to specs and wire conversion (attachment->wire), plus unit + E2E coverage.
• Add “Permission Handling” documentation to README and API reference (and regenerate Codox HTML docs).
• Refresh model examples/test fixtures from gpt-5.2 to gpt-5.4 across tests, docs, and examples.

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
test/github/copilot_sdk_test.clj	Adds unit tests for blob attachment wire format + validates send-options spec acceptance.
test/github/copilot_sdk/mock_server.clj	Updates mocked model listing fixture to gpt-5.4.
test/github/copilot_sdk/integration_test.clj	Updates model strings in integration tests to gpt-5.4.
test/github/copilot_sdk/e2e_test.clj	Adds E2E coverage for sending blob attachments.
src/github/copilot_sdk/util.clj	Implements :blob case in attachment->wire.
src/github/copilot_sdk/specs.clj	Extends outbound ::attachment spec to include :blob; clarifies inbound alias comment.
src/github/copilot_sdk/helpers.clj	Updates example model string to gpt-5.4.
src/github/copilot_sdk/client.clj	Updates docstrings’ example model string to gpt-5.4.
src/github/copilot_sdk.clj	Updates docstrings’ example model string to gpt-5.4.
examples/session_resume.clj	Renames “secret word” phrasing to “code word” in the example.
examples/session_events.clj	Updates default model string to gpt-5.4.
examples/reasoning_effort.clj	Updates example model string to gpt-5.4.
examples/multi_agent.clj	Updates example model strings to gpt-5.4.
examples/metadata_api.clj	Updates switch-model example to gpt-5.4.
examples/helpers_query.clj	Updates example model strings to gpt-5.4.
examples/byok_provider.clj	Updates BYOK example model strings to gpt-5.4.
examples/README.md	Updates example snippets (model + code-word param rename).
doc/reference/API.md	Documents :blob attachments in the attachments table + adds “Blob Attachments” section; updates model strings.
doc/mcp/overview.md	Updates model strings in MCP docs to gpt-5.4.
doc/mcp/debugging.md	Updates model strings in MCP debugging docs to gpt-5.4.
doc/guides/custom-agents.md	Updates model strings in custom agents guide to gpt-5.4.
doc/getting-started.md	Updates model strings in getting-started guide to gpt-5.4.
doc/auth/byok.md	Updates model strings in BYOK guide (including codex model example).
doc/api/overview.html	Regenerated API HTML with updated model strings.
doc/api/intro.html	Regenerated API HTML intro page with updated model strings.
doc/api/github.copilot-sdk.html	Regenerated namespace API HTML with updated model strings.
doc/api/github.copilot-sdk.helpers.html	Regenerated helpers API HTML with updated model strings.
doc/api/github.copilot-sdk.client.html	Regenerated client API HTML with updated model strings.
doc/api/getting-started.html	Regenerated getting-started API HTML with updated model strings.
doc/api/debugging.html	Regenerated debugging API HTML with updated model strings.
doc/api/byok.html	Regenerated BYOK API HTML with updated model strings.
doc/api/API.html	Regenerated API reference HTML with updated model strings and attachments table updates.
README.md	Adds “Permission Handling” section; updates model example string to gpt-5.4.
CHANGELOG.md	Adds Unreleased entries for outbound :blob attachments and README permission docs.

Comments suppressed due to low confidence (2)

doc/api/intro.html:24

• The Quick start snippet creates a session with only {:model "gpt-5.4"}, but create-session requires an :on-permission-request handler and will throw otherwise. This snippet also uses destroy!, which is deprecated in favor of disconnect!. Update the source used to generate this Codox page so the example is runnable (include :on-permission-request and prefer disconnect!).

<pre><code class="language-clojure">(require '[krukow.copilot-sdk :as copilot])

(def client (copilot/client {:log-level :info}))
(copilot/start! client)

(def session (copilot/create-session client {:model "gpt-5.4"}))
(def response (copilot/send-and-wait! session {:prompt "What is 2+2?"}))
(println (get-in response [:data :content]))

(copilot/destroy! session)
(copilot/stop! client)

doc/api/github.copilot-sdk.html:20

• The namespace-level Quick Start example creates a session with only {:model "gpt-5.4"}, but create-session requires an :on-permission-request handler and will throw otherwise. It also uses destroy! in cleanup even though it is deprecated in favor of disconnect!. Fix the underlying docstring/source and regenerate these API docs so the example matches the actual API contract.

<pre><code class="language-clojure">(require '[github.copilot-sdk :as copilot])

;; Create and start client
(def client (copilot/client {:log-level :info}))
(copilot/start! client)

;; Create a session
(def session (copilot/create-session client {:model "gpt-5.4"}))

;; Send a message and wait for response
(def response (copilot/send-and-wait! session {:prompt "What is 2+2?"}))
(println (get-in response [:data :content]))

;; Clean up
(copilot/destroy! session)
(copilot/stop! client)

[Copilot]

Pull request overview

Ports upstream functionality/documentation into the Clojure Copilot SDK by adding outbound :blob attachments support (inline base64 data) and expanding README permission-handling guidance, while updating examples/docs to newer model IDs.

Changes:

• Add outbound :blob attachments to specs + wire encoding, with unit + E2E coverage.
• Add a new README “Permission Handling” section describing the deny-by-default model and handler patterns.
• Refresh documentation/examples/test fixtures to use "gpt-5.4" in model examples and mock model listings.

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
test/github/copilot_sdk_test.clj	Adds unit tests covering :blob attachment spec validity and wire encoding.
test/github/copilot_sdk/mock_server.clj	Updates mock model listing from "gpt-5.2" to "gpt-5.4" for tests/docs consistency.
test/github/copilot_sdk/integration_test.clj	Updates model IDs in session/model tests to "gpt-5.4".
test/github/copilot_sdk/e2e_test.clj	Adds E2E coverage ensuring send-and-wait! with :blob attachment succeeds.
src/github/copilot_sdk/util.clj	Implements :blob case in attachment->wire (emits type/data/mimeType/displayName).
src/github/copilot_sdk/specs.clj	Extends outbound/inbound attachment specs to include :blob.
src/github/copilot_sdk/helpers.clj	Updates docstring example model to "gpt-5.4".
src/github/copilot_sdk/client.clj	Updates docstring examples to "gpt-5.4".
src/github/copilot_sdk.clj	Updates public API docstrings/examples to "gpt-5.4".
examples/session_resume.clj	Renames “secret word” example wording/keys to “code word”.
examples/session_events.clj	Updates default model example to "gpt-5.4".
examples/reasoning_effort.clj	Updates example model to "gpt-5.4".
examples/multi_agent.clj	Updates example model to "gpt-5.4".
examples/metadata_api.clj	Updates model switch example to "gpt-5.4".
examples/helpers_query.clj	Updates example model to "gpt-5.4".
examples/byok_provider.clj	Updates BYOK example model to "gpt-5.4".
examples/README.md	Updates example snippets and CLI args (:code-word) and model IDs.
doc/reference/API.md	Documents :blob attachment type + adds “Blob Attachments” section; updates model IDs.
doc/mcp/overview.md	Updates MCP documentation examples to "gpt-5.4".
doc/mcp/debugging.md	Updates debugging examples to "gpt-5.4".
doc/guides/custom-agents.md	Updates custom agent examples to "gpt-5.4".
doc/getting-started.md	Updates getting-started snippets to "gpt-5.4".
doc/auth/byok.md	Updates BYOK guide model IDs.
doc/api/overview.html	Regenerated API HTML with updated model IDs.
doc/api/intro.html	Regenerated API HTML with updated model IDs.
doc/api/github.copilot-sdk.html	Regenerated API HTML with updated model IDs.
doc/api/github.copilot-sdk.helpers.html	Regenerated API HTML with updated model IDs.
doc/api/github.copilot-sdk.client.html	Regenerated API HTML with updated model IDs.
doc/api/getting-started.html	Regenerated API HTML with updated model IDs.
doc/api/debugging.html	Regenerated API HTML with updated model IDs.
doc/api/byok.html	Regenerated API HTML with updated model IDs.
doc/api/API.html	Regenerated API HTML with updated model IDs.
README.md	Adds “Permission Handling” section and updates model ID in JS comparison snippet.
CHANGELOG.md	Adds Unreleased entries for outbound :blob attachments and README permission docs.

[Copilot]

Pull request overview

Ports upstream SDK changes to support outbound blob attachments and expands user-facing permission-handling documentation, keeping the Clojure SDK aligned with upstream behavior and examples.

Changes:

• Add outbound :blob attachment support in wire encoding + specs, with new unit and E2E coverage.
• Add a “Permission Handling” section to the README and update docs to reference it.
• Refresh example/test/docs model strings (e.g. gpt-5.2 → gpt-5.4) for consistency across the repo.

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/github/copilot_sdk/util.clj	Add :blob case to attachment->wire to emit {:type "blob" ...} payloads.
src/github/copilot_sdk/specs.clj	Extend outbound ::attachment spec to include :blob; clarify inbound alias comment.
test/github/copilot_sdk_test.clj	Add unit tests for blob wire encoding and spec validity in ::send-options.
test/github/copilot_sdk/e2e_test.clj	Add E2E coverage for sending a blob attachment (explicit 30s timeout).
test/github/copilot_sdk/mock_server.clj	Update mocked model listing to use gpt-5.4.
test/github/copilot_sdk/integration_test.clj	Update model strings in integration tests to gpt-5.4.
README.md	Add “Permission Handling” section and update model example string.
doc/reference/API.md	Document :blob in attachments table and add a “Blob Attachments” subsection; update model strings.
CHANGELOG.md	Add Unreleased entries for outbound blob attachments and permission docs.
src/github/copilot_sdk/client.clj	Update docstrings/examples to reference gpt-5.4.
src/github/copilot_sdk.clj	Update top-level namespace docs/examples to reference gpt-5.4.
src/github/copilot_sdk/helpers.clj	Update helpers docs snippet to reference gpt-5.4.
examples/session_resume.clj	Rename “secret word” wording/arg to “code word” in the resume example.
examples/session_events.clj	Update default model string to gpt-5.4.
examples/reasoning_effort.clj	Update model string to gpt-5.4.
examples/multi_agent.clj	Update model strings to gpt-5.4.
examples/metadata_api.clj	Update switch-model! example to gpt-5.4.
examples/helpers_query.clj	Update model strings to gpt-5.4.
examples/byok_provider.clj	Update model strings to gpt-5.4.
examples/README.md	Update model strings and rename :secret-word → :code-word invocation docs.
doc/mcp/overview.md	Update model strings to gpt-5.4 in MCP examples.
doc/mcp/debugging.md	Update model strings to gpt-5.4 in debugging examples.
doc/guides/custom-agents.md	Update model strings to gpt-5.4 in custom agent examples.
doc/getting-started.md	Update model strings to gpt-5.4 in tutorial snippets.
doc/auth/byok.md	Update model strings in BYOK guide examples.
doc/api/overview.html	Regenerated API site HTML with updated model strings.
doc/api/intro.html	Regenerated API site HTML with updated model strings.
doc/api/github.copilot-sdk.html	Regenerated API site HTML with updated model strings.
doc/api/github.copilot-sdk.helpers.html	Regenerated API site HTML with updated model strings.
doc/api/github.copilot-sdk.client.html	Regenerated API site HTML with updated model strings.
doc/api/getting-started.html	Regenerated API site HTML with updated model strings.
doc/api/debugging.html	Regenerated API site HTML with updated model strings.
doc/api/byok.html	Regenerated API site HTML with updated model strings.
doc/api/API.html	Regenerated API site HTML with updated model strings.

Comments suppressed due to low confidence (1)

src/github/copilot_sdk/specs.clj:357

• ::inbound-attachment is described as “identical to ::attachment”, but it’s re-specified with a duplicated s/or form. This duplication can drift over time (e.g., if a new attachment type is added to one but not the other). If the intent is true aliasing, consider defining ::inbound-attachment directly in terms of ::attachment to enforce identical behavior.

;; Inbound attachment (identical to ::attachment, kept as a semantic alias
;; for event data contexts where attachments are received rather than sent)
(s/def ::inbound-attachment
  (s/or :file-or-directory ::file-or-directory-attachment
        :selection ::selection-attachment
        :github-reference ::github-reference-attachment
        :blob ::blob-attachment))

[Copilot]

Pull request overview

Ports upstream SDK changes to support outbound blob attachments (inline base64 data) and expands permission-handling documentation, aligning tests/docs/examples with updated model strings.

Changes:

• Add outbound :blob attachments support via specs + attachment->wire, with new unit + E2E tests.
• Add/expand “Permission Handling” documentation in README.md and API reference, plus changelog entries.
• Update many examples/docs/tests from "gpt-5.2" to "gpt-5.4".

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test/github/copilot_sdk_test.clj	Adds unit tests for blob attachment wire encoding + send-options validity; updates model string in config tests.
test/github/copilot_sdk/mock_server.clj	Updates mock model listing to "gpt-5.4".
test/github/copilot_sdk/integration_test.clj	Updates integration tests to use "gpt-5.4" in session creation and model assertions.
test/github/copilot_sdk/e2e_test.clj	Adds E2E coverage for sending a blob attachment.
src/github/copilot_sdk/util.clj	Adds :blob case in attachment->wire emitting {:type \"blob\" :data ... :mimeType ...}.
src/github/copilot_sdk/specs.clj	Extends outbound ::attachment spec to include :blob; clarifies inbound attachment alias comment.
src/github/copilot_sdk/helpers.clj	Updates docstring example model to "gpt-5.4".
src/github/copilot_sdk/client.clj	Updates docstrings/examples to "gpt-5.4".
src/github/copilot_sdk.clj	Updates docstrings/examples to "gpt-5.4".
examples/session_resume.clj	Renames “secret word” terminology to “code word” in example prompts/opts.
examples/session_events.clj	Updates default model to "gpt-5.4".
examples/reasoning_effort.clj	Updates example model to "gpt-5.4".
examples/multi_agent.clj	Updates example model to "gpt-5.4".
examples/metadata_api.clj	Updates model switching example to "gpt-5.4".
examples/helpers_query.clj	Updates helper examples to "gpt-5.4".
examples/byok_provider.clj	Updates BYOK example model to "gpt-5.4".
examples/README.md	Updates example snippets and CLI args (:code-word, "gpt-5.4").
doc/reference/API.md	Documents :blob attachments; updates permission-handling wording; updates model strings.
doc/mcp/overview.md	Updates model strings in MCP examples.
doc/mcp/debugging.md	Updates model strings in MCP debugging examples.
doc/guides/custom-agents.md	Updates model strings in custom-agent examples.
doc/getting-started.md	Updates model strings in getting-started snippets.
doc/auth/byok.md	Updates BYOK example model strings (incl. "gpt-5.3-codex" / "gpt-5.4").
doc/api/overview.html	Updates rendered docs model strings.
doc/api/intro.html	Updates rendered docs model strings.
doc/api/github.copilot-sdk.html	Updates rendered docs model strings.
doc/api/github.copilot-sdk.helpers.html	Updates rendered docs model strings.
doc/api/github.copilot-sdk.client.html	Updates rendered docs model strings.
doc/api/getting-started.html	Updates rendered docs model strings.
doc/api/debugging.html	Updates rendered docs model strings.
doc/api/byok.html	Updates rendered docs model strings.
doc/api/API.html	Updates rendered docs model strings; adds blob row in attachment table.
README.md	Adds “Permission Handling” section; updates model string in example output.
CHANGELOG.md	Adds Unreleased entries for outbound blob attachments and permission docs section.

Comments suppressed due to low confidence (3)

doc/mcp/overview.md:40

• The MCP config examples here omit :on-permission-request, but create-session/with-client-session validate ::session-config and will throw when the handler is missing. Update the example session opts to include a handler (e.g. copilot/approve-all) so the snippet runs as written.

(copilot/with-client-session [session
                              {:model "gpt-5.4"
                               :mcp-servers
                               {"my-local-server"
                                {:mcp-command "node"
                                 :mcp-args ["./mcp-server.js"]
                                 :mcp-tools ["*"]
                                 :env {"DEBUG" "true"}
                                 :cwd "./servers"}}}]

doc/auth/byok.md:28

• The BYOK quick start snippets omit :on-permission-request, but with-client-session ultimately calls create-session, which requires an :on-permission-request handler and will throw if it’s missing. Add a handler (commonly copilot/approve-all) to each example session config so users can copy/paste successfully.

(copilot/with-client-session [session
                              {:model "gpt-5.3-codex"
                               :provider {:provider-type :openai
                                          :base-url "https://your-resource.openai.azure.com/openai/v1/"
                                          :wire-api :responses
                                          :api-key (System/getenv "FOUNDRY_API_KEY")}}]
  (println (h/query "What is 2+2?" :session session)))

doc/api/intro.html:23

• This quick start snippet is out of sync with the actual public API: create-session requires :on-permission-request and will throw without it, and destroy! is deprecated in favor of disconnect!. Also, the surrounding snippet uses the old krukow.copilot-sdk namespace; the library’s namespace is github.copilot-sdk (see CHANGELOG.md breaking rename). Consider regenerating doc/api so it matches the current namespace docstrings.

(def session (copilot/create-session client {:model "gpt-5.4"}))
(def response (copilot/send-and-wait! session {:prompt "What is 2+2?"}))
(println (get-in response [:data :content]))

(copilot/destroy! session)

[Copilot]

Pull request overview

Ports upstream functionality into the Clojure Copilot SDK, adding outbound blob attachments support and expanding/aligning permission-handling documentation, plus updating examples/tests to use the newer default model string.

Changes:

• Add outbound :blob attachment support (spec + wire encoding) and accompanying unit/E2E tests.
• Add/extend permission-handling docs (README + API reference) and update changelog.
• Refresh model examples/usages from "gpt-5.2" → "gpt-5.4" across tests, docs, and examples.

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
src/github/copilot_sdk/util.clj	Adds :blob case to attachment->wire for outbound messages.
src/github/copilot_sdk/specs.clj	Expands outbound ::attachment to include :blob and clarifies inbound aliasing.
test/github/copilot_sdk_test.clj	Adds unit tests covering blob attachment wire format + spec validation; updates model string.
test/github/copilot_sdk/e2e_test.clj	Adds E2E coverage for sending a blob attachment (with explicit timeout).
test/github/copilot_sdk/mock_server.clj	Updates mocked model list values to "gpt-5.4".
test/github/copilot_sdk/integration_test.clj	Updates model expectations/usages to "gpt-5.4".
README.md	Adds a “Permission Handling” section and updates model string in examples.
doc/reference/API.md	Documents :blob in attachment table + adds “Blob Attachments” section and permission wording alignment.
CHANGELOG.md	Adds Unreleased entries for outbound blob attachments and README permission docs.
src/github/copilot_sdk/client.clj	Updates docstrings/examples to "gpt-5.4".
src/github/copilot_sdk/helpers.clj	Updates docstring example model string.
src/github/copilot_sdk.clj	Updates docstrings/examples to "gpt-5.4".
examples/session_resume.clj	Renames “secret word” → “code word” in the resume example.
examples/session_events.clj	Updates default model string.
examples/reasoning_effort.clj	Updates example model string.
examples/multi_agent.clj	Updates example model string(s).
examples/metadata_api.clj	Updates example switch-model! target.
examples/helpers_query.clj	Updates example model string(s).
examples/byok_provider.clj	Updates example model string(s).
examples/README.md	Updates model strings and CLI option name for session-resume example.
doc/mcp/overview.md	Updates model strings in MCP guide examples.
doc/mcp/debugging.md	Updates model string and adds permission handler in examples.
doc/guides/custom-agents.md	Updates model strings in examples.
doc/getting-started.md	Updates model strings in examples.
doc/auth/byok.md	Updates model strings in BYOK guide examples.
doc/api/intro.html	Generated docs updated for model string (but still contains stale/unrunnable snippets).
doc/api/getting-started.html	Generated docs updated for model string (but still contains stale/unrunnable snippets).
doc/api/debugging.html	Generated docs updated for model string (but still contains stale/unrunnable snippets).
doc/api/overview.html	Generated docs updated for model string (but still contains stale/unrunnable snippets).
doc/api/API.html	Generated API topic updated for model string (but still contains stale/unrunnable snippets).
doc/api/byok.html	Generated BYOK topic updated for model string.
doc/api/github.copilot-sdk.html	Generated namespace docs updated for model string (but still contains stale/unrunnable snippets).
doc/api/github.copilot-sdk.helpers.html	Generated helpers docs updated for model string (but still contains stale/unrunnable snippets).
doc/api/github.copilot-sdk.client.html	Generated client docs updated for model string.

Comments suppressed due to low confidence (3)

doc/auth/byok.md:27

• All with-client-session examples in this BYOK guide omit :on-permission-request, but session creation validates config and requires a permission handler. As written, these snippets will throw when copy/pasted; please add :on-permission-request (e.g. copilot/approve-all) to the session options in each example.

(copilot/with-client-session [session
                              {:model "gpt-5.3-codex"
                               :provider {:provider-type :openai
                                          :base-url "https://your-resource.openai.azure.com/openai/v1/"
                                          :wire-api :responses
                                          :api-key (System/getenv "FOUNDRY_API_KEY")}}]

doc/api/getting-started.html:71

• This streaming example also omits :on-permission-request in the session opts. Since the SDK enforces deny-by-default permissions at session creation, the example is not runnable as written; please include a handler in the with-client-session config when regenerating these docs.

(copilot/with-client-session [session {:model "gpt-5.4" :streaming? true}]
  (let [ch (chan 256)

doc/api/API.html:126

• All with-client-session forms here omit :on-permission-request in the session opts. Since session creation validates and requires a permission handler, these examples won’t run as written. Please regenerate/update the docs so each form includes a handler (e.g. :on-permission-request copilot/approve-all).

<pre><code class="language-clojure">;; Form 1: [session session-opts] - anonymous client with default options
(copilot/with-client-session [session {:model "gpt-5.4"}]
  ;; use session
  )

[Copilot]

Pull request overview

Ports upstream Copilot SDK updates into the Clojure SDK, adding outbound blob attachments support while refreshing documentation/examples (including model ID updates) and regenerating Codox HTML.

Changes:

• Add outbound :blob attachments support in wire conversion + specs, with unit/E2E coverage.
• Refresh docs/examples and mock server/test fixtures from gpt-5.2 → gpt-5.4 (and gpt-5.3-codex where applicable).
• Expand/align permission-handling documentation and regenerate doc/api/* (Codox) plus update the docs update skill.

Reviewed changes

Copilot reviewed 47 out of 47 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/github/copilot_sdk/util.clj	Adds :blob case to attachment->wire for outbound inline base64 attachments.
src/github/copilot_sdk/specs.clj	Extends outbound ::attachment to include :blob; clarifies inbound attachment alias comment.
test/github/copilot_sdk_test.clj	Updates model strings in spec tests and adds unit tests for blob wire-format + spec validity.
test/github/copilot_sdk/mock_server.clj	Updates mocked models.list response to return gpt-5.4 metadata.
test/github/copilot_sdk/integration_test.clj	Updates integration tests to use gpt-5.4.
test/github/copilot_sdk/e2e_test.clj	Adds E2E test covering send-and-wait! with a :blob attachment.
src/github/copilot_sdk/helpers.clj	Updates docstring example model to gpt-5.4.
src/github/copilot_sdk/client.clj	Updates docstring examples to gpt-5.4.
src/github/copilot_sdk.clj	Updates public API docstrings/examples to gpt-5.4.
examples/session_resume.clj	Renames “secret word” → “code word” in the resume example.
examples/session_events.clj	Updates default model to gpt-5.4.
examples/reasoning_effort.clj	Updates example model to gpt-5.4.
examples/multi_agent.clj	Updates example models to gpt-5.4.
examples/metadata_api.clj	Updates switch-model! example target to gpt-5.4.
examples/helpers_query.clj	Updates example model to gpt-5.4.
examples/byok_provider.clj	Updates BYOK examples to gpt-5.4.
examples/README.md	Updates example snippets + CLI args (e.g., :code-word) and model IDs.
README.md	Adds “Permission Handling” section and refreshes model IDs in snippets.
doc/reference/API.md	Documents :blob attachments; aligns permission-handling wording and refreshes model IDs.
doc/mcp/overview.md	Refreshes model IDs in MCP guide snippets.
doc/mcp/debugging.md	Adds missing :on-permission-request to examples and refreshes model IDs.
doc/guides/custom-agents.md	Refreshes model IDs in custom agents guide.
doc/getting-started.md	Refreshes model IDs and updates examples to include permission handlers where needed.
doc/auth/byok.md	Refreshes model IDs and updates codex model example to gpt-5.3-codex.
CHANGELOG.md	Notes new outbound :blob attachment support and README permission docs addition.
.github/skills/update-docs/SKILL.md	Adds Codox regeneration step to the docs update procedure.
doc/api/style.html	Regenerated Codox HTML reflecting doc style updates (cleanup guidance).
doc/api/overview.html	Regenerated Codox HTML reflecting MCP overview updates.
doc/api/intro.html	Regenerated/updated Codox intro page content (model string updated).
doc/api/index.html	Regenerated Codox index, including updated navigation and counts.
doc/api/github.copilot-sdk.util.html	Regenerated Codox HTML for util namespace docs.
doc/api/github.copilot-sdk.tools.html	Regenerated Codox HTML for tools namespace docs.
doc/api/github.copilot-sdk.specs.html	Regenerated Codox HTML for specs namespace docs.
doc/api/github.copilot-sdk.session.html	Regenerated Codox HTML for session namespace docs.
doc/api/github.copilot-sdk.protocol.html	Regenerated Codox HTML for protocol namespace docs.
doc/api/github.copilot-sdk.process.html	Regenerated Codox HTML for process namespace docs.
doc/api/github.copilot-sdk.logging.html	Regenerated Codox HTML for logging namespace docs.
doc/api/github.copilot-sdk.instrument.html	Regenerated Codox HTML for instrumentation docs.
doc/api/github.copilot-sdk.helpers.html	Regenerated Codox HTML for helpers docs.
doc/api/getting-started.html	Regenerated Codox HTML for getting-started content.
doc/api/debugging.html	Regenerated Codox HTML for MCP debugging content.
doc/api/custom-agents.html	Adds new Codox HTML page for custom agents guide.
doc/api/byok.html	Regenerated Codox HTML for BYOK docs updates.
doc/api/azure-managed-identity.html	Adds new Codox HTML page for Azure managed identity BYOK guide.

Comments suppressed due to low confidence (1)

doc/api/intro.html:23

• The quick-start snippet is not copy/paste runnable: it requires krukow.copilot-sdk (this repo’s public namespace is github.copilot-sdk), calls create-session without the required :on-permission-request handler (will throw during config validation), and uses deprecated destroy! for cleanup. Please update the source for this page and regenerate Codox so the snippet uses the current namespace, includes a permission handler, and uses disconnect!.

(def session (copilot/create-session client {:model "gpt-5.4"}))
(def response (copilot/send-and-wait! session {:prompt "What is 2+2?"}))
(println (get-in response [:data :content]))

(copilot/destroy! session)

[Copilot]

Pull request overview

Ports upstream Copilot SDK changes into the Clojure implementation, primarily adding outbound blob attachments support and refreshing permission-handling documentation/examples, alongside a repo-wide model-id refresh (gpt-5.2 → gpt-5.4) and regenerated Codox HTML.

Changes:

• Add outbound :blob attachments support (specs + wire encoding) and tests (unit + E2E).
• Expand/align permission-handling documentation (deny-by-default, join-session exception) across README + API reference.
• Refresh examples/docs/tests for updated model IDs and regenerate doc/api/* HTML.

Reviewed changes

Copilot reviewed 47 out of 47 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
test/github/copilot_sdk_test.clj	Adds unit coverage for blob attachment wire format + send-options spec; updates model id in config tests.
test/github/copilot_sdk/mock_server.clj	Updates mock models.list response to gpt-5.4.
test/github/copilot_sdk/integration_test.clj	Updates integration tests to use gpt-5.4 in session creation/resume paths.
test/github/copilot_sdk/e2e_test.clj	Adds E2E test that sends a blob attachment (with explicit timeout).
src/github/copilot_sdk/util.clj	Adds :blob branch to attachment->wire (emits type/data/mimeType/displayName).
src/github/copilot_sdk/specs.clj	Extends ::attachment to include ::blob-attachment; clarifies inbound-attachment alias comment.
src/github/copilot_sdk/helpers.clj	Refreshes docstring example model id to gpt-5.4.
src/github/copilot_sdk/client.clj	Refreshes docstring examples to gpt-5.4.
src/github/copilot_sdk.clj	Refreshes top-level/public docstring examples to gpt-5.4.
examples/session_resume.clj	Renames “secret word” terminology to “code word” in the resume example.
examples/session_events.clj	Updates default model to gpt-5.4.
examples/reasoning_effort.clj	Updates example model to gpt-5.4.
examples/multi_agent.clj	Updates example model to gpt-5.4.
examples/metadata_api.clj	Updates switch-model example target to gpt-5.4.
examples/helpers_query.clj	Updates helper session options to gpt-5.4.
examples/byok_provider.clj	Updates BYOK example models to gpt-5.4.
examples/README.md	Updates embedded snippets + CLI args to gpt-5.4 and :code-word naming.
doc/reference/API.md	Documents :blob attachments; aligns permission-handling text with join-session behavior; model refresh throughout.
doc/mcp/overview.md	Fixes MCP examples to include required :on-permission-request; model refresh.
doc/mcp/debugging.md	Fixes MCP debugging examples to include required :on-permission-request; model refresh.
doc/guides/custom-agents.md	Model refresh throughout custom agents guide snippets.
doc/getting-started.md	Model refresh + permission handler included in snippets.
doc/auth/byok.md	Updates codex model and adds required permission handler in examples; model refresh elsewhere.
doc/api/style.html	Regenerated Codox HTML (includes updated lifecycle cleanup guidance).
doc/api/overview.html	Regenerated Codox HTML for MCP overview (includes permission handler in snippets).
doc/api/intro.html	Regenerated Codox HTML intro page (model refresh).
doc/api/index.html	Regenerated Codox HTML index (updates topic list and examples count).
doc/api/github.copilot-sdk.util.html	Regenerated Codox namespace docs for util (reflects blob support).
doc/api/github.copilot-sdk.tools.html	Regenerated Codox namespace docs for tools (updated signatures/docs).
doc/api/github.copilot-sdk.specs.html	Regenerated Codox namespace docs for specs.
doc/api/github.copilot-sdk.session.html	Regenerated Codox namespace docs for session (updated lifecycle docs).
doc/api/github.copilot-sdk.protocol.html	Regenerated Codox namespace docs for protocol.
doc/api/github.copilot-sdk.process.html	Regenerated Codox namespace docs for process.
doc/api/github.copilot-sdk.logging.html	Regenerated Codox namespace docs for logging.
doc/api/github.copilot-sdk.instrument.html	Regenerated Codox namespace docs for instrumentation.
doc/api/github.copilot-sdk.helpers.html	Regenerated Codox namespace docs for helpers (permission handler examples).
doc/api/getting-started.html	Regenerated Codox HTML getting-started guide (model refresh + permission handler).
doc/api/debugging.html	Regenerated Codox HTML MCP debugging guide (permission handler + model refresh).
doc/api/custom-agents.html	New generated Codox HTML page for custom agents guide.
doc/api/byok.html	Regenerated Codox HTML BYOK guide (permission handler + model refresh + additions).
doc/api/azure-managed-identity.html	New generated Codox HTML page for Azure Managed Identity BYOK guide.
README.md	Adds “Permission Handling” section + model refresh in examples.
CHANGELOG.md	Notes blob attachments outbound support + permission docs addition.
.github/skills/update-docs/SKILL.md	Updates docs skill instructions to include Codox regeneration step.

Comments suppressed due to low confidence (1)

doc/api/intro.html:24

• The Quick start snippet creates a session with only {:model "gpt-5.4"}, but create-session throws when :on-permission-request is missing. As-is, this example will fail when copy/pasted. Update the snippet to include an :on-permission-request handler (and consider using disconnect! instead of destroy! if the docs are meant to reflect the current lifecycle API).

(def session (copilot/create-session client {:model "gpt-5.4"}))
(def response (copilot/send-and-wait! session {:prompt "What is 2+2?"}))
(println (get-in response [:data :content]))

(copilot/destroy! session)
(copilot/stop! client)

[Copilot]

Pull request overview

Ports upstream SDK changes to support outbound blob attachments, refreshes model IDs in docs/examples/tests, and expands permission-handling documentation while regenerating Codox HTML outputs.

Changes:

• Add outbound :blob attachments support (spec + wire conversion) with unit and E2E coverage.
• Refresh examples/tests/docs from gpt-5.2 → gpt-5.4 (keeping BYOK codex at gpt-5.3-codex) and update session resume wording.
• Expand permission-handling documentation and regenerate doc/api/* Codox HTML.

Reviewed changes

Copilot reviewed 47 out of 47 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
test/github/copilot_sdk_test.clj	Updates model strings and adds blob attachment unit/spec tests.
test/github/copilot_sdk/mock_server.clj	Updates mock list-models response to gpt-5.4.
test/github/copilot_sdk/integration_test.clj	Updates integration tests to gpt-5.4.
test/github/copilot_sdk/e2e_test.clj	Adds E2E coverage for sending blob attachments.
src/github/copilot_sdk/util.clj	Adds :blob case to attachment->wire conversion.
src/github/copilot_sdk/specs.clj	Extends outbound attachment spec to include :blob and updates inbound spec commentary.
src/github/copilot_sdk/helpers.clj	Refreshes example docstring model to gpt-5.4.
src/github/copilot_sdk/client.clj	Refreshes docstring examples to gpt-5.4.
src/github/copilot_sdk.clj	Refreshes public API docs/examples to gpt-5.4.
examples/session_resume.clj	Renames “secret word” → “code word” and adjusts prompts.
examples/session_events.clj	Updates default model to gpt-5.4.
examples/reasoning_effort.clj	Updates model to gpt-5.4.
examples/multi_agent.clj	Updates models in multi-agent example to gpt-5.4.
examples/metadata_api.clj	Updates model switching example to gpt-5.4.
examples/helpers_query.clj	Updates helper query examples to gpt-5.4.
examples/byok_provider.clj	Updates BYOK examples to gpt-5.4.
examples/README.md	Updates examples README for model refresh and code-word param rename.
doc/reference/API.md	Adds blob attachment docs, refreshes models, and clarifies permission handling semantics.
doc/mcp/overview.md	Updates MCP docs examples (adds :on-permission-request, model refresh).
doc/mcp/debugging.md	Updates MCP debugging docs examples (adds :on-permission-request, model refresh).
doc/guides/custom-agents.md	Refreshes models in custom agents guide.
doc/getting-started.md	Refreshes models and updates examples to include permission handler.
doc/auth/byok.md	Refreshes models and codex model ID; updates examples to include permission handler.
doc/api/style.html	Regenerated Codox HTML; updates lifecycle cleanup wording.
doc/api/overview.html	Regenerated Codox HTML for MCP overview updates.
doc/api/intro.html	Regenerated Codox HTML; updates quick-start model ID.
doc/api/index.html	Regenerated Codox HTML; adds links to new docs and updates examples count.
doc/api/github.copilot-sdk.util.html	Regenerated Codox HTML for util namespace updates.
doc/api/github.copilot-sdk.tools.html	Regenerated Codox HTML for tools namespace doc updates.
doc/api/github.copilot-sdk.specs.html	Regenerated Codox HTML for specs namespace updates.
doc/api/github.copilot-sdk.session.html	Regenerated Codox HTML for session API updates (disconnect/destroy, etc.).
doc/api/github.copilot-sdk.protocol.html	Regenerated Codox HTML for protocol API docs updates.
doc/api/github.copilot-sdk.process.html	Regenerated Codox HTML for process namespace updates.
doc/api/github.copilot-sdk.logging.html	Regenerated Codox HTML for logging namespace updates.
doc/api/github.copilot-sdk.instrument.html	Regenerated Codox HTML for instrumentation docs.
doc/api/github.copilot-sdk.helpers.html	Regenerated Codox HTML for helpers docs updates.
doc/api/getting-started.html	Regenerated Codox HTML for getting-started revisions.
doc/api/debugging.html	Regenerated Codox HTML for MCP debugging page revisions.
doc/api/custom-agents.html	Adds regenerated Codox HTML page for custom agents.
doc/api/byok.html	Regenerated Codox HTML for BYOK docs updates.
doc/api/azure-managed-identity.html	Adds regenerated Codox HTML page for Azure managed identity guide.
README.md	Adds “Permission Handling” section and refreshes model IDs in examples.
CHANGELOG.md	Notes new outbound :blob attachment support and README permission docs addition.
.github/skills/update-docs/SKILL.md	Adds step to regenerate Codox HTML (bb docs) to keep doc/api/ in sync.

Comments suppressed due to low confidence (2)

src/github/copilot_sdk/specs.clj:1

• The comment states ::inbound-attachment is identical to ::attachment, but the shown s/or for ::inbound-attachment does not include :github-reference or :blob. This mismatch can cause inbound blob (and possibly GitHub reference) attachments in events to fail spec validation. Recommended fix: define ::inbound-attachment as a direct alias of ::attachment (e.g., (s/def ::inbound-attachment ::attachment)), or update the s/or to include the same branches as ::attachment.
  test/github/copilot_sdk/e2e_test.clj:1
• This new E2E test creates a session without explicitly setting :model, while the rest of the suite (and this PR’s stated model refresh) uses gpt-5.4. If the SDK’s default model changes (or defaults are removed), this test may become flaky or start exercising an unintended model. Recommended fix: pass :model \"gpt-5.4\" in the session config for consistency and stability.

[Copilot]

Pull request overview

Ports upstream Copilot SDK changes into the Clojure implementation, primarily adding outbound blob attachments support and refreshing documentation/examples (including permission-handling guidance and model name updates).

Changes:

• Add outbound :blob attachments support in specs and wire conversion, plus unit + E2E coverage.
• Refresh docs/examples for permission handling and update model strings (e.g. gpt-5.2 → gpt-5.4, BYOK codex → gpt-5.3-codex).
• Regenerate Codox HTML docs and update the update-docs skill to include Codox regeneration.

Reviewed changes

Copilot reviewed 47 out of 47 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
test/github/copilot_sdk_test.clj	Adds unit tests covering blob attachment wire format + spec validity; updates model string in config tests.
test/github/copilot_sdk/mock_server.clj	Updates mocked model list to return gpt-5.4.
test/github/copilot_sdk/integration_test.clj	Updates integration tests to use gpt-5.4 as the model.
test/github/copilot_sdk/e2e_test.clj	Adds an E2E test sending a blob attachment.
src/github/copilot_sdk/util.clj	Adds :blob case to attachment->wire.
src/github/copilot_sdk/specs.clj	Extends ::attachment / ::inbound-attachment with ::blob-attachment.
src/github/copilot_sdk/helpers.clj	Updates docstring example model to gpt-5.4.
src/github/copilot_sdk/client.clj	Updates docstrings/examples to gpt-5.4.
src/github/copilot_sdk.clj	Updates top-level docstrings/examples to gpt-5.4.
examples/session_resume.clj	Renames “secret word” → “code word” and updates prompts accordingly.
examples/session_events.clj	Updates default model to gpt-5.4.
examples/reasoning_effort.clj	Updates example model to gpt-5.4.
examples/multi_agent.clj	Updates example model to gpt-5.4.
examples/metadata_api.clj	Updates example switch-model target to gpt-5.4.
examples/helpers_query.clj	Updates example model to gpt-5.4.
examples/byok_provider.clj	Updates BYOK examples to default to gpt-5.4.
examples/README.md	Updates example snippets (model refresh + code-word option rename).
doc/reference/API.md	Documents :blob attachments, aligns permission wording with join-session, refreshes models.
doc/mcp/overview.md	Adds missing :on-permission-request and refreshes models.
doc/mcp/debugging.md	Adds missing :on-permission-request and refreshes models.
doc/guides/custom-agents.md	Refreshes model strings to gpt-5.4.
doc/getting-started.md	Refreshes model strings and permission-handler examples.
doc/auth/byok.md	Adds missing :on-permission-request, updates codex model to gpt-5.3-codex, refreshes models.
doc/api/style.html	Regenerated Codox HTML; updates cleanup guidance to disconnect!.
doc/api/overview.html	Regenerated Codox HTML for MCP overview examples (incl. permission handler).
doc/api/intro.html	Regenerated Codox HTML intro page (quick-start snippet updated).
doc/api/index.html	Regenerated Codox HTML index (updated examples count + new guide links).
doc/api/github.copilot-sdk.util.html	Regenerated Codox HTML for util namespace.
doc/api/github.copilot-sdk.tools.html	Regenerated Codox HTML for tools namespace.
doc/api/github.copilot-sdk.specs.html	Regenerated Codox HTML for specs namespace.
doc/api/github.copilot-sdk.session.html	Regenerated Codox HTML for session namespace (includes disconnect!/destroy! deprecation text).
doc/api/github.copilot-sdk.protocol.html	Regenerated Codox HTML for protocol namespace.
doc/api/github.copilot-sdk.process.html	Regenerated Codox HTML for process namespace.
doc/api/github.copilot-sdk.logging.html	Regenerated Codox HTML for logging namespace.
doc/api/github.copilot-sdk.instrument.html	Regenerated Codox HTML for instrument namespace.
doc/api/github.copilot-sdk.helpers.html	Regenerated Codox HTML for helpers namespace (permission handler examples).
doc/api/getting-started.html	Regenerated Codox HTML for getting-started guide (adds permission handler in examples).
doc/api/debugging.html	Regenerated Codox HTML for MCP debugging guide (adds permission handler).
doc/api/custom-agents.html	New generated Codox HTML guide for custom agents.
doc/api/byok.html	Regenerated Codox HTML BYOK guide (adds permission handler + Foundry Local section).
doc/api/azure-managed-identity.html	New generated Codox HTML guide for Azure Managed Identity BYOK workaround.
README.md	Adds Permission Handling section; refreshes model examples.
CHANGELOG.md	Adds unreleased entry for outbound :blob attachments and README permission docs.
.github/skills/update-docs/SKILL.md	Adds Codox regeneration step to the update-docs skill.

Comments suppressed due to low confidence (1)

doc/api/intro.html:24

• This quick-start uses destroy! for cleanup. destroy! is deprecated in favor of disconnect! (and examples/docs elsewhere use disconnect! + stop!). Consider updating this snippet to call disconnect! instead so copy/paste users don’t adopt the deprecated API.

(def session (copilot/create-session client {:model "gpt-5.4"}))
(def response (copilot/send-and-wait! session {:prompt "What is 2+2?"}))
(println (get-in response [:data :content]))

(copilot/destroy! session)
(copilot/stop! client)