ADR: Add scope-bound query sequences before deprecating query-seq!
+Generated by Codox
ADR: Add scope-bound query sequences before deprecating query-seq!
- Status: Accepted
- Deciders: @krukow diff --git a/doc/api/2026-08-10-host-owned-inference-boundary.html b/doc/api/2026-08-10-host-owned-inference-boundary.html index ed584e0..0cdcbda 100644 --- a/doc/api/2026-08-10-host-owned-inference-boundary.html +++ b/doc/api/2026-08-10-host-owned-inference-boundary.html @@ -1,6 +1,6 @@ -
- Status: Accepted
- Deciders: @krukow diff --git a/doc/api/2026-09-27-dynamic-workflow-migration.html b/doc/api/2026-09-27-dynamic-workflow-migration.html index 1f9a9a7..081c863 100644 --- a/doc/api/2026-09-27-dynamic-workflow-migration.html +++ b/doc/api/2026-09-27-dynamic-workflow-migration.html @@ -1,6 +1,6 @@ -
- Status: Accepted
- Related: upstream snapshot, migration guide diff --git a/doc/api/2026-09-30-model-policy-and-lifecycle-sync.html b/doc/api/2026-09-30-model-policy-and-lifecycle-sync.html index abe2a92..44fb79d 100644 --- a/doc/api/2026-09-30-model-policy-and-lifecycle-sync.html +++ b/doc/api/2026-09-30-model-policy-and-lifecycle-sync.html @@ -1,6 +1,6 @@ -
- Status: Accepted
- Related: upstream snapshot, session configuration diff --git a/doc/api/2026-10-02-transcript-recovery-and-owned-exit.html b/doc/api/2026-10-02-transcript-recovery-and-owned-exit.html index 7ce5cbc..2b03b65 100644 --- a/doc/api/2026-10-02-transcript-recovery-and-owned-exit.html +++ b/doc/api/2026-10-02-transcript-recovery-and-owned-exit.html @@ -1,6 +1,6 @@ -
- Status: Accepted
- Related: upstream snapshot, model policy and lifecycle ADR diff --git a/doc/api/2026-10-04-byok-provider-telemetry.html b/doc/api/2026-10-04-byok-provider-telemetry.html index a75cbaf..c92fe9b 100644 --- a/doc/api/2026-10-04-byok-provider-telemetry.html +++ b/doc/api/2026-10-04-byok-provider-telemetry.html @@ -1,6 +1,6 @@ -
- Status: Accepted
- Related: upstream snapshot diff --git a/doc/api/2026-10-05-callback-and-event-contracts.html b/doc/api/2026-10-05-callback-and-event-contracts.html index f59d8fc..9be2bc1 100644 --- a/doc/api/2026-10-05-callback-and-event-contracts.html +++ b/doc/api/2026-10-05-callback-and-event-contracts.html @@ -1,6 +1,6 @@ -
- Status: Accepted
- Related: upstream snapshot diff --git a/doc/api/2026-10-09-extensible-routing-and-event-contracts.html b/doc/api/2026-10-09-extensible-routing-and-event-contracts.html index 06e5b42..97cf82a 100644 --- a/doc/api/2026-10-09-extensible-routing-and-event-contracts.html +++ b/doc/api/2026-10-09-extensible-routing-and-event-contracts.html @@ -1,6 +1,6 @@ -
- Status: Accepted
- Related: upstream snapshot diff --git a/doc/api/2026-10-12-transport-diagnostics-and-opaque-policy.html b/doc/api/2026-10-12-transport-diagnostics-and-opaque-policy.html index 88c5c6e..e09ea52 100644 --- a/doc/api/2026-10-12-transport-diagnostics-and-opaque-policy.html +++ b/doc/api/2026-10-12-transport-diagnostics-and-opaque-policy.html @@ -1,6 +1,6 @@ -
- Status: Accepted
- Related: upstream snapshot diff --git a/doc/api/2026-10-16-session-hooks-and-compaction.html b/doc/api/2026-10-16-session-hooks-and-compaction.html index c1d1af7..86369a2 100644 --- a/doc/api/2026-10-16-session-hooks-and-compaction.html +++ b/doc/api/2026-10-16-session-hooks-and-compaction.html @@ -1,6 +1,6 @@ -
- Status: Accepted
- Related: upstream snapshot diff --git a/doc/api/2026-10-19-mcp-recovery-and-readiness.html b/doc/api/2026-10-19-mcp-recovery-and-readiness.html new file mode 100644 index 0000000..18018ee --- /dev/null +++ b/doc/api/2026-10-19-mcp-recovery-and-readiness.html @@ -0,0 +1,19 @@ + +
- Status: Accepted +
- Related: upstream snapshot +
- An
McpAuthRequestmap (the event data). - A context map
{:session-id "..."}.
@@ -1344,13 +1340,27 @@ - SQLite handler exceptions propagate as JSON-RPC errors (not wrapped as
SessionFsError). - ADR: Preserve MCP recovery and readiness contracts – Capability-gated OAuth renewal, terminal outcomes, tool readiness, and compression diagnostics.
- ADR: Preserve session, hook, and compaction contracts – Session naming/discovery, callback context, and stable event metadata without new experimental authority.
- ADR: Preserve transport diagnostics and opaque policy – Request compression, WebSocket fallback attribution, and passive policy/usage metadata.
- ADR: Preserve extensible identifiers and policy boundaries – Dynamic Auto tiers, managed policy, write previews, accounting metadata, and bounded generated validators. diff --git a/doc/api/dynamic-workflows.html b/doc/api/dynamic-workflows.html index fbd9e9e..a922388 100644 --- a/doc/api/dynamic-workflows.html +++ b/doc/api/dynamic-workflows.html @@ -1,6 +1,6 @@ -
Generated by Codox
ADR: Defer a host-owned inference boundary
+Generated by Codox
ADR: Defer a host-owned inference boundary
Generated by Codox
ADR: Migrate the existing orchestration API to Dynamic Workflows
+Generated by Codox
ADR: Migrate the existing orchestration API to Dynamic Workflows
Generated by Codox
ADR: Separate stable model policy from experimental host controls
+Generated by Codox
ADR: Separate stable model policy from experimental host controls
Generated by Codox
ADR: Expose transcript recovery and bound owned-runtime disconnection
+Generated by Codox
ADR: Expose transcript recovery and bound owned-runtime disconnection
Generated by Codox
ADR: Separate BYOK configuration identity from runtime telemetry
+Generated by Codox
ADR: Separate BYOK configuration identity from runtime telemetry
Generated by Codox
ADR: Preserve callback, filesystem, and event authority boundaries
+Generated by Codox
ADR: Preserve callback, filesystem, and event authority boundaries
Generated by Codox
ADR: Preserve extensible identifiers and policy boundaries
+Generated by Codox
ADR: Preserve extensible identifiers and policy boundaries
Generated by Codox
ADR: Preserve transport diagnostics and opaque policy
+Generated by Codox
ADR: Preserve transport diagnostics and opaque policy
Generated by Codox
ADR: Preserve session, hook, and compaction contracts
+Generated by Codox
ADR: Preserve session, hook, and compaction contracts
Generated by Codox
ADR: Preserve MCP recovery and readiness contracts
+-
+
Context
+The Node SDK lets an MCP OAuth handler delegate advertised, noninteractive credential renewal to the runtime. New events distinguish authorization recovery completion from accepting the host response, and MCP tool readiness from connection status. Usage and failure events gain compression-fallback diagnostics. Other additions remain experimental or internal.
+Decision
+Use the canonical handler result {:kind :runtime-refresh} and send "runtimeRefresh" only when the request has :runtime-refresh-supported true. Preserve omission and explicit false in callback data. Explicit cancellation takes precedence over a token; a nonempty string token takes precedence over handoff. Preserve bare-token maps and existing optional-token-field omission. Malformed results and handler exceptions are logged and cancel the host request. The same callback path serves create, resume, join, and channel variants.
Keep renewal, grant storage, reconnect, and cancellation runtime-owned. Handoff acceptance is not completion. Expose the persisted :copilot/mcp.oauth_recovery_completed event with its request/server identity and exact "succeeded", "cancelled", or "failed" outcome. Expose ephemeral :copilot/session.mcp_server_tools_loaded with string server name and the schema’s integer tool count. Do not infer readiness from "connected", impose event ordering, or fabricate history for an ephemeral event.
Expose the three optional compression diagnostic fields on both usage and failure events. Preserve string enums and the schema’s integer status range of 0-999. Omission is not zero; explicit nil is invalid. Keep payload maps open for future fields and preserve live/history behavior without new coercion.
Retain the existing :additional-directories and :enable-file-hooks APIs. Document startup directories as trust in repository commands and prompts, including the containing Git root. Prove enabled/disabled and cold-resume behavior with isolated repositories and a local model provider. Do not add runtime discovery or authorization logic to the SDK.
Keep skill-provider supporting files, Azure ML model acquisition, catalog category filtering, hosting discovery hints, and generated MCP configuration observations outside the supported API. Internal provider-type telemetry and the durable compression-disable marker remain wire-only.
+Consequences
+The public snapshot adds event/spec membership and the existing OAuth dispatcher’s fdef, without new client or session operations. Complete symbol-based evidence extends the historical certification at its original pin. The target has no Node test tree; retained upstream tests remain historical, while new behavior is checked through local protocol and real-runtime tests.
+CLI compatibility and schema provenance advance to 1.0.100-1. The library version stays 1.0.16.0; this decision does not cut a release, tag, or deployment.
Generated by Codox
API Reference
+Generated by Codox
API Reference
Helpers API
The helpers namespace provides simple, stateless query functions with automatic client management.
(require '[github.copilot-sdk.helpers :as h])
@@ -306,7 +306,7 @@ with-clien
:agent-directories vector Explicit discovery-only agent roots, separate from :custom-agents. Available without :enable-config-discovery; source and managed-policy disables still apply. :hook-directories vector Explicit discovery-only file-hook roots, separate from callback :hooks. Available without :enable-config-discovery or :enable-file-hooks; the latter controls repository-origin hooks only. Hook and managed-policy disables still apply. :instruction-directories vector Explicit discovery-only instruction roots, using the existing SDK instruction formats. Available without :enable-config-discovery; instruction and managed-policy disables still apply. :additional-directories vector Extra directories the runtime is allowed to read/write outside the session’s working directory. Vector of non-blank strings. Serialized as wire additionalDirectories. Re-supply the vector when resuming a session. (upstream PR #2180) :additional-directories vector Extra trusted directories the runtime may access outside the working directory. Startup directories also authorize repository-origin hooks from their containing Git roots. Supply only trusted repositories; see Session Hooks. Vector of non-blank strings, sent as additionalDirectories; re-supply on cold resume. (upstream PR #2180) :disabled-skills vector Disable specific skills by name :included-builtin-skills vector Allowlist of runtime-bundled skill names, applied through session.options.update after create/resume. :empty client mode defaults this to []; an explicit vector overrides that default. :copilot-cli mode omits it unless explicitly supplied, including an explicit []. Custom skill loading remains controlled separately. (upstream PR #2410) :large-output map Tool output handling config. Supports :enabled, :max-size-bytes, and :output-directory (:output-dir remains a deprecated alias). The official SDK exposes the same config as largeOutput. with-clien
:skip-embedding-retrieval boolean Skip embedding-based context retrieval. (upstream PR #1474) :organization-custom-instructions string Organization-wide instructions injected by the host. (upstream PR #1474) :enable-on-demand-instruction-discovery boolean Auto-discover instruction files on demand. (upstream PR #1474) :enable-file-hooks boolean Enable file-watcher-style lifecycle hooks. (upstream PR #1474) :enable-file-hooks boolean Controls repository-origin hooks from the primary repository and eligible additional startup directories. false suppresses them; explicit :hook-directories and SDK callback :hooks are independent. Omission preserves the runtime default; nil is invalid. See Session Hooks. :enable-host-git-operations boolean Allow the CLI to run git operations through the host. (upstream PR #1474) :enable-session-store boolean Enable the disk-backed session store. (upstream PR #1474) :enable-skills boolean Enable skills discovery and loading. (upstream PR #1474) ui-elicitation!
MCP OAuth Handler
-Some MCP servers require interactive (browser-based) OAuth. Register an :on-mcp-auth-request handler to take over that flow; without it, the runtime falls back to a browserless cached-token path and never prompts. (upstream PR #1669)
Register an :on-mcp-auth-request handler to supply MCP OAuth credentials or hand supported refresh requests back to the runtime. Without a handler, authorization remains runtime-owned, including cached-credential handling.
(require '[github.copilot-sdk :as copilot])
-(def session
- (copilot/create-session
- client
- {:on-permission-request copilot/approve-all
- :on-mcp-auth-request
- (fn [request ctx]
- ;; request is the McpAuthRequest; ctx is {:session-id "..."}
- (let [token (acquire-oauth-token! (:server-url request))]
- (if token
- {:access-token token :token-type "Bearer" :expires-in 3600}
- {:kind :cancelled})))}))
-When the handler is provided, the SDK registers interest in the mcp.oauth_required event (before the session.create/session.resume runtime work begins) so the runtime delegates the OAuth request to your handler. The handler is invoked with two arguments:
When the handler is provided, the SDK registers interest in the mcp.oauth_required event after session.create, and before session.resume on resume or join. Registration failures fail the session operation rather than silently falling back. The handler is invoked with two arguments:
MCP OAuth Handler :server-name string Configured name of the MCP server.
:server-url string URL of the MCP server requiring auth. :reason string Why authentication is needed. :runtime-refresh-supported boolean Optional, non-null capability for noninteractive runtime renewal. Omission or false means unsupported. :www-authenticate-params map (optional) Parsed WWW-Authenticate challenge params. :resource-metadata string (optional) Raw OAuth protected-resource metadata document. :static-client-config map (optional) Pre-registered OAuth client config.
:server-name :server-url :reason :runtime-refresh-supported false means unsupported. :www-authenticate-params WWW-Authenticate challenge params. :resource-metadata :static-client-config :static-client-config requires string :client-id and permits string :client-secret, boolean :public-client, :grant-type "client_credentials", and string :scope. The configured scope is used when the server challenge omits scope or supplies an empty scope. It is forwarded to the handler unchanged; absence and "" remain distinct, and explicit nil is invalid. The same shape appears in live :copilot/mcp.oauth_required events and get-messages history. This does not add CLI-only oauthScopes to SDK MCP server configuration.
Result mapping: Return a map with :access-token (plus optional :token-type and :expires-in) to answer with a token. Return nil, {:kind :cancelled}, or throw to cancel the request — a thrown handler never wedges the pending request (errors are swallowed and treated as a cancel, matching upstream).
Result mapping, in precedence order:
+| Handler result | Response |
|---|---|
nil or {:kind :cancelled} | Cancel, even when the map also contains a token. |
Nonempty string :access-token, with optional :token-type and :expires-in | Supply a token, including bare-token maps. A token takes precedence over a refresh handoff. Empty optional values and zero are preserved; nil optional values are omitted. |
{:kind :runtime-refresh} | Send wire kind "runtimeRefresh" only when the request’s capability is exactly true; otherwise cancel. |
| Malformed result or thrown exception | Log the failure and cancel, without leaving the host request unanswered. |
A supported handoff renews the runtime’s saved grant within the original authorization attempt; it does not start an independent refresh or consent flow. Acceptance is not reconnect or tool completion. The persisted :copilot/mcp.oauth_recovery_completed event carries the same :request-id, plus :server-name and :outcome ("succeeded", "cancelled", or "failed"). For an accepted handoff, mcp.oauth_completed is emitted once at that terminal outcome: "token" on success, "cancelled" otherwise.
The runtime owns grant storage, reconnect, and cancellation. A stopped invocation cannot later resume, but an already-issued token exchange may still settle its storage work. Neither handoff acceptance nor cancellation proves that storage settlement has finished. Ordinary cancellation without an accepted handoff retains its existing meaning; it is not reclassified as stopping a turn.
Event Types
Sessions emit various events during processing. All event types are namespaced keywords prefixed with copilot/.
Exported Constants ;; :copilot/elicitation.requested :copilot/elicitation.completed ;; :copilot/external_tool.requested :copilot/external_tool.completed ;; :copilot/mcp.oauth_required :copilot/mcp.oauth_completed +;; :copilot/mcp.oauth_recovery_completed ;; :copilot/command.queued :copilot/command.execute ;; :copilot/command.completed :copilot/commands.changed ;; :copilot/exit_plan_mode.requested :copilot/exit_plan_mode.completed} -
For schema 1.0.92-0, :copilot/assistant.server_tool_progress also belongs to copilot/assistant-events. :copilot/session.managed_settings_enforced and :copilot/session.managed_settings_resolved, :copilot/session.indexed_search, :copilot/session.permission_recovery, and :copilot/session.model_deselected belong to copilot/session-events. :copilot/tool_search.activated intentionally belongs only to the master copilot/event-types set, not copilot/interaction-events or copilot/tool-events.
The generated wire schemas also contain internal events such as assistant.turn_retry, model.call_start, model.call_final_result, and the durable skill-context reference events. They are wire-only and intentionally excluded from every curated public event set. Experimental HydraFusion routing events likewise remain generated wire evidence and are not curated as public idiom events. The experimental reasoningBlocks field on assistant.message and :shell-execution field on tool.execution_complete also remain generated wire evidence rather than stable curated idiom fields. Runtime schema 1.0.92-0 additionally carries experimental workflow pause/checkpoint, permission, workspace, and managed-catalog protocol declarations that are not part of the stable Clojure API. The new experimental permission declarations include permission.assentDetected, permission.contextualAuthorization, and the activatesExtraction field on permission.messageAuthorizationRead. Experimental extension launch-provider declarations and structured task-blocker payloads also remain generated wire evidence only. Connector management and command-enqueue APIs are not exposed by the Clojure SDK. Dynamic Workflows remain a supported experimental surface; pause/checkpoint mutation and argsSchema authoring remain excluded. Diagnostics configuration and diagnostic read/configure RPCs also remain experimental, even though the Node session config references the experimental DiagnosticsConfiguration type. Connector type re-exports do not make that subsystem stable. Fusion hints and steering attribution remain experimental; the runtime-only session.fusion_change_checkpoint event is internal and absent from the curated public event sets. Runtime-supervised AHP hosts, installation-confirmation callbacks and skill installation management, sandbox configuration/provenance and path grants, and read-only session permission decisions remain excluded. Passive permission.completed events can still carry the runtime’s "approved-read-only-for-session" result and its directory vector; observing that result does not add permission-granting authority to the SDK. New AHP transport-selection and Connector-account type exports, sessionless managed-settings composition/resolution, environment management, and provider withdrawal also remain outside the stable API. Session-scoped skill providers, image-generation consent, tool-invocation agent/request identity, compute-scoped AHP catalogs, provider quota observations, managed-plugin progress/retry, and configured-MCP inventory remain excluded. Passive experimental provider accounting and internal accounting snapshots retain their wire data without becoming curated stable APIs. Fast remains an integrator-only Auto preset and does not require dynamic tier catalog discovery. Runtime rejection is propagated without substituting another tier. A skill’s :allowed-tools metadata does not automatically approve tools in SDK sessions; the permission handler still decides.
For schema 1.0.92-0, :copilot/assistant.server_tool_progress also belongs to copilot/assistant-events. :copilot/session.managed_settings_enforced and :copilot/session.managed_settings_resolved, :copilot/session.indexed_search, :copilot/session.permission_recovery, and :copilot/session.model_deselected belong to copilot/session-events. :copilot/tool_search.activated intentionally belongs only to the master copilot/event-types set, not copilot/interaction-events or copilot/tool-events. :copilot/session.mcp_server_tools_loaded belongs to copilot/session-events; :copilot/mcp.oauth_recovery_completed belongs to copilot/interaction-events.
The generated wire schemas also contain internal events such as assistant.turn_retry, model.call_start, model.call_final_result, session.request_body_compression_disabled, and the durable skill-context reference events. They are wire-only and intentionally excluded from every curated public event set. Experimental HydraFusion routing events likewise remain generated wire evidence and are not curated as public idiom events. The experimental reasoningBlocks field on assistant.message and :shell-execution field on tool.execution_complete also remain generated wire evidence rather than stable curated idiom fields. Runtime schema 1.0.92-0 additionally carries experimental workflow pause/checkpoint, permission, workspace, and managed-catalog protocol declarations that are not part of the stable Clojure API. The new experimental permission declarations include permission.assentDetected, permission.contextualAuthorization, and the activatesExtraction field on permission.messageAuthorizationRead. Experimental extension launch-provider declarations and structured task-blocker payloads also remain generated wire evidence only. Connector management and command-enqueue APIs are not exposed by the Clojure SDK. Dynamic Workflows remain a supported experimental surface; pause/checkpoint mutation and argsSchema authoring remain excluded. Diagnostics configuration and diagnostic read/configure RPCs also remain experimental, even though the Node session config references the experimental DiagnosticsConfiguration type. Connector type re-exports do not make that subsystem stable. Fusion hints and steering attribution remain experimental; the runtime-only session.fusion_change_checkpoint event is internal and absent from the curated public event sets. Runtime-supervised AHP hosts, installation-confirmation callbacks and skill installation management, sandbox configuration/provenance and path grants, and read-only session permission decisions remain excluded. Passive permission.completed events can still carry the runtime’s "approved-read-only-for-session" result and its directory vector; observing that result does not add permission-granting authority to the SDK. New AHP transport-selection and Connector-account type exports, sessionless managed-settings composition/resolution, environment management, and provider withdrawal also remain outside the stable API. Session-scoped skill providers, image-generation consent, tool-invocation agent/request identity, compute-scoped AHP catalogs, provider quota observations, managed-plugin progress/retry, and configured-MCP inventory remain excluded. Passive experimental provider accounting and internal accounting snapshots retain their wire data without becoming curated stable APIs. Fast remains an integrator-only Auto preset and does not require dynamic tier catalog discovery. Runtime rejection is propagated without substituting another tier. A skill’s :allowed-tools metadata does not automatically approve tools in SDK sessions; the permission handler still decides.
evt — Event Keyword Helper
(copilot/evt :session.info) ;; => :copilot/session.info
(copilot/evt :assistant.message) ;; => :copilot/assistant.message
@@ -1402,8 +1413,11 @@ Event Reference
(def usage
{:model "example-model"
:request-body-bytes 4096
- :request-body-wire-bytes 1024
- :request-body-encoding "gzip"
+ :request-body-wire-bytes 4096
+ :request-body-encoding "identity"
+ :request-body-compression-fallback "retried"
+ :request-body-compression-fallback-from "gzip"
+ :request-body-compression-rejected-status 415
:websocket-fallback-error-kind "http_status"
:websocket-fallback-status-code 503
:websocket-fallback-reconnect-attempted false
@@ -1421,6 +1435,9 @@ Event Reference
:request-body-bytes Non-negative integer Serialized request size before compression. :request-body-wire-bytes Non-negative integer Body bytes sent for the attempt that produced this outcome, after compression. Equal to :request-body-bytes when uncompressed. :request-body-encoding "identity", "gzip", or "zstd" Encoding of that attempt’s body; "identity" means uncompressed, including WebSocket requests. :request-body-compression-fallback "retried" or "disabled" "retried" describes the single uncompressed resend after HTTP 400/415 rejected compression. "disabled" means an earlier rejection already disabled compression for this session. :request-body-compression-fallback-from "identity", "gzip", or "zstd" Requested encoding before fallback; reported with the fallback outcome. :request-body-compression-rejected-status Integer, 0-999 Status that rejected compression; reported for the "retried" outcome. :websocket-fallback-after-ms Non-negative integer Time spent on the WebSocket attempt before HTTP fallback. :websocket-fallback-reason String "connect_failed", "connection_unavailable", "send_failed", "api_error", or "transport_failed". :websocket-fallback-error-kind String Normalized cause: "dns", "tls", "timeout", "connection_refused", "connection_reset", "closed_by_peer", "closed_locally", "not_connected", "http_status", "protocol", "configuration", or "other". Event Reference
:websocket-fallback-started-this-call Boolean True when this call initiated fallback; false when it inherited fallback from an earlier call. Fallback descriptors can persist across calls. Do not count every event with fallback metadata as a new transport failure. Missing error-kind or status/close codes do not establish that no failure occurred.
+Fallback descriptors can persist across calls. Do not count every event with fallback metadata as a new transport failure. Missing error-kind or status/close codes do not establish that no failure occurred. Compression fallback follows the same rule: "disabled" is retained session state, including after resume, not a new rejection on each call.
Failures may also include non-negative :retry-attempt and request-fingerprint :encrypted-content-bytes, :image-bytes, and :reasoning-item-count. These are content-free diagnostics, not copies of the request.
-Experimental monthly quota readings are not per-call or session spending. Their amounts, availability, and cycle timestamps pass through without deriving missing consumption from balances. Managed-policy event contexts preserve the runtime-owned opaque :permissions JSON verbatim; they are snapshots, not approval tokens. Monthly quota APIs and managed-browser policy evaluation remain outside the stable Clojure API.
+Experimental monthly quota readings are not per-call or session spending. Their amounts, availability, and cycle timestamps pass through without deriving missing consumption from balances. Managed-policy event contexts preserve the runtime-owned opaque :permissions JSON verbatim; they are snapshots, not approval tokens. Monthly quota APIs and managed-browser policy evaluation remain outside the stable Clojure API. Provider-type telemetry remains internal. Experimental skill-provider supporting files, Azure ML acquisition, catalog category filters, and hosting discovery controls do not add stable Clojure APIs.
Curated ::specs/result and ::specs/error values accept recursive JSON: nil, strings, booleans, finite non-ratio numbers, vectors, and maps whose keys are strings or keywords and whose values recursively satisfy the same contract. Event-specific specs may impose a narrower shape. Generated event envelopes remain open at the top-level data map for forward-compatible fields, while nested schema objects marked closed by upstream reject unknown keys.
@@ -1522,8 +1539,9 @@ Event Reference
:copilot/elicitation.completed Elicitation request resolved :copilot/external_tool.requested External tool call requested (v3); data includes :request-id, :session-id, :tool-call-id, :tool-name, and optional string-or-nil :provider-id for host routing. :copilot/external_tool.completed External tool call completed (v3) :copilot/mcp.oauth_required MCP server requires OAuth authentication :copilot/mcp.oauth_completed MCP OAuth authentication completed :copilot/mcp.oauth_required MCP server requests OAuth credentials; optional boolean :runtime-refresh-supported permits a noninteractive runtime handoff. :copilot/mcp.oauth_completed OAuth host request completed. For an accepted runtime handoff, emitted once at the authorization terminal outcome: "token" on success, "cancelled" otherwise. :copilot/mcp.oauth_recovery_completed Persisted terminal result of an accepted runtime refresh, including reconnect. Required :request-id, :server-name, and :outcome ("succeeded", "cancelled", or "failed"). :copilot/mcp.headers_refresh_required Dynamic headers refresh request for a remote MCP server. Data requires :request-id, :server-name, :server-url, and :reason ("auth-failed", "startup", or "ttl-expired"). :copilot/mcp.headers_refresh_completed MCP headers refresh request completed. Data requires :request-id and :outcome ("headers", "none", "error", or "timeout"); "error" was added in runtime schema 1.0.84-6. :copilot/mcp.tools.list_changed Remote MCP server signalled its tool list changed; data includes :server-name (upstream schema 1.0.70) Event Reference
:copilot/session.skills_loaded Skills loaded for the session :copilot/session.mcp_servers_loaded MCP servers loaded for the session. Each server may include a managed-catalog :display-name, :source ("user", "workspace", "plugin", "builtin", or "managed"), plugin identity, :error, and :server-metadata {:instructions <string-or-nil>}. :copilot/session.mcp_server_status_changed MCP server status changed. Optional :error, :config-source, and :error-classification are non-null strings. :config-source describes connected or failed servers. Provenance and failure classifications are extensible strings, not closed enums; omission, empty strings, and future runtime values remain distinct in live events and history. :copilot/session.mcp_server_tools_loaded Ephemeral notification that an MCP connection’s initial tool list is available. Requires string :server-name and integer :tool-count, including zero. Emitted once per connection, possibly before "connected" when using a cached snapshot. :copilot/session.mcp_server_removed MCP server was removed; data: {:server-name "..."} :copilot/session.mcp_server_needs_reconnect MCP server requires reconnection; data: {:server-name "..."} :copilot/session.extensions_loaded Extensions loaded for the session SQLite s
Session Hooks
+Additional-directory trust: :additional-directories supplied at local creation or cold resume also authorize repository hooks, not just file access. Discovery uses each directory’s containing Git root, or the directory itself outside Git. For example, adding /srv/project-b/packages/core can authorize commands and prompts in /srv/project-b/.github/hooks without another approval. Supply only trusted repositories.
+:enable-file-hooks false suppresses repository-origin hooks, independently of explicit :hook-directories and SDK callback :hooks. DISABLE_ADDITIONAL_DIRECTORY_HOOKS=true restores primary-only repository scope when the runtime captures startup authorization. Later file-access grants or changes to that environment variable do not expand the retained hook scope. Re-supply additional directories on cold resume. Managed policy, hook-disable settings, and sandbox rules still apply; they do not make untrusted hooks safe.
Lifecycle hooks allow custom logic at various points during the session:
(def session (copilot/create-session client
{:model "gpt-5.4"
diff --git a/doc/api/azure-managed-identity.html b/doc/api/azure-managed-identity.html
index ed95049..b0730be 100644
--- a/doc/api/azure-managed-identity.html
+++ b/doc/api/azure-managed-identity.html
@@ -1,6 +1,6 @@
-Azure Managed Identity with BYOK Generated by Codox
Azure Managed Identity with BYOK
+Azure Managed Identity with BYOK Generated by Codox
Azure Managed Identity with BYOK
The Copilot SDK’s BYOK mode accepts static API keys, but Azure deployments often use Managed Identity (Entra ID) instead of long-lived keys. Since the SDK does not natively support Entra ID authentication, you can obtain a short-lived bearer token and pass it via the :bearer-token provider config field.
This guide shows how to use DefaultAzureCredential from the Azure Identity SDK to authenticate with Azure AI Foundry models through the Copilot SDK.
How It Works
diff --git a/doc/api/byok.html b/doc/api/byok.html
index 552dcd1..da90144 100644
--- a/doc/api/byok.html
+++ b/doc/api/byok.html
@@ -1,6 +1,6 @@
-BYOK (Bring Your Own Key) Generated by Codox
BYOK (Bring Your Own Key)
+BYOK (Bring Your Own Key) Generated by Codox
BYOK (Bring Your Own Key)
BYOK allows you to use the Copilot SDK with your own API keys from model providers, bypassing GitHub Copilot authentication. This is useful for enterprise deployments, custom model hosting, or when you want direct billing with your model provider.
Supported Providers
diff --git a/doc/api/codegen.html b/doc/api/codegen.html
index e3f37fa..501fd85 100644
--- a/doc/api/codegen.html
+++ b/doc/api/codegen.html
@@ -1,6 +1,6 @@
-Schema-Driven Code Generation Generated by Codox
Schema-Driven Code Generation
+Schema-Driven Code Generation Generated by Codox
Schema-Driven Code Generation
The Clojure SDK generates portions of its clojure.spec registry from the JSON Schemas distributed with the Copilot CLI instead of maintaining them by hand. This guarantees the SDK’s view of the wire protocol cannot drift from what the Copilot CLI actually emits.
What is generated
Source files under src/github/copilot_sdk/generated/ are produced by the generator in script/codegen/. Currently:
diff --git a/doc/api/custom-agents.html b/doc/api/custom-agents.html
index d1b52c4..b62718c 100644
--- a/doc/api/custom-agents.html
+++ b/doc/api/custom-agents.html
@@ -1,6 +1,6 @@
-Custom Agents & Sub-Agent Orchestration Generated by Codox
Custom Agents & Sub-Agent Orchestration
+Custom Agents & Sub-Agent Orchestration Generated by Codox
Custom Agents & Sub-Agent Orchestration
Define specialized agents with scoped tools and prompts, then let Copilot orchestrate them as sub-agents within a single session.
Overview
Custom agents are lightweight agent definitions attached to a session. Each agent has its own system prompt, tool restrictions, and optional MCP servers. When a user’s request matches an agent’s expertise, the Copilot runtime automatically delegates to that agent as a sub-agent — running it in an isolated context while streaming lifecycle events back to the parent session.
diff --git a/doc/api/debugging.html b/doc/api/debugging.html
index 8a81436..ea1e64f 100644
--- a/doc/api/debugging.html
+++ b/doc/api/debugging.html
@@ -1,6 +1,6 @@
-MCP Server Debugging Guide Generated by Codox
MCP Server Debugging Guide
+MCP Server Debugging Guide Generated by Codox
MCP Server Debugging Guide
This guide covers debugging techniques specific to MCP (Model Context Protocol) servers when using the Copilot SDK for Clojure.
Quick Diagnostics
Checklist
diff --git a/doc/api/doc-auth-index.html b/doc/api/doc-auth-index.html
index 6199ea4..ac93da5 100644
--- a/doc/api/doc-auth-index.html
+++ b/doc/api/doc-auth-index.html
@@ -1,6 +1,6 @@
-Authentication Generated by Codox
Authentication
+Authentication Generated by Codox
Authentication
The Copilot SDK for Clojure supports multiple authentication methods. Choose the method that best matches your deployment scenario.
Authentication Methods
diff --git a/doc/api/doc-index.html b/doc/api/doc-index.html
index 73deaf6..ecbe614 100644
--- a/doc/api/doc-index.html
+++ b/doc/api/doc-index.html
@@ -1,6 +1,6 @@
-Documentation Generated by Codox
Documentation
+Documentation Generated by Codox
Documentation
Clojure SDK for programmatic control of the GitHub Copilot CLI via JSON-RPC.
Getting Started
Architecture Decisions
+Dynamic Workflows Generated by Codox
Dynamic Workflows
+Dynamic Workflows Generated by Codox
Dynamic Workflows
Experimental. This API is not covered by GA semver guarantees. The wire protocol and API surface may change without a major version bump.
diff --git a/doc/api/getting-started.html b/doc/api/getting-started.html
index bfd6b2a..a3ab22c 100644
--- a/doc/api/getting-started.html
+++ b/doc/api/getting-started.html
@@ -1,6 +1,6 @@
-Getting Started with the Copilot SDK for Clojure Generated by Codox
Getting Started with the Copilot SDK for Clojure
+Getting Started with the Copilot SDK for Clojure Generated by Codox
Getting Started with the Copilot SDK for Clojure
Note: Version 1.0.0.0 is the first generally available (GA) release (tracking upstream github/copilot-sdk v1.0.0). The public API is stable. Subsequent releases follow the upstream versioning scheme (see Versioning); any breaking changes are called out in the CHANGELOG.
diff --git a/doc/api/github.copilot-sdk.client.html b/doc/api/github.copilot-sdk.client.html
index 61c7479..17094bb 100644
--- a/doc/api/github.copilot-sdk.client.html
+++ b/doc/api/github.copilot-sdk.client.html
@@ -1,6 +1,6 @@
-github.copilot-sdk.client documentation Generated by Codox
github.copilot-sdk.client
CopilotClient - manages connection to the Copilot CLI server.
+github.copilot-sdk.client documentation Generated by Codox
github.copilot-sdk.client
CopilotClient - manages connection to the Copilot CLI server.
<create-session
(<create-session client config)Async version of create-session. Returns a channel that delivers a CopilotSession.
Same config options as create-session (:on-permission-request is optional since upstream PR #1308). Configuration validation, connection setup, and local preparation are performed synchronously. For every path whose session id is known before the RPC, this includes construction of the session filesystem handler. Failures in those steps throw before a result channel is returned. A cloud create without a caller-supplied session id defers filesystem-handler construction until the server returns the id, so that failure is delivered on the channel. The RPC call parks instead of blocking, making the returned channel safe to consume inside go blocks.
On RPC or later setup error, delivers an ExceptionInfo to the channel (not nil). Callers should check the result with (instance? Throwable result).
diff --git a/doc/api/github.copilot-sdk.generated.coerce.html b/doc/api/github.copilot-sdk.generated.coerce.html
index 0e12e3a..278bd0c 100644
--- a/doc/api/github.copilot-sdk.generated.coerce.html
+++ b/doc/api/github.copilot-sdk.generated.coerce.html
@@ -1,6 +1,6 @@
-github.copilot-sdk.generated.coerce documentation Generated by Codox
github.copilot-sdk.generated.coerce
AUTO-GENERATED — do not edit. Run bb codegen.
+github.copilot-sdk.generated.coerce documentation Generated by Codox
github.copilot-sdk.generated.coerce
AUTO-GENERATED — do not edit. Run bb codegen.
Per-event-type coercion between the upstream wire shape and the Clojure-idiomatic public API. Source: script/codegen/coercions.edn
attachment-type-keyword->string
(attachment-type-keyword->string v)Convert an idiomatic attachment discriminator to its closed wire string domain.
attachment-type-keywords->strings
(attachment-type-keywords->strings attachments)Convert attachment discriminator keywords within a collection to wire strings.
diff --git a/doc/api/github.copilot-sdk.generated.event-metadata.html b/doc/api/github.copilot-sdk.generated.event-metadata.html
index 8804be6..d5d4585 100644
--- a/doc/api/github.copilot-sdk.generated.event-metadata.html
+++ b/doc/api/github.copilot-sdk.generated.event-metadata.html
@@ -1,6 +1,6 @@
-github.copilot-sdk.generated.event-metadata documentation Generated by Codox
github.copilot-sdk.generated.event-metadata
AUTO-GENERATED event normalization metadata.
+github.copilot-sdk.generated.event-metadata documentation Generated by Codox
github.copilot-sdk.generated.event-metadata
AUTO-GENERATED event normalization metadata.
Source: schemas/session-events.schema.json
opaque-json-paths
Event-type -> raw/idiom paths whose JSON key spelling is opaque.
\ No newline at end of file
diff --git a/doc/api/github.copilot-sdk.generated.event-specs.html b/doc/api/github.copilot-sdk.generated.event-specs.html
index a8c3eba..5076615 100644
--- a/doc/api/github.copilot-sdk.generated.event-specs.html
+++ b/doc/api/github.copilot-sdk.generated.event-specs.html
@@ -1,6 +1,6 @@
-github.copilot-sdk.generated.event-specs documentation Generated by Codox
github.copilot-sdk.generated.event-specs
AUTO-GENERATED. clojure.spec definitions for upstream session events.
+github.copilot-sdk.generated.event-specs documentation Generated by Codox
github.copilot-sdk.generated.event-specs
AUTO-GENERATED. clojure.spec definitions for upstream session events.
Each event variant’s data payload is registered under ::<event-type>-data (e.g. ::session.start-data). The envelope (id/timestamp/parentId/type/data) is registered under ::<event-type> (e.g. ::session.start).
Nested $ref’d object definitions (reached via properties on the above) are registered once each under ::<definition>-shape (e.g. ::assistant-message-tool-request-caller-shape). Oversized shapes compose internal spec keywords in the .shape-parts namespace. These are entries in this file, not namespaces to require; explanations retain both the part identifier and the failing property.
Source: schemas/session-events.schema.json
diff --git a/doc/api/github.copilot-sdk.helpers.html b/doc/api/github.copilot-sdk.helpers.html
index 30126ed..a168aed 100644
--- a/doc/api/github.copilot-sdk.helpers.html
+++ b/doc/api/github.copilot-sdk.helpers.html
@@ -1,6 +1,6 @@
-github.copilot-sdk.helpers documentation Generated by Codox
github.copilot-sdk.helpers
Convenience functions for simple, stateless queries to Copilot.
+github.copilot-sdk.helpers documentation Generated by Codox
github.copilot-sdk.helpers
Convenience functions for simple, stateless queries to Copilot.
This namespace provides a higher-level API inspired by Claude Agent SDK’s query() function. It manages a shared client internally to avoid CLI startup overhead across multiple queries.
Quick Start
(require '[github.copilot-sdk.helpers :as h])
diff --git a/doc/api/github.copilot-sdk.html b/doc/api/github.copilot-sdk.html
index c1af960..e14daca 100644
--- a/doc/api/github.copilot-sdk.html
+++ b/doc/api/github.copilot-sdk.html
@@ -1,6 +1,6 @@
-github.copilot-sdk documentation Generated by Codox
github.copilot-sdk
Clojure SDK for programmatic control of GitHub Copilot CLI via JSON-RPC.
+github.copilot-sdk documentation Generated by Codox
github.copilot-sdk
Clojure SDK for programmatic control of GitHub Copilot CLI via JSON-RPC.
Quick Start:
(require '[github.copilot-sdk :as copilot])
diff --git a/doc/api/github.copilot-sdk.instrument.html b/doc/api/github.copilot-sdk.instrument.html
index 14599bb..397f37a 100644
--- a/doc/api/github.copilot-sdk.instrument.html
+++ b/doc/api/github.copilot-sdk.instrument.html
@@ -1,6 +1,6 @@
-github.copilot-sdk.instrument documentation Generated by Codox
github.copilot-sdk.instrument
Spec instrumentation for development/testing.
+github.copilot-sdk.instrument documentation Generated by Codox
github.copilot-sdk.instrument
Spec instrumentation for development/testing.
Require this namespace to enable spec checking on public API functions. This adds runtime validation which is useful during development but may impact performance in production.
Usage: (require ’github.copilot-sdk.instrument) ;; Now all public API calls are spec-checked
To disable: (require ’clojure.spec.test.alpha :as stest) (stest/unstrument)
diff --git a/doc/api/github.copilot-sdk.logging.html b/doc/api/github.copilot-sdk.logging.html
index 0e7c540..7cb9987 100644
--- a/doc/api/github.copilot-sdk.logging.html
+++ b/doc/api/github.copilot-sdk.logging.html
@@ -1,6 +1,6 @@
-github.copilot-sdk.logging documentation Generated by Codox
github.copilot-sdk.logging
Logging facade for the Copilot SDK using clojure.tools.logging.
+github.copilot-sdk.logging documentation Generated by Codox
github.copilot-sdk.logging
Logging facade for the Copilot SDK using clojure.tools.logging.
This wraps clojure.tools.logging to provide SDK-specific defaults. Configure logging via your preferred SLF4J backend (logback, log4j2, etc.).
debug
macro
(debug & args)Log a debug message. A leading Throwable is attached to the log event.
error
macro
(error & args)Log an error message. A leading Throwable is attached to the log event.
diff --git a/doc/api/github.copilot-sdk.process.html b/doc/api/github.copilot-sdk.process.html
index 79ebdf1..acaec4a 100644
--- a/doc/api/github.copilot-sdk.process.html
+++ b/doc/api/github.copilot-sdk.process.html
@@ -1,6 +1,6 @@
-github.copilot-sdk.process documentation Generated by Codox
github.copilot-sdk.process
Process management for spawning and managing the Copilot CLI.
+github.copilot-sdk.process documentation Generated by Codox
github.copilot-sdk.process
Process management for spawning and managing the Copilot CLI.
alive?
(alive? mp)Check if process is still running.
cli-env-overrides
(cli-env-overrides {:keys [github-token telemetry copilot-home tcp-connection-token mode], :as _opts})Compute the environment variable contract the SDK applies to the spawned CLI.
Returns a map with two entries: - :defaults — env-var → value-or-nil applied before user-provided :env so the user can override them. Currently just {"NODE_DEBUG" nil} (default: strip NODE_DEBUG to avoid polluting stdout, but a user can re-enable it via :env). - :overrides — env-var → value-or-nil applied after user-provided :env so explicit SDK options win over stale env (e.g. an explicit :github-token must beat a COPILOT_SDK_AUTH_TOKEN coming from :env).
diff --git a/doc/api/github.copilot-sdk.protocol.html b/doc/api/github.copilot-sdk.protocol.html
index 297f103..0c7f871 100644
--- a/doc/api/github.copilot-sdk.protocol.html
+++ b/doc/api/github.copilot-sdk.protocol.html
@@ -1,6 +1,6 @@
-github.copilot-sdk.protocol documentation Generated by Codox
github.copilot-sdk.protocol
JSON-RPC 2.0 protocol implementation using java.nio channels.
+github.copilot-sdk.protocol documentation Generated by Codox
github.copilot-sdk.protocol
JSON-RPC 2.0 protocol implementation using java.nio channels.
Architecture: - NIO channels for interruptible I/O (clean shutdown) - core.async channels for message flow - Single reader thread resolves responses and queues notifications - Notification dispatcher drains accepted messages before closing incoming-ch on EOF - Writer go-loop takes from outgoing-ch - Reverse requests run on a bounded worker pool owned by the connection - State is managed externally (passed in as atom)
This design allows clean shutdown: closing NIO channels causes reader to throw AsynchronousCloseException and exit gracefully.
connect
(connect in out state-atom)Create a JSON-RPC connection from input/output streams. Uses NIO channels for interruptible I/O.
diff --git a/doc/api/github.copilot-sdk.session.html b/doc/api/github.copilot-sdk.session.html
index 3f99fcd..aa6effb 100644
--- a/doc/api/github.copilot-sdk.session.html
+++ b/doc/api/github.copilot-sdk.session.html
@@ -1,6 +1,6 @@
-github.copilot-sdk.session documentation Generated by Codox
github.copilot-sdk.session
CopilotSession - session operations using centralized client state.
+github.copilot-sdk.session documentation Generated by Codox
github.copilot-sdk.session
CopilotSession - session operations using centralized client state.
All session state is stored in the client’s :state atom under: - :sessions session-id -> {:tool-handlers {} :permission-handler nil :destroyed? false :workspace-path nil} - :session-io session-id -> {:event-chan :event-mult :send-lock :shutdown-chan :async-send-state}
Functions take client + session-id, accessing state through the client.
<handle-pending-permission-request!
(<handle-pending-permission-request! session opts)core.async variant of handle-pending-permission-request!. Returns a channel.
@@ -60,8 +60,8 @@
handle-exit-plan-mode-request!
(handle-exit-plan-mode-request! client session-id request)Handle an incoming exitPlanMode.request RPC (upstream PR #1228). The server asks the client whether to exit plan mode. Calls the session’s :exit-plan-mode-handler with (request, {:session-id ...}). If the handler returns a channel, awaits its value. Returns a channel with a wire-shaped response wrapped in {:result …} or {:error …}.
Default behavior (no handler): {:result {:approved true}}. Handler must return an idiomatic map containing :approved? (required boolean), optional :selected-action (string), :feedback (string). If the handler result is malformed (non-map, missing :approved?, or :approved? is not a boolean), a warning is logged and the response falls back to {:result {:approved true}} (matching the no-handler default). Exceptions thrown by the handler are converted to {:error {:code -32603 :message …}}.
handle-hooks-invoke!
(handle-hooks-invoke! client session-id hook-type input)Handle an incoming hooks invocation. Returns a channel with the result. PR #269 feature.
-handle-mcp-auth-request!
(handle-mcp-auth-request! client session-id request)Handle an mcp.oauth_required MCP OAuth request (upstream PR #1669). Returns a channel yielding the wire result map for session.mcp.oauth.handlePendingRequest.
-The configured :on-mcp-auth-request handler is invoked with the idiomatic McpAuthRequest map (the event data — {:request-id :server-name :server-url :reason …}) and a context map {:session-id …}; it may return a channel. A result carrying :access-token answers with a token; nil, {:kind :cancelled}, or a thrown exception cancels the request (matching upstream’s error-swallowing behavior, so a transient handler failure never wedges the pending request).
+handle-mcp-auth-request!
(handle-mcp-auth-request! client session-id request)Handle an mcp.oauth_required MCP OAuth request. Returns a channel yielding the wire result map for session.mcp.oauth.handlePendingRequest.
+The configured :on-mcp-auth-request handler is invoked with the idiomatic McpAuthRequest map (the event data — {:request-id :server-name :server-url :reason …}) and a context map {:session-id …}; it may return a channel. Explicit {:kind :cancelled} takes precedence over any token. Otherwise a nonempty string :access-token answers with a token, including bare-token maps. {:kind :runtime-refresh} hands renewal to the runtime only when :runtime-refresh-supported is true on the request. Omitted or false support cancels that handoff; nil, malformed results, and handler errors also cancel. Handoff acceptance is not completion: observe mcp.oauth_recovery_completed for the terminal outcome, including reconnect.
handle-pending-permission-request!
(handle-pending-permission-request! session {:keys [request-id result], :as opts})Manually resolve a pending permission request (upstream PR #1308).
Use this when no :on-permission-request handler was registered and the runtime has emitted a :copilot/permission.requested event. The consumer reads the :request-id from (:data event) and supplies a permission decision in :result.
Options map keys: - :request-id - The :request-id from the permission.requested event (required) - :result - Permission decision map with :kind, matching the upstream PermissionDecision union. Allowed kinds: :approve-once, :approve-for-session, :approve-for-location, :approve-permanently, :reject, :user-not-available. :no-result is not supported here — to decline answering, simply don’t call this function.
diff --git a/doc/api/github.copilot-sdk.specs.html b/doc/api/github.copilot-sdk.specs.html
index c1668e5..81f5502 100644
--- a/doc/api/github.copilot-sdk.specs.html
+++ b/doc/api/github.copilot-sdk.specs.html
@@ -1,6 +1,6 @@
-github.copilot-sdk.specs documentation Generated by Codox
github.copilot-sdk.specs
Clojure specs for Copilot SDK data structures.
+github.copilot-sdk.specs documentation Generated by Codox
github.copilot-sdk.specs
Clojure specs for Copilot SDK data structures.
client-options-keys
session-config-keys
system-message-sections
Alias for system-prompt-sections matching the upstream SYSTEM_MESSAGE_SECTIONS name (upstream PR #1377).
system-prompt-sections
Known system message section identifiers for the customize mode. Each section corresponds to a distinct part of the system message. Upstream alias: SystemMessageSection.
unknown-keys
(unknown-keys m allowed-keys)Returns the set of unknown keys in a map, given the allowed keys.
diff --git a/doc/api/github.copilot-sdk.teardown.html b/doc/api/github.copilot-sdk.teardown.html
index adc8e94..7d4821c 100644
--- a/doc/api/github.copilot-sdk.teardown.html
+++ b/doc/api/github.copilot-sdk.teardown.html
@@ -1,6 +1,6 @@
-github.copilot-sdk.teardown documentation Generated by Codox
github.copilot-sdk.teardown
One teardown-outcome contract shared by the client, protocol, and process layers.
+github.copilot-sdk.teardown documentation Generated by Codox
github.copilot-sdk.teardown
One teardown-outcome contract shared by the client, protocol, and process layers.
Closing a socket, closing an NIO channel, and joining a finished thread are idempotent by contract: they do not throw when the resource is already gone. A teardown step that does throw is therefore either an interruption of the calling thread or a genuine failure that left the resource live. Collapsing both into (catch Exception _) is what makes a leaked resource invisible.
attempt keeps the two apart: expected outcomes are silent, unexpected ones become an ex-info carrying the operation and resource identity so the caller can return or log it. Nothing is propagated, so a failing step cannot short-circuit the steps that follow it.
attach-cleanup-failures!
(attach-cleanup-failures! primary cleanup-failures)Attach cleanup failures to primary and log each retained failure.
diff --git a/doc/api/github.copilot-sdk.tool-set.html b/doc/api/github.copilot-sdk.tool-set.html
index 5293f34..9c03983 100644
--- a/doc/api/github.copilot-sdk.tool-set.html
+++ b/doc/api/github.copilot-sdk.tool-set.html
@@ -1,6 +1,6 @@
-github.copilot-sdk.tool-set documentation Generated by Codox
github.copilot-sdk.tool-set
Helpers for building source-qualified tool filter patterns used by :available-tools and :excluded-tools in session configs.
+github.copilot-sdk.tool-set documentation Generated by Codox
github.copilot-sdk.tool-set
Helpers for building source-qualified tool filter patterns used by :available-tools and :excluded-tools in session configs.
The runtime matches each tool reference against patterns of the form "<source>:<name>" where source is one of builtin, mcp, or custom and name is either a literal tool name or the wildcard "*". The bare wildcard "*" (no source) is intentionally rejected by the SDK — apps must explicitly opt into a source so an absent source can never silently grant access to unexpected tools.
Mirrors upstream ToolSet and BuiltInTools from nodejs/src/toolSet.ts (upstream PR #1428).
Examples:
diff --git a/doc/api/github.copilot-sdk.tools.html b/doc/api/github.copilot-sdk.tools.html
index 72f17fb..6fb5583 100644
--- a/doc/api/github.copilot-sdk.tools.html
+++ b/doc/api/github.copilot-sdk.tools.html
@@ -1,6 +1,6 @@
-github.copilot-sdk.tools documentation Generated by Codox
github.copilot-sdk.tools
Helper functions for defining tools.
+github.copilot-sdk.tools documentation Generated by Codox
github.copilot-sdk.tools
Helper functions for defining tools.
convert-mcp-call-tool-result
(convert-mcp-call-tool-result {:keys [content is-error]})Convert an MCP CallToolResult into the SDK’s ToolResultObject format.
The input map should have Clojure-idiomatic keys: - :content - vector of content blocks, each with :type and type-specific fields - :is-error - optional boolean, when true the result-type is “failure”
Content block types: - {:type “text” :text “…”} - {:type “image” :data “base64…” :mime-type “image/png”} - {:type “resource” :resource {:uri “…” :text “…” :blob “…” :mime-type “…”}}
diff --git a/doc/api/github.copilot-sdk.util.html b/doc/api/github.copilot-sdk.util.html
index 67a2ed5..6904d93 100644
--- a/doc/api/github.copilot-sdk.util.html
+++ b/doc/api/github.copilot-sdk.util.html
@@ -1,6 +1,6 @@
-github.copilot-sdk.util documentation Generated by Codox
github.copilot-sdk.util
Utility functions for the Copilot SDK.
+github.copilot-sdk.util documentation Generated by Codox
github.copilot-sdk.util
Utility functions for the Copilot SDK.
->clj-keys
(->clj-keys m)Convert map keys from camelCase to kebab-case for Clojure idiom. Works recursively on nested maps. Non-keyword keys are preserved.
->wire-keys
(->wire-keys m)Convert map keys from kebab-case to camelCase for wire format. Works recursively on nested maps. Non-keyword keys are preserved.
attachment->wire
(attachment->wire att)Convert an attachment from Clojure format to wire format. Handles the special mapping for selection attachments where :file-path -> filePath and :selection-range -> selection.
diff --git a/doc/api/github.copilot-sdk.workflow.html b/doc/api/github.copilot-sdk.workflow.html
index 78659f9..25f11ec 100644
--- a/doc/api/github.copilot-sdk.workflow.html
+++ b/doc/api/github.copilot-sdk.workflow.html
@@ -1,6 +1,6 @@
-github.copilot-sdk.workflow documentation Generated by Codox
github.copilot-sdk.workflow