From a1a8836e7ad96aa1a4259bfdae9787ad16edfa27 Mon Sep 17 00:00:00 2001 From: Karl Krukow Date: Mon, 18 May 2026 08:23:33 +0200 Subject: [PATCH 01/10] feat(custom-agents): add :agent-model field (upstream PR #1309) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add optional :agent-model to entries in :custom-agents. When set, the runtime tries to use that model for the agent, falling back to the parent session model if unavailable. Wire conversion goes through util/clj->wire automatically: :agent-model becomes :agentModel on the wire, sent on both session.create and session.resume custom-agents entries — consistent with the existing :agent-name / :agent-display-name / :agent-skills convention. Upstream parity: matches the new model?: string field added to CustomAgentConfig in nodejs/src/types.ts (upstream commit d0eb531e, PR #1309). No other upstream changes since v1.0.0-beta.4 require porting: - #1295 (remote_session) was already shipped in CLI 1.0.48 sync (PR #103) - E2E test stabilization commits affect upstream test fixtures only - CLI version bumps (1.0.49-*) are prerelease; we stay pinned to 1.0.48 Tests: 3 new integration tests (spec validation, wire payload on session.create/resume, omission when not set). Full suite: 257 tests, 1203 assertions, 0 failures. bb ci:full passes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CHANGELOG.md | 8 +++ doc/reference/API.md | 2 +- src/github/copilot_sdk/specs.clj | 6 ++- test/github/copilot_sdk/integration_test.clj | 51 ++++++++++++++++++++ 4 files changed, 65 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2daeefe..0918531 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,14 @@ All notable changes to this project will be documented in this file. This change ## [Unreleased] +### Added (post-v1.0.0-beta.4 sync) +- **`:agent-model` on custom-agent configs** — Custom agent maps in + `:custom-agents` now accept an optional `:agent-model` string (e.g. + `"claude-haiku-4.5"`). When set, the runtime attempts to use that model + for the agent, falling back to the parent session model if unavailable. + Forwarded on the wire as `agentModel` on each entry in `customAgents` + for both `session.create` and `session.resume`. (upstream PR #1309) + ### Notes (v1.0.0-beta.4 sync) Upstream `v1.0.0-beta.4` shipped no new Node.js SDK API surface relative to `v1.0.0-beta.3` — every SDK-visible change in the upstream diff diff --git a/doc/reference/API.md b/doc/reference/API.md index fafa972..73df036 100644 --- a/doc/reference/API.md +++ b/doc/reference/API.md @@ -243,7 +243,7 @@ Create a client and session together, ensuring both are cleaned up on exit. | `:provider` | map | Provider config for BYOK (see [BYOK docs](../auth/byok.md)). Required key: `:base-url`. Optional: `:provider-type` (`:openai`/`:azure`/`:anthropic`), `:wire-api` (`:completions`/`:responses`), `:api-key`, `:bearer-token`, `:azure-options`, `:headers` (map of HTTP header name→value, sent with each provider request — upstream PR #1094), `:model-id` (string — the model identifier to send to the provider; overrides session `:model`), `:wire-model` (string — model name as sent on the provider wire when it differs from `:model-id`), `:max-input-tokens` (integer — input/prompt token cap; serialized as wire `maxPromptTokens`), `:max-output-tokens` (integer — output token cap). The four override fields were added in upstream PR #966 | | `:mcp-servers` | map | MCP server configs keyed by server ID (see [MCP docs](../mcp/overview.md)). Local (stdio) servers: `:mcp-command`, `:mcp-args`, `:mcp-tools`. Remote (HTTP/SSE) servers: `:mcp-server-type` (`:http`/`:sse`), `:mcp-url`, `:mcp-tools`. Spec aliases: `::mcp-stdio-server` = `::mcp-local-server`, `::mcp-http-server` = `::mcp-remote-server` | | `:commands` | vector | Command definitions (slash commands). See [Commands](#commands) | -| `:custom-agents` | vector | Custom agent configs. Each agent map: `:agent-name` (required), `:agent-prompt` (required), `:agent-display-name`, `:agent-description`, `:agent-tools`, `:agent-infer?`, `:agent-skills` (vector of strings), `:mcp-servers` | +| `:custom-agents` | vector | Custom agent configs. Each agent map: `:agent-name` (required), `:agent-prompt` (required), `:agent-display-name`, `:agent-description`, `:agent-tools`, `:agent-infer?`, `:agent-skills` (vector of strings), `:agent-model` (string, e.g. `"claude-haiku-4.5"`; when set the runtime tries this model for the agent, falling back to the parent session model — upstream PR #1309), `:mcp-servers` | | `:default-agent` | map | Built-in/default agent config. Use `{:excluded-tools [...]}` to hide tools from the default agent while leaving them available to custom agents | | `:on-permission-request` | fn | **Required.** Permission handler function. Use `copilot/approve-all` to approve everything. | | `:streaming?` | boolean | Enable streaming deltas | diff --git a/src/github/copilot_sdk/specs.clj b/src/github/copilot_sdk/specs.clj index bf74734..368e3d9 100644 --- a/src/github/copilot_sdk/specs.clj +++ b/src/github/copilot_sdk/specs.clj @@ -274,11 +274,15 @@ (s/def ::agent-prompt ::non-blank-string) (s/def ::agent-infer? boolean?) (s/def ::agent-skills (s/coll-of string?)) +;; Model identifier for the agent (e.g. "claude-haiku-4.5"). When set, the +;; runtime will attempt to use this model for the agent, falling back to the +;; parent session model if unavailable. Upstream PR #1309. +(s/def ::agent-model ::non-blank-string) (s/def ::custom-agent (s/keys :req-un [::agent-name ::agent-prompt] :opt-un [::agent-display-name ::agent-description ::agent-tools - ::mcp-servers ::agent-infer? ::agent-skills])) + ::mcp-servers ::agent-infer? ::agent-skills ::agent-model])) (s/def ::custom-agents (s/coll-of ::custom-agent)) diff --git a/test/github/copilot_sdk/integration_test.clj b/test/github/copilot_sdk/integration_test.clj index 3461004..723a814 100644 --- a/test/github/copilot_sdk/integration_test.clj +++ b/test/github/copilot_sdk/integration_test.clj @@ -3356,6 +3356,57 @@ agent (first (:customAgents create-params))] (is (= ["my-skill"] (:agentSkills agent)))))) +;; --- Per-agent model field (upstream PR #1309) ------------------------------ + +(deftest test-custom-agent-model-spec + (testing "::custom-agent spec accepts optional :agent-model field" + (is (s/valid? :github.copilot-sdk.specs/custom-agent + {:agent-name "test" :agent-prompt "You are helpful"})) + (is (s/valid? :github.copilot-sdk.specs/custom-agent + {:agent-name "test" :agent-prompt "You are helpful" + :agent-model "claude-haiku-4.5"})) + (is (not (s/valid? :github.copilot-sdk.specs/custom-agent + {:agent-name "test" :agent-prompt "You are helpful" + :agent-model 42})) + ":agent-model must be a string when provided"))) + +(deftest test-custom-agent-model-on-wire + (testing "model field is sent on wire in session.create and session.resume (upstream PR #1309)" + (let [seen (atom {}) + _ (mock/set-request-hook! *mock-server* (fn [method params] + (when (#{"session.create" "session.resume"} method) + (swap! seen assoc method params)))) + _ (sdk/create-session *test-client* + {:on-permission-request sdk/approve-all + :custom-agents [{:agent-name "haiku-agent" + :agent-prompt "Hello" + :agent-model "claude-haiku-4.5"}]}) + session-id (sdk/get-last-session-id *test-client*) + _ (sdk/resume-session *test-client* session-id + {:on-permission-request sdk/approve-all + :custom-agents [{:agent-name "haiku-agent-2" + :agent-prompt "Hi" + :agent-model "gpt-5.4"}]}) + create-params (get @seen "session.create") + resume-params (get @seen "session.resume")] + (is (= "claude-haiku-4.5" + (get-in create-params [:customAgents 0 :agentModel]))) + (is (= "gpt-5.4" + (get-in resume-params [:customAgents 0 :agentModel])))))) + +(deftest test-custom-agent-model-omitted-when-not-set + (testing ":agent-model is omitted from wire when not provided" + (let [seen (atom {}) + _ (mock/set-request-hook! *mock-server* (fn [method params] + (when (#{"session.create"} method) + (swap! seen assoc method params)))) + _ (sdk/create-session *test-client* + {:on-permission-request sdk/approve-all + :custom-agents [{:agent-name "no-model" + :agent-prompt "Hi"}]}) + agent (first (get-in @seen ["session.create" :customAgents]))] + (is (not (contains? agent :agentModel)))))) + ;; --- Default agent config (upstream PR #1098) -------------------------------- (deftest test-default-agent-excluded-tools-on-wire From 96376739e5a0409bd0cc05b5c2a8e96bd19d0b55 Mon Sep 17 00:00:00 2001 From: Karl Krukow Date: Tue, 19 May 2026 10:14:09 +0200 Subject: [PATCH 02/10] chore(schema): bump to 1.0.49-1 Regenerate wire specs and coercions for upstream PRs #1305, #1307. New pass-through event fields: :display-prompt, :reasoning-summary, :previous-reasoning-summary. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .copilot-schema-version | 2 +- schemas/README.md | 2 +- schemas/api.schema.json | 1252 +++++++++++++---- schemas/session-events.schema.json | 933 ++++++++---- .../copilot_sdk/generated/event_specs.clj | 36 +- 5 files changed, 1641 insertions(+), 584 deletions(-) diff --git a/.copilot-schema-version b/.copilot-schema-version index 56d0dad..a700f32 100644 --- a/.copilot-schema-version +++ b/.copilot-schema-version @@ -1 +1 @@ -1.0.48 +1.0.49-1 diff --git a/schemas/README.md b/schemas/README.md index b239b19..49b68f1 100644 --- a/schemas/README.md +++ b/schemas/README.md @@ -4,4 +4,4 @@ These files are fetched verbatim from the `@github/copilot` npm package at the v **Do not edit by hand.** To update, run `bb schemas:fetch` after bumping `.copilot-schema-version`. -Currently pinned version: `1.0.48` +Currently pinned version: `1.0.49-1` diff --git a/schemas/api.schema.json b/schemas/api.schema.json index 30250b9..7e23234 100644 --- a/schemas/api.schema.json +++ b/schemas/api.schema.json @@ -5,53 +5,68 @@ "server": { "ping": { "rpcMethod": "ping", + "description": "Checks server responsiveness and returns protocol information.", "params": { - "$ref": "#/definitions/PingRequest" + "$ref": "#/definitions/PingRequest", + "description": "Optional message to echo back to the caller." }, "result": { - "$ref": "#/definitions/PingResult" + "$ref": "#/definitions/PingResult", + "description": "Server liveness response, including the echoed message, current timestamp, and protocol version." } }, "connect": { "rpcMethod": "connect", + "description": "Performs the SDK server connection handshake and validates the optional connection token.", "params": { - "$ref": "#/definitions/ConnectRequest" + "$ref": "#/definitions/ConnectRequest", + "description": "Optional connection token presented by the SDK client during the handshake." }, "result": { - "$ref": "#/definitions/ConnectResult" + "$ref": "#/definitions/ConnectResult", + "description": "Handshake result reporting the server's protocol version and package version on success." }, "visibility": "internal" }, "models": { "list": { "rpcMethod": "models.list", + "description": "Lists Copilot models available to the authenticated user.", "params": { - "$ref": "#/definitions/ModelsListRequest" + "$ref": "#/definitions/ModelsListRequest", + "description": "Optional GitHub token used to list models for a specific user instead of the global auth context." }, "result": { - "$ref": "#/definitions/ModelList" + "$ref": "#/definitions/ModelList", + "description": "List of Copilot models available to the resolved user, including capabilities and billing metadata." } } }, "tools": { "list": { "rpcMethod": "tools.list", + "description": "Lists built-in tools available for a model.", "params": { - "$ref": "#/definitions/ToolsListRequest" + "$ref": "#/definitions/ToolsListRequest", + "description": "Optional model identifier whose tool overrides should be applied to the listing." }, "result": { - "$ref": "#/definitions/ToolList" + "$ref": "#/definitions/ToolList", + "description": "Built-in tools available for the requested model, with their parameters and instructions." } } }, "account": { "getQuota": { "rpcMethod": "account.getQuota", + "description": "Gets Copilot quota usage for the authenticated user or supplied GitHub token.", "params": { - "$ref": "#/definitions/AccountGetQuotaRequest" + "$ref": "#/definitions/AccountGetQuotaRequest", + "description": "Optional GitHub token used to look up quota for a specific user instead of the global auth context." }, "result": { - "$ref": "#/definitions/AccountGetQuotaResult" + "$ref": "#/definitions/AccountGetQuotaResult", + "description": "Quota usage snapshots for the resolved user, keyed by quota type." } } }, @@ -59,69 +74,79 @@ "config": { "list": { "rpcMethod": "mcp.config.list", + "description": "Lists MCP servers from user configuration.", "params": null, "result": { - "$ref": "#/definitions/McpConfigList" + "$ref": "#/definitions/McpConfigList", + "description": "User-configured MCP servers, keyed by server name." } }, "add": { "rpcMethod": "mcp.config.add", + "description": "Adds an MCP server to user configuration.", "params": { - "$ref": "#/definitions/McpConfigAddRequest" + "$ref": "#/definitions/McpConfigAddRequest", + "description": "MCP server name and configuration to add to user configuration." }, "result": { - "type": "null", - "title": "McpConfigAddResult" + "type": "null" } }, "update": { "rpcMethod": "mcp.config.update", + "description": "Updates an MCP server in user configuration.", "params": { - "$ref": "#/definitions/McpConfigUpdateRequest" + "$ref": "#/definitions/McpConfigUpdateRequest", + "description": "MCP server name and replacement configuration to write to user configuration." }, "result": { - "type": "null", - "title": "McpConfigUpdateResult" + "type": "null" } }, "remove": { "rpcMethod": "mcp.config.remove", + "description": "Removes an MCP server from user configuration.", "params": { - "$ref": "#/definitions/McpConfigRemoveRequest" + "$ref": "#/definitions/McpConfigRemoveRequest", + "description": "MCP server name to remove from user configuration." }, "result": { - "type": "null", - "title": "McpConfigRemoveResult" + "type": "null" } }, "enable": { "rpcMethod": "mcp.config.enable", + "description": "Enables MCP servers in user configuration for new sessions.", "params": { - "$ref": "#/definitions/McpConfigEnableRequest" + "$ref": "#/definitions/McpConfigEnableRequest", + "description": "MCP server names to enable for new sessions." }, "result": { - "type": "null", - "title": "McpConfigEnableResult" + "type": "null" } }, "disable": { "rpcMethod": "mcp.config.disable", + "description": "Disables MCP servers in user configuration for new sessions.", "params": { - "$ref": "#/definitions/McpConfigDisableRequest" + "$ref": "#/definitions/McpConfigDisableRequest", + "description": "MCP server names to disable for new sessions." }, "result": { - "type": "null", - "title": "McpConfigDisableResult" + "type": "null" } } }, "discover": { "rpcMethod": "mcp.discover", + "description": "Discovers MCP servers from user, workspace, plugin, and builtin sources.", "params": { - "$ref": "#/definitions/McpDiscoverRequest" + "$ref": "#/definitions/McpDiscoverRequest", + "description": "Optional working directory used as context for MCP server discovery." }, "result": { - "$ref": "#/definitions/McpDiscoverResult" + "$ref": "#/definitions/McpDiscoverResult", + "description": "MCP servers discovered from user, workspace, plugin, and built-in sources." } } }, @@ -129,44 +154,67 @@ "config": { "setDisabledSkills": { "rpcMethod": "skills.config.setDisabledSkills", + "description": "Replaces the global list of disabled skills.", "params": { - "$ref": "#/definitions/SkillsConfigSetDisabledSkillsRequest" + "$ref": "#/definitions/SkillsConfigSetDisabledSkillsRequest", + "description": "Skill names to mark as disabled in global configuration, replacing any previous list." }, "result": { - "type": "null", - "title": "SkillsConfigSetDisabledSkillsResult" + "type": "null" } } }, "discover": { "rpcMethod": "skills.discover", + "description": "Discovers skills across global and project sources.", "params": { - "$ref": "#/definitions/SkillsDiscoverRequest" + "$ref": "#/definitions/SkillsDiscoverRequest", + "description": "Optional project paths and additional skill directories to include in discovery." }, "result": { - "$ref": "#/definitions/ServerSkillList" + "$ref": "#/definitions/ServerSkillList", + "description": "Skills discovered across global and project sources." } } }, "sessionFs": { "setProvider": { "rpcMethod": "sessionFs.setProvider", + "description": "Registers an SDK client as the session filesystem provider.", "params": { - "$ref": "#/definitions/SessionFsSetProviderRequest" + "$ref": "#/definitions/SessionFsSetProviderRequest", + "description": "Initial working directory, session-state path layout, and path conventions used to register the calling SDK client as the session filesystem provider." }, "result": { - "$ref": "#/definitions/SessionFsSetProviderResult" + "$ref": "#/definitions/SessionFsSetProviderResult", + "description": "Indicates whether the calling client was registered as the session filesystem provider." } } }, "sessions": { "fork": { "rpcMethod": "sessions.fork", + "description": "Creates a new session by forking persisted history from an existing session.", "params": { - "$ref": "#/definitions/SessionsForkRequest" + "$ref": "#/definitions/SessionsForkRequest", + "description": "Source session identifier to fork from, optional event-ID boundary, and optional friendly name for the new session." }, "result": { - "$ref": "#/definitions/SessionsForkResult" + "$ref": "#/definitions/SessionsForkResult", + "description": "Identifier and optional friendly name assigned to the newly forked session." + }, + "stability": "experimental" + }, + "connect": { + "rpcMethod": "sessions.connect", + "description": "Connects to an existing remote session and exposes it as an SDK session.", + "params": { + "$ref": "#/definitions/ConnectRemoteSessionParams", + "description": "Remote session connection parameters." + }, + "result": { + "$ref": "#/definitions/RemoteSessionConnectionResult", + "description": "Remote session connection result." }, "stability": "experimental" } @@ -175,8 +223,10 @@ "session": { "suspend": { "rpcMethod": "session.suspend", + "description": "Suspends the session while preserving persisted state for later resume.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -189,15 +239,16 @@ "additionalProperties": false }, "result": { - "type": "null", - "title": "SuspendResult" + "type": "null" } }, "auth": { "getStatus": { "rpcMethod": "session.auth.getStatus", + "description": "Gets authentication status and account metadata for the session.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -210,15 +261,18 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/SessionAuthStatus" + "$ref": "#/definitions/SessionAuthStatus", + "description": "Authentication status and account metadata for the session." } } }, "model": { "getCurrent": { "rpcMethod": "session.model.getCurrent", + "description": "Gets the currently selected model for the session.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -231,11 +285,13 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/CurrentModel" + "$ref": "#/definitions/CurrentModel", + "description": "The currently selected model for the session." } }, "switchTo": { "rpcMethod": "session.model.switchTo", + "description": "Switches the session to a model and optional reasoning configuration.", "params": { "type": "object", "properties": { @@ -249,7 +305,11 @@ }, "reasoningEffort": { "type": "string", - "description": "Reasoning effort level to use for the model" + "description": "Reasoning effort level to use for the model. \"none\" disables reasoning." + }, + "reasoningSummary": { + "$ref": "#/definitions/ReasoningSummary", + "description": "Reasoning summary mode to request for supported model clients" }, "modelCapabilities": { "$ref": "#/definitions/ModelCapabilitiesOverride", @@ -261,18 +321,22 @@ "modelId" ], "additionalProperties": false, + "description": "Target model identifier and optional reasoning effort, summary, and capability overrides.", "title": "ModelSwitchToRequest" }, "result": { - "$ref": "#/definitions/ModelSwitchToResult" + "$ref": "#/definitions/ModelSwitchToResult", + "description": "The model identifier active on the session after the switch." } } }, "mode": { "get": { "rpcMethod": "session.mode.get", + "description": "Gets the current agent interaction mode.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -291,6 +355,7 @@ }, "set": { "rpcMethod": "session.mode.set", + "description": "Sets the current agent interaction mode.", "params": { "type": "object", "properties": { @@ -308,19 +373,21 @@ "mode" ], "additionalProperties": false, + "description": "Agent interaction mode to apply to the session.", "title": "ModeSetRequest" }, "result": { - "type": "null", - "title": "ModeSetResult" + "type": "null" } } }, "name": { "get": { "rpcMethod": "session.name.get", + "description": "Gets the session's friendly name.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -333,11 +400,13 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/NameGetResult" + "$ref": "#/definitions/NameGetResult", + "description": "The session's friendly name, or null when not yet set." } }, "set": { "rpcMethod": "session.name.set", + "description": "Sets the session's friendly name.", "params": { "type": "object", "properties": { @@ -357,19 +426,21 @@ "name" ], "additionalProperties": false, + "description": "New friendly name to apply to the session.", "title": "NameSetRequest" }, "result": { - "type": "null", - "title": "NameSetResult" + "type": "null" } } }, "plan": { "read": { "rpcMethod": "session.plan.read", + "description": "Reads the session plan file from the workspace.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -382,11 +453,13 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/PlanReadResult" + "$ref": "#/definitions/PlanReadResult", + "description": "Existence, contents, and resolved path of the session plan file." } }, "update": { "rpcMethod": "session.plan.update", + "description": "Writes new content to the session plan file.", "params": { "type": "object", "properties": { @@ -404,17 +477,19 @@ "content" ], "additionalProperties": false, + "description": "Replacement contents to write to the session plan file.", "title": "PlanUpdateRequest" }, "result": { - "type": "null", - "title": "PlanUpdateResult" + "type": "null" } }, "delete": { "rpcMethod": "session.plan.delete", + "description": "Deletes the session plan file from the workspace.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -427,16 +502,17 @@ "additionalProperties": false }, "result": { - "type": "null", - "title": "PlanDeleteResult" + "type": "null" } } }, "workspaces": { "getWorkspace": { "rpcMethod": "session.workspaces.getWorkspace", + "description": "Gets current workspace metadata for the session.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -449,13 +525,16 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/WorkspacesGetWorkspaceResult" + "$ref": "#/definitions/WorkspacesGetWorkspaceResult", + "description": "Current workspace metadata for the session, or null when not available." } }, "listFiles": { "rpcMethod": "session.workspaces.listFiles", + "description": "Lists files stored in the session workspace files directory.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -468,11 +547,13 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/WorkspacesListFilesResult" + "$ref": "#/definitions/WorkspacesListFilesResult", + "description": "Relative paths of files stored in the session workspace files directory." } }, "readFile": { "rpcMethod": "session.workspaces.readFile", + "description": "Reads a file from the session workspace files directory.", "params": { "type": "object", "properties": { @@ -490,14 +571,17 @@ "path" ], "additionalProperties": false, + "description": "Relative path of the workspace file to read.", "title": "WorkspacesReadFileRequest" }, "result": { - "$ref": "#/definitions/WorkspacesReadFileResult" + "$ref": "#/definitions/WorkspacesReadFileResult", + "description": "Contents of the requested workspace file as a UTF-8 string." } }, "createFile": { "rpcMethod": "session.workspaces.createFile", + "description": "Creates or overwrites a file in the session workspace files directory.", "params": { "type": "object", "properties": { @@ -520,19 +604,21 @@ "content" ], "additionalProperties": false, + "description": "Relative path and UTF-8 content for the workspace file to create or overwrite.", "title": "WorkspacesCreateFileRequest" }, "result": { - "type": "null", - "title": "WorkspacesCreateFileResult" + "type": "null" } } }, "instructions": { "getSources": { "rpcMethod": "session.instructions.getSources", + "description": "Gets instruction sources loaded for the session.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -545,13 +631,15 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/InstructionsGetSourcesResult" + "$ref": "#/definitions/InstructionsGetSourcesResult", + "description": "Instruction sources loaded for the session, in merge order." } } }, "fleet": { "start": { "rpcMethod": "session.fleet.start", + "description": "Starts fleet mode by submitting the fleet orchestration prompt to the session.", "params": { "type": "object", "properties": { @@ -565,13 +653,15 @@ } }, "additionalProperties": false, + "description": "Optional user prompt to combine with the fleet orchestration instructions.", "title": "FleetStartRequest", "required": [ "sessionId" ] }, "result": { - "$ref": "#/definitions/FleetStartResult" + "$ref": "#/definitions/FleetStartResult", + "description": "Indicates whether fleet mode was successfully activated." }, "stability": "experimental" } @@ -579,8 +669,10 @@ "agent": { "list": { "rpcMethod": "session.agent.list", + "description": "Lists custom agents available to the session.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -593,14 +685,17 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/AgentList" + "$ref": "#/definitions/AgentList", + "description": "Custom agents available to the session." }, "stability": "experimental" }, "getCurrent": { "rpcMethod": "session.agent.getCurrent", + "description": "Gets the currently selected custom agent for the session.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -613,12 +708,14 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/AgentGetCurrentResult" + "$ref": "#/definitions/AgentGetCurrentResult", + "description": "The currently selected custom agent, or null when using the default agent." }, "stability": "experimental" }, "select": { "rpcMethod": "session.agent.select", + "description": "Selects a custom agent for subsequent turns in the session.", "params": { "type": "object", "properties": { @@ -636,17 +733,21 @@ "name" ], "additionalProperties": false, + "description": "Name of the custom agent to select for subsequent turns.", "title": "AgentSelectRequest" }, "result": { - "$ref": "#/definitions/AgentSelectResult" + "$ref": "#/definitions/AgentSelectResult", + "description": "The newly selected custom agent." }, "stability": "experimental" }, "deselect": { "rpcMethod": "session.agent.deselect", + "description": "Clears the selected custom agent and returns the session to the default agent.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -659,15 +760,16 @@ "additionalProperties": false }, "result": { - "type": "null", - "title": "AgentDeselectResult" + "type": "null" }, "stability": "experimental" }, "reload": { "rpcMethod": "session.agent.reload", + "description": "Reloads custom agent definitions and returns the refreshed list.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -680,7 +782,8 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/AgentReloadResult" + "$ref": "#/definitions/AgentReloadResult", + "description": "Custom agents available to the session after reloading definitions from disk." }, "stability": "experimental" } @@ -688,6 +791,7 @@ "tasks": { "startAgent": { "rpcMethod": "session.tasks.startAgent", + "description": "Starts a background agent task in the session.", "params": { "type": "object", "properties": { @@ -723,17 +827,21 @@ "name" ], "additionalProperties": false, + "description": "Agent type, prompt, name, and optional description and model override for the new task.", "title": "TasksStartAgentRequest" }, "result": { - "$ref": "#/definitions/TasksStartAgentResult" + "$ref": "#/definitions/TasksStartAgentResult", + "description": "Identifier assigned to the newly started background agent task." }, "stability": "experimental" }, "list": { "rpcMethod": "session.tasks.list", + "description": "Lists background tasks tracked by the session.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -746,12 +854,14 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/TaskList" + "$ref": "#/definitions/TaskList", + "description": "Background tasks currently tracked by the session." }, "stability": "experimental" }, "promoteToBackground": { "rpcMethod": "session.tasks.promoteToBackground", + "description": "Promotes an eligible synchronously-waited task so it continues running in the background.", "params": { "type": "object", "properties": { @@ -769,15 +879,18 @@ "id" ], "additionalProperties": false, + "description": "Identifier of the task to promote to background mode.", "title": "TasksPromoteToBackgroundRequest" }, "result": { - "$ref": "#/definitions/TasksPromoteToBackgroundResult" + "$ref": "#/definitions/TasksPromoteToBackgroundResult", + "description": "Indicates whether the task was successfully promoted to background mode." }, "stability": "experimental" }, "cancel": { "rpcMethod": "session.tasks.cancel", + "description": "Cancels a background task.", "params": { "type": "object", "properties": { @@ -795,15 +908,18 @@ "id" ], "additionalProperties": false, + "description": "Identifier of the background task to cancel.", "title": "TasksCancelRequest" }, "result": { - "$ref": "#/definitions/TasksCancelResult" + "$ref": "#/definitions/TasksCancelResult", + "description": "Indicates whether the background task was successfully cancelled." }, "stability": "experimental" }, "remove": { "rpcMethod": "session.tasks.remove", + "description": "Removes a completed or cancelled background task from tracking.", "params": { "type": "object", "properties": { @@ -821,15 +937,18 @@ "id" ], "additionalProperties": false, + "description": "Identifier of the completed or cancelled task to remove from tracking.", "title": "TasksRemoveRequest" }, "result": { - "$ref": "#/definitions/TasksRemoveResult" + "$ref": "#/definitions/TasksRemoveResult", + "description": "Indicates whether the task was removed. False when the task does not exist or is still running/idle." }, "stability": "experimental" }, "sendMessage": { "rpcMethod": "session.tasks.sendMessage", + "description": "Sends a message to a background agent task.", "params": { "type": "object", "properties": { @@ -856,10 +975,12 @@ "message" ], "additionalProperties": false, + "description": "Identifier of the target agent task, message content, and optional sender agent ID.", "title": "TasksSendMessageRequest" }, "result": { - "$ref": "#/definitions/TasksSendMessageResult" + "$ref": "#/definitions/TasksSendMessageResult", + "description": "Indicates whether the message was delivered, with an error message when delivery failed." }, "stability": "experimental" } @@ -867,8 +988,10 @@ "skills": { "list": { "rpcMethod": "session.skills.list", + "description": "Lists skills available to the session.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -881,12 +1004,14 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/SkillList" + "$ref": "#/definitions/SkillList", + "description": "Skills available to the session, with their enabled state." }, "stability": "experimental" }, "enable": { "rpcMethod": "session.skills.enable", + "description": "Enables a skill for the session.", "params": { "type": "object", "properties": { @@ -904,16 +1029,17 @@ "name" ], "additionalProperties": false, + "description": "Name of the skill to enable for the session.", "title": "SkillsEnableRequest" }, "result": { - "type": "null", - "title": "SkillsEnableResult" + "type": "null" }, "stability": "experimental" }, "disable": { "rpcMethod": "session.skills.disable", + "description": "Disables a skill for the session.", "params": { "type": "object", "properties": { @@ -931,18 +1057,20 @@ "name" ], "additionalProperties": false, + "description": "Name of the skill to disable for the session.", "title": "SkillsDisableRequest" }, "result": { - "type": "null", - "title": "SkillsDisableResult" + "type": "null" }, "stability": "experimental" }, "reload": { "rpcMethod": "session.skills.reload", + "description": "Reloads skill definitions for the session.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -955,7 +1083,8 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/SkillsLoadDiagnostics" + "$ref": "#/definitions/SkillsLoadDiagnostics", + "description": "Diagnostics from reloading skill definitions, with warnings and errors as separate lists." }, "stability": "experimental" } @@ -963,8 +1092,10 @@ "mcp": { "list": { "rpcMethod": "session.mcp.list", + "description": "Lists MCP servers configured for the session and their connection status.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -977,12 +1108,14 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/McpServerList" + "$ref": "#/definitions/McpServerList", + "description": "MCP servers configured for the session, with their connection status." }, "stability": "experimental" }, "enable": { "rpcMethod": "session.mcp.enable", + "description": "Enables an MCP server for the session.", "params": { "type": "object", "properties": { @@ -1002,16 +1135,17 @@ "serverName" ], "additionalProperties": false, + "description": "Name of the MCP server to enable for the session.", "title": "McpEnableRequest" }, "result": { - "type": "null", - "title": "McpEnableResult" + "type": "null" }, "stability": "experimental" }, "disable": { "rpcMethod": "session.mcp.disable", + "description": "Disables an MCP server for the session.", "params": { "type": "object", "properties": { @@ -1031,18 +1165,20 @@ "serverName" ], "additionalProperties": false, + "description": "Name of the MCP server to disable for the session.", "title": "McpDisableRequest" }, "result": { - "type": "null", - "title": "McpDisableResult" + "type": "null" }, "stability": "experimental" }, "reload": { "rpcMethod": "session.mcp.reload", + "description": "Reloads MCP server connections for the session.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -1055,14 +1191,14 @@ "additionalProperties": false }, "result": { - "type": "null", - "title": "McpReloadResult" + "type": "null" }, "stability": "experimental" }, "oauth": { "login": { "rpcMethod": "session.mcp.oauth.login", + "description": "Starts OAuth authentication for a remote MCP server.", "params": { "type": "object", "properties": { @@ -1094,10 +1230,12 @@ "serverName" ], "additionalProperties": false, + "description": "Remote MCP server name and optional overrides controlling reauthentication, OAuth client display name, and the callback success-page copy.", "title": "McpOauthLoginRequest" }, "result": { - "$ref": "#/definitions/McpOauthLoginResult" + "$ref": "#/definitions/McpOauthLoginResult", + "description": "OAuth authorization URL the caller should open, or empty when cached tokens already authenticated the server." }, "stability": "experimental" } @@ -1106,8 +1244,10 @@ "plugins": { "list": { "rpcMethod": "session.plugins.list", + "description": "Lists plugins installed for the session.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -1120,7 +1260,8 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/PluginList" + "$ref": "#/definitions/PluginList", + "description": "Plugins installed for the session, with their enabled state and version metadata." }, "stability": "experimental" } @@ -1128,8 +1269,10 @@ "extensions": { "list": { "rpcMethod": "session.extensions.list", + "description": "Lists extensions discovered for the session and their current status.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -1142,12 +1285,14 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/ExtensionList" + "$ref": "#/definitions/ExtensionList", + "description": "Extensions discovered for the session, with their current status." }, "stability": "experimental" }, "enable": { "rpcMethod": "session.extensions.enable", + "description": "Enables an extension for the session.", "params": { "type": "object", "properties": { @@ -1165,16 +1310,17 @@ "id" ], "additionalProperties": false, + "description": "Source-qualified extension identifier to enable for the session.", "title": "ExtensionsEnableRequest" }, "result": { - "type": "null", - "title": "ExtensionsEnableResult" + "type": "null" }, "stability": "experimental" }, "disable": { "rpcMethod": "session.extensions.disable", + "description": "Disables an extension for the session.", "params": { "type": "object", "properties": { @@ -1192,18 +1338,20 @@ "id" ], "additionalProperties": false, + "description": "Source-qualified extension identifier to disable for the session.", "title": "ExtensionsDisableRequest" }, "result": { - "type": "null", - "title": "ExtensionsDisableResult" + "type": "null" }, "stability": "experimental" }, "reload": { "rpcMethod": "session.extensions.reload", + "description": "Reloads extension definitions and processes for the session.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -1216,8 +1364,7 @@ "additionalProperties": false }, "result": { - "type": "null", - "title": "ExtensionsReloadResult" + "type": "null" }, "stability": "experimental" } @@ -1225,6 +1372,7 @@ "tools": { "handlePendingToolCall": { "rpcMethod": "session.tools.handlePendingToolCall", + "description": "Provides the result for a pending external tool call.", "params": { "type": "object", "properties": { @@ -1250,16 +1398,19 @@ "requestId" ], "additionalProperties": false, + "description": "Pending external tool call request ID, with the tool result or an error describing why it failed.", "title": "HandlePendingToolCallRequest" }, "result": { - "$ref": "#/definitions/HandlePendingToolCallResult" + "$ref": "#/definitions/HandlePendingToolCallResult", + "description": "Indicates whether the external tool call result was handled successfully." } } }, "commands": { "list": { "rpcMethod": "session.commands.list", + "description": "Lists slash commands available in the session.", "params": { "anyOf": [ { @@ -1284,6 +1435,7 @@ "additionalProperties": false } ], + "description": "Optional filters controlling which command sources to include in the listing.", "title": "CommandsListRequest", "properties": { "sessionId": { @@ -1296,11 +1448,13 @@ ] }, "result": { - "$ref": "#/definitions/CommandList" + "$ref": "#/definitions/CommandList", + "description": "Slash commands available in the session, after applying any include/exclude filters." } }, "invoke": { "rpcMethod": "session.commands.invoke", + "description": "Invokes a slash command in the session.", "params": { "type": "object", "properties": { @@ -1322,14 +1476,17 @@ "name" ], "additionalProperties": false, + "description": "Slash command name and optional raw input string to invoke.", "title": "CommandsInvokeRequest" }, "result": { - "$ref": "#/definitions/SlashCommandInvocationResult" + "$ref": "#/definitions/SlashCommandInvocationResult", + "description": "Result of invoking the slash command (text output, prompt to send to the agent, or completion)." } }, "handlePendingCommand": { "rpcMethod": "session.commands.handlePendingCommand", + "description": "Reports completion of a pending client-handled slash command.", "params": { "type": "object", "properties": { @@ -1351,14 +1508,17 @@ "requestId" ], "additionalProperties": false, + "description": "Pending command request ID and an optional error if the client handler failed.", "title": "CommandsHandlePendingCommandRequest" }, "result": { - "$ref": "#/definitions/CommandsHandlePendingCommandResult" + "$ref": "#/definitions/CommandsHandlePendingCommandResult", + "description": "Indicates whether the pending client-handled command was completed successfully." } }, "respondToQueuedCommand": { "rpcMethod": "session.commands.respondToQueuedCommand", + "description": "Responds to a queued command request from the session.", "params": { "type": "object", "properties": { @@ -1381,16 +1541,19 @@ "result" ], "additionalProperties": false, + "description": "Queued command request ID and the result indicating whether the client handled it.", "title": "CommandsRespondToQueuedCommandRequest" }, "result": { - "$ref": "#/definitions/CommandsRespondToQueuedCommandResult" + "$ref": "#/definitions/CommandsRespondToQueuedCommandResult", + "description": "Indicates whether the queued-command response was accepted by the session." } } }, "ui": { "elicitation": { "rpcMethod": "session.ui.elicitation", + "description": "Requests structured input from a UI-capable client.", "params": { "type": "object", "properties": { @@ -1413,6 +1576,7 @@ "requestedSchema" ], "additionalProperties": false, + "description": "Prompt message and JSON schema describing the form fields to elicit from the user.", "title": "UIElicitationRequest" }, "result": { @@ -1422,6 +1586,7 @@ }, "handlePendingElicitation": { "rpcMethod": "session.ui.handlePendingElicitation", + "description": "Provides the user response for a pending elicitation request.", "params": { "type": "object", "properties": { @@ -1444,16 +1609,19 @@ "result" ], "additionalProperties": false, + "description": "Pending elicitation request ID and the user's response (accept/decline/cancel + form values).", "title": "UIHandlePendingElicitationRequest" }, "result": { - "$ref": "#/definitions/UIElicitationResult" + "$ref": "#/definitions/UIElicitationResult", + "description": "Indicates whether the elicitation response was accepted; false if it was already resolved by another client." } } }, "permissions": { "handlePendingPermissionRequest": { "rpcMethod": "session.permissions.handlePendingPermissionRequest", + "description": "Provides a decision for a pending tool permission request.", "params": { "type": "object", "properties": { @@ -1466,7 +1634,8 @@ "description": "Request ID of the pending permission request" }, "result": { - "$ref": "#/definitions/PermissionDecision" + "$ref": "#/definitions/PermissionDecision", + "description": "Decision to apply to a pending permission request." } }, "required": [ @@ -1475,14 +1644,17 @@ "result" ], "additionalProperties": false, + "description": "Pending permission request ID and the decision to apply (approve/reject and scope).", "title": "PermissionDecisionRequest" }, "result": { - "$ref": "#/definitions/PermissionRequestResult" + "$ref": "#/definitions/PermissionRequestResult", + "description": "Indicates whether the permission decision was applied; false when the request was already resolved." } }, "setApproveAll": { "rpcMethod": "session.permissions.setApproveAll", + "description": "Enables or disables automatic approval of tool permission requests for the session.", "params": { "type": "object", "properties": { @@ -1500,14 +1672,17 @@ "enabled" ], "additionalProperties": false, + "description": "Whether to auto-approve all tool permission requests for the rest of the session.", "title": "PermissionsSetApproveAllRequest" }, "result": { - "$ref": "#/definitions/PermissionsSetApproveAllResult" + "$ref": "#/definitions/PermissionsSetApproveAllResult", + "description": "Indicates whether the operation succeeded." } }, "resetSessionApprovals": { "rpcMethod": "session.permissions.resetSessionApprovals", + "description": "Clears session-scoped tool permission approvals.", "params": { "type": "object", "properties": { @@ -1517,18 +1692,21 @@ } }, "additionalProperties": false, + "description": "No parameters; clears all session-scoped tool permission approvals.", "title": "PermissionsResetSessionApprovalsRequest", "required": [ "sessionId" ] }, "result": { - "$ref": "#/definitions/PermissionsResetSessionApprovalsResult" + "$ref": "#/definitions/PermissionsResetSessionApprovalsResult", + "description": "Indicates whether the operation succeeded." } } }, "log": { "rpcMethod": "session.log", + "description": "Emits a user-visible session log event.", "params": { "type": "object", "properties": { @@ -1559,15 +1737,18 @@ "message" ], "additionalProperties": false, + "description": "Message text, optional severity level, persistence flag, and optional follow-up URL.", "title": "LogRequest" }, "result": { - "$ref": "#/definitions/LogResult" + "$ref": "#/definitions/LogResult", + "description": "Identifier of the session event that was emitted for the log message." } }, "shell": { "exec": { "rpcMethod": "session.shell.exec", + "description": "Starts a shell command and streams output through session notifications.", "params": { "type": "object", "properties": { @@ -1595,14 +1776,17 @@ "command" ], "additionalProperties": false, + "description": "Shell command to run, with optional working directory and timeout in milliseconds.", "title": "ShellExecRequest" }, "result": { - "$ref": "#/definitions/ShellExecResult" + "$ref": "#/definitions/ShellExecResult", + "description": "Identifier of the spawned process, used to correlate streamed output and exit notifications." } }, "kill": { "rpcMethod": "session.shell.kill", + "description": "Sends a signal to a shell process previously started via \"shell.exec\".", "params": { "type": "object", "properties": { @@ -1624,18 +1808,22 @@ "processId" ], "additionalProperties": false, + "description": "Identifier of a process previously returned by \"shell.exec\" and the signal to send.", "title": "ShellKillRequest" }, "result": { - "$ref": "#/definitions/ShellKillResult" + "$ref": "#/definitions/ShellKillResult", + "description": "Indicates whether the signal was delivered; false if the process was unknown or already exited." } } }, "history": { "compact": { "rpcMethod": "session.history.compact", + "description": "Compacts the session history to reduce context usage.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -1648,12 +1836,14 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/HistoryCompactResult" + "$ref": "#/definitions/HistoryCompactResult", + "description": "Compaction outcome with the number of tokens and messages removed and the resulting context window breakdown." }, "stability": "experimental" }, "truncate": { "rpcMethod": "session.history.truncate", + "description": "Truncates persisted session history to a specific event.", "params": { "type": "object", "properties": { @@ -1671,10 +1861,12 @@ "eventId" ], "additionalProperties": false, + "description": "Identifier of the event to truncate to; this event and all later events are removed.", "title": "HistoryTruncateRequest" }, "result": { - "$ref": "#/definitions/HistoryTruncateResult" + "$ref": "#/definitions/HistoryTruncateResult", + "description": "Number of events that were removed by the truncation." }, "stability": "experimental" } @@ -1682,8 +1874,10 @@ "usage": { "getMetrics": { "rpcMethod": "session.usage.getMetrics", + "description": "Gets accumulated usage metrics for the session.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -1696,7 +1890,8 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/UsageGetMetricsResult" + "$ref": "#/definitions/UsageGetMetricsResult", + "description": "Accumulated session usage metrics, including premium request cost, token counts, model breakdown, and code-change totals." }, "stability": "experimental" } @@ -1704,6 +1899,7 @@ "remote": { "enable": { "rpcMethod": "session.remote.enable", + "description": "Enables remote session export or steering.", "params": { "type": "object", "properties": { @@ -1713,24 +1909,28 @@ }, "mode": { "$ref": "#/definitions/RemoteSessionMode", - "description": "Per-session remote mode. \"off\" disables remote, \"export\" exports session events to Mission Control without enabling remote steering, \"on\" enables both export and remote steering." + "description": "Per-session remote mode. \"off\" disables remote, \"export\" exports session events to GitHub without enabling remote steering, \"on\" enables both export and remote steering." } }, "additionalProperties": false, + "description": "Optional remote session mode (\"off\", \"export\", or \"on\"); defaults to enabling both export and remote steering.", "title": "RemoteEnableRequest", "required": [ "sessionId" ] }, "result": { - "$ref": "#/definitions/RemoteEnableResult" + "$ref": "#/definitions/RemoteEnableResult", + "description": "GitHub URL for the session and a flag indicating whether remote steering is enabled." }, "stability": "experimental" }, "disable": { "rpcMethod": "session.remote.disable", + "description": "Disables remote session export and steering.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", @@ -1743,8 +1943,7 @@ "additionalProperties": false }, "result": { - "type": "null", - "title": "RemoteDisableResult" + "type": "null" }, "stability": "experimental" } @@ -1754,6 +1953,7 @@ "sessionFs": { "readFile": { "rpcMethod": "sessionFs.readFile", + "description": "Reads a file from the client-provided session filesystem.", "params": { "type": "object", "properties": { @@ -1771,14 +1971,17 @@ "path" ], "additionalProperties": false, + "description": "Path of the file to read from the client-provided session filesystem.", "title": "SessionFsReadFileRequest" }, "result": { - "$ref": "#/definitions/SessionFsReadFileResult" + "$ref": "#/definitions/SessionFsReadFileResult", + "description": "File content as a UTF-8 string, or a filesystem error if the read failed." } }, "writeFile": { "rpcMethod": "sessionFs.writeFile", + "description": "Writes a file in the client-provided session filesystem.", "params": { "type": "object", "properties": { @@ -1806,6 +2009,7 @@ "content" ], "additionalProperties": false, + "description": "File path, content to write, and optional mode for the client-provided session filesystem.", "title": "SessionFsWriteFileRequest" }, "result": { @@ -1823,6 +2027,7 @@ }, "appendFile": { "rpcMethod": "sessionFs.appendFile", + "description": "Appends content to a file in the client-provided session filesystem.", "params": { "type": "object", "properties": { @@ -1850,6 +2055,7 @@ "content" ], "additionalProperties": false, + "description": "File path, content to append, and optional mode for the client-provided session filesystem.", "title": "SessionFsAppendFileRequest" }, "result": { @@ -1867,6 +2073,7 @@ }, "exists": { "rpcMethod": "sessionFs.exists", + "description": "Checks whether a path exists in the client-provided session filesystem.", "params": { "type": "object", "properties": { @@ -1884,14 +2091,17 @@ "path" ], "additionalProperties": false, + "description": "Path to test for existence in the client-provided session filesystem.", "title": "SessionFsExistsRequest" }, "result": { - "$ref": "#/definitions/SessionFsExistsResult" + "$ref": "#/definitions/SessionFsExistsResult", + "description": "Indicates whether the requested path exists in the client-provided session filesystem." } }, "stat": { "rpcMethod": "sessionFs.stat", + "description": "Gets metadata for a path in the client-provided session filesystem.", "params": { "type": "object", "properties": { @@ -1909,14 +2119,17 @@ "path" ], "additionalProperties": false, + "description": "Path whose metadata should be returned from the client-provided session filesystem.", "title": "SessionFsStatRequest" }, "result": { - "$ref": "#/definitions/SessionFsStatResult" + "$ref": "#/definitions/SessionFsStatResult", + "description": "Filesystem metadata for the requested path, or a filesystem error if the stat failed." } }, "mkdir": { "rpcMethod": "sessionFs.mkdir", + "description": "Creates a directory in the client-provided session filesystem.", "params": { "type": "object", "properties": { @@ -1943,6 +2156,7 @@ "path" ], "additionalProperties": false, + "description": "Directory path to create in the client-provided session filesystem, with options for recursive creation and POSIX mode.", "title": "SessionFsMkdirRequest" }, "result": { @@ -1960,6 +2174,7 @@ }, "readdir": { "rpcMethod": "sessionFs.readdir", + "description": "Lists entry names in a directory from the client-provided session filesystem.", "params": { "type": "object", "properties": { @@ -1977,14 +2192,17 @@ "path" ], "additionalProperties": false, + "description": "Directory path whose entries should be listed from the client-provided session filesystem.", "title": "SessionFsReaddirRequest" }, "result": { - "$ref": "#/definitions/SessionFsReaddirResult" + "$ref": "#/definitions/SessionFsReaddirResult", + "description": "Names of entries in the requested directory, or a filesystem error if the read failed." } }, "readdirWithTypes": { "rpcMethod": "sessionFs.readdirWithTypes", + "description": "Lists directory entries with type information from the client-provided session filesystem.", "params": { "type": "object", "properties": { @@ -2002,14 +2220,17 @@ "path" ], "additionalProperties": false, + "description": "Directory path whose entries (with type information) should be listed from the client-provided session filesystem.", "title": "SessionFsReaddirWithTypesRequest" }, "result": { - "$ref": "#/definitions/SessionFsReaddirWithTypesResult" + "$ref": "#/definitions/SessionFsReaddirWithTypesResult", + "description": "Entries in the requested directory paired with file/directory type information, or a filesystem error if the read failed." } }, "rm": { "rpcMethod": "sessionFs.rm", + "description": "Removes a file or directory from the client-provided session filesystem.", "params": { "type": "object", "properties": { @@ -2035,6 +2256,7 @@ "path" ], "additionalProperties": false, + "description": "Path to remove from the client-provided session filesystem, with options for recursive removal and force.", "title": "SessionFsRmRequest" }, "result": { @@ -2052,6 +2274,7 @@ }, "rename": { "rpcMethod": "sessionFs.rename", + "description": "Renames or moves a path in the client-provided session filesystem.", "params": { "type": "object", "properties": { @@ -2074,6 +2297,7 @@ "dest" ], "additionalProperties": false, + "description": "Source and destination paths for renaming or moving an entry in the client-provided session filesystem.", "title": "SessionFsRenameRequest" }, "result": { @@ -2108,6 +2332,7 @@ "additionalProperties": false } ], + "description": "Optional GitHub token used to look up quota for a specific user instead of the global auth context.", "title": "AccountGetQuotaRequest" }, "AccountGetQuotaResult": { @@ -2125,6 +2350,7 @@ "quotaSnapshots" ], "additionalProperties": false, + "description": "Quota usage snapshots for the resolved user, keyed by quota type.", "title": "AccountGetQuotaResult" }, "AccountQuotaSnapshot": { @@ -2175,7 +2401,8 @@ "overageAllowedWithExhaustedQuota" ], "additionalProperties": false, - "title": "AccountQuotaSnapshot" + "title": "AccountQuotaSnapshot", + "description": "Schema for the `AccountQuotaSnapshot` type." }, "AgentGetCurrentResult": { "type": "object", @@ -2189,6 +2416,7 @@ "agent" ], "additionalProperties": false, + "description": "The currently selected custom agent, or null when using the default agent.", "title": "AgentGetCurrentResult" }, "AgentInfo": { @@ -2217,7 +2445,8 @@ "description" ], "additionalProperties": false, - "title": "AgentInfo" + "title": "AgentInfo", + "description": "Schema for the `AgentInfo` type." }, "AgentList": { "type": "object", @@ -2234,6 +2463,7 @@ "agents" ], "additionalProperties": false, + "description": "Custom agents available to the session.", "title": "AgentList" }, "AgentReloadResult": { @@ -2251,6 +2481,7 @@ "agents" ], "additionalProperties": false, + "description": "Custom agents available to the session after reloading definitions from disk.", "title": "AgentReloadResult" }, "AgentSelectRequest": { @@ -2265,6 +2496,7 @@ "name" ], "additionalProperties": false, + "description": "Name of the custom agent to select for subsequent turns.", "title": "AgentSelectRequest" }, "AgentSelectResult": { @@ -2279,6 +2511,7 @@ "agent" ], "additionalProperties": false, + "description": "The newly selected custom agent.", "title": "AgentSelectResult" }, "AuthInfoType": { @@ -2310,6 +2543,7 @@ "commands" ], "additionalProperties": false, + "description": "Slash commands available in the session, after applying any include/exclude filters.", "title": "CommandList" }, "CommandsHandlePendingCommandRequest": { @@ -2328,6 +2562,7 @@ "requestId" ], "additionalProperties": false, + "description": "Pending command request ID and an optional error if the client handler failed.", "title": "CommandsHandlePendingCommandRequest" }, "CommandsHandlePendingCommandResult": { @@ -2342,6 +2577,7 @@ "success" ], "additionalProperties": false, + "description": "Indicates whether the pending client-handled command was completed successfully.", "title": "CommandsHandlePendingCommandResult" }, "CommandsInvokeRequest": { @@ -2360,6 +2596,7 @@ "name" ], "additionalProperties": false, + "description": "Slash command name and optional raw input string to invoke.", "title": "CommandsInvokeRequest" }, "CommandsListRequest": { @@ -2386,6 +2623,7 @@ "additionalProperties": false } ], + "description": "Optional filters controlling which command sources to include in the listing.", "title": "CommandsListRequest" }, "CommandsRespondToQueuedCommandRequest": { @@ -2405,6 +2643,7 @@ "result" ], "additionalProperties": false, + "description": "Queued command request ID and the result indicating whether the client handled it.", "title": "CommandsRespondToQueuedCommandRequest" }, "CommandsRespondToQueuedCommandResult": { @@ -2419,8 +2658,117 @@ "success" ], "additionalProperties": false, + "description": "Indicates whether the queued-command response was accepted by the session.", "title": "CommandsRespondToQueuedCommandResult" }, + "ConnectedRemoteSessionMetadata": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "SDK session ID for the connected remote session." + }, + "name": { + "type": "string", + "description": "Optional friendly session name." + }, + "summary": { + "type": "string", + "description": "Optional session summary." + }, + "startTime": { + "type": "string", + "description": "Session start time as an ISO 8601 string." + }, + "modifiedTime": { + "type": "string", + "description": "Last session update time as an ISO 8601 string." + }, + "repository": { + "$ref": "#/definitions/ConnectedRemoteSessionMetadataRepository", + "description": "Repository associated with the connected remote session." + }, + "pullRequestNumber": { + "type": "integer", + "description": "Pull request number associated with the session." + }, + "resourceId": { + "type": "string", + "description": "Original remote resource identifier." + }, + "kind": { + "$ref": "#/definitions/ConnectedRemoteSessionMetadataKind", + "description": "Neutral SDK discriminator for the connected remote session kind." + }, + "staleAt": { + "type": "string", + "description": "Remote session staleness deadline as an ISO 8601 string." + }, + "state": { + "type": "string", + "description": "Remote session state returned by the backing service." + } + }, + "required": [ + "sessionId", + "startTime", + "modifiedTime", + "repository", + "kind" + ], + "additionalProperties": false, + "description": "Metadata for a connected remote session.", + "title": "ConnectedRemoteSessionMetadata" + }, + "ConnectedRemoteSessionMetadataKind": { + "type": "string", + "enum": [ + "remote-session", + "coding-agent" + ], + "description": "Neutral SDK discriminator for the connected remote session kind.", + "title": "ConnectedRemoteSessionMetadataKind" + }, + "ConnectedRemoteSessionMetadataRepository": { + "type": "object", + "properties": { + "owner": { + "type": "string", + "description": "Repository owner or organization login." + }, + "name": { + "type": "string", + "description": "Repository name." + }, + "branch": { + "type": "string", + "description": "Branch associated with the remote session." + } + }, + "required": [ + "owner", + "name", + "branch" + ], + "additionalProperties": false, + "description": "Repository associated with the connected remote session.", + "title": "ConnectedRemoteSessionMetadataRepository" + }, + "ConnectRemoteSessionParams": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Session ID to connect to." + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false, + "description": "Remote session connection parameters.", + "title": "ConnectRemoteSessionParams" + }, "ConnectRequest": { "type": "object", "properties": { @@ -2430,6 +2778,7 @@ } }, "additionalProperties": false, + "description": "Optional connection token presented by the SDK client during the handshake.", "title": "ConnectRequest", "visibility": "internal" }, @@ -2456,6 +2805,7 @@ "version" ], "additionalProperties": false, + "description": "Handshake result reporting the server's protocol version and package version on success.", "title": "ConnectResult", "visibility": "internal" }, @@ -2468,6 +2818,7 @@ } }, "additionalProperties": false, + "description": "The currently selected model for the session.", "title": "CurrentModel" }, "DiscoveredMcpServer": { @@ -2498,7 +2849,8 @@ "enabled" ], "additionalProperties": false, - "title": "DiscoveredMcpServer" + "title": "DiscoveredMcpServer", + "description": "Schema for the `DiscoveredMcpServer` type." }, "DiscoveredMcpServerSource": { "type": "string", @@ -2544,7 +2896,8 @@ "blob" ], "additionalProperties": false, - "title": "EmbeddedBlobResourceContents" + "title": "EmbeddedBlobResourceContents", + "description": "Schema for the `EmbeddedBlobResourceContents` type." }, "EmbeddedTextResourceContents": { "type": "object", @@ -2567,7 +2920,8 @@ "text" ], "additionalProperties": false, - "title": "EmbeddedTextResourceContents" + "title": "EmbeddedTextResourceContents", + "description": "Schema for the `EmbeddedTextResourceContents` type." }, "Extension": { "type": "object", @@ -2600,7 +2954,8 @@ "status" ], "additionalProperties": false, - "title": "Extension" + "title": "Extension", + "description": "Schema for the `Extension` type." }, "ExtensionList": { "type": "object", @@ -2617,6 +2972,7 @@ "extensions" ], "additionalProperties": false, + "description": "Extensions discovered for the session, with their current status.", "title": "ExtensionList" }, "ExtensionsDisableRequest": { @@ -2631,6 +2987,7 @@ "id" ], "additionalProperties": false, + "description": "Source-qualified extension identifier to disable for the session.", "title": "ExtensionsDisableRequest" }, "ExtensionsEnableRequest": { @@ -2645,6 +3002,7 @@ "id" ], "additionalProperties": false, + "description": "Source-qualified extension identifier to enable for the session.", "title": "ExtensionsEnableRequest" }, "ExtensionSource": { @@ -2989,6 +3347,7 @@ "$ref": "#/definitions/FilterMappingString" } ], + "description": "Content filtering mode to apply to all tools, or a map of tool name to content filtering mode.", "title": "FilterMapping" }, "FilterMappingString": { @@ -2998,7 +3357,8 @@ "markdown", "hidden_characters" ], - "title": "FilterMappingString" + "title": "FilterMappingString", + "description": "Allowed values for the `FilterMappingString` enumeration." }, "FilterMappingValue": { "type": "string", @@ -3007,7 +3367,8 @@ "markdown", "hidden_characters" ], - "title": "FilterMappingValue" + "title": "FilterMappingValue", + "description": "Allowed values for the `FilterMappingValue` enumeration." }, "FleetStartRequest": { "type": "object", @@ -3018,6 +3379,7 @@ } }, "additionalProperties": false, + "description": "Optional user prompt to combine with the fleet orchestration instructions.", "title": "FleetStartRequest" }, "FleetStartResult": { @@ -3032,6 +3394,7 @@ "started" ], "additionalProperties": false, + "description": "Indicates whether fleet mode was successfully activated.", "title": "FleetStartResult" }, "HandlePendingToolCallRequest": { @@ -3054,6 +3417,7 @@ "requestId" ], "additionalProperties": false, + "description": "Pending external tool call request ID, with the tool result or an error describing why it failed.", "title": "HandlePendingToolCallRequest" }, "HandlePendingToolCallResult": { @@ -3068,6 +3432,7 @@ "success" ], "additionalProperties": false, + "description": "Indicates whether the external tool call result was handled successfully.", "title": "HandlePendingToolCallResult" }, "HistoryCompactContextWindow": { @@ -3141,6 +3506,7 @@ "messagesRemoved" ], "additionalProperties": false, + "description": "Compaction outcome with the number of tokens and messages removed and the resulting context window breakdown.", "title": "HistoryCompactResult" }, "HistoryTruncateRequest": { @@ -3155,6 +3521,7 @@ "eventId" ], "additionalProperties": false, + "description": "Identifier of the event to truncate to; this event and all later events are removed.", "title": "HistoryTruncateRequest" }, "HistoryTruncateResult": { @@ -3170,6 +3537,7 @@ "eventsRemoved" ], "additionalProperties": false, + "description": "Number of events that were removed by the truncation.", "title": "HistoryTruncateResult" }, "InstructionsGetSourcesResult": { @@ -3187,6 +3555,7 @@ "sources" ], "additionalProperties": false, + "description": "Instruction sources loaded for the session, in merge order.", "title": "InstructionsGetSourcesResult" }, "InstructionsSources": { @@ -3234,7 +3603,8 @@ "location" ], "additionalProperties": false, - "title": "InstructionsSources" + "title": "InstructionsSources", + "description": "Schema for the `InstructionsSources` type." }, "InstructionsSourcesLocation": { "type": "string", @@ -3284,6 +3654,7 @@ "message" ], "additionalProperties": false, + "description": "Message text, optional severity level, persistence flag, and optional follow-up URL.", "title": "LogRequest" }, "LogResult": { @@ -3299,6 +3670,7 @@ "eventId" ], "additionalProperties": false, + "description": "Identifier of the session event that was emitted for the log message.", "title": "LogResult" }, "McpConfigAddRequest": { @@ -3320,6 +3692,7 @@ "config" ], "additionalProperties": false, + "description": "MCP server name and configuration to add to user configuration.", "title": "McpConfigAddRequest" }, "McpConfigDisableRequest": { @@ -3330,7 +3703,8 @@ "items": { "type": "string", "minLength": 1, - "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$" + "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", + "description": "MCP server name used as a configuration key." }, "description": "Names of MCP servers to disable. Each server is added to the persisted disabled list so new sessions skip it. Already-disabled names are ignored. Active sessions keep their current connections until they end." } @@ -3339,6 +3713,7 @@ "names" ], "additionalProperties": false, + "description": "MCP server names to disable for new sessions.", "title": "McpConfigDisableRequest" }, "McpConfigEnableRequest": { @@ -3349,7 +3724,8 @@ "items": { "type": "string", "minLength": 1, - "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$" + "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", + "description": "MCP server name used as a configuration key." }, "description": "Names of MCP servers to enable. Each server is removed from the persisted disabled list so new sessions spawn it. Unknown or already-enabled names are ignored." } @@ -3358,6 +3734,7 @@ "names" ], "additionalProperties": false, + "description": "MCP server names to enable for new sessions.", "title": "McpConfigEnableRequest" }, "McpConfigList": { @@ -3380,6 +3757,7 @@ "servers" ], "additionalProperties": false, + "description": "User-configured MCP servers, keyed by server name.", "title": "McpConfigList" }, "McpConfigRemoveRequest": { @@ -3396,6 +3774,7 @@ "name" ], "additionalProperties": false, + "description": "MCP server name to remove from user configuration.", "title": "McpConfigRemoveRequest" }, "McpConfigUpdateRequest": { @@ -3417,6 +3796,7 @@ "config" ], "additionalProperties": false, + "description": "MCP server name and replacement configuration to write to user configuration.", "title": "McpConfigUpdateRequest" }, "McpDisableRequest": { @@ -3433,6 +3813,7 @@ "serverName" ], "additionalProperties": false, + "description": "Name of the MCP server to disable for the session.", "title": "McpDisableRequest" }, "McpDiscoverRequest": { @@ -3444,6 +3825,7 @@ } }, "additionalProperties": false, + "description": "Optional working directory used as context for MCP server discovery.", "title": "McpDiscoverRequest" }, "McpDiscoverResult": { @@ -3461,6 +3843,7 @@ "servers" ], "additionalProperties": false, + "description": "MCP servers discovered from user, workspace, plugin, and built-in sources.", "title": "McpDiscoverResult" }, "McpEnableRequest": { @@ -3477,6 +3860,7 @@ "serverName" ], "additionalProperties": false, + "description": "Name of the MCP server to enable for the session.", "title": "McpEnableRequest" }, "McpOauthLoginRequest": { @@ -3505,6 +3889,7 @@ "serverName" ], "additionalProperties": false, + "description": "Remote MCP server name and optional overrides controlling reauthentication, OAuth client display name, and the callback success-page copy.", "title": "McpOauthLoginRequest" }, "McpOauthLoginResult": { @@ -3516,6 +3901,7 @@ } }, "additionalProperties": false, + "description": "OAuth authorization URL the caller should open, or empty when cached tokens already authenticated the server.", "title": "McpOauthLoginResult" }, "McpServer": { @@ -3545,15 +3931,18 @@ "status" ], "additionalProperties": false, - "title": "McpServer" + "title": "McpServer", + "description": "Schema for the `McpServer` type." }, "McpServerConfig": { "anyOf": [ { - "$ref": "#/definitions/McpServerConfigLocal" + "$ref": "#/definitions/McpServerConfigLocal", + "description": "Local MCP server configuration launched as a child process." }, { - "$ref": "#/definitions/McpServerConfigHttp" + "$ref": "#/definitions/McpServerConfigHttp", + "description": "Remote MCP server configuration accessed over HTTP or SSE." } ], "description": "MCP server configuration (local/stdio or remote/http)", @@ -3574,10 +3963,12 @@ "description": "Remote transport type. Defaults to \"http\" when omitted." }, "isDefaultServer": { - "type": "boolean" + "type": "boolean", + "description": "Whether this server is a built-in fallback used when the user has not configured their own server." }, "filterMapping": { - "$ref": "#/definitions/FilterMapping" + "$ref": "#/definitions/FilterMapping", + "description": "Content filtering mode to apply to all tools, or a map of tool name to content filtering mode." }, "timeout": { "type": "integer", @@ -3588,28 +3979,34 @@ }, "url": { "type": "string", - "format": "uri" + "format": "uri", + "description": "URL of the remote MCP server endpoint." }, "headers": { "type": "object", "additionalProperties": { "type": "string" - } + }, + "description": "HTTP headers to include in requests to the remote MCP server." }, "oauthClientId": { - "type": "string" + "type": "string", + "description": "OAuth client ID for a pre-registered remote MCP OAuth client." }, "oauthPublicClient": { - "type": "boolean" + "type": "boolean", + "description": "Whether the configured OAuth client is public and does not require a client secret." }, "oauthGrantType": { - "$ref": "#/definitions/McpServerConfigHttpOauthGrantType" + "$ref": "#/definitions/McpServerConfigHttpOauthGrantType", + "description": "OAuth grant type to use when authenticating to the remote MCP server." } }, "required": [ "url" ], "additionalProperties": false, + "description": "Remote MCP server configuration accessed over HTTP or SSE.", "title": "McpServerConfigHttp" }, "McpServerConfigHttpOauthGrantType": { @@ -3618,6 +4015,7 @@ "authorization_code", "client_credentials" ], + "description": "OAuth grant type to use when authenticating to the remote MCP server.", "title": "McpServerConfigHttpOauthGrantType" }, "McpServerConfigHttpType": { @@ -3641,13 +4039,16 @@ "description": "Tools to include. Defaults to all tools if not specified." }, "type": { - "$ref": "#/definitions/McpServerConfigLocalType" + "$ref": "#/definitions/McpServerConfigLocalType", + "description": "Local transport type. Defaults to \"local\"." }, "isDefaultServer": { - "type": "boolean" + "type": "boolean", + "description": "Whether this server is a built-in fallback used when the user has not configured their own server." }, "filterMapping": { - "$ref": "#/definitions/FilterMapping" + "$ref": "#/definitions/FilterMapping", + "description": "Content filtering mode to apply to all tools, or a map of tool name to content filtering mode." }, "timeout": { "type": "integer", @@ -3657,22 +4058,26 @@ "format": "duration" }, "command": { - "type": "string" + "type": "string", + "description": "Executable command used to start the local MCP server process." }, "args": { "type": "array", "items": { "type": "string" - } + }, + "description": "Command-line arguments passed to the local MCP server process." }, "cwd": { - "type": "string" + "type": "string", + "description": "Working directory for the local MCP server process." }, "env": { "type": "object", "additionalProperties": { "type": "string" - } + }, + "description": "Environment variables to pass to the local MCP server process." } }, "required": [ @@ -3680,6 +4085,7 @@ "args" ], "additionalProperties": false, + "description": "Local MCP server configuration launched as a child process.", "title": "McpServerConfigLocal" }, "McpServerConfigLocalType": { @@ -3688,6 +4094,7 @@ "local", "stdio" ], + "description": "Local transport type. Defaults to \"local\".", "title": "McpServerConfigLocalType" }, "McpServerList": { @@ -3705,6 +4112,7 @@ "servers" ], "additionalProperties": false, + "description": "MCP servers configured for the session, with their connection status.", "title": "McpServerList" }, "McpServerSource": { @@ -3780,7 +4188,8 @@ "capabilities" ], "additionalProperties": false, - "title": "Model" + "title": "Model", + "description": "Schema for the `Model` type." }, "ModelBilling": { "type": "object", @@ -3916,11 +4325,13 @@ "properties": { "max_prompt_tokens": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Maximum number of prompt/input tokens" }, "max_output_tokens": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Maximum number of output/completion tokens" }, "max_context_window_tokens": { "type": "integer", @@ -3928,7 +4339,8 @@ "description": "Maximum total context window size in tokens" }, "vision": { - "$ref": "#/definitions/ModelCapabilitiesOverrideLimitsVision" + "$ref": "#/definitions/ModelCapabilitiesOverrideLimitsVision", + "description": "Vision-specific limits" } }, "additionalProperties": false, @@ -3957,16 +4369,19 @@ } }, "additionalProperties": false, + "description": "Vision-specific limits", "title": "ModelCapabilitiesOverrideLimitsVision" }, "ModelCapabilitiesOverrideSupports": { "type": "object", "properties": { "vision": { - "type": "boolean" + "type": "boolean", + "description": "Whether this model supports vision/image input" }, "reasoningEffort": { - "type": "boolean" + "type": "boolean", + "description": "Whether this model supports reasoning effort configuration" } }, "additionalProperties": false, @@ -4004,6 +4419,7 @@ "models" ], "additionalProperties": false, + "description": "List of Copilot models available to the resolved user, including capabilities and billing metadata.", "title": "ModelList" }, "ModelPickerCategory": { @@ -4062,6 +4478,7 @@ "additionalProperties": false } ], + "description": "Optional GitHub token used to list models for a specific user instead of the global auth context.", "title": "ModelsListRequest" }, "ModelSwitchToRequest": { @@ -4073,7 +4490,11 @@ }, "reasoningEffort": { "type": "string", - "description": "Reasoning effort level to use for the model" + "description": "Reasoning effort level to use for the model. \"none\" disables reasoning." + }, + "reasoningSummary": { + "$ref": "#/definitions/ReasoningSummary", + "description": "Reasoning summary mode to request for supported model clients" }, "modelCapabilities": { "$ref": "#/definitions/ModelCapabilitiesOverride", @@ -4084,6 +4505,7 @@ "modelId" ], "additionalProperties": false, + "description": "Target model identifier and optional reasoning effort, summary, and capability overrides.", "title": "ModelSwitchToRequest" }, "ModelSwitchToResult": { @@ -4095,6 +4517,7 @@ } }, "additionalProperties": false, + "description": "The model identifier active on the session after the switch.", "title": "ModelSwitchToResult" }, "ModeSetRequest": { @@ -4109,6 +4532,7 @@ "mode" ], "additionalProperties": false, + "description": "Agent interaction mode to apply to the session.", "title": "ModeSetRequest" }, "NameGetResult": { @@ -4126,6 +4550,7 @@ "name" ], "additionalProperties": false, + "description": "The session's friendly name, or null when not yet set.", "title": "NameGetResult" }, "NameSetRequest": { @@ -4142,6 +4567,7 @@ "name" ], "additionalProperties": false, + "description": "New friendly name to apply to the session.", "title": "NameSetRequest" }, "PermissionDecision": { @@ -4165,6 +4591,7 @@ "$ref": "#/definitions/PermissionDecisionUserNotAvailable" } ], + "description": "Decision to apply to a pending permission request.", "title": "PermissionDecision" }, "PermissionDecisionApproveForLocation": { @@ -4190,7 +4617,8 @@ "locationKey" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocation" + "title": "PermissionDecisionApproveForLocation", + "description": "Schema for the `PermissionDecisionApproveForLocation` type." }, "PermissionDecisionApproveForLocationApproval": { "anyOf": [ @@ -4230,13 +4658,15 @@ "properties": { "kind": { "type": "string", - "const": "commands" + "const": "commands", + "description": "Approval scoped to specific command identifiers." }, "commandIdentifiers": { "type": "array", "items": { "type": "string" - } + }, + "description": "Command identifiers covered by this approval." } }, "required": [ @@ -4244,17 +4674,20 @@ "commandIdentifiers" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalCommands" + "title": "PermissionDecisionApproveForLocationApprovalCommands", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalCommands` type." }, "PermissionDecisionApproveForLocationApprovalCustomTool": { "type": "object", "properties": { "kind": { "type": "string", - "const": "custom-tool" + "const": "custom-tool", + "description": "Approval covering a custom tool." }, "toolName": { - "type": "string" + "type": "string", + "description": "Custom tool name." } }, "required": [ @@ -4262,34 +4695,40 @@ "toolName" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalCustomTool" + "title": "PermissionDecisionApproveForLocationApprovalCustomTool", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalCustomTool` type." }, "PermissionDecisionApproveForLocationApprovalExtensionManagement": { "type": "object", "properties": { "kind": { "type": "string", - "const": "extension-management" + "const": "extension-management", + "description": "Approval covering extension lifecycle operations such as enable, disable, or reload." }, "operation": { - "type": "string" + "type": "string", + "description": "Optional operation identifier; when omitted, the approval covers all extension management operations." } }, "required": [ "kind" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalExtensionManagement" + "title": "PermissionDecisionApproveForLocationApprovalExtensionManagement", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalExtensionManagement` type." }, "PermissionDecisionApproveForLocationApprovalExtensionPermissionAccess": { "type": "object", "properties": { "kind": { "type": "string", - "const": "extension-permission-access" + "const": "extension-permission-access", + "description": "Approval covering an extension's request to access a permission-gated capability." }, "extensionName": { - "type": "string" + "type": "string", + "description": "Extension name." } }, "required": [ @@ -4297,23 +4736,27 @@ "extensionName" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalExtensionPermissionAccess" + "title": "PermissionDecisionApproveForLocationApprovalExtensionPermissionAccess", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalExtensionPermissionAccess` type." }, "PermissionDecisionApproveForLocationApprovalMcp": { "type": "object", "properties": { "kind": { "type": "string", - "const": "mcp" + "const": "mcp", + "description": "Approval covering an MCP tool." }, "serverName": { - "type": "string" + "type": "string", + "description": "MCP server name." }, "toolName": { "type": [ "string", "null" - ] + ], + "description": "MCP tool name, or null to cover every tool on the server." } }, "required": [ @@ -4322,17 +4765,20 @@ "toolName" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalMcp" + "title": "PermissionDecisionApproveForLocationApprovalMcp", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalMcp` type." }, "PermissionDecisionApproveForLocationApprovalMcpSampling": { "type": "object", "properties": { "kind": { "type": "string", - "const": "mcp-sampling" + "const": "mcp-sampling", + "description": "Approval covering MCP sampling requests for a server." }, "serverName": { - "type": "string" + "type": "string", + "description": "MCP server name." } }, "required": [ @@ -4340,49 +4786,56 @@ "serverName" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalMcpSampling" + "title": "PermissionDecisionApproveForLocationApprovalMcpSampling", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalMcpSampling` type." }, "PermissionDecisionApproveForLocationApprovalMemory": { "type": "object", "properties": { "kind": { "type": "string", - "const": "memory" + "const": "memory", + "description": "Approval covering writes to long-term memory." } }, "required": [ "kind" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalMemory" + "title": "PermissionDecisionApproveForLocationApprovalMemory", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalMemory` type." }, "PermissionDecisionApproveForLocationApprovalRead": { "type": "object", "properties": { "kind": { "type": "string", - "const": "read" + "const": "read", + "description": "Approval covering read-only filesystem operations." } }, "required": [ "kind" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalRead" + "title": "PermissionDecisionApproveForLocationApprovalRead", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalRead` type." }, "PermissionDecisionApproveForLocationApprovalWrite": { "type": "object", "properties": { "kind": { "type": "string", - "const": "write" + "const": "write", + "description": "Approval covering filesystem write operations." } }, "required": [ "kind" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalWrite" + "title": "PermissionDecisionApproveForLocationApprovalWrite", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalWrite` type." }, "PermissionDecisionApproveForSession": { "type": "object", @@ -4405,7 +4858,8 @@ "kind" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSession" + "title": "PermissionDecisionApproveForSession", + "description": "Schema for the `PermissionDecisionApproveForSession` type." }, "PermissionDecisionApproveForSessionApproval": { "anyOf": [ @@ -4445,13 +4899,15 @@ "properties": { "kind": { "type": "string", - "const": "commands" + "const": "commands", + "description": "Approval scoped to specific command identifiers." }, "commandIdentifiers": { "type": "array", "items": { "type": "string" - } + }, + "description": "Command identifiers covered by this approval." } }, "required": [ @@ -4459,17 +4915,20 @@ "commandIdentifiers" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalCommands" + "title": "PermissionDecisionApproveForSessionApprovalCommands", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalCommands` type." }, "PermissionDecisionApproveForSessionApprovalCustomTool": { "type": "object", "properties": { "kind": { "type": "string", - "const": "custom-tool" + "const": "custom-tool", + "description": "Approval covering a custom tool." }, "toolName": { - "type": "string" + "type": "string", + "description": "Custom tool name." } }, "required": [ @@ -4477,34 +4936,40 @@ "toolName" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalCustomTool" + "title": "PermissionDecisionApproveForSessionApprovalCustomTool", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalCustomTool` type." }, "PermissionDecisionApproveForSessionApprovalExtensionManagement": { "type": "object", "properties": { "kind": { "type": "string", - "const": "extension-management" + "const": "extension-management", + "description": "Approval covering extension lifecycle operations such as enable, disable, or reload." }, "operation": { - "type": "string" + "type": "string", + "description": "Optional operation identifier; when omitted, the approval covers all extension management operations." } }, "required": [ "kind" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalExtensionManagement" + "title": "PermissionDecisionApproveForSessionApprovalExtensionManagement", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalExtensionManagement` type." }, "PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess": { "type": "object", "properties": { "kind": { "type": "string", - "const": "extension-permission-access" + "const": "extension-permission-access", + "description": "Approval covering an extension's request to access a permission-gated capability." }, "extensionName": { - "type": "string" + "type": "string", + "description": "Extension name." } }, "required": [ @@ -4512,23 +4977,27 @@ "extensionName" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess" + "title": "PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess` type." }, "PermissionDecisionApproveForSessionApprovalMcp": { "type": "object", "properties": { "kind": { "type": "string", - "const": "mcp" + "const": "mcp", + "description": "Approval covering an MCP tool." }, "serverName": { - "type": "string" + "type": "string", + "description": "MCP server name." }, "toolName": { "type": [ "string", "null" - ] + ], + "description": "MCP tool name, or null to cover every tool on the server." } }, "required": [ @@ -4537,17 +5006,20 @@ "toolName" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalMcp" + "title": "PermissionDecisionApproveForSessionApprovalMcp", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalMcp` type." }, "PermissionDecisionApproveForSessionApprovalMcpSampling": { "type": "object", "properties": { "kind": { "type": "string", - "const": "mcp-sampling" + "const": "mcp-sampling", + "description": "Approval covering MCP sampling requests for a server." }, "serverName": { - "type": "string" + "type": "string", + "description": "MCP server name." } }, "required": [ @@ -4555,49 +5027,56 @@ "serverName" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalMcpSampling" + "title": "PermissionDecisionApproveForSessionApprovalMcpSampling", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalMcpSampling` type." }, "PermissionDecisionApproveForSessionApprovalMemory": { "type": "object", "properties": { "kind": { "type": "string", - "const": "memory" + "const": "memory", + "description": "Approval covering writes to long-term memory." } }, "required": [ "kind" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalMemory" + "title": "PermissionDecisionApproveForSessionApprovalMemory", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalMemory` type." }, "PermissionDecisionApproveForSessionApprovalRead": { "type": "object", "properties": { "kind": { "type": "string", - "const": "read" + "const": "read", + "description": "Approval covering read-only filesystem operations." } }, "required": [ "kind" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalRead" + "title": "PermissionDecisionApproveForSessionApprovalRead", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalRead` type." }, "PermissionDecisionApproveForSessionApprovalWrite": { "type": "object", "properties": { "kind": { "type": "string", - "const": "write" + "const": "write", + "description": "Approval covering filesystem write operations." } }, "required": [ "kind" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalWrite" + "title": "PermissionDecisionApproveForSessionApprovalWrite", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalWrite` type." }, "PermissionDecisionApproveOnce": { "type": "object", @@ -4612,7 +5091,8 @@ "kind" ], "additionalProperties": false, - "title": "PermissionDecisionApproveOnce" + "title": "PermissionDecisionApproveOnce", + "description": "Schema for the `PermissionDecisionApproveOnce` type." }, "PermissionDecisionApprovePermanently": { "type": "object", @@ -4632,7 +5112,8 @@ "domain" ], "additionalProperties": false, - "title": "PermissionDecisionApprovePermanently" + "title": "PermissionDecisionApprovePermanently", + "description": "Schema for the `PermissionDecisionApprovePermanently` type." }, "PermissionDecisionReject": { "type": "object", @@ -4651,7 +5132,8 @@ "kind" ], "additionalProperties": false, - "title": "PermissionDecisionReject" + "title": "PermissionDecisionReject", + "description": "Schema for the `PermissionDecisionReject` type." }, "PermissionDecisionRequest": { "type": "object", @@ -4661,7 +5143,8 @@ "description": "Request ID of the pending permission request" }, "result": { - "$ref": "#/definitions/PermissionDecision" + "$ref": "#/definitions/PermissionDecision", + "description": "Decision to apply to a pending permission request." } }, "required": [ @@ -4669,6 +5152,7 @@ "result" ], "additionalProperties": false, + "description": "Pending permission request ID and the decision to apply (approve/reject and scope).", "title": "PermissionDecisionRequest" }, "PermissionDecisionUserNotAvailable": { @@ -4684,7 +5168,8 @@ "kind" ], "additionalProperties": false, - "title": "PermissionDecisionUserNotAvailable" + "title": "PermissionDecisionUserNotAvailable", + "description": "Schema for the `PermissionDecisionUserNotAvailable` type." }, "PermissionRequestResult": { "type": "object", @@ -4698,12 +5183,14 @@ "success" ], "additionalProperties": false, + "description": "Indicates whether the permission decision was applied; false when the request was already resolved.", "title": "PermissionRequestResult" }, "PermissionsResetSessionApprovalsRequest": { "type": "object", "properties": {}, "additionalProperties": false, + "description": "No parameters; clears all session-scoped tool permission approvals.", "title": "PermissionsResetSessionApprovalsRequest" }, "PermissionsResetSessionApprovalsResult": { @@ -4718,6 +5205,7 @@ "success" ], "additionalProperties": false, + "description": "Indicates whether the operation succeeded.", "title": "PermissionsResetSessionApprovalsResult" }, "PermissionsSetApproveAllRequest": { @@ -4732,6 +5220,7 @@ "enabled" ], "additionalProperties": false, + "description": "Whether to auto-approve all tool permission requests for the rest of the session.", "title": "PermissionsSetApproveAllRequest" }, "PermissionsSetApproveAllResult": { @@ -4746,6 +5235,7 @@ "success" ], "additionalProperties": false, + "description": "Indicates whether the operation succeeded.", "title": "PermissionsSetApproveAllResult" }, "PingRequest": { @@ -4757,6 +5247,7 @@ } }, "additionalProperties": false, + "description": "Optional message to echo back to the caller.", "title": "PingRequest" }, "PingResult": { @@ -4781,6 +5272,7 @@ "protocolVersion" ], "additionalProperties": false, + "description": "Server liveness response, including the echoed message, current timestamp, and protocol version.", "title": "PingResult" }, "PlanReadResult": { @@ -4811,6 +5303,7 @@ "path" ], "additionalProperties": false, + "description": "Existence, contents, and resolved path of the session plan file.", "title": "PlanReadResult" }, "PlanUpdateRequest": { @@ -4825,6 +5318,7 @@ "content" ], "additionalProperties": false, + "description": "Replacement contents to write to the session plan file.", "title": "PlanUpdateRequest" }, "Plugin": { @@ -4853,7 +5347,8 @@ "enabled" ], "additionalProperties": false, - "title": "Plugin" + "title": "Plugin", + "description": "Schema for the `Plugin` type." }, "PluginList": { "type": "object", @@ -4870,6 +5365,7 @@ "plugins" ], "additionalProperties": false, + "description": "Plugins installed for the session, with their enabled state and version metadata.", "title": "PluginList" }, "QueuedCommandHandled": { @@ -4889,7 +5385,8 @@ "handled" ], "additionalProperties": false, - "title": "QueuedCommandHandled" + "title": "QueuedCommandHandled", + "description": "Schema for the `QueuedCommandHandled` type." }, "QueuedCommandNotHandled": { "type": "object", @@ -4904,7 +5401,8 @@ "handled" ], "additionalProperties": false, - "title": "QueuedCommandNotHandled" + "title": "QueuedCommandNotHandled", + "description": "Schema for the `QueuedCommandNotHandled` type." }, "QueuedCommandResult": { "anyOf": [ @@ -4918,15 +5416,26 @@ "description": "Result of the queued command execution", "title": "QueuedCommandResult" }, + "ReasoningSummary": { + "type": "string", + "enum": [ + "none", + "concise", + "detailed" + ], + "description": "Reasoning summary mode to request for supported model clients", + "title": "ReasoningSummary" + }, "RemoteEnableRequest": { "type": "object", "properties": { "mode": { "$ref": "#/definitions/RemoteSessionMode", - "description": "Per-session remote mode. \"off\" disables remote, \"export\" exports session events to Mission Control without enabling remote steering, \"on\" enables both export and remote steering." + "description": "Per-session remote mode. \"off\" disables remote, \"export\" exports session events to GitHub without enabling remote steering, \"on\" enables both export and remote steering." } }, "additionalProperties": false, + "description": "Optional remote session mode (\"off\", \"export\", or \"on\"); defaults to enabling both export and remote steering.", "title": "RemoteEnableRequest" }, "RemoteEnableResult": { @@ -4934,7 +5443,7 @@ "properties": { "url": { "type": "string", - "description": "Mission Control frontend URL for this session" + "description": "GitHub frontend URL for this session" }, "remoteSteerable": { "type": "boolean", @@ -4945,8 +5454,29 @@ "remoteSteerable" ], "additionalProperties": false, + "description": "GitHub URL for the session and a flag indicating whether remote steering is enabled.", "title": "RemoteEnableResult" }, + "RemoteSessionConnectionResult": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "SDK session ID for the connected remote session." + }, + "metadata": { + "$ref": "#/definitions/ConnectedRemoteSessionMetadata", + "description": "Metadata for a connected remote session." + } + }, + "required": [ + "sessionId", + "metadata" + ], + "additionalProperties": false, + "description": "Remote session connection result.", + "title": "RemoteSessionConnectionResult" + }, "RemoteSessionMode": { "type": "string", "enum": [ @@ -4954,7 +5484,7 @@ "export", "on" ], - "description": "Per-session remote mode. \"off\" disables remote, \"export\" exports session events to Mission Control without enabling remote steering, \"on\" enables both export and remote steering.", + "description": "Per-session remote mode. \"off\" disables remote, \"export\" exports session events to GitHub without enabling remote steering, \"on\" enables both export and remote steering.", "title": "RemoteSessionMode" }, "ServerSkill": { @@ -4997,7 +5527,8 @@ "enabled" ], "additionalProperties": false, - "title": "ServerSkill" + "title": "ServerSkill", + "description": "Schema for the `ServerSkill` type." }, "ServerSkillList": { "type": "object", @@ -5014,6 +5545,7 @@ "skills" ], "additionalProperties": false, + "description": "Skills discovered across global and project sources.", "title": "ServerSkillList" }, "SessionAuthStatus": { @@ -5048,6 +5580,7 @@ "isAuthenticated" ], "additionalProperties": false, + "description": "Authentication status and account metadata for the session.", "title": "SessionAuthStatus" }, "SessionFsAppendFileRequest": { @@ -5072,6 +5605,7 @@ "content" ], "additionalProperties": false, + "description": "File path, content to append, and optional mode for the client-provided session filesystem.", "title": "SessionFsAppendFileRequest" }, "SessionFsError": { @@ -5114,6 +5648,7 @@ "path" ], "additionalProperties": false, + "description": "Path to test for existence in the client-provided session filesystem.", "title": "SessionFsExistsRequest" }, "SessionFsExistsResult": { @@ -5128,6 +5663,7 @@ "exists" ], "additionalProperties": false, + "description": "Indicates whether the requested path exists in the client-provided session filesystem.", "title": "SessionFsExistsResult" }, "SessionFsMkdirRequest": { @@ -5151,6 +5687,7 @@ "path" ], "additionalProperties": false, + "description": "Directory path to create in the client-provided session filesystem, with options for recursive creation and POSIX mode.", "title": "SessionFsMkdirRequest" }, "SessionFsReaddirRequest": { @@ -5165,6 +5702,7 @@ "path" ], "additionalProperties": false, + "description": "Directory path whose entries should be listed from the client-provided session filesystem.", "title": "SessionFsReaddirRequest" }, "SessionFsReaddirResult": { @@ -5186,6 +5724,7 @@ "entries" ], "additionalProperties": false, + "description": "Names of entries in the requested directory, or a filesystem error if the read failed.", "title": "SessionFsReaddirResult" }, "SessionFsReaddirWithTypesEntry": { @@ -5205,7 +5744,8 @@ "type" ], "additionalProperties": false, - "title": "SessionFsReaddirWithTypesEntry" + "title": "SessionFsReaddirWithTypesEntry", + "description": "Schema for the `SessionFsReaddirWithTypesEntry` type." }, "SessionFsReaddirWithTypesEntryType": { "type": "string", @@ -5228,6 +5768,7 @@ "path" ], "additionalProperties": false, + "description": "Directory path whose entries (with type information) should be listed from the client-provided session filesystem.", "title": "SessionFsReaddirWithTypesRequest" }, "SessionFsReaddirWithTypesResult": { @@ -5249,6 +5790,7 @@ "entries" ], "additionalProperties": false, + "description": "Entries in the requested directory paired with file/directory type information, or a filesystem error if the read failed.", "title": "SessionFsReaddirWithTypesResult" }, "SessionFsReadFileRequest": { @@ -5263,6 +5805,7 @@ "path" ], "additionalProperties": false, + "description": "Path of the file to read from the client-provided session filesystem.", "title": "SessionFsReadFileRequest" }, "SessionFsReadFileResult": { @@ -5281,6 +5824,7 @@ "content" ], "additionalProperties": false, + "description": "File content as a UTF-8 string, or a filesystem error if the read failed.", "title": "SessionFsReadFileResult" }, "SessionFsRenameRequest": { @@ -5300,6 +5844,7 @@ "dest" ], "additionalProperties": false, + "description": "Source and destination paths for renaming or moving an entry in the client-provided session filesystem.", "title": "SessionFsRenameRequest" }, "SessionFsRmRequest": { @@ -5322,6 +5867,7 @@ "path" ], "additionalProperties": false, + "description": "Path to remove from the client-provided session filesystem, with options for recursive removal and force.", "title": "SessionFsRmRequest" }, "SessionFsSetProviderConventions": { @@ -5355,6 +5901,7 @@ "conventions" ], "additionalProperties": false, + "description": "Initial working directory, session-state path layout, and path conventions used to register the calling SDK client as the session filesystem provider.", "title": "SessionFsSetProviderRequest" }, "SessionFsSetProviderResult": { @@ -5369,6 +5916,7 @@ "success" ], "additionalProperties": false, + "description": "Indicates whether the calling client was registered as the session filesystem provider.", "title": "SessionFsSetProviderResult" }, "SessionFsStatRequest": { @@ -5383,6 +5931,7 @@ "path" ], "additionalProperties": false, + "description": "Path whose metadata should be returned from the client-provided session filesystem.", "title": "SessionFsStatRequest" }, "SessionFsStatResult": { @@ -5424,6 +5973,7 @@ "birthtime" ], "additionalProperties": false, + "description": "Filesystem metadata for the requested path, or a filesystem error if the stat failed.", "title": "SessionFsStatResult" }, "SessionFsWriteFileRequest": { @@ -5448,6 +5998,7 @@ "content" ], "additionalProperties": false, + "description": "File path, content to write, and optional mode for the client-provided session filesystem.", "title": "SessionFsWriteFileRequest" }, "SessionLogLevel": { @@ -5490,6 +6041,7 @@ "sessionId" ], "additionalProperties": false, + "description": "Source session identifier to fork from, optional event-ID boundary, and optional friendly name for the new session.", "title": "SessionsForkRequest" }, "SessionsForkResult": { @@ -5508,6 +6060,7 @@ "sessionId" ], "additionalProperties": false, + "description": "Identifier and optional friendly name assigned to the newly forked session.", "title": "SessionsForkResult" }, "ShellExecRequest": { @@ -5532,6 +6085,7 @@ "command" ], "additionalProperties": false, + "description": "Shell command to run, with optional working directory and timeout in milliseconds.", "title": "ShellExecRequest" }, "ShellExecResult": { @@ -5546,6 +6100,7 @@ "processId" ], "additionalProperties": false, + "description": "Identifier of the spawned process, used to correlate streamed output and exit notifications.", "title": "ShellExecResult" }, "ShellKillRequest": { @@ -5564,6 +6119,7 @@ "processId" ], "additionalProperties": false, + "description": "Identifier of a process previously returned by \"shell.exec\" and the signal to send.", "title": "ShellKillRequest" }, "ShellKillResult": { @@ -5578,6 +6134,7 @@ "killed" ], "additionalProperties": false, + "description": "Indicates whether the signal was delivered; false if the process was unknown or already exited.", "title": "ShellKillResult" }, "ShellKillSignal": { @@ -5626,7 +6183,8 @@ "enabled" ], "additionalProperties": false, - "title": "Skill" + "title": "Skill", + "description": "Schema for the `Skill` type." }, "SkillList": { "type": "object", @@ -5643,6 +6201,7 @@ "skills" ], "additionalProperties": false, + "description": "Skills available to the session, with their enabled state.", "title": "SkillList" }, "SkillsConfigSetDisabledSkillsRequest": { @@ -5660,6 +6219,7 @@ "disabledSkills" ], "additionalProperties": false, + "description": "Skill names to mark as disabled in global configuration, replacing any previous list.", "title": "SkillsConfigSetDisabledSkillsRequest" }, "SkillsDisableRequest": { @@ -5674,6 +6234,7 @@ "name" ], "additionalProperties": false, + "description": "Name of the skill to disable for the session.", "title": "SkillsDisableRequest" }, "SkillsDiscoverRequest": { @@ -5695,6 +6256,7 @@ } }, "additionalProperties": false, + "description": "Optional project paths and additional skill directories to include in discovery.", "title": "SkillsDiscoverRequest" }, "SkillsEnableRequest": { @@ -5709,6 +6271,7 @@ "name" ], "additionalProperties": false, + "description": "Name of the skill to enable for the session.", "title": "SkillsEnableRequest" }, "SkillsLoadDiagnostics": { @@ -5734,6 +6297,7 @@ "errors" ], "additionalProperties": false, + "description": "Diagnostics from reloading skill definitions, with warnings and errors as separate lists.", "title": "SkillsLoadDiagnostics" }, "SlashCommandAgentPromptMode": { @@ -5777,7 +6341,8 @@ "displayPrompt" ], "additionalProperties": false, - "title": "SlashCommandAgentPromptResult" + "title": "SlashCommandAgentPromptResult", + "description": "Schema for the `SlashCommandAgentPromptResult` type." }, "SlashCommandCompletedResult": { "type": "object", @@ -5800,7 +6365,8 @@ "kind" ], "additionalProperties": false, - "title": "SlashCommandCompletedResult" + "title": "SlashCommandCompletedResult", + "description": "Schema for the `SlashCommandCompletedResult` type." }, "SlashCommandInfo": { "type": "object", @@ -5844,7 +6410,8 @@ "allowDuringAgentExecution" ], "additionalProperties": false, - "title": "SlashCommandInfo" + "title": "SlashCommandInfo", + "description": "Schema for the `SlashCommandInfo` type." }, "SlashCommandInput": { "type": "object", @@ -5893,6 +6460,7 @@ "$ref": "#/definitions/SlashCommandCompletedResult" } ], + "description": "Result of invoking the slash command (text output, prompt to send to the agent, or completion).", "title": "SlashCommandInvocationResult" }, "SlashCommandKind": { @@ -5935,7 +6503,8 @@ "text" ], "additionalProperties": false, - "title": "SlashCommandTextResult" + "title": "SlashCommandTextResult", + "description": "Schema for the `SlashCommandTextResult` type." }, "TaskAgentInfo": { "type": "object", @@ -6030,7 +6599,8 @@ "prompt" ], "additionalProperties": false, - "title": "TaskAgentInfo" + "title": "TaskAgentInfo", + "description": "Schema for the `TaskAgentInfo` type." }, "TaskAgentInfoExecutionMode": { "type": "string", @@ -6062,7 +6632,8 @@ "$ref": "#/definitions/TaskShellInfo" } ], - "title": "TaskInfo" + "title": "TaskInfo", + "description": "Schema for the `TaskInfo` type." }, "TaskList": { "type": "object", @@ -6079,6 +6650,7 @@ "tasks" ], "additionalProperties": false, + "description": "Background tasks currently tracked by the session.", "title": "TaskList" }, "TasksCancelRequest": { @@ -6093,6 +6665,7 @@ "id" ], "additionalProperties": false, + "description": "Identifier of the background task to cancel.", "title": "TasksCancelRequest" }, "TasksCancelResult": { @@ -6107,6 +6680,7 @@ "cancelled" ], "additionalProperties": false, + "description": "Indicates whether the background task was successfully cancelled.", "title": "TasksCancelResult" }, "TaskShellInfo": { @@ -6174,7 +6748,8 @@ "attachmentMode" ], "additionalProperties": false, - "title": "TaskShellInfo" + "title": "TaskShellInfo", + "description": "Schema for the `TaskShellInfo` type." }, "TaskShellInfoAttachmentMode": { "type": "string", @@ -6218,6 +6793,7 @@ "id" ], "additionalProperties": false, + "description": "Identifier of the task to promote to background mode.", "title": "TasksPromoteToBackgroundRequest" }, "TasksPromoteToBackgroundResult": { @@ -6232,6 +6808,7 @@ "promoted" ], "additionalProperties": false, + "description": "Indicates whether the task was successfully promoted to background mode.", "title": "TasksPromoteToBackgroundResult" }, "TasksRemoveRequest": { @@ -6246,6 +6823,7 @@ "id" ], "additionalProperties": false, + "description": "Identifier of the completed or cancelled task to remove from tracking.", "title": "TasksRemoveRequest" }, "TasksRemoveResult": { @@ -6260,6 +6838,7 @@ "removed" ], "additionalProperties": false, + "description": "Indicates whether the task was removed. False when the task does not exist or is still running/idle.", "title": "TasksRemoveResult" }, "TasksSendMessageRequest": { @@ -6283,6 +6862,7 @@ "message" ], "additionalProperties": false, + "description": "Identifier of the target agent task, message content, and optional sender agent ID.", "title": "TasksSendMessageRequest" }, "TasksSendMessageResult": { @@ -6301,6 +6881,7 @@ "sent" ], "additionalProperties": false, + "description": "Indicates whether the message was delivered, with an error message when delivery failed.", "title": "TasksSendMessageResult" }, "TasksStartAgentRequest": { @@ -6333,6 +6914,7 @@ "name" ], "additionalProperties": false, + "description": "Agent type, prompt, name, and optional description and model override for the new task.", "title": "TasksStartAgentRequest" }, "TasksStartAgentResult": { @@ -6347,6 +6929,7 @@ "agentId" ], "additionalProperties": false, + "description": "Identifier assigned to the newly started background agent task.", "title": "TasksStartAgentResult" }, "Tool": { @@ -6379,7 +6962,8 @@ "description" ], "additionalProperties": false, - "title": "Tool" + "title": "Tool", + "description": "Schema for the `Tool` type." }, "ToolList": { "type": "object", @@ -6396,6 +6980,7 @@ "tools" ], "additionalProperties": false, + "description": "Built-in tools available for the requested model, with their parameters and instructions.", "title": "ToolList" }, "ToolsListRequest": { @@ -6407,6 +6992,7 @@ } }, "additionalProperties": false, + "description": "Optional model identifier whose tool overrides should be applied to the listing.", "title": "ToolsListRequest" }, "UIElicitationArrayAnyOfField": { @@ -6414,28 +7000,35 @@ "properties": { "type": { "type": "string", - "const": "array" + "const": "array", + "description": "Type discriminator. Always \"array\"." }, "title": { - "type": "string" + "type": "string", + "description": "Human-readable label for the field." }, "description": { - "type": "string" + "type": "string", + "description": "Help text describing the field." }, "minItems": { - "type": "number" + "type": "number", + "description": "Minimum number of items the user must select." }, "maxItems": { - "type": "number" + "type": "number", + "description": "Maximum number of items the user may select." }, "items": { - "$ref": "#/definitions/UIElicitationArrayAnyOfFieldItems" + "$ref": "#/definitions/UIElicitationArrayAnyOfFieldItems", + "description": "Schema applied to each item in the array." }, "default": { "type": "array", "items": { "type": "string" - } + }, + "description": "Default values selected when the form is first shown." } }, "required": [ @@ -6443,6 +7036,7 @@ "items" ], "additionalProperties": false, + "description": "Multi-select string field where each option pairs a value with a display label.", "title": "UIElicitationArrayAnyOfField" }, "UIElicitationArrayAnyOfFieldItems": { @@ -6452,23 +7046,27 @@ "type": "array", "items": { "$ref": "#/definitions/UIElicitationArrayAnyOfFieldItemsAnyOf" - } + }, + "description": "Selectable options, each with a value and a display label." } }, "required": [ "anyOf" ], "additionalProperties": false, + "description": "Schema applied to each item in the array.", "title": "UIElicitationArrayAnyOfFieldItems" }, "UIElicitationArrayAnyOfFieldItemsAnyOf": { "type": "object", "properties": { "const": { - "type": "string" + "type": "string", + "description": "Value submitted when this option is selected." }, "title": { - "type": "string" + "type": "string", + "description": "Display label for this option." } }, "required": [ @@ -6476,35 +7074,43 @@ "title" ], "additionalProperties": false, - "title": "UIElicitationArrayAnyOfFieldItemsAnyOf" + "title": "UIElicitationArrayAnyOfFieldItemsAnyOf", + "description": "Schema for the `UIElicitationArrayAnyOfFieldItemsAnyOf` type." }, "UIElicitationArrayEnumField": { "type": "object", "properties": { "type": { "type": "string", - "const": "array" + "const": "array", + "description": "Type discriminator. Always \"array\"." }, "title": { - "type": "string" + "type": "string", + "description": "Human-readable label for the field." }, "description": { - "type": "string" + "type": "string", + "description": "Help text describing the field." }, "minItems": { - "type": "number" + "type": "number", + "description": "Minimum number of items the user must select." }, "maxItems": { - "type": "number" + "type": "number", + "description": "Maximum number of items the user may select." }, "items": { - "$ref": "#/definitions/UIElicitationArrayEnumFieldItems" + "$ref": "#/definitions/UIElicitationArrayEnumFieldItems", + "description": "Schema applied to each item in the array." }, "default": { "type": "array", "items": { "type": "string" - } + }, + "description": "Default values selected when the form is first shown." } }, "required": [ @@ -6512,6 +7118,7 @@ "items" ], "additionalProperties": false, + "description": "Multi-select string field whose allowed values are defined inline.", "title": "UIElicitationArrayEnumField" }, "UIElicitationArrayEnumFieldItems": { @@ -6519,13 +7126,15 @@ "properties": { "type": { "type": "string", - "const": "string" + "const": "string", + "description": "Type discriminator. Always \"string\"." }, "enum": { "type": "array", "items": { "type": "string" - } + }, + "description": "Allowed string values for each selected item." } }, "required": [ @@ -6533,6 +7142,7 @@ "enum" ], "additionalProperties": false, + "description": "Schema applied to each item in the array.", "title": "UIElicitationArrayEnumFieldItems" }, "UIElicitationFieldValue": { @@ -6553,7 +7163,8 @@ } } ], - "title": "UIElicitationFieldValue" + "title": "UIElicitationFieldValue", + "description": "Schema for the `UIElicitationFieldValue` type." }, "UIElicitationRequest": { "type": "object", @@ -6572,6 +7183,7 @@ "requestedSchema" ], "additionalProperties": false, + "description": "Prompt message and JSON schema describing the form fields to elicit from the user.", "title": "UIElicitationRequest" }, "UIElicitationResponse": { @@ -6623,6 +7235,7 @@ "success" ], "additionalProperties": false, + "description": "Indicates whether the elicitation response was accepted; false if it was already resolved by another client.", "title": "UIElicitationResult" }, "UIElicitationSchema": { @@ -6636,7 +7249,8 @@ "properties": { "type": "object", "additionalProperties": { - "$ref": "#/definitions/UIElicitationSchemaProperty" + "$ref": "#/definitions/UIElicitationSchemaProperty", + "description": "Definition for a single elicitation form field." }, "description": "Form field definitions, keyed by field name" }, @@ -6659,27 +7273,35 @@ "UIElicitationSchemaProperty": { "anyOf": [ { - "$ref": "#/definitions/UIElicitationStringEnumField" + "$ref": "#/definitions/UIElicitationStringEnumField", + "description": "Single-select string field whose allowed values are defined inline." }, { - "$ref": "#/definitions/UIElicitationStringOneOfField" + "$ref": "#/definitions/UIElicitationStringOneOfField", + "description": "Single-select string field where each option pairs a value with a display label." }, { - "$ref": "#/definitions/UIElicitationArrayEnumField" + "$ref": "#/definitions/UIElicitationArrayEnumField", + "description": "Multi-select string field whose allowed values are defined inline." }, { - "$ref": "#/definitions/UIElicitationArrayAnyOfField" + "$ref": "#/definitions/UIElicitationArrayAnyOfField", + "description": "Multi-select string field where each option pairs a value with a display label." }, { - "$ref": "#/definitions/UIElicitationSchemaPropertyBoolean" + "$ref": "#/definitions/UIElicitationSchemaPropertyBoolean", + "description": "Boolean field rendered as a yes/no toggle." }, { - "$ref": "#/definitions/UIElicitationSchemaPropertyString" + "$ref": "#/definitions/UIElicitationSchemaPropertyString", + "description": "Free-text string field with optional length and format constraints." }, { - "$ref": "#/definitions/UIElicitationSchemaPropertyNumber" + "$ref": "#/definitions/UIElicitationSchemaPropertyNumber", + "description": "Numeric field accepting either a number or an integer." } ], + "description": "Definition for a single elicitation form field.", "title": "UIElicitationSchemaProperty" }, "UIElicitationSchemaPropertyBoolean": { @@ -6687,50 +7309,62 @@ "properties": { "type": { "type": "string", - "const": "boolean" + "const": "boolean", + "description": "Type discriminator. Always \"boolean\"." }, "title": { - "type": "string" + "type": "string", + "description": "Human-readable label for the field." }, "description": { - "type": "string" + "type": "string", + "description": "Help text describing the field." }, "default": { - "type": "boolean" + "type": "boolean", + "description": "Default value selected when the form is first shown." } }, "required": [ "type" ], "additionalProperties": false, + "description": "Boolean field rendered as a yes/no toggle.", "title": "UIElicitationSchemaPropertyBoolean" }, "UIElicitationSchemaPropertyNumber": { "type": "object", "properties": { "type": { - "$ref": "#/definitions/UIElicitationSchemaPropertyNumberType" + "$ref": "#/definitions/UIElicitationSchemaPropertyNumberType", + "description": "Numeric type accepted by the field." }, "title": { - "type": "string" + "type": "string", + "description": "Human-readable label for the field." }, "description": { - "type": "string" + "type": "string", + "description": "Help text describing the field." }, "minimum": { - "type": "number" + "type": "number", + "description": "Minimum allowed value (inclusive)." }, "maximum": { - "type": "number" + "type": "number", + "description": "Maximum allowed value (inclusive)." }, "default": { - "type": "number" + "type": "number", + "description": "Default value populated in the input when the form is first shown." } }, "required": [ "type" ], "additionalProperties": false, + "description": "Numeric field accepting either a number or an integer.", "title": "UIElicitationSchemaPropertyNumber" }, "UIElicitationSchemaPropertyNumberType": { @@ -6739,6 +7373,7 @@ "number", "integer" ], + "description": "Numeric type accepted by the field.", "title": "UIElicitationSchemaPropertyNumberType" }, "UIElicitationSchemaPropertyString": { @@ -6746,31 +7381,39 @@ "properties": { "type": { "type": "string", - "const": "string" + "const": "string", + "description": "Type discriminator. Always \"string\"." }, "title": { - "type": "string" + "type": "string", + "description": "Human-readable label for the field." }, "description": { - "type": "string" + "type": "string", + "description": "Help text describing the field." }, "minLength": { - "type": "number" + "type": "number", + "description": "Minimum number of characters required." }, "maxLength": { - "type": "number" + "type": "number", + "description": "Maximum number of characters allowed." }, "format": { - "$ref": "#/definitions/UIElicitationSchemaPropertyStringFormat" + "$ref": "#/definitions/UIElicitationSchemaPropertyStringFormat", + "description": "Optional format hint that constrains the accepted input." }, "default": { - "type": "string" + "type": "string", + "description": "Default value populated in the input when the form is first shown." } }, "required": [ "type" ], "additionalProperties": false, + "description": "Free-text string field with optional length and format constraints.", "title": "UIElicitationSchemaPropertyString" }, "UIElicitationSchemaPropertyStringFormat": { @@ -6781,6 +7424,7 @@ "date", "date-time" ], + "description": "Optional format hint that constrains the accepted input.", "title": "UIElicitationSchemaPropertyStringFormat" }, "UIElicitationStringEnumField": { @@ -6788,28 +7432,34 @@ "properties": { "type": { "type": "string", - "const": "string" + "const": "string", + "description": "Type discriminator. Always \"string\"." }, "title": { - "type": "string" + "type": "string", + "description": "Human-readable label for the field." }, "description": { - "type": "string" + "type": "string", + "description": "Help text describing the field." }, "enum": { "type": "array", "items": { "type": "string" - } + }, + "description": "Allowed string values." }, "enumNames": { "type": "array", "items": { "type": "string" - } + }, + "description": "Optional display labels for each enum value, in the same order as `enum`." }, "default": { - "type": "string" + "type": "string", + "description": "Default value selected when the form is first shown." } }, "required": [ @@ -6817,6 +7467,7 @@ "enum" ], "additionalProperties": false, + "description": "Single-select string field whose allowed values are defined inline.", "title": "UIElicitationStringEnumField" }, "UIElicitationStringOneOfField": { @@ -6824,22 +7475,27 @@ "properties": { "type": { "type": "string", - "const": "string" + "const": "string", + "description": "Type discriminator. Always \"string\"." }, "title": { - "type": "string" + "type": "string", + "description": "Human-readable label for the field." }, "description": { - "type": "string" + "type": "string", + "description": "Help text describing the field." }, "oneOf": { "type": "array", "items": { "$ref": "#/definitions/UIElicitationStringOneOfFieldOneOf" - } + }, + "description": "Selectable options, each with a value and a display label." }, "default": { - "type": "string" + "type": "string", + "description": "Default value selected when the form is first shown." } }, "required": [ @@ -6847,16 +7503,19 @@ "oneOf" ], "additionalProperties": false, + "description": "Single-select string field where each option pairs a value with a display label.", "title": "UIElicitationStringOneOfField" }, "UIElicitationStringOneOfFieldOneOf": { "type": "object", "properties": { "const": { - "type": "string" + "type": "string", + "description": "Value submitted when this option is selected." }, "title": { - "type": "string" + "type": "string", + "description": "Display label for this option." } }, "required": [ @@ -6864,7 +7523,8 @@ "title" ], "additionalProperties": false, - "title": "UIElicitationStringOneOfFieldOneOf" + "title": "UIElicitationStringOneOfFieldOneOf", + "description": "Schema for the `UIElicitationStringOneOfFieldOneOf` type." }, "UIHandlePendingElicitationRequest": { "type": "object", @@ -6883,6 +7543,7 @@ "result" ], "additionalProperties": false, + "description": "Pending elicitation request ID and the user's response (accept/decline/cancel + form values).", "title": "UIHandlePendingElicitationRequest" }, "UsageGetMetricsResult": { @@ -6956,6 +7617,7 @@ "lastCallOutputTokens" ], "additionalProperties": false, + "description": "Accumulated session usage metrics, including premium request cost, token counts, model breakdown, and code-change totals.", "title": "UsageGetMetricsResult" }, "UsageMetricsCodeChanges": { @@ -7012,7 +7674,8 @@ "usage" ], "additionalProperties": false, - "title": "UsageMetricsModelMetric" + "title": "UsageMetricsModelMetric", + "description": "Schema for the `UsageMetricsModelMetric` type." }, "UsageMetricsModelMetricRequests": { "type": "object", @@ -7047,7 +7710,8 @@ "tokenCount" ], "additionalProperties": false, - "title": "UsageMetricsModelMetricTokenDetail" + "title": "UsageMetricsModelMetricTokenDetail", + "description": "Schema for the `UsageMetricsModelMetricTokenDetail` type." }, "UsageMetricsModelMetricUsage": { "type": "object", @@ -7101,7 +7765,8 @@ "tokenCount" ], "additionalProperties": false, - "title": "UsageMetricsTokenDetail" + "title": "UsageMetricsTokenDetail", + "description": "Schema for the `UsageMetricsTokenDetail` type." }, "WorkspacesCreateFileRequest": { "type": "object", @@ -7120,6 +7785,7 @@ "content" ], "additionalProperties": false, + "description": "Relative path and UTF-8 content for the workspace file to create or overwrite.", "title": "WorkspacesCreateFileRequest" }, "WorkspacesGetWorkspaceResult": { @@ -7204,6 +7870,7 @@ "workspace" ], "additionalProperties": false, + "description": "Current workspace metadata for the session, or null when not available.", "title": "WorkspacesGetWorkspaceResult" }, "WorkspacesListFilesResult": { @@ -7221,6 +7888,7 @@ "files" ], "additionalProperties": false, + "description": "Relative paths of files stored in the session workspace files directory.", "title": "WorkspacesListFilesResult" }, "WorkspacesReadFileRequest": { @@ -7235,6 +7903,7 @@ "path" ], "additionalProperties": false, + "description": "Relative path of the workspace file to read.", "title": "WorkspacesReadFileRequest" }, "WorkspacesReadFileResult": { @@ -7249,6 +7918,7 @@ "content" ], "additionalProperties": false, + "description": "Contents of the requested workspace file as a UTF-8 string.", "title": "WorkspacesReadFileResult" } } diff --git a/schemas/session-events.schema.json b/schemas/session-events.schema.json index ce89f29..37ff396 100644 --- a/schemas/session-events.schema.json +++ b/schemas/session-events.schema.json @@ -51,7 +51,8 @@ }, "type": { "type": "string", - "const": "abort" + "const": "abort", + "description": "Type discriminator. Always \"abort\"." }, "data": { "$ref": "#/definitions/AbortData", @@ -66,6 +67,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"abort\". Turn abort information including the reason for termination", "title": "AbortEvent" }, "AbortReason": { @@ -120,7 +122,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -128,7 +131,8 @@ }, "type": { "type": "string", - "const": "assistant.intent" + "const": "assistant.intent", + "description": "Type discriminator. Always \"assistant.intent\"." }, "data": { "$ref": "#/definitions/AssistantIntentData", @@ -144,6 +148,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"assistant.intent\". Agent intent description for current activity or plan", "title": "AssistantIntentEvent" }, "AssistantMessageData": { @@ -276,7 +281,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -284,7 +290,8 @@ }, "type": { "type": "string", - "const": "assistant.message_delta" + "const": "assistant.message_delta", + "description": "Type discriminator. Always \"assistant.message_delta\"." }, "data": { "$ref": "#/definitions/AssistantMessageDeltaData", @@ -300,6 +307,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"assistant.message_delta\". Streaming assistant message delta for incremental response updates", "title": "AssistantMessageDeltaEvent" }, "AssistantMessageEvent": { @@ -337,7 +345,8 @@ }, "type": { "type": "string", - "const": "assistant.message" + "const": "assistant.message", + "description": "Type discriminator. Always \"assistant.message\"." }, "data": { "$ref": "#/definitions/AssistantMessageData", @@ -352,6 +361,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"assistant.message\". Assistant response containing text content, optional tool requests, and interaction metadata", "title": "AssistantMessageEvent" }, "AssistantMessageStartData": { @@ -400,7 +410,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -408,7 +419,8 @@ }, "type": { "type": "string", - "const": "assistant.message_start" + "const": "assistant.message_start", + "description": "Type discriminator. Always \"assistant.message_start\"." }, "data": { "$ref": "#/definitions/AssistantMessageStartData", @@ -424,6 +436,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"assistant.message_start\". Streaming assistant message start metadata", "title": "AssistantMessageStartEvent" }, "AssistantMessageToolRequest": { @@ -548,7 +561,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -556,7 +570,8 @@ }, "type": { "type": "string", - "const": "assistant.reasoning_delta" + "const": "assistant.reasoning_delta", + "description": "Type discriminator. Always \"assistant.reasoning_delta\"." }, "data": { "$ref": "#/definitions/AssistantReasoningDeltaData", @@ -572,6 +587,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"assistant.reasoning_delta\". Streaming reasoning delta for incremental extended thinking updates", "title": "AssistantReasoningDeltaEvent" }, "AssistantReasoningEvent": { @@ -609,7 +625,8 @@ }, "type": { "type": "string", - "const": "assistant.reasoning" + "const": "assistant.reasoning", + "description": "Type discriminator. Always \"assistant.reasoning\"." }, "data": { "$ref": "#/definitions/AssistantReasoningData", @@ -624,6 +641,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"assistant.reasoning\". Assistant reasoning content for timeline display with complete thinking text", "title": "AssistantReasoningEvent" }, "AssistantStreamingDeltaData": { @@ -668,7 +686,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -676,7 +695,8 @@ }, "type": { "type": "string", - "const": "assistant.streaming_delta" + "const": "assistant.streaming_delta", + "description": "Type discriminator. Always \"assistant.streaming_delta\"." }, "data": { "$ref": "#/definitions/AssistantStreamingDeltaData", @@ -692,6 +712,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"assistant.streaming_delta\". Streaming response progress with cumulative byte count", "title": "AssistantStreamingDeltaEvent" }, "AssistantTurnEndData": { @@ -744,7 +765,8 @@ }, "type": { "type": "string", - "const": "assistant.turn_end" + "const": "assistant.turn_end", + "description": "Type discriminator. Always \"assistant.turn_end\"." }, "data": { "$ref": "#/definitions/AssistantTurnEndData", @@ -759,6 +781,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"assistant.turn_end\". Turn completion metadata including the turn identifier", "title": "AssistantTurnEndEvent" }, "AssistantTurnStartData": { @@ -815,7 +838,8 @@ }, "type": { "type": "string", - "const": "assistant.turn_start" + "const": "assistant.turn_start", + "description": "Type discriminator. Always \"assistant.turn_start\"." }, "data": { "$ref": "#/definitions/AssistantTurnStartData", @@ -830,6 +854,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"assistant.turn_start\". Turn initialization metadata including identifier and interaction tracking", "title": "AssistantTurnStartEvent" }, "AssistantUsageApiEndpoint": { @@ -974,7 +999,7 @@ }, "reasoningEffort": { "type": "string", - "description": "Reasoning effort level used for model calls, if applicable (e.g. \"low\", \"medium\", \"high\", \"xhigh\")" + "description": "Reasoning effort level used for model calls, if applicable (e.g. \"none\", \"low\", \"medium\", \"high\", \"xhigh\")" } }, "required": [ @@ -1011,7 +1036,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -1019,7 +1045,8 @@ }, "type": { "type": "string", - "const": "assistant.usage" + "const": "assistant.usage", + "description": "Type discriminator. Always \"assistant.usage\"." }, "data": { "$ref": "#/definitions/AssistantUsageData", @@ -1035,6 +1062,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"assistant.usage\". LLM API call usage metrics including tokens, costs, quotas, and billing information", "title": "AssistantUsageEvent" }, "AssistantUsageQuotaSnapshot": { @@ -1084,7 +1112,8 @@ "remainingPercentage" ], "additionalProperties": false, - "title": "AssistantUsageQuotaSnapshot" + "title": "AssistantUsageQuotaSnapshot", + "description": "Schema for the `AssistantUsageQuotaSnapshot` type." }, "AutoModeSwitchCompletedData": { "type": "object", @@ -1133,7 +1162,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -1141,7 +1171,8 @@ }, "type": { "type": "string", - "const": "auto_mode_switch.completed" + "const": "auto_mode_switch.completed", + "description": "Type discriminator. Always \"auto_mode_switch.completed\"." }, "data": { "$ref": "#/definitions/AutoModeSwitchCompletedData", @@ -1157,6 +1188,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"auto_mode_switch.completed\". Auto mode switch completion notification", "title": "AutoModeSwitchCompletedEvent" }, "AutoModeSwitchRequestedData": { @@ -1209,7 +1241,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -1217,7 +1250,8 @@ }, "type": { "type": "string", - "const": "auto_mode_switch.requested" + "const": "auto_mode_switch.requested", + "description": "Type discriminator. Always \"auto_mode_switch.requested\"." }, "data": { "$ref": "#/definitions/AutoModeSwitchRequestedData", @@ -1233,13 +1267,15 @@ "data" ], "additionalProperties": false, + "description": "Session event \"auto_mode_switch.requested\". Auto mode switch request notification requiring user approval", "title": "AutoModeSwitchRequestedEvent" }, "BackgroundTasksChangedData": { "type": "object", "properties": {}, "additionalProperties": false, - "title": "BackgroundTasksChangedData" + "title": "BackgroundTasksChangedData", + "description": "Schema for the `BackgroundTasksChangedData` type." }, "BackgroundTasksChangedEvent": { "type": "object", @@ -1268,7 +1304,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -1276,10 +1313,12 @@ }, "type": { "type": "string", - "const": "session.background_tasks_changed" + "const": "session.background_tasks_changed", + "description": "Type discriminator. Always \"session.background_tasks_changed\"." }, "data": { - "$ref": "#/definitions/BackgroundTasksChangedData" + "$ref": "#/definitions/BackgroundTasksChangedData", + "description": "Schema for the `BackgroundTasksChangedData` type." } }, "required": [ @@ -1291,6 +1330,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.background_tasks_changed\".", "title": "BackgroundTasksChangedEvent" }, "CapabilitiesChangedData": { @@ -1332,7 +1372,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -1340,7 +1381,8 @@ }, "type": { "type": "string", - "const": "capabilities.changed" + "const": "capabilities.changed", + "description": "Type discriminator. Always \"capabilities.changed\"." }, "data": { "$ref": "#/definitions/CapabilitiesChangedData", @@ -1356,6 +1398,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"capabilities.changed\". Session capability change notification", "title": "CapabilitiesChangedEvent" }, "CapabilitiesChangedUI": { @@ -1412,7 +1455,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -1420,7 +1464,8 @@ }, "type": { "type": "string", - "const": "command.completed" + "const": "command.completed", + "description": "Type discriminator. Always \"command.completed\"." }, "data": { "$ref": "#/definitions/CommandCompletedData", @@ -1436,6 +1481,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"command.completed\". Queued command completion notification signaling UI dismissal", "title": "CommandCompletedEvent" }, "CommandExecuteData": { @@ -1495,7 +1541,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -1503,7 +1550,8 @@ }, "type": { "type": "string", - "const": "command.execute" + "const": "command.execute", + "description": "Type discriminator. Always \"command.execute\"." }, "data": { "$ref": "#/definitions/CommandExecuteData", @@ -1519,6 +1567,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"command.execute\". Registered command dispatch request routed to the owning client", "title": "CommandExecuteEvent" }, "CommandQueuedData": { @@ -1568,7 +1617,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -1576,7 +1626,8 @@ }, "type": { "type": "string", - "const": "command.queued" + "const": "command.queued", + "description": "Type discriminator. Always \"command.queued\"." }, "data": { "$ref": "#/definitions/CommandQueuedData", @@ -1592,23 +1643,27 @@ "data" ], "additionalProperties": false, + "description": "Session event \"command.queued\". Queued slash command dispatch request for client execution", "title": "CommandQueuedEvent" }, "CommandsChangedCommand": { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Slash command name without the leading slash." }, "description": { - "type": "string" + "type": "string", + "description": "Optional human-readable command description." } }, "required": [ "name" ], "additionalProperties": false, - "title": "CommandsChangedCommand" + "title": "CommandsChangedCommand", + "description": "Schema for the `CommandsChangedCommand` type." }, "CommandsChangedData": { "type": "object", @@ -1655,7 +1710,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -1663,7 +1719,8 @@ }, "type": { "type": "string", - "const": "commands.changed" + "const": "commands.changed", + "description": "Type discriminator. Always \"commands.changed\"." }, "data": { "$ref": "#/definitions/CommandsChangedData", @@ -1679,6 +1736,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"commands.changed\". SDK command registration change notification", "title": "CommandsChangedEvent" }, "CompactionCompleteCompactionTokensUsed": { @@ -1877,7 +1935,8 @@ }, "type": { "type": "string", - "const": "session.compaction_complete" + "const": "session.compaction_complete", + "description": "Type discriminator. Always \"session.compaction_complete\"." }, "data": { "$ref": "#/definitions/CompactionCompleteData", @@ -1892,6 +1951,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.compaction_complete\". Conversation compaction results including success status, metrics, and optional error details", "title": "CompactionCompleteEvent" }, "CompactionStartData": { @@ -1949,7 +2009,8 @@ }, "type": { "type": "string", - "const": "session.compaction_start" + "const": "session.compaction_start", + "description": "Type discriminator. Always \"session.compaction_start\"." }, "data": { "$ref": "#/definitions/CompactionStartData", @@ -1964,6 +2025,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.compaction_start\". Context window breakdown at the start of LLM-powered conversation compaction", "title": "CompactionStartEvent" }, "ContextChangedEvent": { @@ -2001,7 +2063,8 @@ }, "type": { "type": "string", - "const": "session.context_changed" + "const": "session.context_changed", + "description": "Type discriminator. Always \"session.context_changed\"." }, "data": { "$ref": "#/definitions/WorkingDirectoryContext", @@ -2016,6 +2079,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.context_changed\". Updated working directory and git context after the change", "title": "ContextChangedEvent" }, "CustomAgentsUpdatedAgent": { @@ -2074,7 +2138,8 @@ "userInvocable" ], "additionalProperties": false, - "title": "CustomAgentsUpdatedAgent" + "title": "CustomAgentsUpdatedAgent", + "description": "Schema for the `CustomAgentsUpdatedAgent` type." }, "CustomAgentsUpdatedData": { "type": "object", @@ -2107,7 +2172,8 @@ "errors" ], "additionalProperties": false, - "title": "CustomAgentsUpdatedData" + "title": "CustomAgentsUpdatedData", + "description": "Schema for the `CustomAgentsUpdatedData` type." }, "CustomAgentsUpdatedEvent": { "type": "object", @@ -2136,7 +2202,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -2144,10 +2211,12 @@ }, "type": { "type": "string", - "const": "session.custom_agents_updated" + "const": "session.custom_agents_updated", + "description": "Type discriminator. Always \"session.custom_agents_updated\"." }, "data": { - "$ref": "#/definitions/CustomAgentsUpdatedData" + "$ref": "#/definitions/CustomAgentsUpdatedData", + "description": "Schema for the `CustomAgentsUpdatedData` type." } }, "required": [ @@ -2159,6 +2228,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.custom_agents_updated\".", "title": "CustomAgentsUpdatedEvent" }, "CustomNotificationData": { @@ -2224,7 +2294,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -2232,7 +2303,8 @@ }, "type": { "type": "string", - "const": "session.custom_notification" + "const": "session.custom_notification", + "description": "Type discriminator. Always \"session.custom_notification\"." }, "data": { "$ref": "#/definitions/CustomNotificationData", @@ -2248,6 +2320,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.custom_notification\". Opaque custom notification data. Consumers may branch on source and name, but payload semantics are source-defined.", "title": "CustomNotificationEvent" }, "CustomNotificationPayload": { @@ -2312,7 +2385,8 @@ } } ], - "title": "ElicitationCompletedContent" + "title": "ElicitationCompletedContent", + "description": "Schema for the `ElicitationCompletedContent` type." }, "ElicitationCompletedData": { "type": "object", @@ -2367,7 +2441,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -2375,7 +2450,8 @@ }, "type": { "type": "string", - "const": "elicitation.completed" + "const": "elicitation.completed", + "description": "Type discriminator. Always \"elicitation.completed\"." }, "data": { "$ref": "#/definitions/ElicitationCompletedData", @@ -2391,6 +2467,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"elicitation.completed\". Elicitation request completion with the user's response", "title": "ElicitationCompletedEvent" }, "ElicitationRequestedData": { @@ -2460,7 +2537,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -2468,7 +2546,8 @@ }, "type": { "type": "string", - "const": "elicitation.requested" + "const": "elicitation.requested", + "description": "Type discriminator. Always \"elicitation.requested\"." }, "data": { "$ref": "#/definitions/ElicitationRequestedData", @@ -2484,6 +2563,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"elicitation.requested\". Elicitation request; may be form-based (structured input) or URL-based (browser redirect)", "title": "ElicitationRequestedEvent" }, "ElicitationRequestedMode": { @@ -2546,7 +2626,8 @@ "blob" ], "additionalProperties": false, - "title": "EmbeddedBlobResourceContents" + "title": "EmbeddedBlobResourceContents", + "description": "Schema for the `EmbeddedBlobResourceContents` type." }, "EmbeddedTextResourceContents": { "type": "object", @@ -2569,7 +2650,8 @@ "text" ], "additionalProperties": false, - "title": "EmbeddedTextResourceContents" + "title": "EmbeddedTextResourceContents", + "description": "Schema for the `EmbeddedTextResourceContents` type." }, "ErrorData": { "type": "object", @@ -2651,7 +2733,8 @@ }, "type": { "type": "string", - "const": "session.error" + "const": "session.error", + "description": "Type discriminator. Always \"session.error\"." }, "data": { "$ref": "#/definitions/ErrorData", @@ -2666,6 +2749,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.error\". Error details for timeline display including message and optional diagnostic information", "title": "ErrorEvent" }, "ExitPlanModeCompletedData": { @@ -2726,7 +2810,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -2734,7 +2819,8 @@ }, "type": { "type": "string", - "const": "exit_plan_mode.completed" + "const": "exit_plan_mode.completed", + "description": "Type discriminator. Always \"exit_plan_mode.completed\"." }, "data": { "$ref": "#/definitions/ExitPlanModeCompletedData", @@ -2750,6 +2836,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"exit_plan_mode.completed\". Plan mode exit completion with the user's approval decision and optional feedback", "title": "ExitPlanModeCompletedEvent" }, "ExitPlanModeRequestedData": { @@ -2817,7 +2904,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -2825,7 +2913,8 @@ }, "type": { "type": "string", - "const": "exit_plan_mode.requested" + "const": "exit_plan_mode.requested", + "description": "Type discriminator. Always \"exit_plan_mode.requested\"." }, "data": { "$ref": "#/definitions/ExitPlanModeRequestedData", @@ -2841,6 +2930,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"exit_plan_mode.requested\". Plan approval request with plan content and available user actions", "title": "ExitPlanModeRequestedEvent" }, "ExtensionsLoadedData": { @@ -2858,7 +2948,8 @@ "extensions" ], "additionalProperties": false, - "title": "ExtensionsLoadedData" + "title": "ExtensionsLoadedData", + "description": "Schema for the `ExtensionsLoadedData` type." }, "ExtensionsLoadedEvent": { "type": "object", @@ -2887,7 +2978,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -2895,10 +2987,12 @@ }, "type": { "type": "string", - "const": "session.extensions_loaded" + "const": "session.extensions_loaded", + "description": "Type discriminator. Always \"session.extensions_loaded\"." }, "data": { - "$ref": "#/definitions/ExtensionsLoadedData" + "$ref": "#/definitions/ExtensionsLoadedData", + "description": "Schema for the `ExtensionsLoadedData` type." } }, "required": [ @@ -2910,6 +3004,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.extensions_loaded\".", "title": "ExtensionsLoadedEvent" }, "ExtensionsLoadedExtension": { @@ -2939,7 +3034,8 @@ "status" ], "additionalProperties": false, - "title": "ExtensionsLoadedExtension" + "title": "ExtensionsLoadedExtension", + "description": "Schema for the `ExtensionsLoadedExtension` type." }, "ExtensionsLoadedExtensionSource": { "type": "string", @@ -3003,7 +3099,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -3011,7 +3108,8 @@ }, "type": { "type": "string", - "const": "external_tool.completed" + "const": "external_tool.completed", + "description": "Type discriminator. Always \"external_tool.completed\"." }, "data": { "$ref": "#/definitions/ExternalToolCompletedData", @@ -3026,6 +3124,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"external_tool.completed\". External tool completion notification signaling UI dismissal", "title": "ExternalToolCompletedEvent" }, "ExternalToolRequestedData": { @@ -3104,7 +3203,8 @@ }, "type": { "type": "string", - "const": "external_tool.requested" + "const": "external_tool.requested", + "description": "Type discriminator. Always \"external_tool.requested\"." }, "data": { "$ref": "#/definitions/ExternalToolRequestedData", @@ -3119,6 +3219,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"external_tool.requested\". External tool invocation request for client-side tool execution", "title": "ExternalToolRequestedEvent" }, "HandoffData": { @@ -3197,7 +3298,8 @@ }, "type": { "type": "string", - "const": "session.handoff" + "const": "session.handoff", + "description": "Type discriminator. Always \"session.handoff\"." }, "data": { "$ref": "#/definitions/HandoffData", @@ -3212,6 +3314,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.handoff\". Session handoff metadata including source, context, and repository information", "title": "HandoffEvent" }, "HandoffRepository": { @@ -3333,7 +3436,8 @@ }, "type": { "type": "string", - "const": "hook.end" + "const": "hook.end", + "description": "Type discriminator. Always \"hook.end\"." }, "data": { "$ref": "#/definitions/HookEndData", @@ -3348,6 +3452,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"hook.end\". Hook invocation completion details including output, success status, and error information", "title": "HookEndEvent" }, "HookStartData": { @@ -3408,7 +3513,8 @@ }, "type": { "type": "string", - "const": "hook.start" + "const": "hook.start", + "description": "Type discriminator. Always \"hook.start\"." }, "data": { "$ref": "#/definitions/HookStartData", @@ -3423,6 +3529,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"hook.start\". Hook invocation start details including type and input data", "title": "HookStartEvent" }, "IdleData": { @@ -3464,7 +3571,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -3472,7 +3580,8 @@ }, "type": { "type": "string", - "const": "session.idle" + "const": "session.idle", + "description": "Type discriminator. Always \"session.idle\"." }, "data": { "$ref": "#/definitions/IdleData", @@ -3488,6 +3597,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.idle\". Payload indicating the session is idle with no background agents in flight", "title": "IdleEvent" }, "InfoData": { @@ -3554,7 +3664,8 @@ }, "type": { "type": "string", - "const": "session.info" + "const": "session.info", + "description": "Type discriminator. Always \"session.info\"." }, "data": { "$ref": "#/definitions/InfoData", @@ -3569,6 +3680,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.info\". Informational message for timeline display with categorization", "title": "InfoEvent" }, "McpOauthCompletedData": { @@ -3613,7 +3725,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -3621,7 +3734,8 @@ }, "type": { "type": "string", - "const": "mcp.oauth_completed" + "const": "mcp.oauth_completed", + "description": "Type discriminator. Always \"mcp.oauth_completed\"." }, "data": { "$ref": "#/definitions/McpOauthCompletedData", @@ -3637,6 +3751,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"mcp.oauth_completed\". MCP OAuth request completion notification", "title": "McpOauthCompletedEvent" }, "McpOauthRequiredData": { @@ -3695,7 +3810,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -3703,7 +3819,8 @@ }, "type": { "type": "string", - "const": "mcp.oauth_required" + "const": "mcp.oauth_required", + "description": "Type discriminator. Always \"mcp.oauth_required\"." }, "data": { "$ref": "#/definitions/McpOauthRequiredData", @@ -3719,6 +3836,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"mcp.oauth_required\". OAuth authentication request for an MCP server", "title": "McpOauthRequiredEvent" }, "McpOauthRequiredStaticClientConfig": { @@ -3760,7 +3878,8 @@ "servers" ], "additionalProperties": false, - "title": "McpServersLoadedData" + "title": "McpServersLoadedData", + "description": "Schema for the `McpServersLoadedData` type." }, "McpServersLoadedEvent": { "type": "object", @@ -3789,7 +3908,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -3797,10 +3917,12 @@ }, "type": { "type": "string", - "const": "session.mcp_servers_loaded" + "const": "session.mcp_servers_loaded", + "description": "Type discriminator. Always \"session.mcp_servers_loaded\"." }, "data": { - "$ref": "#/definitions/McpServersLoadedData" + "$ref": "#/definitions/McpServersLoadedData", + "description": "Schema for the `McpServersLoadedData` type." } }, "required": [ @@ -3812,6 +3934,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.mcp_servers_loaded\".", "title": "McpServersLoadedEvent" }, "McpServersLoadedServer": { @@ -3839,7 +3962,8 @@ "status" ], "additionalProperties": false, - "title": "McpServersLoadedServer" + "title": "McpServersLoadedServer", + "description": "Schema for the `McpServersLoadedServer` type." }, "McpServersLoadedServerStatus": { "type": "string", @@ -3871,7 +3995,8 @@ "status" ], "additionalProperties": false, - "title": "McpServerStatusChangedData" + "title": "McpServerStatusChangedData", + "description": "Schema for the `McpServerStatusChangedData` type." }, "McpServerStatusChangedEvent": { "type": "object", @@ -3900,7 +4025,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -3908,10 +4034,12 @@ }, "type": { "type": "string", - "const": "session.mcp_server_status_changed" + "const": "session.mcp_server_status_changed", + "description": "Type discriminator. Always \"session.mcp_server_status_changed\"." }, "data": { - "$ref": "#/definitions/McpServerStatusChangedData" + "$ref": "#/definitions/McpServerStatusChangedData", + "description": "Schema for the `McpServerStatusChangedData` type." } }, "required": [ @@ -3923,6 +4051,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.mcp_server_status_changed\".", "title": "McpServerStatusChangedEvent" }, "McpServerStatusChangedStatus": { @@ -3993,7 +4122,8 @@ }, "type": { "type": "string", - "const": "session.mode_changed" + "const": "session.mode_changed", + "description": "Type discriminator. Always \"session.mode_changed\"." }, "data": { "$ref": "#/definitions/ModeChangedData", @@ -4008,6 +4138,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.mode_changed\". Agent mode change details including previous and new modes", "title": "ModeChangedEvent" }, "ModelCallFailureData": { @@ -4080,7 +4211,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -4088,7 +4220,8 @@ }, "type": { "type": "string", - "const": "model.call_failure" + "const": "model.call_failure", + "description": "Type discriminator. Always \"model.call_failure\"." }, "data": { "$ref": "#/definitions/ModelCallFailureData", @@ -4104,6 +4237,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"model.call_failure\". Failed LLM API call metadata for telemetry", "title": "ModelCallFailureEvent" }, "ModelCallFailureSource": { @@ -4132,9 +4266,20 @@ "description": "Reasoning effort level before the model change, if applicable" }, "reasoningEffort": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "Reasoning effort level after the model change, if applicable" }, + "previousReasoningSummary": { + "$ref": "#/definitions/ReasoningSummary", + "description": "Reasoning summary mode before the model change, if applicable" + }, + "reasoningSummary": { + "$ref": "#/definitions/ReasoningSummary", + "description": "Reasoning summary mode after the model change, if applicable" + }, "cause": { "type": "string", "description": "Reason the change happened, when not user-initiated. Currently `\"rate_limit_auto_switch\"` for changes triggered by the auto-mode-switch rate-limit recovery path. UI clients can use this to render contextual copy." @@ -4182,7 +4327,8 @@ }, "type": { "type": "string", - "const": "session.model_change" + "const": "session.model_change", + "description": "Type discriminator. Always \"session.model_change\"." }, "data": { "$ref": "#/definitions/ModelChangeData", @@ -4197,6 +4343,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.model_change\". Model change details including previous and new model identifiers", "title": "ModelChangeEvent" }, "PendingMessagesModifiedData": { @@ -4233,7 +4380,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -4241,7 +4389,8 @@ }, "type": { "type": "string", - "const": "pending_messages.modified" + "const": "pending_messages.modified", + "description": "Type discriminator. Always \"pending_messages.modified\"." }, "data": { "$ref": "#/definitions/PendingMessagesModifiedData", @@ -4257,6 +4406,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"pending_messages.modified\". Empty payload; the event signals that the pending message queue has changed", "title": "PendingMessagesModifiedEvent" }, "PermissionApproved": { @@ -4272,7 +4422,8 @@ "kind" ], "additionalProperties": false, - "title": "PermissionApproved" + "title": "PermissionApproved", + "description": "Schema for the `PermissionApproved` type." }, "PermissionApprovedForLocation": { "type": "object", @@ -4297,7 +4448,8 @@ "locationKey" ], "additionalProperties": false, - "title": "PermissionApprovedForLocation" + "title": "PermissionApprovedForLocation", + "description": "Schema for the `PermissionApprovedForLocation` type." }, "PermissionApprovedForSession": { "type": "object", @@ -4317,7 +4469,8 @@ "approval" ], "additionalProperties": false, - "title": "PermissionApprovedForSession" + "title": "PermissionApprovedForSession", + "description": "Schema for the `PermissionApprovedForSession` type." }, "PermissionCancelled": { "type": "object", @@ -4336,7 +4489,8 @@ "kind" ], "additionalProperties": false, - "title": "PermissionCancelled" + "title": "PermissionCancelled", + "description": "Schema for the `PermissionCancelled` type." }, "PermissionCompletedData": { "type": "object", @@ -4397,7 +4551,8 @@ }, "type": { "type": "string", - "const": "permission.completed" + "const": "permission.completed", + "description": "Type discriminator. Always \"permission.completed\"." }, "data": { "$ref": "#/definitions/PermissionCompletedData", @@ -4412,6 +4567,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"permission.completed\". Permission request completion notification signaling UI dismissal", "title": "PermissionCompletedEvent" }, "PermissionDeniedByContentExclusionPolicy": { @@ -4437,7 +4593,8 @@ "message" ], "additionalProperties": false, - "title": "PermissionDeniedByContentExclusionPolicy" + "title": "PermissionDeniedByContentExclusionPolicy", + "description": "Schema for the `PermissionDeniedByContentExclusionPolicy` type." }, "PermissionDeniedByPermissionRequestHook": { "type": "object", @@ -4460,7 +4617,8 @@ "kind" ], "additionalProperties": false, - "title": "PermissionDeniedByPermissionRequestHook" + "title": "PermissionDeniedByPermissionRequestHook", + "description": "Schema for the `PermissionDeniedByPermissionRequestHook` type." }, "PermissionDeniedByRules": { "type": "object", @@ -4483,7 +4641,8 @@ "rules" ], "additionalProperties": false, - "title": "PermissionDeniedByRules" + "title": "PermissionDeniedByRules", + "description": "Schema for the `PermissionDeniedByRules` type." }, "PermissionDeniedInteractivelyByUser": { "type": "object", @@ -4506,7 +4665,8 @@ "kind" ], "additionalProperties": false, - "title": "PermissionDeniedInteractivelyByUser" + "title": "PermissionDeniedInteractivelyByUser", + "description": "Schema for the `PermissionDeniedInteractivelyByUser` type." }, "PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser": { "type": "object", @@ -4521,7 +4681,8 @@ "kind" ], "additionalProperties": false, - "title": "PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser" + "title": "PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser", + "description": "Schema for the `PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser` type." }, "PermissionPromptRequest": { "anyOf": [ @@ -5144,7 +5305,8 @@ }, "type": { "type": "string", - "const": "permission.requested" + "const": "permission.requested", + "description": "Type discriminator. Always \"permission.requested\"." }, "data": { "$ref": "#/definitions/PermissionRequestedData", @@ -5159,6 +5321,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"permission.requested\". Permission request notification requiring client approval with request details", "title": "PermissionRequestedEvent" }, "PermissionRequestExtensionManagement": { @@ -5477,7 +5640,8 @@ "readOnly" ], "additionalProperties": false, - "title": "PermissionRequestShellCommand" + "title": "PermissionRequestShellCommand", + "description": "Schema for the `PermissionRequestShellCommand` type." }, "PermissionRequestShellPossibleUrl": { "type": "object", @@ -5491,7 +5655,8 @@ "url" ], "additionalProperties": false, - "title": "PermissionRequestShellPossibleUrl" + "title": "PermissionRequestShellPossibleUrl", + "description": "Schema for the `PermissionRequestShellPossibleUrl` type." }, "PermissionRequestUrl": { "type": "object", @@ -5620,7 +5785,8 @@ "argument" ], "additionalProperties": false, - "title": "PermissionRule" + "title": "PermissionRule", + "description": "Schema for the `PermissionRule` type." }, "PlanChangedData": { "type": "object", @@ -5672,7 +5838,8 @@ }, "type": { "type": "string", - "const": "session.plan_changed" + "const": "session.plan_changed", + "description": "Type discriminator. Always \"session.plan_changed\"." }, "data": { "$ref": "#/definitions/PlanChangedData", @@ -5687,6 +5854,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.plan_changed\". Plan file operation details indicating what changed", "title": "PlanChangedEvent" }, "PlanChangedOperation": { @@ -5699,19 +5867,29 @@ "description": "The type of operation performed on the plan file", "title": "PlanChangedOperation" }, + "ReasoningSummary": { + "type": "string", + "enum": [ + "none", + "concise", + "detailed" + ], + "description": "Reasoning summary mode used for model calls, if applicable (e.g. \"none\", \"concise\", \"detailed\")", + "title": "ReasoningSummary" + }, "RemoteSteerableChangedData": { "type": "object", "properties": { "remoteSteerable": { "type": "boolean", - "description": "Whether this session now supports remote steering via Mission Control" + "description": "Whether this session now supports remote steering via GitHub" } }, "required": [ "remoteSteerable" ], "additionalProperties": false, - "description": "Notifies Mission Control that the session's remote steering capability has changed", + "description": "Notifies that the session's remote steering capability has changed", "title": "RemoteSteerableChangedData" }, "RemoteSteerableChangedEvent": { @@ -5749,11 +5927,12 @@ }, "type": { "type": "string", - "const": "session.remote_steerable_changed" + "const": "session.remote_steerable_changed", + "description": "Type discriminator. Always \"session.remote_steerable_changed\"." }, "data": { "$ref": "#/definitions/RemoteSteerableChangedData", - "description": "Notifies Mission Control that the session's remote steering capability has changed" + "description": "Notifies that the session's remote steering capability has changed" } }, "required": [ @@ -5764,6 +5943,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.remote_steerable_changed\". Notifies that the session's remote steering capability has changed", "title": "RemoteSteerableChangedEvent" }, "ResumeData": { @@ -5784,7 +5964,11 @@ }, "reasoningEffort": { "type": "string", - "description": "Reasoning effort level used for model calls, if applicable (e.g. \"low\", \"medium\", \"high\", \"xhigh\")" + "description": "Reasoning effort level used for model calls, if applicable (e.g. \"none\", \"low\", \"medium\", \"high\", \"xhigh\")" + }, + "reasoningSummary": { + "$ref": "#/definitions/ReasoningSummary", + "description": "Reasoning summary mode used for model calls, if applicable (e.g. \"none\", \"concise\", \"detailed\")" }, "context": { "$ref": "#/definitions/WorkingDirectoryContext", @@ -5800,7 +5984,7 @@ }, "remoteSteerable": { "type": "boolean", - "description": "Whether this session supports remote steering via Mission Control" + "description": "Whether this session supports remote steering via GitHub" }, "continuePendingWork": { "type": "boolean", @@ -5850,7 +6034,8 @@ }, "type": { "type": "string", - "const": "session.resume" + "const": "session.resume", + "description": "Type discriminator. Always \"session.resume\"." }, "data": { "$ref": "#/definitions/ResumeData", @@ -5865,6 +6050,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.resume\". Session resume metadata including current context and event count", "title": "ResumeEvent" }, "SamplingCompletedData": { @@ -5909,7 +6095,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -5917,7 +6104,8 @@ }, "type": { "type": "string", - "const": "sampling.completed" + "const": "sampling.completed", + "description": "Type discriminator. Always \"sampling.completed\"." }, "data": { "$ref": "#/definitions/SamplingCompletedData", @@ -5933,6 +6121,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"sampling.completed\". Sampling request completion notification signaling UI dismissal", "title": "SamplingCompletedEvent" }, "SamplingRequestedData": { @@ -5990,7 +6179,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -5998,7 +6188,8 @@ }, "type": { "type": "string", - "const": "sampling.requested" + "const": "sampling.requested", + "description": "Type discriminator. Always \"sampling.requested\"." }, "data": { "$ref": "#/definitions/SamplingRequestedData", @@ -6014,6 +6205,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"sampling.requested\". Sampling request from an MCP server; contains the server name and a requestId for correlation", "title": "SamplingRequestedEvent" }, "ScheduleCancelledData": { @@ -6067,7 +6259,8 @@ }, "type": { "type": "string", - "const": "session.schedule_cancelled" + "const": "session.schedule_cancelled", + "description": "Type discriminator. Always \"session.schedule_cancelled\"." }, "data": { "$ref": "#/definitions/ScheduleCancelledData", @@ -6082,6 +6275,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.schedule_cancelled\". Scheduled prompt cancelled from the schedule manager dialog", "title": "ScheduleCancelledEvent" }, "ScheduleCreatedData": { @@ -6104,6 +6298,10 @@ "recurring": { "type": "boolean", "description": "Whether the schedule re-arms after each tick (`/every`) or fires once (`/after`)" + }, + "displayPrompt": { + "type": "string", + "description": "Optional user-facing label shown in the timeline instead of the actual prompt (e.g. `/skill-name args` when the prompt is a skill invocation expansion)" } }, "required": [ @@ -6150,7 +6348,8 @@ }, "type": { "type": "string", - "const": "session.schedule_created" + "const": "session.schedule_created", + "description": "Type discriminator. Always \"session.schedule_created\"." }, "data": { "$ref": "#/definitions/ScheduleCreatedData", @@ -6165,254 +6364,337 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.schedule_created\". Scheduled prompt registered via /every or /after", "title": "ScheduleCreatedEvent" }, "SessionEvent": { "anyOf": [ { - "$ref": "#/definitions/StartEvent" + "$ref": "#/definitions/StartEvent", + "description": "Session event \"session.start\". Session initialization metadata including context and configuration" }, { - "$ref": "#/definitions/ResumeEvent" + "$ref": "#/definitions/ResumeEvent", + "description": "Session event \"session.resume\". Session resume metadata including current context and event count" }, { - "$ref": "#/definitions/RemoteSteerableChangedEvent" + "$ref": "#/definitions/RemoteSteerableChangedEvent", + "description": "Session event \"session.remote_steerable_changed\". Notifies that the session's remote steering capability has changed" }, { - "$ref": "#/definitions/ErrorEvent" + "$ref": "#/definitions/ErrorEvent", + "description": "Session event \"session.error\". Error details for timeline display including message and optional diagnostic information" }, { - "$ref": "#/definitions/IdleEvent" + "$ref": "#/definitions/IdleEvent", + "description": "Session event \"session.idle\". Payload indicating the session is idle with no background agents in flight" }, { - "$ref": "#/definitions/TitleChangedEvent" + "$ref": "#/definitions/TitleChangedEvent", + "description": "Session event \"session.title_changed\". Session title change payload containing the new display title" }, { - "$ref": "#/definitions/ScheduleCreatedEvent" + "$ref": "#/definitions/ScheduleCreatedEvent", + "description": "Session event \"session.schedule_created\". Scheduled prompt registered via /every or /after" }, { - "$ref": "#/definitions/ScheduleCancelledEvent" + "$ref": "#/definitions/ScheduleCancelledEvent", + "description": "Session event \"session.schedule_cancelled\". Scheduled prompt cancelled from the schedule manager dialog" }, { - "$ref": "#/definitions/InfoEvent" + "$ref": "#/definitions/InfoEvent", + "description": "Session event \"session.info\". Informational message for timeline display with categorization" }, { - "$ref": "#/definitions/WarningEvent" + "$ref": "#/definitions/WarningEvent", + "description": "Session event \"session.warning\". Warning message for timeline display with categorization" }, { - "$ref": "#/definitions/ModelChangeEvent" + "$ref": "#/definitions/ModelChangeEvent", + "description": "Session event \"session.model_change\". Model change details including previous and new model identifiers" }, { - "$ref": "#/definitions/ModeChangedEvent" + "$ref": "#/definitions/ModeChangedEvent", + "description": "Session event \"session.mode_changed\". Agent mode change details including previous and new modes" }, { - "$ref": "#/definitions/PlanChangedEvent" + "$ref": "#/definitions/PlanChangedEvent", + "description": "Session event \"session.plan_changed\". Plan file operation details indicating what changed" }, { - "$ref": "#/definitions/WorkspaceFileChangedEvent" + "$ref": "#/definitions/WorkspaceFileChangedEvent", + "description": "Session event \"session.workspace_file_changed\". Workspace file change details including path and operation type" }, { - "$ref": "#/definitions/HandoffEvent" + "$ref": "#/definitions/HandoffEvent", + "description": "Session event \"session.handoff\". Session handoff metadata including source, context, and repository information" }, { - "$ref": "#/definitions/TruncationEvent" + "$ref": "#/definitions/TruncationEvent", + "description": "Session event \"session.truncation\". Conversation truncation statistics including token counts and removed content metrics" }, { - "$ref": "#/definitions/SnapshotRewindEvent" + "$ref": "#/definitions/SnapshotRewindEvent", + "description": "Session event \"session.snapshot_rewind\". Session rewind details including target event and count of removed events" }, { - "$ref": "#/definitions/ShutdownEvent" + "$ref": "#/definitions/ShutdownEvent", + "description": "Session event \"session.shutdown\". Session termination metrics including usage statistics, code changes, and shutdown reason" }, { - "$ref": "#/definitions/ContextChangedEvent" + "$ref": "#/definitions/ContextChangedEvent", + "description": "Session event \"session.context_changed\". Updated working directory and git context after the change" }, { - "$ref": "#/definitions/UsageInfoEvent" + "$ref": "#/definitions/UsageInfoEvent", + "description": "Session event \"session.usage_info\". Current context window usage statistics including token and message counts" }, { - "$ref": "#/definitions/CompactionStartEvent" + "$ref": "#/definitions/CompactionStartEvent", + "description": "Session event \"session.compaction_start\". Context window breakdown at the start of LLM-powered conversation compaction" }, { - "$ref": "#/definitions/CompactionCompleteEvent" + "$ref": "#/definitions/CompactionCompleteEvent", + "description": "Session event \"session.compaction_complete\". Conversation compaction results including success status, metrics, and optional error details" }, { - "$ref": "#/definitions/TaskCompleteEvent" + "$ref": "#/definitions/TaskCompleteEvent", + "description": "Session event \"session.task_complete\". Task completion notification with summary from the agent" }, { - "$ref": "#/definitions/UserMessageEvent" + "$ref": "#/definitions/UserMessageEvent", + "description": "Session event \"user.message\"." }, { - "$ref": "#/definitions/PendingMessagesModifiedEvent" + "$ref": "#/definitions/PendingMessagesModifiedEvent", + "description": "Session event \"pending_messages.modified\". Empty payload; the event signals that the pending message queue has changed" }, { - "$ref": "#/definitions/AssistantTurnStartEvent" + "$ref": "#/definitions/AssistantTurnStartEvent", + "description": "Session event \"assistant.turn_start\". Turn initialization metadata including identifier and interaction tracking" }, { - "$ref": "#/definitions/AssistantIntentEvent" + "$ref": "#/definitions/AssistantIntentEvent", + "description": "Session event \"assistant.intent\". Agent intent description for current activity or plan" }, { - "$ref": "#/definitions/AssistantReasoningEvent" + "$ref": "#/definitions/AssistantReasoningEvent", + "description": "Session event \"assistant.reasoning\". Assistant reasoning content for timeline display with complete thinking text" }, { - "$ref": "#/definitions/AssistantReasoningDeltaEvent" + "$ref": "#/definitions/AssistantReasoningDeltaEvent", + "description": "Session event \"assistant.reasoning_delta\". Streaming reasoning delta for incremental extended thinking updates" }, { - "$ref": "#/definitions/AssistantStreamingDeltaEvent" + "$ref": "#/definitions/AssistantStreamingDeltaEvent", + "description": "Session event \"assistant.streaming_delta\". Streaming response progress with cumulative byte count" }, { - "$ref": "#/definitions/AssistantMessageEvent" + "$ref": "#/definitions/AssistantMessageEvent", + "description": "Session event \"assistant.message\". Assistant response containing text content, optional tool requests, and interaction metadata" }, { - "$ref": "#/definitions/AssistantMessageStartEvent" + "$ref": "#/definitions/AssistantMessageStartEvent", + "description": "Session event \"assistant.message_start\". Streaming assistant message start metadata" }, { - "$ref": "#/definitions/AssistantMessageDeltaEvent" + "$ref": "#/definitions/AssistantMessageDeltaEvent", + "description": "Session event \"assistant.message_delta\". Streaming assistant message delta for incremental response updates" }, { - "$ref": "#/definitions/AssistantTurnEndEvent" + "$ref": "#/definitions/AssistantTurnEndEvent", + "description": "Session event \"assistant.turn_end\". Turn completion metadata including the turn identifier" }, { - "$ref": "#/definitions/AssistantUsageEvent" + "$ref": "#/definitions/AssistantUsageEvent", + "description": "Session event \"assistant.usage\". LLM API call usage metrics including tokens, costs, quotas, and billing information" }, { - "$ref": "#/definitions/ModelCallFailureEvent" + "$ref": "#/definitions/ModelCallFailureEvent", + "description": "Session event \"model.call_failure\". Failed LLM API call metadata for telemetry" }, { - "$ref": "#/definitions/AbortEvent" + "$ref": "#/definitions/AbortEvent", + "description": "Session event \"abort\". Turn abort information including the reason for termination" }, { - "$ref": "#/definitions/ToolUserRequestedEvent" + "$ref": "#/definitions/ToolUserRequestedEvent", + "description": "Session event \"tool.user_requested\". User-initiated tool invocation request with tool name and arguments" }, { - "$ref": "#/definitions/ToolExecutionStartEvent" + "$ref": "#/definitions/ToolExecutionStartEvent", + "description": "Session event \"tool.execution_start\". Tool execution startup details including MCP server information when applicable" }, { - "$ref": "#/definitions/ToolExecutionPartialResultEvent" + "$ref": "#/definitions/ToolExecutionPartialResultEvent", + "description": "Session event \"tool.execution_partial_result\". Streaming tool execution output for incremental result display" }, { - "$ref": "#/definitions/ToolExecutionProgressEvent" + "$ref": "#/definitions/ToolExecutionProgressEvent", + "description": "Session event \"tool.execution_progress\". Tool execution progress notification with status message" }, { - "$ref": "#/definitions/ToolExecutionCompleteEvent" + "$ref": "#/definitions/ToolExecutionCompleteEvent", + "description": "Session event \"tool.execution_complete\". Tool execution completion results including success status, detailed output, and error information" }, { - "$ref": "#/definitions/SkillInvokedEvent" + "$ref": "#/definitions/SkillInvokedEvent", + "description": "Session event \"skill.invoked\". Skill invocation details including content, allowed tools, and plugin metadata" }, { - "$ref": "#/definitions/SubagentStartedEvent" + "$ref": "#/definitions/SubagentStartedEvent", + "description": "Session event \"subagent.started\". Sub-agent startup details including parent tool call and agent information" }, { - "$ref": "#/definitions/SubagentCompletedEvent" + "$ref": "#/definitions/SubagentCompletedEvent", + "description": "Session event \"subagent.completed\". Sub-agent completion details for successful execution" }, { - "$ref": "#/definitions/SubagentFailedEvent" + "$ref": "#/definitions/SubagentFailedEvent", + "description": "Session event \"subagent.failed\". Sub-agent failure details including error message and agent information" }, { - "$ref": "#/definitions/SubagentSelectedEvent" + "$ref": "#/definitions/SubagentSelectedEvent", + "description": "Session event \"subagent.selected\". Custom agent selection details including name and available tools" }, { - "$ref": "#/definitions/SubagentDeselectedEvent" + "$ref": "#/definitions/SubagentDeselectedEvent", + "description": "Session event \"subagent.deselected\". Empty payload; the event signals that the custom agent was deselected, returning to the default agent" }, { - "$ref": "#/definitions/HookStartEvent" + "$ref": "#/definitions/HookStartEvent", + "description": "Session event \"hook.start\". Hook invocation start details including type and input data" }, { - "$ref": "#/definitions/HookEndEvent" + "$ref": "#/definitions/HookEndEvent", + "description": "Session event \"hook.end\". Hook invocation completion details including output, success status, and error information" }, { - "$ref": "#/definitions/SystemMessageEvent" + "$ref": "#/definitions/SystemMessageEvent", + "description": "Session event \"system.message\". System/developer instruction content with role and optional template metadata" }, { - "$ref": "#/definitions/SystemNotificationEvent" + "$ref": "#/definitions/SystemNotificationEvent", + "description": "Session event \"system.notification\". System-generated notification for runtime events like background task completion" }, { - "$ref": "#/definitions/PermissionRequestedEvent" + "$ref": "#/definitions/PermissionRequestedEvent", + "description": "Session event \"permission.requested\". Permission request notification requiring client approval with request details" }, { - "$ref": "#/definitions/PermissionCompletedEvent" + "$ref": "#/definitions/PermissionCompletedEvent", + "description": "Session event \"permission.completed\". Permission request completion notification signaling UI dismissal" }, { - "$ref": "#/definitions/UserInputRequestedEvent" + "$ref": "#/definitions/UserInputRequestedEvent", + "description": "Session event \"user_input.requested\". User input request notification with question and optional predefined choices" }, { - "$ref": "#/definitions/UserInputCompletedEvent" + "$ref": "#/definitions/UserInputCompletedEvent", + "description": "Session event \"user_input.completed\". User input request completion with the user's response" }, { - "$ref": "#/definitions/ElicitationRequestedEvent" + "$ref": "#/definitions/ElicitationRequestedEvent", + "description": "Session event \"elicitation.requested\". Elicitation request; may be form-based (structured input) or URL-based (browser redirect)" }, { - "$ref": "#/definitions/ElicitationCompletedEvent" + "$ref": "#/definitions/ElicitationCompletedEvent", + "description": "Session event \"elicitation.completed\". Elicitation request completion with the user's response" }, { - "$ref": "#/definitions/SamplingRequestedEvent" + "$ref": "#/definitions/SamplingRequestedEvent", + "description": "Session event \"sampling.requested\". Sampling request from an MCP server; contains the server name and a requestId for correlation" }, { - "$ref": "#/definitions/SamplingCompletedEvent" + "$ref": "#/definitions/SamplingCompletedEvent", + "description": "Session event \"sampling.completed\". Sampling request completion notification signaling UI dismissal" }, { - "$ref": "#/definitions/McpOauthRequiredEvent" + "$ref": "#/definitions/McpOauthRequiredEvent", + "description": "Session event \"mcp.oauth_required\". OAuth authentication request for an MCP server" }, { - "$ref": "#/definitions/McpOauthCompletedEvent" + "$ref": "#/definitions/McpOauthCompletedEvent", + "description": "Session event \"mcp.oauth_completed\". MCP OAuth request completion notification" }, { - "$ref": "#/definitions/CustomNotificationEvent" + "$ref": "#/definitions/CustomNotificationEvent", + "description": "Session event \"session.custom_notification\". Opaque custom notification data. Consumers may branch on source and name, but payload semantics are source-defined." }, { - "$ref": "#/definitions/ExternalToolRequestedEvent" + "$ref": "#/definitions/ExternalToolRequestedEvent", + "description": "Session event \"external_tool.requested\". External tool invocation request for client-side tool execution" }, { - "$ref": "#/definitions/ExternalToolCompletedEvent" + "$ref": "#/definitions/ExternalToolCompletedEvent", + "description": "Session event \"external_tool.completed\". External tool completion notification signaling UI dismissal" }, { - "$ref": "#/definitions/CommandQueuedEvent" + "$ref": "#/definitions/CommandQueuedEvent", + "description": "Session event \"command.queued\". Queued slash command dispatch request for client execution" }, { - "$ref": "#/definitions/CommandExecuteEvent" + "$ref": "#/definitions/CommandExecuteEvent", + "description": "Session event \"command.execute\". Registered command dispatch request routed to the owning client" }, { - "$ref": "#/definitions/CommandCompletedEvent" + "$ref": "#/definitions/CommandCompletedEvent", + "description": "Session event \"command.completed\". Queued command completion notification signaling UI dismissal" }, { - "$ref": "#/definitions/AutoModeSwitchRequestedEvent" + "$ref": "#/definitions/AutoModeSwitchRequestedEvent", + "description": "Session event \"auto_mode_switch.requested\". Auto mode switch request notification requiring user approval" }, { - "$ref": "#/definitions/AutoModeSwitchCompletedEvent" + "$ref": "#/definitions/AutoModeSwitchCompletedEvent", + "description": "Session event \"auto_mode_switch.completed\". Auto mode switch completion notification" }, { - "$ref": "#/definitions/CommandsChangedEvent" + "$ref": "#/definitions/CommandsChangedEvent", + "description": "Session event \"commands.changed\". SDK command registration change notification" }, { - "$ref": "#/definitions/CapabilitiesChangedEvent" + "$ref": "#/definitions/CapabilitiesChangedEvent", + "description": "Session event \"capabilities.changed\". Session capability change notification" }, { - "$ref": "#/definitions/ExitPlanModeRequestedEvent" + "$ref": "#/definitions/ExitPlanModeRequestedEvent", + "description": "Session event \"exit_plan_mode.requested\". Plan approval request with plan content and available user actions" }, { - "$ref": "#/definitions/ExitPlanModeCompletedEvent" + "$ref": "#/definitions/ExitPlanModeCompletedEvent", + "description": "Session event \"exit_plan_mode.completed\". Plan mode exit completion with the user's approval decision and optional feedback" }, { - "$ref": "#/definitions/ToolsUpdatedEvent" + "$ref": "#/definitions/ToolsUpdatedEvent", + "description": "Session event \"session.tools_updated\"." }, { - "$ref": "#/definitions/BackgroundTasksChangedEvent" + "$ref": "#/definitions/BackgroundTasksChangedEvent", + "description": "Session event \"session.background_tasks_changed\"." }, { - "$ref": "#/definitions/SkillsLoadedEvent" + "$ref": "#/definitions/SkillsLoadedEvent", + "description": "Session event \"session.skills_loaded\"." }, { - "$ref": "#/definitions/CustomAgentsUpdatedEvent" + "$ref": "#/definitions/CustomAgentsUpdatedEvent", + "description": "Session event \"session.custom_agents_updated\"." }, { - "$ref": "#/definitions/McpServersLoadedEvent" + "$ref": "#/definitions/McpServersLoadedEvent", + "description": "Session event \"session.mcp_servers_loaded\"." }, { - "$ref": "#/definitions/McpServerStatusChangedEvent" + "$ref": "#/definitions/McpServerStatusChangedEvent", + "description": "Session event \"session.mcp_server_status_changed\"." }, { - "$ref": "#/definitions/ExtensionsLoadedEvent" + "$ref": "#/definitions/ExtensionsLoadedEvent", + "description": "Session event \"session.extensions_loaded\"." } - ] + ], + "description": "Union of all session event variants emitted by the Copilot CLI runtime." }, "ShutdownCodeChanges": { "type": "object", @@ -6555,7 +6837,8 @@ }, "type": { "type": "string", - "const": "session.shutdown" + "const": "session.shutdown", + "description": "Type discriminator. Always \"session.shutdown\"." }, "data": { "$ref": "#/definitions/ShutdownData", @@ -6570,6 +6853,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.shutdown\". Session termination metrics including usage statistics, code changes, and shutdown reason", "title": "ShutdownEvent" }, "ShutdownModelMetric": { @@ -6600,7 +6884,8 @@ "usage" ], "additionalProperties": false, - "title": "ShutdownModelMetric" + "title": "ShutdownModelMetric", + "description": "Schema for the `ShutdownModelMetric` type." }, "ShutdownModelMetricRequests": { "type": "object", @@ -6634,7 +6919,8 @@ "tokenCount" ], "additionalProperties": false, - "title": "ShutdownModelMetricTokenDetail" + "title": "ShutdownModelMetricTokenDetail", + "description": "Schema for the `ShutdownModelMetricTokenDetail` type." }, "ShutdownModelMetricUsage": { "type": "object", @@ -6682,7 +6968,8 @@ "tokenCount" ], "additionalProperties": false, - "title": "ShutdownTokenDetail" + "title": "ShutdownTokenDetail", + "description": "Schema for the `ShutdownTokenDetail` type." }, "ShutdownType": { "type": "string", @@ -6772,7 +7059,8 @@ }, "type": { "type": "string", - "const": "skill.invoked" + "const": "skill.invoked", + "description": "Type discriminator. Always \"skill.invoked\"." }, "data": { "$ref": "#/definitions/SkillInvokedData", @@ -6787,6 +7075,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"skill.invoked\". Skill invocation details including content, allowed tools, and plugin metadata", "title": "SkillInvokedEvent" }, "SkillsLoadedData": { @@ -6804,7 +7093,8 @@ "skills" ], "additionalProperties": false, - "title": "SkillsLoadedData" + "title": "SkillsLoadedData", + "description": "Schema for the `SkillsLoadedData` type." }, "SkillsLoadedEvent": { "type": "object", @@ -6833,7 +7123,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -6841,10 +7132,12 @@ }, "type": { "type": "string", - "const": "session.skills_loaded" + "const": "session.skills_loaded", + "description": "Type discriminator. Always \"session.skills_loaded\"." }, "data": { - "$ref": "#/definitions/SkillsLoadedData" + "$ref": "#/definitions/SkillsLoadedData", + "description": "Schema for the `SkillsLoadedData` type." } }, "required": [ @@ -6856,6 +7149,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.skills_loaded\".", "title": "SkillsLoadedEvent" }, "SkillsLoadedSkill": { @@ -6894,7 +7188,8 @@ "enabled" ], "additionalProperties": false, - "title": "SkillsLoadedSkill" + "title": "SkillsLoadedSkill", + "description": "Schema for the `SkillsLoadedSkill` type." }, "SnapshotRewindData": { "type": "object", @@ -6943,7 +7238,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -6951,7 +7247,8 @@ }, "type": { "type": "string", - "const": "session.snapshot_rewind" + "const": "session.snapshot_rewind", + "description": "Type discriminator. Always \"session.snapshot_rewind\"." }, "data": { "$ref": "#/definitions/SnapshotRewindData", @@ -6967,6 +7264,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.snapshot_rewind\". Session rewind details including target event and count of removed events", "title": "SnapshotRewindEvent" }, "StartData": { @@ -6999,7 +7297,11 @@ }, "reasoningEffort": { "type": "string", - "description": "Reasoning effort level used for model calls, if applicable (e.g. \"low\", \"medium\", \"high\", \"xhigh\")" + "description": "Reasoning effort level used for model calls, if applicable (e.g. \"none\", \"low\", \"medium\", \"high\", \"xhigh\")" + }, + "reasoningSummary": { + "$ref": "#/definitions/ReasoningSummary", + "description": "Reasoning summary mode used for model calls, if applicable (e.g. \"none\", \"concise\", \"detailed\")" }, "context": { "$ref": "#/definitions/WorkingDirectoryContext", @@ -7011,7 +7313,7 @@ }, "remoteSteerable": { "type": "boolean", - "description": "Whether this session supports remote steering via Mission Control" + "description": "Whether this session supports remote steering via GitHub" }, "detachedFromSpawningParentSessionId": { "type": "string", @@ -7064,7 +7366,8 @@ }, "type": { "type": "string", - "const": "session.start" + "const": "session.start", + "description": "Type discriminator. Always \"session.start\"." }, "data": { "$ref": "#/definitions/StartData", @@ -7079,6 +7382,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.start\". Session initialization metadata including context and configuration", "title": "StartEvent" }, "SubagentCompletedData": { @@ -7157,7 +7461,8 @@ }, "type": { "type": "string", - "const": "subagent.completed" + "const": "subagent.completed", + "description": "Type discriminator. Always \"subagent.completed\"." }, "data": { "$ref": "#/definitions/SubagentCompletedData", @@ -7172,6 +7477,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"subagent.completed\". Sub-agent completion details for successful execution", "title": "SubagentCompletedEvent" }, "SubagentDeselectedData": { @@ -7216,7 +7522,8 @@ }, "type": { "type": "string", - "const": "subagent.deselected" + "const": "subagent.deselected", + "description": "Type discriminator. Always \"subagent.deselected\"." }, "data": { "$ref": "#/definitions/SubagentDeselectedData", @@ -7231,6 +7538,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"subagent.deselected\". Empty payload; the event signals that the custom agent was deselected, returning to the default agent", "title": "SubagentDeselectedEvent" }, "SubagentFailedData": { @@ -7314,7 +7622,8 @@ }, "type": { "type": "string", - "const": "subagent.failed" + "const": "subagent.failed", + "description": "Type discriminator. Always \"subagent.failed\"." }, "data": { "$ref": "#/definitions/SubagentFailedData", @@ -7329,6 +7638,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"subagent.failed\". Sub-agent failure details including error message and agent information", "title": "SubagentFailedEvent" }, "SubagentSelectedData": { @@ -7401,7 +7711,8 @@ }, "type": { "type": "string", - "const": "subagent.selected" + "const": "subagent.selected", + "description": "Type discriminator. Always \"subagent.selected\"." }, "data": { "$ref": "#/definitions/SubagentSelectedData", @@ -7416,6 +7727,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"subagent.selected\". Custom agent selection details including name and available tools", "title": "SubagentSelectedEvent" }, "SubagentStartedData": { @@ -7487,7 +7799,8 @@ }, "type": { "type": "string", - "const": "subagent.started" + "const": "subagent.started", + "description": "Type discriminator. Always \"subagent.started\"." }, "data": { "$ref": "#/definitions/SubagentStartedData", @@ -7502,6 +7815,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"subagent.started\". Sub-agent startup details including parent tool call and agent information", "title": "SubagentStartedEvent" }, "SystemMessageData": { @@ -7567,7 +7881,8 @@ }, "type": { "type": "string", - "const": "system.message" + "const": "system.message", + "description": "Type discriminator. Always \"system.message\"." }, "data": { "$ref": "#/definitions/SystemMessageData", @@ -7582,6 +7897,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"system.message\". System/developer instruction content with role and optional template metadata", "title": "SystemMessageEvent" }, "SystemMessageMetadata": { @@ -7639,7 +7955,8 @@ "properties": { "type": { "type": "string", - "const": "agent_completed" + "const": "agent_completed", + "description": "Type discriminator. Always \"agent_completed\"." }, "agentId": { "type": "string", @@ -7669,7 +7986,8 @@ "status" ], "additionalProperties": false, - "title": "SystemNotificationAgentCompleted" + "title": "SystemNotificationAgentCompleted", + "description": "Schema for the `SystemNotificationAgentCompleted` type." }, "SystemNotificationAgentCompletedStatus": { "type": "string", @@ -7685,7 +8003,8 @@ "properties": { "type": { "type": "string", - "const": "agent_idle" + "const": "agent_idle", + "description": "Type discriminator. Always \"agent_idle\"." }, "agentId": { "type": "string", @@ -7706,7 +8025,8 @@ "agentType" ], "additionalProperties": false, - "title": "SystemNotificationAgentIdle" + "title": "SystemNotificationAgentIdle", + "description": "Schema for the `SystemNotificationAgentIdle` type." }, "SystemNotificationData": { "type": "object", @@ -7763,7 +8083,8 @@ }, "type": { "type": "string", - "const": "system.notification" + "const": "system.notification", + "description": "Type discriminator. Always \"system.notification\"." }, "data": { "$ref": "#/definitions/SystemNotificationData", @@ -7778,6 +8099,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"system.notification\". System-generated notification for runtime events like background task completion", "title": "SystemNotificationEvent" }, "SystemNotificationInstructionDiscovered": { @@ -7785,7 +8107,8 @@ "properties": { "type": { "type": "string", - "const": "instruction_discovered" + "const": "instruction_discovered", + "description": "Type discriminator. Always \"instruction_discovered\"." }, "sourcePath": { "type": "string", @@ -7811,14 +8134,16 @@ "triggerTool" ], "additionalProperties": false, - "title": "SystemNotificationInstructionDiscovered" + "title": "SystemNotificationInstructionDiscovered", + "description": "Schema for the `SystemNotificationInstructionDiscovered` type." }, "SystemNotificationNewInboxMessage": { "type": "object", "properties": { "type": { "type": "string", - "const": "new_inbox_message" + "const": "new_inbox_message", + "description": "Type discriminator. Always \"new_inbox_message\"." }, "entryId": { "type": "string", @@ -7845,14 +8170,16 @@ "summary" ], "additionalProperties": false, - "title": "SystemNotificationNewInboxMessage" + "title": "SystemNotificationNewInboxMessage", + "description": "Schema for the `SystemNotificationNewInboxMessage` type." }, "SystemNotificationShellCompleted": { "type": "object", "properties": { "type": { "type": "string", - "const": "shell_completed" + "const": "shell_completed", + "description": "Type discriminator. Always \"shell_completed\"." }, "shellId": { "type": "string", @@ -7872,14 +8199,16 @@ "shellId" ], "additionalProperties": false, - "title": "SystemNotificationShellCompleted" + "title": "SystemNotificationShellCompleted", + "description": "Schema for the `SystemNotificationShellCompleted` type." }, "SystemNotificationShellDetachedCompleted": { "type": "object", "properties": { "type": { "type": "string", - "const": "shell_detached_completed" + "const": "shell_detached_completed", + "description": "Type discriminator. Always \"shell_detached_completed\"." }, "shellId": { "type": "string", @@ -7895,7 +8224,8 @@ "shellId" ], "additionalProperties": false, - "title": "SystemNotificationShellDetachedCompleted" + "title": "SystemNotificationShellDetachedCompleted", + "description": "Schema for the `SystemNotificationShellDetachedCompleted` type." }, "TaskCompleteData": { "type": "object", @@ -7949,7 +8279,8 @@ }, "type": { "type": "string", - "const": "session.task_complete" + "const": "session.task_complete", + "description": "Type discriminator. Always \"session.task_complete\"." }, "data": { "$ref": "#/definitions/TaskCompleteData", @@ -7964,6 +8295,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.task_complete\". Task completion notification with summary from the agent", "title": "TaskCompleteEvent" }, "TitleChangedData": { @@ -8008,7 +8340,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -8016,7 +8349,8 @@ }, "type": { "type": "string", - "const": "session.title_changed" + "const": "session.title_changed", + "description": "Type discriminator. Always \"session.title_changed\"." }, "data": { "$ref": "#/definitions/TitleChangedData", @@ -8032,6 +8366,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.title_changed\". Session title change payload containing the new display title", "title": "TitleChangedEvent" }, "ToolExecutionCompleteContent": { @@ -8398,7 +8733,8 @@ }, "type": { "type": "string", - "const": "tool.execution_complete" + "const": "tool.execution_complete", + "description": "Type discriminator. Always \"tool.execution_complete\"." }, "data": { "$ref": "#/definitions/ToolExecutionCompleteData", @@ -8413,6 +8749,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"tool.execution_complete\". Tool execution completion results including success status, detailed output, and error information", "title": "ToolExecutionCompleteEvent" }, "ToolExecutionCompleteResult": { @@ -8489,7 +8826,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -8497,7 +8835,8 @@ }, "type": { "type": "string", - "const": "tool.execution_partial_result" + "const": "tool.execution_partial_result", + "description": "Type discriminator. Always \"tool.execution_partial_result\"." }, "data": { "$ref": "#/definitions/ToolExecutionPartialData", @@ -8513,6 +8852,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"tool.execution_partial_result\". Streaming tool execution output for incremental result display", "title": "ToolExecutionPartialResultEvent" }, "ToolExecutionProgressData": { @@ -8562,7 +8902,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -8570,7 +8911,8 @@ }, "type": { "type": "string", - "const": "tool.execution_progress" + "const": "tool.execution_progress", + "description": "Type discriminator. Always \"tool.execution_progress\"." }, "data": { "$ref": "#/definitions/ToolExecutionProgressData", @@ -8586,6 +8928,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"tool.execution_progress\". Tool execution progress notification with status message", "title": "ToolExecutionProgressEvent" }, "ToolExecutionStartData": { @@ -8663,7 +9006,8 @@ }, "type": { "type": "string", - "const": "tool.execution_start" + "const": "tool.execution_start", + "description": "Type discriminator. Always \"tool.execution_start\"." }, "data": { "$ref": "#/definitions/ToolExecutionStartData", @@ -8678,20 +9022,23 @@ "data" ], "additionalProperties": false, + "description": "Session event \"tool.execution_start\". Tool execution startup details including MCP server information when applicable", "title": "ToolExecutionStartEvent" }, "ToolsUpdatedData": { "type": "object", "properties": { "model": { - "type": "string" + "type": "string", + "description": "Identifier of the model the resolved tools apply to." } }, "required": [ "model" ], "additionalProperties": false, - "title": "ToolsUpdatedData" + "title": "ToolsUpdatedData", + "description": "Schema for the `ToolsUpdatedData` type." }, "ToolsUpdatedEvent": { "type": "object", @@ -8720,7 +9067,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -8728,10 +9076,12 @@ }, "type": { "type": "string", - "const": "session.tools_updated" + "const": "session.tools_updated", + "description": "Type discriminator. Always \"session.tools_updated\"." }, "data": { - "$ref": "#/definitions/ToolsUpdatedData" + "$ref": "#/definitions/ToolsUpdatedData", + "description": "Schema for the `ToolsUpdatedData` type." } }, "required": [ @@ -8743,6 +9093,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.tools_updated\".", "title": "ToolsUpdatedEvent" }, "ToolUserRequestedData": { @@ -8803,7 +9154,8 @@ }, "type": { "type": "string", - "const": "tool.user_requested" + "const": "tool.user_requested", + "description": "Type discriminator. Always \"tool.user_requested\"." }, "data": { "$ref": "#/definitions/ToolUserRequestedData", @@ -8818,6 +9170,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"tool.user_requested\". User-initiated tool invocation request with tool name and arguments", "title": "ToolUserRequestedEvent" }, "TruncationData": { @@ -8905,7 +9258,8 @@ }, "type": { "type": "string", - "const": "session.truncation" + "const": "session.truncation", + "description": "Type discriminator. Always \"session.truncation\"." }, "data": { "$ref": "#/definitions/TruncationData", @@ -8920,6 +9274,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.truncation\". Conversation truncation statistics including token counts and removed content metrics", "title": "TruncationEvent" }, "UsageInfoData": { @@ -8990,7 +9345,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -8998,7 +9354,8 @@ }, "type": { "type": "string", - "const": "session.usage_info" + "const": "session.usage_info", + "description": "Type discriminator. Always \"session.usage_info\"." }, "data": { "$ref": "#/definitions/UsageInfoData", @@ -9014,6 +9371,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.usage_info\". Current context window usage statistics including token and message counts", "title": "UsageInfoEvent" }, "UserInputCompletedData": { @@ -9066,7 +9424,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -9074,7 +9433,8 @@ }, "type": { "type": "string", - "const": "user_input.completed" + "const": "user_input.completed", + "description": "Type discriminator. Always \"user_input.completed\"." }, "data": { "$ref": "#/definitions/UserInputCompletedData", @@ -9090,6 +9450,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"user_input.completed\". User input request completion with the user's response", "title": "UserInputCompletedEvent" }, "UserInputRequestedData": { @@ -9154,7 +9515,8 @@ }, "ephemeral": { "type": "boolean", - "const": true + "const": true, + "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", @@ -9162,7 +9524,8 @@ }, "type": { "type": "string", - "const": "user_input.requested" + "const": "user_input.requested", + "description": "Type discriminator. Always \"user_input.requested\"." }, "data": { "$ref": "#/definitions/UserInputRequestedData", @@ -9178,6 +9541,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"user_input.requested\". User input request notification with question and optional predefined choices", "title": "UserInputRequestedEvent" }, "UserMessageAgentMode": { @@ -9529,7 +9893,8 @@ "content" ], "additionalProperties": false, - "title": "UserMessageData" + "title": "UserMessageData", + "description": "Schema for the `UserMessageData` type." }, "UserMessageEvent": { "type": "object", @@ -9566,10 +9931,12 @@ }, "type": { "type": "string", - "const": "user.message" + "const": "user.message", + "description": "Type discriminator. Always \"user.message\"." }, "data": { - "$ref": "#/definitions/UserMessageData" + "$ref": "#/definitions/UserMessageData", + "description": "Schema for the `UserMessageData` type." } }, "required": [ @@ -9580,6 +9947,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"user.message\".", "title": "UserMessageEvent" }, "UserToolSessionApproval": { @@ -9633,7 +10001,8 @@ "commandIdentifiers" ], "additionalProperties": false, - "title": "UserToolSessionApprovalCommands" + "title": "UserToolSessionApprovalCommands", + "description": "Schema for the `UserToolSessionApprovalCommands` type." }, "UserToolSessionApprovalCustomTool": { "type": "object", @@ -9653,7 +10022,8 @@ "toolName" ], "additionalProperties": false, - "title": "UserToolSessionApprovalCustomTool" + "title": "UserToolSessionApprovalCustomTool", + "description": "Schema for the `UserToolSessionApprovalCustomTool` type." }, "UserToolSessionApprovalExtensionManagement": { "type": "object", @@ -9672,7 +10042,8 @@ "kind" ], "additionalProperties": false, - "title": "UserToolSessionApprovalExtensionManagement" + "title": "UserToolSessionApprovalExtensionManagement", + "description": "Schema for the `UserToolSessionApprovalExtensionManagement` type." }, "UserToolSessionApprovalExtensionPermissionAccess": { "type": "object", @@ -9692,7 +10063,8 @@ "extensionName" ], "additionalProperties": false, - "title": "UserToolSessionApprovalExtensionPermissionAccess" + "title": "UserToolSessionApprovalExtensionPermissionAccess", + "description": "Schema for the `UserToolSessionApprovalExtensionPermissionAccess` type." }, "UserToolSessionApprovalMcp": { "type": "object", @@ -9720,7 +10092,8 @@ "toolName" ], "additionalProperties": false, - "title": "UserToolSessionApprovalMcp" + "title": "UserToolSessionApprovalMcp", + "description": "Schema for the `UserToolSessionApprovalMcp` type." }, "UserToolSessionApprovalMemory": { "type": "object", @@ -9735,7 +10108,8 @@ "kind" ], "additionalProperties": false, - "title": "UserToolSessionApprovalMemory" + "title": "UserToolSessionApprovalMemory", + "description": "Schema for the `UserToolSessionApprovalMemory` type." }, "UserToolSessionApprovalRead": { "type": "object", @@ -9750,7 +10124,8 @@ "kind" ], "additionalProperties": false, - "title": "UserToolSessionApprovalRead" + "title": "UserToolSessionApprovalRead", + "description": "Schema for the `UserToolSessionApprovalRead` type." }, "UserToolSessionApprovalWrite": { "type": "object", @@ -9765,7 +10140,8 @@ "kind" ], "additionalProperties": false, - "title": "UserToolSessionApprovalWrite" + "title": "UserToolSessionApprovalWrite", + "description": "Schema for the `UserToolSessionApprovalWrite` type." }, "WarningData": { "type": "object", @@ -9827,7 +10203,8 @@ }, "type": { "type": "string", - "const": "session.warning" + "const": "session.warning", + "description": "Type discriminator. Always \"session.warning\"." }, "data": { "$ref": "#/definitions/WarningData", @@ -9842,6 +10219,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.warning\". Warning message for timeline display with categorization", "title": "WarningEvent" }, "WorkingDirectoryContext": { @@ -9951,7 +10329,8 @@ }, "type": { "type": "string", - "const": "session.workspace_file_changed" + "const": "session.workspace_file_changed", + "description": "Type discriminator. Always \"session.workspace_file_changed\"." }, "data": { "$ref": "#/definitions/WorkspaceFileChangedData", @@ -9966,6 +10345,7 @@ "data" ], "additionalProperties": false, + "description": "Session event \"session.workspace_file_changed\". Workspace file change details including path and operation type", "title": "WorkspaceFileChangedEvent" }, "WorkspaceFileChangedOperation": { @@ -9978,5 +10358,6 @@ "title": "WorkspaceFileChangedOperation" } }, - "$schema": "http://json-schema.org/draft-07/schema#" + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "JSON Schema for session events emitted by the Copilot CLI runtime." } diff --git a/src/github/copilot_sdk/generated/event_specs.clj b/src/github/copilot_sdk/generated/event_specs.clj index 61a3d2c..4e5fbf3 100644 --- a/src/github/copilot_sdk/generated/event_specs.clj +++ b/src/github/copilot_sdk/generated/event_specs.clj @@ -73,9 +73,9 @@ (s/def :github.copilot-sdk.generated.event-specs/compaction-tokens-used clojure.core/map?) -(s/def :github.copilot-sdk.generated.event-specs/content (s/spec (fn [v941] (or (s/valid? clojure.core/string? v941) (s/valid? clojure.core/map? v941))))) +(s/def :github.copilot-sdk.generated.event-specs/content (s/spec (fn [v943] (or (s/valid? clojure.core/string? v943) (s/valid? clojure.core/map? v943))))) -(s/def :github.copilot-sdk.generated.event-specs/context (s/spec (fn [v939] (or (s/valid? clojure.core/map? v939) (s/valid? clojure.core/string? v939))))) +(s/def :github.copilot-sdk.generated.event-specs/context (s/spec (fn [v941] (or (s/valid? clojure.core/map? v941) (s/valid? clojure.core/string? v941))))) (s/def :github.copilot-sdk.generated.event-specs/continue-pending-work clojure.core/boolean?) @@ -101,6 +101,8 @@ (s/def :github.copilot-sdk.generated.event-specs/detached-from-spawning-parent-session-id clojure.core/string?) +(s/def :github.copilot-sdk.generated.event-specs/display-prompt clojure.core/string?) + (s/def :github.copilot-sdk.generated.event-specs/duration clojure.core/number?) (s/def :github.copilot-sdk.generated.event-specs/duration-ms clojure.core/number?) @@ -113,7 +115,7 @@ (s/def :github.copilot-sdk.generated.event-specs/ephemeral clojure.core/boolean?) -(s/def :github.copilot-sdk.generated.event-specs/error (s/spec (fn [v937] (or (s/valid? clojure.core/string? v937) (s/valid? clojure.core/map? v937))))) +(s/def :github.copilot-sdk.generated.event-specs/error (s/spec (fn [v938] (or (s/valid? clojure.core/string? v938) (s/valid? clojure.core/map? v938))))) (s/def :github.copilot-sdk.generated.event-specs/error-code clojure.core/string?) @@ -147,7 +149,7 @@ (s/def :github.copilot-sdk.generated.event-specs/host-type #{"github" "ado"}) -(s/def :github.copilot-sdk.generated.event-specs/id (s/spec (fn [v938] (or (s/valid? clojure.core/string? v938) (s/valid? clojure.core/integer? v938))))) +(s/def :github.copilot-sdk.generated.event-specs/id (s/spec (fn [v939] (or (s/valid? clojure.core/string? v939) (s/valid? clojure.core/integer? v939))))) (s/def :github.copilot-sdk.generated.event-specs/info-type clojure.core/string?) @@ -205,7 +207,7 @@ (s/def :github.copilot-sdk.generated.event-specs/new-model clojure.core/string?) -(s/def :github.copilot-sdk.generated.event-specs/operation (s/spec (fn [v940] (or (s/valid? #{"delete" "update" "create"} v940) (s/valid? #{"update" "create"} v940))))) +(s/def :github.copilot-sdk.generated.event-specs/operation (s/spec (fn [v942] (or (s/valid? #{"delete" "update" "create"} v942) (s/valid? #{"update" "create"} v942))))) (s/def :github.copilot-sdk.generated.event-specs/output clojure.core/any?) @@ -255,6 +257,8 @@ (s/def :github.copilot-sdk.generated.event-specs/previous-reasoning-effort clojure.core/string?) +(s/def :github.copilot-sdk.generated.event-specs/previous-reasoning-summary #{"detailed" "none" "concise"}) + (s/def :github.copilot-sdk.generated.event-specs/producer clojure.core/string?) (s/def :github.copilot-sdk.generated.event-specs/progress-message clojure.core/string?) @@ -271,12 +275,14 @@ (s/def :github.copilot-sdk.generated.event-specs/reason #{"user_abort" "remote_command" "user_initiated"}) -(s/def :github.copilot-sdk.generated.event-specs/reasoning-effort clojure.core/string?) +(s/def :github.copilot-sdk.generated.event-specs/reasoning-effort (s/spec (fn [v940] (or (s/valid? clojure.core/string? v940) (s/valid? clojure.core/any? v940))))) (s/def :github.copilot-sdk.generated.event-specs/reasoning-id clojure.core/string?) (s/def :github.copilot-sdk.generated.event-specs/reasoning-opaque clojure.core/string?) +(s/def :github.copilot-sdk.generated.event-specs/reasoning-summary #{"detailed" "none" "concise"}) + (s/def :github.copilot-sdk.generated.event-specs/reasoning-text clojure.core/string?) (s/def :github.copilot-sdk.generated.event-specs/reasoning-tokens clojure.core/number?) @@ -289,7 +295,7 @@ (s/def :github.copilot-sdk.generated.event-specs/remote-steerable clojure.core/boolean?) -(s/def :github.copilot-sdk.generated.event-specs/repository (s/spec (fn [v936] (or (s/valid? clojure.core/map? v936) (s/valid? clojure.core/string? v936))))) +(s/def :github.copilot-sdk.generated.event-specs/repository (s/spec (fn [v937] (or (s/valid? clojure.core/map? v937) (s/valid? clojure.core/string? v937))))) (s/def :github.copilot-sdk.generated.event-specs/repository-host clojure.core/string?) @@ -301,7 +307,7 @@ (s/def :github.copilot-sdk.generated.event-specs/response clojure.core/string?) -(s/def :github.copilot-sdk.generated.event-specs/result (s/spec (fn [v945] (or (s/valid? clojure.core/map? v945) (s/valid? (s/or :branch-0 clojure.core/map? :branch-1 clojure.core/map? :branch-2 clojure.core/map? :branch-3 clojure.core/map? :branch-4 clojure.core/map? :branch-5 clojure.core/map? :branch-6 clojure.core/map? :branch-7 clojure.core/map? :branch-8 clojure.core/map?) v945))))) +(s/def :github.copilot-sdk.generated.event-specs/result (s/spec (fn [v947] (or (s/valid? clojure.core/map? v947) (s/valid? (s/or :branch-0 clojure.core/map? :branch-1 clojure.core/map? :branch-2 clojure.core/map? :branch-3 clojure.core/map? :branch-4 clojure.core/map? :branch-5 clojure.core/map? :branch-6 clojure.core/map? :branch-7 clojure.core/map? :branch-8 clojure.core/map?) v947))))) (s/def :github.copilot-sdk.generated.event-specs/resume-time clojure.core/string?) @@ -329,7 +335,7 @@ (s/def :github.copilot-sdk.generated.event-specs/skills (s/coll-of clojure.core/map?)) -(s/def :github.copilot-sdk.generated.event-specs/source (s/spec (fn [v942] (or (s/valid? clojure.core/string? v942) (s/valid? #{"top_level" "subagent" "mcp_sampling"} v942))))) +(s/def :github.copilot-sdk.generated.event-specs/source (s/spec (fn [v944] (or (s/valid? clojure.core/string? v944) (s/valid? #{"top_level" "subagent" "mcp_sampling"} v944))))) (s/def :github.copilot-sdk.generated.event-specs/source-type #{"remote" "local"}) @@ -403,7 +409,7 @@ (s/def :github.copilot-sdk.generated.event-specs/turn-id clojure.core/string?) -(s/def :github.copilot-sdk.generated.event-specs/type (s/spec (fn [v943] (or (s/valid? #{"session.start"} v943) (s/valid? #{"session.resume"} v943) (s/valid? #{"session.remote_steerable_changed"} v943) (s/valid? #{"session.error"} v943) (s/valid? #{"session.idle"} v943) (s/valid? #{"session.title_changed"} v943) (s/valid? #{"session.schedule_created"} v943) (s/valid? #{"session.schedule_cancelled"} v943) (s/valid? #{"session.info"} v943) (s/valid? #{"session.warning"} v943) (s/valid? #{"session.model_change"} v943) (s/valid? #{"session.mode_changed"} v943) (s/valid? #{"session.plan_changed"} v943) (s/valid? #{"session.workspace_file_changed"} v943) (s/valid? #{"session.handoff"} v943) (s/valid? #{"session.truncation"} v943) (s/valid? #{"session.snapshot_rewind"} v943) (s/valid? #{"session.shutdown"} v943) (s/valid? #{"session.context_changed"} v943) (s/valid? #{"session.usage_info"} v943) (s/valid? #{"session.compaction_start"} v943) (s/valid? #{"session.compaction_complete"} v943) (s/valid? #{"session.task_complete"} v943) (s/valid? #{"user.message"} v943) (s/valid? #{"pending_messages.modified"} v943) (s/valid? #{"assistant.turn_start"} v943) (s/valid? #{"assistant.intent"} v943) (s/valid? #{"assistant.reasoning"} v943) (s/valid? #{"assistant.reasoning_delta"} v943) (s/valid? #{"assistant.streaming_delta"} v943) (s/valid? #{"assistant.message"} v943) (s/valid? #{"assistant.message_start"} v943) (s/valid? #{"assistant.message_delta"} v943) (s/valid? #{"assistant.turn_end"} v943) (s/valid? #{"assistant.usage"} v943) (s/valid? #{"model.call_failure"} v943) (s/valid? #{"abort"} v943) (s/valid? #{"tool.user_requested"} v943) (s/valid? #{"tool.execution_start"} v943) (s/valid? #{"tool.execution_partial_result"} v943) (s/valid? #{"tool.execution_progress"} v943) (s/valid? #{"tool.execution_complete"} v943) (s/valid? #{"skill.invoked"} v943) (s/valid? #{"subagent.started"} v943) (s/valid? #{"subagent.completed"} v943) (s/valid? #{"subagent.failed"} v943) (s/valid? #{"subagent.selected"} v943) (s/valid? #{"subagent.deselected"} v943) (s/valid? #{"hook.start"} v943) (s/valid? #{"hook.end"} v943) (s/valid? #{"system.message"} v943) (s/valid? #{"system.notification"} v943) (s/valid? #{"permission.requested"} v943) (s/valid? #{"permission.completed"} v943) (s/valid? #{"user_input.requested"} v943) (s/valid? #{"user_input.completed"} v943) (s/valid? #{"elicitation.requested"} v943) (s/valid? #{"elicitation.completed"} v943) (s/valid? #{"sampling.requested"} v943) (s/valid? #{"sampling.completed"} v943) (s/valid? #{"mcp.oauth_required"} v943) (s/valid? #{"mcp.oauth_completed"} v943) (s/valid? #{"session.custom_notification"} v943) (s/valid? #{"external_tool.requested"} v943) (s/valid? #{"external_tool.completed"} v943) (s/valid? #{"command.queued"} v943) (s/valid? #{"command.execute"} v943) (s/valid? #{"command.completed"} v943) (s/valid? #{"auto_mode_switch.requested"} v943) (s/valid? #{"auto_mode_switch.completed"} v943) (s/valid? #{"commands.changed"} v943) (s/valid? #{"capabilities.changed"} v943) (s/valid? #{"exit_plan_mode.requested"} v943) (s/valid? #{"exit_plan_mode.completed"} v943) (s/valid? #{"session.tools_updated"} v943) (s/valid? #{"session.background_tasks_changed"} v943) (s/valid? #{"session.skills_loaded"} v943) (s/valid? #{"session.custom_agents_updated"} v943) (s/valid? #{"session.mcp_servers_loaded"} v943) (s/valid? #{"session.mcp_server_status_changed"} v943) (s/valid? #{"session.extensions_loaded"} v943))))) +(s/def :github.copilot-sdk.generated.event-specs/type (s/spec (fn [v945] (or (s/valid? #{"session.start"} v945) (s/valid? #{"session.resume"} v945) (s/valid? #{"session.remote_steerable_changed"} v945) (s/valid? #{"session.error"} v945) (s/valid? #{"session.idle"} v945) (s/valid? #{"session.title_changed"} v945) (s/valid? #{"session.schedule_created"} v945) (s/valid? #{"session.schedule_cancelled"} v945) (s/valid? #{"session.info"} v945) (s/valid? #{"session.warning"} v945) (s/valid? #{"session.model_change"} v945) (s/valid? #{"session.mode_changed"} v945) (s/valid? #{"session.plan_changed"} v945) (s/valid? #{"session.workspace_file_changed"} v945) (s/valid? #{"session.handoff"} v945) (s/valid? #{"session.truncation"} v945) (s/valid? #{"session.snapshot_rewind"} v945) (s/valid? #{"session.shutdown"} v945) (s/valid? #{"session.context_changed"} v945) (s/valid? #{"session.usage_info"} v945) (s/valid? #{"session.compaction_start"} v945) (s/valid? #{"session.compaction_complete"} v945) (s/valid? #{"session.task_complete"} v945) (s/valid? #{"user.message"} v945) (s/valid? #{"pending_messages.modified"} v945) (s/valid? #{"assistant.turn_start"} v945) (s/valid? #{"assistant.intent"} v945) (s/valid? #{"assistant.reasoning"} v945) (s/valid? #{"assistant.reasoning_delta"} v945) (s/valid? #{"assistant.streaming_delta"} v945) (s/valid? #{"assistant.message"} v945) (s/valid? #{"assistant.message_start"} v945) (s/valid? #{"assistant.message_delta"} v945) (s/valid? #{"assistant.turn_end"} v945) (s/valid? #{"assistant.usage"} v945) (s/valid? #{"model.call_failure"} v945) (s/valid? #{"abort"} v945) (s/valid? #{"tool.user_requested"} v945) (s/valid? #{"tool.execution_start"} v945) (s/valid? #{"tool.execution_partial_result"} v945) (s/valid? #{"tool.execution_progress"} v945) (s/valid? #{"tool.execution_complete"} v945) (s/valid? #{"skill.invoked"} v945) (s/valid? #{"subagent.started"} v945) (s/valid? #{"subagent.completed"} v945) (s/valid? #{"subagent.failed"} v945) (s/valid? #{"subagent.selected"} v945) (s/valid? #{"subagent.deselected"} v945) (s/valid? #{"hook.start"} v945) (s/valid? #{"hook.end"} v945) (s/valid? #{"system.message"} v945) (s/valid? #{"system.notification"} v945) (s/valid? #{"permission.requested"} v945) (s/valid? #{"permission.completed"} v945) (s/valid? #{"user_input.requested"} v945) (s/valid? #{"user_input.completed"} v945) (s/valid? #{"elicitation.requested"} v945) (s/valid? #{"elicitation.completed"} v945) (s/valid? #{"sampling.requested"} v945) (s/valid? #{"sampling.completed"} v945) (s/valid? #{"mcp.oauth_required"} v945) (s/valid? #{"mcp.oauth_completed"} v945) (s/valid? #{"session.custom_notification"} v945) (s/valid? #{"external_tool.requested"} v945) (s/valid? #{"external_tool.completed"} v945) (s/valid? #{"command.queued"} v945) (s/valid? #{"command.execute"} v945) (s/valid? #{"command.completed"} v945) (s/valid? #{"auto_mode_switch.requested"} v945) (s/valid? #{"auto_mode_switch.completed"} v945) (s/valid? #{"commands.changed"} v945) (s/valid? #{"capabilities.changed"} v945) (s/valid? #{"exit_plan_mode.requested"} v945) (s/valid? #{"exit_plan_mode.completed"} v945) (s/valid? #{"session.tools_updated"} v945) (s/valid? #{"session.background_tasks_changed"} v945) (s/valid? #{"session.skills_loaded"} v945) (s/valid? #{"session.custom_agents_updated"} v945) (s/valid? #{"session.mcp_servers_loaded"} v945) (s/valid? #{"session.mcp_server_status_changed"} v945) (s/valid? #{"session.extensions_loaded"} v945))))) (s/def :github.copilot-sdk.generated.event-specs/ui clojure.core/map?) @@ -411,7 +417,7 @@ (s/def :github.copilot-sdk.generated.event-specs/url clojure.core/string?) -(s/def :github.copilot-sdk.generated.event-specs/version (s/spec (fn [v944] (or (s/valid? clojure.core/number? v944) (s/valid? clojure.core/integer? v944))))) +(s/def :github.copilot-sdk.generated.event-specs/version (s/spec (fn [v946] (or (s/valid? clojure.core/number? v946) (s/valid? clojure.core/integer? v946))))) (s/def :github.copilot-sdk.generated.event-specs/warning-type clojure.core/string?) @@ -515,17 +521,17 @@ (s/def :github.copilot-sdk.generated.event-specs/session.mode_changed-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/new-mode :github.copilot-sdk.generated.event-specs/previous-mode])) -(s/def :github.copilot-sdk.generated.event-specs/session.model_change-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/new-model] :opt-un [:github.copilot-sdk.generated.event-specs/cause :github.copilot-sdk.generated.event-specs/previous-model :github.copilot-sdk.generated.event-specs/previous-reasoning-effort :github.copilot-sdk.generated.event-specs/reasoning-effort])) +(s/def :github.copilot-sdk.generated.event-specs/session.model_change-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/new-model] :opt-un [:github.copilot-sdk.generated.event-specs/cause :github.copilot-sdk.generated.event-specs/previous-model :github.copilot-sdk.generated.event-specs/previous-reasoning-effort :github.copilot-sdk.generated.event-specs/previous-reasoning-summary :github.copilot-sdk.generated.event-specs/reasoning-effort :github.copilot-sdk.generated.event-specs/reasoning-summary])) (s/def :github.copilot-sdk.generated.event-specs/session.plan_changed-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/operation])) (s/def :github.copilot-sdk.generated.event-specs/session.remote_steerable_changed-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/remote-steerable])) -(s/def :github.copilot-sdk.generated.event-specs/session.resume-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/event-count :github.copilot-sdk.generated.event-specs/resume-time] :opt-un [:github.copilot-sdk.generated.event-specs/already-in-use :github.copilot-sdk.generated.event-specs/context :github.copilot-sdk.generated.event-specs/continue-pending-work :github.copilot-sdk.generated.event-specs/reasoning-effort :github.copilot-sdk.generated.event-specs/remote-steerable :github.copilot-sdk.generated.event-specs/selected-model :github.copilot-sdk.generated.event-specs/session-was-active])) +(s/def :github.copilot-sdk.generated.event-specs/session.resume-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/event-count :github.copilot-sdk.generated.event-specs/resume-time] :opt-un [:github.copilot-sdk.generated.event-specs/already-in-use :github.copilot-sdk.generated.event-specs/context :github.copilot-sdk.generated.event-specs/continue-pending-work :github.copilot-sdk.generated.event-specs/reasoning-effort :github.copilot-sdk.generated.event-specs/reasoning-summary :github.copilot-sdk.generated.event-specs/remote-steerable :github.copilot-sdk.generated.event-specs/selected-model :github.copilot-sdk.generated.event-specs/session-was-active])) (s/def :github.copilot-sdk.generated.event-specs/session.schedule_cancelled-data (s/and (s/keys :req-un [:github.copilot-sdk.generated.event-specs/id]) (fn [data] (s/valid? clojure.core/integer? (:id data))))) -(s/def :github.copilot-sdk.generated.event-specs/session.schedule_created-data (s/and (s/keys :req-un [:github.copilot-sdk.generated.event-specs/id :github.copilot-sdk.generated.event-specs/interval-ms :github.copilot-sdk.generated.event-specs/prompt] :opt-un [:github.copilot-sdk.generated.event-specs/recurring]) (fn [data] (s/valid? clojure.core/integer? (:id data))))) +(s/def :github.copilot-sdk.generated.event-specs/session.schedule_created-data (s/and (s/keys :req-un [:github.copilot-sdk.generated.event-specs/id :github.copilot-sdk.generated.event-specs/interval-ms :github.copilot-sdk.generated.event-specs/prompt] :opt-un [:github.copilot-sdk.generated.event-specs/display-prompt :github.copilot-sdk.generated.event-specs/recurring]) (fn [data] (s/valid? clojure.core/integer? (:id data))))) (s/def :github.copilot-sdk.generated.event-specs/session.shutdown-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/code-changes :github.copilot-sdk.generated.event-specs/model-metrics :github.copilot-sdk.generated.event-specs/session-start-time :github.copilot-sdk.generated.event-specs/shutdown-type :github.copilot-sdk.generated.event-specs/total-api-duration-ms :github.copilot-sdk.generated.event-specs/total-premium-requests] :opt-un [:github.copilot-sdk.generated.event-specs/conversation-tokens :github.copilot-sdk.generated.event-specs/current-model :github.copilot-sdk.generated.event-specs/current-tokens :github.copilot-sdk.generated.event-specs/error-reason :github.copilot-sdk.generated.event-specs/system-tokens :github.copilot-sdk.generated.event-specs/token-details :github.copilot-sdk.generated.event-specs/tool-definitions-tokens :github.copilot-sdk.generated.event-specs/total-nano-aiu])) @@ -533,7 +539,7 @@ (s/def :github.copilot-sdk.generated.event-specs/session.snapshot_rewind-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/events-removed :github.copilot-sdk.generated.event-specs/up-to-event-id])) -(s/def :github.copilot-sdk.generated.event-specs/session.start-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/copilot-version :github.copilot-sdk.generated.event-specs/producer :github.copilot-sdk.generated.event-specs/session-id :github.copilot-sdk.generated.event-specs/start-time :github.copilot-sdk.generated.event-specs/version] :opt-un [:github.copilot-sdk.generated.event-specs/already-in-use :github.copilot-sdk.generated.event-specs/context :github.copilot-sdk.generated.event-specs/detached-from-spawning-parent-session-id :github.copilot-sdk.generated.event-specs/reasoning-effort :github.copilot-sdk.generated.event-specs/remote-steerable :github.copilot-sdk.generated.event-specs/selected-model])) +(s/def :github.copilot-sdk.generated.event-specs/session.start-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/copilot-version :github.copilot-sdk.generated.event-specs/producer :github.copilot-sdk.generated.event-specs/session-id :github.copilot-sdk.generated.event-specs/start-time :github.copilot-sdk.generated.event-specs/version] :opt-un [:github.copilot-sdk.generated.event-specs/already-in-use :github.copilot-sdk.generated.event-specs/context :github.copilot-sdk.generated.event-specs/detached-from-spawning-parent-session-id :github.copilot-sdk.generated.event-specs/reasoning-effort :github.copilot-sdk.generated.event-specs/reasoning-summary :github.copilot-sdk.generated.event-specs/remote-steerable :github.copilot-sdk.generated.event-specs/selected-model])) (s/def :github.copilot-sdk.generated.event-specs/session.task_complete-data (s/keys :opt-un [:github.copilot-sdk.generated.event-specs/success :github.copilot-sdk.generated.event-specs/summary])) From 57ba1ec6135c689db631f3055ecb83d51c3ba5d2 Mon Sep 17 00:00:00 2001 From: Karl Krukow Date: Tue, 19 May 2026 10:14:42 +0200 Subject: [PATCH 03/10] feat: port post-beta.4 upstream changes (#1290, #1306, #1308) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Port three upstream copilot-sdk changes following v1.0.0-beta.4: * #1290 — :session-id on hook input maps. Hook handlers now receive a :session-id key on the input map. The wire-provided sessionId from sub-agent hooks is preserved; otherwise the SDK fills in the parent session id. * #1306 — :cloud session config option. create-session and resume-session accept an optional :cloud {:repository {:owner _ :repository _}} map for binding the session to a cloud repository. Forwarded as cloud.repository.* on the wire. * #1308 — Optional permission and tool callbacks. :on-permission-request is now optional on create-session/resume-session; :handler is optional on tools defined via define-tool. When omitted, requests are not auto-resolved and applications resolve them via the new public functions: - handle-pending-tool-call! / --- CHANGELOG.md | 29 ++ doc/reference/API.md | 58 +++- src/github/copilot_sdk.clj | 39 +++ src/github/copilot_sdk/client.clj | 54 ++-- src/github/copilot_sdk/instrument.clj | 25 ++ src/github/copilot_sdk/session.clj | 131 ++++++++- src/github/copilot_sdk/specs.clj | 43 ++- src/github/copilot_sdk/tools.clj | 8 +- test/github/copilot_sdk/integration_test.clj | 278 +++++++++++++++++-- 9 files changed, 607 insertions(+), 58 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0918531..092d91d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,12 +4,41 @@ All notable changes to this project will be documented in this file. This change ## [Unreleased] ### Added (post-v1.0.0-beta.4 sync) +- **`:session-id` on hook input maps** — `:on-hook-invoke` handlers now receive + a `:session-id` key on the input map. When the upstream wire payload includes + a `sessionId` (sub-agent hooks), the wire-provided value is preserved; + otherwise the SDK fills in the parent session id as a convenience. + (upstream PR #1290) +- **`:cloud` session config option** — `create-session` and `resume-session` + accept an optional `:cloud` map for binding the session to a cloud repository. + Shape: `{:repository {:owner "user-or-org" :repository "repo-name"}}`. Both + `:owner` and `:repository` are required non-blank strings. Forwarded on the + wire as `cloud.repository.owner` / `cloud.repository.repository`. + (upstream PR #1306) +- **Optional permission and tool callbacks (manual pending RPCs)** — Following + upstream PR #1308, `:on-permission-request` is now **optional** on + `create-session` and `resume-session`, and `:handler` is optional on tools + built via `tools/define-tool`. When omitted, the runtime no longer + auto-responds to permission requests or tool calls. Applications can resolve + these requests asynchronously via the new public functions: + - `sdk/handle-pending-tool-call!` / `sdk/wire (:cloud config))) (:model-capabilities config) (assoc :model-capabilities (util/clj->wire (:model-capabilities config))) true (assoc :include-sub-agent-streaming-events @@ -1581,6 +1590,8 @@ (assoc :enable-session-telemetry (:enable-session-telemetry? config)) (:remote-session config) (assoc :remote-session (name (:remote-session config))) + (:cloud config) + (assoc :cloud (util/clj->wire (:cloud config))) (:model-capabilities config) (assoc :model-capabilities (util/clj->wire (:model-capabilities config))) true (assoc :include-sub-agent-streaming-events @@ -1658,6 +1669,11 @@ - :remote-session - Keyword. Per-session Mission Control remote mode: :off, :export, or :on. Forwarded as `remoteSession` on session.create. When omitted, the CLI applies its default. (upstream PR #1295, CLI 1.0.48) + - :cloud - Map. Creates a remote session in the cloud instead of a local session. + Optional `:repository` associates the cloud session with a GitHub + repository: `{:repository {:owner \"...\" :name \"...\" :branch \"...\"}}`. + `:branch` is optional. Forwarded as `cloud` on session.create. + (upstream PR #1306) Returns a CopilotSession." [client config] @@ -1734,11 +1750,6 @@ Returns a CopilotSession." [client session-id config] - (when-not (:on-permission-request config) - (throw (ex-info (str "An :on-permission-request handler is required when resuming a session. " - "For example, to allow all permissions, use " - "{:on-permission-request copilot/approve-all}.") - {:config config}))) (when-not (s/valid? ::specs/resume-session-config config) (throw (ex-info "Invalid resume session config" {:config config @@ -1851,11 +1862,6 @@ ;; use result as session )))" [client session-id config] - (when-not (:on-permission-request config) - (throw (ex-info (str "An :on-permission-request handler is required when resuming a session. " - "For example, to allow all permissions, use " - "{:on-permission-request copilot/approve-all}.") - {:config config}))) (when-not (s/valid? ::specs/resume-session-config config) (throw (ex-info "Invalid resume session config" {:config config diff --git a/src/github/copilot_sdk/instrument.clj b/src/github/copilot_sdk/instrument.clj index 5155c1e..f4efa3e 100644 --- a/src/github/copilot_sdk/instrument.clj +++ b/src/github/copilot_sdk/instrument.clj @@ -220,6 +220,31 @@ :args (s/cat :session ::specs/session) :ret (s/coll-of map?)) +;; Upstream PR #1308: manual resolution of pending tool calls and permission +;; requests. Inner functions perform more thorough validation (e.g. permission +;; :kind enum, mutual exclusivity of :result/:error). The fdef only enforces +;; the universally-required :request-id; the rest is checked at call time so +;; the spec doesn't have to mirror the full result/decision shape here. +(register-fdef! github.copilot-sdk.session/handle-pending-tool-call! + :args (s/cat :session ::specs/session + :opts (s/keys :req-un [::specs/request-id])) + :ret any?) + +(register-fdef! github.copilot-sdk.session/!! :token)) - tool-handlers (into {} (map (fn [t] [(:tool-name t) (:tool-handler t)]) tools)) + ;; Upstream PR #1308: declaration-only tools (no :tool-handler) are + ;; left out of the handler map — they're distinguished from tools with + ;; handlers, and unhandled invocations are left pending for manual + ;; resolution via handle-pending-tool-call!. + tool-handlers (into {} (keep (fn [t] + (when-let [h (:tool-handler t)] + [(:tool-name t) h])) + tools)) command-handlers (into {} (map (fn [c] [(:name c) (:command-handler c)]) commands))] ;; Store session state and IO in client's atom (swap! (:state client) @@ -631,11 +638,18 @@ "sessionEnd" :on-session-end "errorOccurred" :on-error-occurred nil) - handler (when handler-key (get hooks handler-key))] - (if-not handler - {:result nil} - (try - (let [result (handler input {:session-id session-id}) + handler (when handler-key (get hooks handler-key))] + (if-not handler + {:result nil} + (try + (let [;; Upstream PR #1290: BaseHookInput.sessionId. Preserve the + ;; wire-provided :session-id when present (it may identify a + ;; sub-agent session distinct from the outer session-id); + ;; otherwise fall back to the outer session-id. + input (cond-> input + (not (contains? input :session-id)) + (assoc :session-id session-id)) + result (handler input {:session-id session-id}) ;; If handler returns a channel, await it result (if (channel? result) ( {:tool-name name :tool-description description - :tool-parameters parameters - :tool-handler handler} + :tool-parameters parameters} + ;; Upstream PR #1308: handler is optional. Declaration-only tools (no + ;; handler) are surfaced as external_tool.requested events; consumers + ;; resolve them via handle-pending-tool-call!. + (some? handler) + (assoc :tool-handler handler) (some? overrides-built-in-tool) (assoc :overrides-built-in-tool overrides-built-in-tool))) diff --git a/test/github/copilot_sdk/integration_test.clj b/test/github/copilot_sdk/integration_test.clj index 723a814..36333b4 100644 --- a/test/github/copilot_sdk/integration_test.clj +++ b/test/github/copilot_sdk/integration_test.clj @@ -1192,6 +1192,65 @@ {:on-permission-request sdk/approve-all :remote-session :bogus}))))) +(deftest test-cloud-session-config-forwarded-on-wire + (testing "cloud {:repository {...}} is forwarded as cloud.repository on session.create (upstream PR #1306)" + (let [seen (atom {}) + _ (mock/set-request-hook! *mock-server* (fn [method params] + (when (= "session.create" method) + (swap! seen assoc method params)))) + _ (sdk/create-session *test-client* + {:on-permission-request sdk/approve-all + :cloud {:repository {:owner "octocat" + :name "hello-world" + :branch "main"}}}) + create-params (get @seen "session.create")] + (is (= {:owner "octocat" :name "hello-world" :branch "main"} + (get-in create-params [:cloud :repository]))) + (is (not (contains? create-params :cloud-repository))))) + + (testing "cloud :repository may omit :branch" + (let [seen (atom {}) + _ (mock/set-request-hook! *mock-server* (fn [method params] + (when (= "session.create" method) + (swap! seen assoc method params)))) + _ (sdk/create-session *test-client* + {:on-permission-request sdk/approve-all + :cloud {:repository {:owner "octocat" + :name "hello-world"}}}) + create-params (get @seen "session.create")] + (is (= {:owner "octocat" :name "hello-world"} + (get-in create-params [:cloud :repository]))))) + + (testing "cloud {} (empty options) is forwarded as empty map" + (let [seen (atom {}) + _ (mock/set-request-hook! *mock-server* (fn [method params] + (when (= "session.create" method) + (swap! seen assoc method params)))) + _ (sdk/create-session *test-client* + {:on-permission-request sdk/approve-all + :cloud {}}) + create-params (get @seen "session.create")] + (is (= {} (:cloud create-params))))) + + (testing "cloud is omitted from wire when not set" + (let [seen (atom {}) + _ (mock/set-request-hook! *mock-server* (fn [method params] + (when (= "session.create" method) + (swap! seen assoc method params)))) + _ (sdk/create-session *test-client* {:on-permission-request sdk/approve-all}) + create-params (get @seen "session.create")] + (is (not (contains? create-params :cloud))))) + + (testing "cloud config with invalid :repository shape is rejected by spec" + (is (thrown? Exception + (sdk/create-session *test-client* + {:on-permission-request sdk/approve-all + :cloud {:repository {:branch "main"}}}))) ; missing :owner and :name + (is (thrown? Exception + (sdk/create-session *test-client* + {:on-permission-request sdk/approve-all + :cloud {:repository "octocat/hello-world"}}))))) + (deftest test-agent-forwarded-on-wire (testing "agent is forwarded in session.create when set (upstream PR #722)" (let [seen (atom {}) @@ -1304,23 +1363,16 @@ (is (= {:kind :approve-once} (sdk/approve-all {:permission-kind kind} {:session-id "s1"})))))) -(deftest test-permission-handler-required - (testing "create-session throws without :on-permission-request" - (is (thrown-with-msg? clojure.lang.ExceptionInfo - #"on-permission-request handler is required" - (sdk/create-session *test-client* {})))) +(deftest test-permission-handler-now-optional + ;; Upstream PR #1308 made :on-permission-request optional. Previously this + ;; test asserted that create-session/resume-session threw without it. + (testing "create-session succeeds without :on-permission-request" + (is (some? (sdk/create-session *test-client* {})))) - (testing "create-session throws with nil handler" - (is (thrown-with-msg? clojure.lang.ExceptionInfo - #"on-permission-request handler is required" - (sdk/create-session *test-client* {:on-permission-request nil})))) - - (testing "resume-session throws without :on-permission-request" - (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all}) - session-id (sdk/session-id session)] - (is (thrown-with-msg? clojure.lang.ExceptionInfo - #"on-permission-request handler is required" - (sdk/resume-session *test-client* session-id {})))))) + (testing "resume-session succeeds without :on-permission-request" + (let [_ (sdk/create-session *test-client* {:on-permission-request sdk/approve-all}) + session-id (sdk/get-last-session-id *test-client*)] + (is (some? (sdk/resume-session *test-client* session-id {})))))) (deftest test-permission-denied-with-deny-handler (testing "Permission requests are denied when handler denies" @@ -2702,6 +2754,70 @@ :cwd "/workspace"}})] (is (nil? (:result response)))))) +(deftest test-hooks-input-exposes-session-id + (testing "hook input includes :session-id (upstream PR #1290 — BaseHookInput.sessionId)" + (let [handler-called (atom nil) + session (sdk/create-session *test-client* + {:on-permission-request sdk/approve-all + :hooks {:on-pre-tool-use + (fn [input _ctx] + (reset! handler-called input) + nil)}}) + session-id (sdk/session-id session) + _ (mock/send-rpc-request! *mock-server* + "hooks.invoke" + {:sessionId session-id + :hookType "preToolUse" + :input {:toolName "bash" + :toolArgs {} + :sessionId session-id + :timestamp 12345 + :cwd "/workspace"}})] + (is (some? @handler-called)) + (is (= session-id (:session-id @handler-called))))) + + (testing "hook input :session-id preserves wire-provided value (sub-agent case)" + (let [handler-called (atom nil) + session (sdk/create-session *test-client* + {:on-permission-request sdk/approve-all + :hooks {:on-pre-tool-use + (fn [input _ctx] + (reset! handler-called input) + nil)}}) + parent-session-id (sdk/session-id session) + sub-agent-session-id "sub-agent-session-xyz" + _ (mock/send-rpc-request! *mock-server* + "hooks.invoke" + {:sessionId parent-session-id + :hookType "preToolUse" + :input {:toolName "bash" + :toolArgs {} + :sessionId sub-agent-session-id + :timestamp 12345 + :cwd "/workspace"}})] + (is (some? @handler-called)) + (is (= sub-agent-session-id (:session-id @handler-called))))) + + (testing "hook input :session-id falls back to outer session-id when wire omits it" + (let [handler-called (atom nil) + session (sdk/create-session *test-client* + {:on-permission-request sdk/approve-all + :hooks {:on-pre-tool-use + (fn [input _ctx] + (reset! handler-called input) + nil)}}) + session-id (sdk/session-id session) + _ (mock/send-rpc-request! *mock-server* + "hooks.invoke" + {:sessionId session-id + :hookType "preToolUse" + :input {:toolName "bash" + :toolArgs {} + :timestamp 12345 + :cwd "/workspace"}})] + (is (some? @handler-called)) + (is (= session-id (:session-id @handler-called)))))) + ;; ----------------------------------------------------------------------------- ;; User Input Handler Tests (server→client RPC) ;; ----------------------------------------------------------------------------- @@ -4042,3 +4158,133 @@ {:tool-call-id "tc-1" :agent-name "rubber-duck" :agent-display-name "Rubber Duck"})))) + +;; ----------------------------------------------------------------------------- +;; Optional callbacks (upstream PR #1308) +;; ----------------------------------------------------------------------------- + +(deftest test-create-session-without-permission-handler + (testing "create-session accepts omission of :on-permission-request (upstream PR #1308)" + (let [requests (atom []) + _ (mock/set-request-hook! *mock-server* + (fn [method params] + (swap! requests conj {:method method :params params}))) + session (sdk/create-session *test-client* {}) + create-rpcs (filter #(= "session.create" (:method %)) @requests)] + (is (= 1 (count create-rpcs)) "session.create still issued") + (is (some? (sdk/session-id session)))))) + +(deftest test-resume-session-without-permission-handler + (testing "resume-session accepts omission of :on-permission-request" + (let [requests (atom []) + _ (sdk/create-session *test-client* {}) + session-id (sdk/get-last-session-id *test-client*) + _ (mock/set-request-hook! *mock-server* + (fn [method params] + (swap! requests conj {:method method :params params}))) + resumed (sdk/resume-session *test-client* session-id {}) + resume-rpcs (filter #(= "session.resume" (:method %)) @requests)] + (is (= 1 (count resume-rpcs))) + (is (some? (sdk/session-id resumed)))))) + +(deftest test-define-tool-without-handler + (testing "define-tool accepts omission of :handler (declaration-only tool, upstream PR #1308)" + (let [tool (tools/define-tool "manual_lookup" + {:description "Look up status manually" + :parameters {:type "object" + :properties {:id {:type "string"}} + :required ["id"]}})] + (is (= "manual_lookup" (:tool-name tool))) + (is (not (contains? tool :tool-handler)) + "tool map must NOT contain :tool-handler key when handler omitted") + ;; Must pass tool spec validation (handler now optional) + (is (s/valid? :github.copilot-sdk.specs/tool tool))))) + +(deftest test-declaration-only-tool-not-stored-in-handler-map + (testing "declaration-only tools don't populate :tool-handlers" + (let [decl-tool (tools/define-tool "decl_only" {:description "decl-only"}) + handled-tool (tools/define-tool "with_handler" + {:description "has handler" + :handler (fn [_ _] "ok")}) + session (sdk/create-session *test-client* + {:on-permission-request sdk/approve-all + :tools [decl-tool handled-tool]}) + session-id (sdk/session-id session) + tool-handlers (get-in @(:state *test-client*) + [:sessions session-id :tool-handlers])] + (is (not (contains? tool-handlers "decl_only")) + "declaration-only tools must not be in :tool-handlers") + (is (contains? tool-handlers "with_handler") + "tools with handlers must remain in :tool-handlers")))) + +(deftest test-handle-pending-permission-request!-sends-rpc + (testing "handle-pending-permission-request! issues session.permissions.handlePendingPermissionRequest" + (let [requests (atom []) + _ (mock/set-request-hook! *mock-server* + (fn [method params] + (swap! requests conj {:method method :params params}))) + session (sdk/create-session *test-client* {})] + (sdk/handle-pending-permission-request! session + {:request-id "req-42" + :result {:kind :approve-once}}) + (let [pending-rpcs (filter #(= "session.permissions.handlePendingPermissionRequest" + (:method %)) + @requests)] + (is (= 1 (count pending-rpcs))) + (is (= "req-42" (get-in (first pending-rpcs) [:params :requestId]))) + ;; Result is wire-serialized via clj->wire: keyword :kind → "approve-once" + (is (= "approve-once" (get-in (first pending-rpcs) + [:params :result :kind])))))) + + (testing "handle-pending-permission-request! rejects :no-result" + (let [session (sdk/create-session *test-client* {})] + (is (thrown? Exception + (sdk/handle-pending-permission-request! + session + {:request-id "req-1" :result {:kind :no-result}}))))) + + (testing "handle-pending-permission-request! rejects malformed result" + (let [session (sdk/create-session *test-client* {})] + (is (thrown? Exception + (sdk/handle-pending-permission-request! + session + {:request-id "req-1" :result "not-a-map"})))))) + +(deftest test-handle-pending-tool-call!-sends-rpc + (testing "handle-pending-tool-call! with :result issues session.tools.handlePendingToolCall" + (let [requests (atom []) + _ (mock/set-request-hook! *mock-server* + (fn [method params] + (swap! requests conj {:method method :params params}))) + session (sdk/create-session *test-client* {})] + (sdk/handle-pending-tool-call! session + {:request-id "tool-req-7" + :result "MANUAL_STATUS_OK"}) + (let [pending (filter #(= "session.tools.handlePendingToolCall" (:method %)) + @requests)] + (is (= 1 (count pending))) + (is (= "tool-req-7" (get-in (first pending) [:params :requestId]))) + ;; String result is normalized through normalize-tool-result + (is (= "MANUAL_STATUS_OK" + (get-in (first pending) [:params :result :textResultForLlm])))))) + + (testing "handle-pending-tool-call! with :error forwards error string" + (let [requests (atom []) + _ (mock/set-request-hook! *mock-server* + (fn [method params] + (swap! requests conj {:method method :params params}))) + session (sdk/create-session *test-client* {})] + (sdk/handle-pending-tool-call! session + {:request-id "tool-req-8" + :error "manual failure"}) + (let [pending (first (filter #(= "session.tools.handlePendingToolCall" (:method %)) + @requests))] + (is (= "manual failure" (get-in pending [:params :error]))) + (is (not (contains? (:params pending) :result)))))) + + (testing "handle-pending-tool-call! rejects :result and :error together" + (let [session (sdk/create-session *test-client* {})] + (is (thrown? Exception + (sdk/handle-pending-tool-call! + session + {:request-id "x" :result "a" :error "b"})))))) From 9c4331d127d298b8cd929d60ad59a8aef07f47fb Mon Sep 17 00:00:00 2001 From: Karl Krukow Date: Tue, 19 May 2026 13:42:52 +0200 Subject: [PATCH 04/10] fix(review): address multi-model review findings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Opus 4.7 finding (MEDIUM): :cloud diverged from upstream — upstream's ResumeSessionConfig is a Pick that explicitly excludes `cloud`. Cloud is creation-only. Drop :cloud from resume-session-config-keys, from the :opt-un of ::resume-session-config and ::join-session-config, and from build-resume-session-params. GPT-5.5 finding (MEDIUM): define-tool-from-spec still installed a :tool-handler wrapper when :handler was omitted, causing v3 external_tool.requested events to auto-resolve to nil instead of remaining pending. Mirror define-tool: only attach :tool-handler when a user handler is supplied. Added a test for declaration-only tools via define-tool-from-spec. Updated CHANGELOG and API.md to clarify that :cloud is create-only. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CHANGELOG.md | 12 +++++++----- doc/reference/API.md | 2 +- src/github/copilot_sdk/client.clj | 2 -- src/github/copilot_sdk/specs.clj | 3 --- src/github/copilot_sdk/tools.clj | 10 +++++++--- test/github/copilot_sdk/integration_test.clj | 8 ++++++++ 6 files changed, 23 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 092d91d..d5b11ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,11 +9,13 @@ All notable changes to this project will be documented in this file. This change a `sessionId` (sub-agent hooks), the wire-provided value is preserved; otherwise the SDK fills in the parent session id as a convenience. (upstream PR #1290) -- **`:cloud` session config option** — `create-session` and `resume-session` - accept an optional `:cloud` map for binding the session to a cloud repository. - Shape: `{:repository {:owner "user-or-org" :repository "repo-name"}}`. Both - `:owner` and `:repository` are required non-blank strings. Forwarded on the - wire as `cloud.repository.owner` / `cloud.repository.repository`. +- **`:cloud` session config option (create only)** — `create-session` accepts + an optional `:cloud` map for creating a remote cloud session. Shape: + `{:repository {:owner "octocat" :name "hello-world" :branch "main"}}` — `:owner` + and `:name` are required non-blank strings; `:branch` is optional. Forwarded on + the wire as `cloud.repository.*`. Matches upstream's `CloudSessionOptions` / + `CloudSessionRepository`. Not accepted on `resume-session` / `join-session`, + matching upstream `ResumeSessionConfig` (Pick excludes `cloud`). (upstream PR #1306) - **Optional permission and tool callbacks (manual pending RPCs)** — Following upstream PR #1308, `:on-permission-request` is now **optional** on diff --git a/doc/reference/API.md b/doc/reference/API.md index f59fc28..4aea125 100644 --- a/doc/reference/API.md +++ b/doc/reference/API.md @@ -266,7 +266,7 @@ Create a client and session together, ensuring both are cleaned up on exit. | `:model-capabilities` | map | Model capabilities override. DeepPartial of model capabilities, e.g. `{:model-supports {:supports-vision true}}`. (upstream PR #1029) | | `:include-sub-agent-streaming-events?` | boolean | Forward streaming events from sub-agents to the parent session's event stream. Defaults to `true` on the wire. (upstream PR #1108) | | `:remote-session` | keyword | Per-session Mission Control mode: `:off`, `:export`, or `:on`. When omitted, the CLI applies its default. `:off` disables remote, `:export` exports session events to Mission Control without enabling remote steering, `:on` enables both. Forwarded as `remoteSession`. (upstream PR #1295, CLI 1.0.48) | -| `:cloud` | map | Bind the session to a cloud repository. Shape: `{:repository {:owner "octocat" :repository "hello"}}`. Both `:owner` and `:repository` are required non-blank strings. Forwarded as `cloud.repository.*` on `session.create` and `session.resume`. (upstream PR #1306) | +| `:cloud` | map | (create-session only) Creates a remote cloud session. Shape: `{:repository {:owner "octocat" :name "hello-world" :branch "main"}}` — `:owner` and `:name` are required non-blank strings; `:branch` is optional. Forwarded as `cloud.repository.*` on `session.create`. Not accepted on `resume-session` (matches upstream `ResumeSessionConfig`). (upstream PR #1306) | #### `resume-session` diff --git a/src/github/copilot_sdk/client.clj b/src/github/copilot_sdk/client.clj index eca519b..dcecd2b 100644 --- a/src/github/copilot_sdk/client.clj +++ b/src/github/copilot_sdk/client.clj @@ -1590,8 +1590,6 @@ (assoc :enable-session-telemetry (:enable-session-telemetry? config)) (:remote-session config) (assoc :remote-session (name (:remote-session config))) - (:cloud config) - (assoc :cloud (util/clj->wire (:cloud config))) (:model-capabilities config) (assoc :model-capabilities (util/clj->wire (:model-capabilities config))) true (assoc :include-sub-agent-streaming-events diff --git a/src/github/copilot_sdk/specs.clj b/src/github/copilot_sdk/specs.clj index aa3dc2d..0fe862f 100644 --- a/src/github/copilot_sdk/specs.clj +++ b/src/github/copilot_sdk/specs.clj @@ -564,7 +564,6 @@ :create-session-fs-handler :enable-config-discovery :model-capabilities :github-token :enable-session-telemetry? :remote-session - :cloud :include-sub-agent-streaming-events?}) (s/def ::resume-session-config @@ -583,7 +582,6 @@ ::continue-pending-work? ::enable-session-telemetry? ::remote-session - ::cloud ::include-sub-agent-streaming-events?]) resume-session-config-keys)) @@ -604,7 +602,6 @@ ::continue-pending-work? ::enable-session-telemetry? ::remote-session - ::cloud ::include-sub-agent-streaming-events?]) resume-session-config-keys)) diff --git a/src/github/copilot_sdk/tools.clj b/src/github/copilot_sdk/tools.clj index c17a079..305fcb6 100644 --- a/src/github/copilot_sdk/tools.clj +++ b/src/github/copilot_sdk/tools.clj @@ -82,13 +82,17 @@ ;; The handler should validate using the spec (cond-> {:tool-name name :tool-description description - :tool-parameters nil ; User should provide JSON schema if needed - :tool-handler (fn [args invocation] + :tool-parameters nil} ; User should provide JSON schema if needed + ;; Upstream PR #1308: handler is optional. Declaration-only tools (no + ;; handler) are surfaced as external_tool.requested events; consumers + ;; resolve them via handle-pending-tool-call!. + (some? handler) + (assoc :tool-handler (fn [args invocation] (if (and spec (not (s/valid? spec args))) {:text-result-for-llm (str "Invalid arguments: " (s/explain-str spec args)) :result-type "failure" :error "spec validation failed"} - (handler args invocation)))} + (handler args invocation)))) (some? overrides-built-in-tool) (assoc :overrides-built-in-tool overrides-built-in-tool))) diff --git a/test/github/copilot_sdk/integration_test.clj b/test/github/copilot_sdk/integration_test.clj index 36333b4..b1100e6 100644 --- a/test/github/copilot_sdk/integration_test.clj +++ b/test/github/copilot_sdk/integration_test.clj @@ -4198,6 +4198,14 @@ (is (not (contains? tool :tool-handler)) "tool map must NOT contain :tool-handler key when handler omitted") ;; Must pass tool spec validation (handler now optional) + (is (s/valid? :github.copilot-sdk.specs/tool tool)))) + + (testing "define-tool-from-spec accepts omission of :handler (upstream PR #1308)" + (let [tool (tools/define-tool-from-spec "manual_spec_tool" + {:description "Declaration-only spec tool"})] + (is (= "manual_spec_tool" (:tool-name tool))) + (is (not (contains? tool :tool-handler)) + "define-tool-from-spec must NOT install a wrapper handler when :handler omitted") (is (s/valid? :github.copilot-sdk.specs/tool tool))))) (deftest test-declaration-only-tool-not-stored-in-handler-map From 2ae8851b79764f44f1e8b8e2f72aa3eaf0458ce2 Mon Sep 17 00:00:00 2001 From: Karl Krukow Date: Tue, 19 May 2026 13:58:54 +0200 Subject: [PATCH 05/10] fix(review-r1): address Copilot review round 1 - session.clj: validate :error is a string in handle-pending-tool-call! and --- doc/reference/API.md | 2 +- src/github/copilot_sdk/session.clj | 4 ++++ test/github/copilot_sdk/integration_test.clj | 13 ++++++++++++- 3 files changed, 17 insertions(+), 2 deletions(-) diff --git a/doc/reference/API.md b/doc/reference/API.md index 4aea125..2fda24c 100644 --- a/doc/reference/API.md +++ b/doc/reference/API.md @@ -1552,7 +1552,7 @@ When Copilot invokes `lookup_issue`, the SDK automatically runs your handler and **Declaration-only tools (manual resolution):** -The `:handler` key is **optional** (upstream PR #1308). When omitted, the SDK does not auto-respond to tool calls — the call surfaces as a `:copilot/session.tool_call` event with a pending request id, and the application resolves it later via `handle-pending-tool-call!`. Useful for human-in-the-loop UIs or out-of-process tool execution. +The `:handler` key is **optional** (upstream PR #1308). When omitted, the SDK does not auto-respond to tool calls — the call surfaces as a `:copilot/external_tool.requested` event with a pending request id, and the application resolves it later via `handle-pending-tool-call!`. Useful for human-in-the-loop UIs or out-of-process tool execution. ```clojure (def manual-tool diff --git a/src/github/copilot_sdk/session.clj b/src/github/copilot_sdk/session.clj index 9faf5bc..1b9016b 100644 --- a/src/github/copilot_sdk/session.clj +++ b/src/github/copilot_sdk/session.clj @@ -1240,6 +1240,8 @@ (throw (ex-info ":request-id is required" {:opts opts}))) (when (and (contains? opts :result) (contains? opts :error)) (throw (ex-info ":result and :error are mutually exclusive" {:opts opts}))) + (when (and (contains? opts :error) (not (string? error))) + (throw (ex-info ":error must be a string when provided" {:opts opts}))) (let [conn (connection-io client) base {:session-id session-id :request-id request-id} params (cond @@ -1258,6 +1260,8 @@ (throw (ex-info ":request-id is required" {:opts opts}))) (when (and (contains? opts :result) (contains? opts :error)) (throw (ex-info ":result and :error are mutually exclusive" {:opts opts}))) + (when (and (contains? opts :error) (not (string? error))) + (throw (ex-info ":error must be a string when provided" {:opts opts}))) (let [conn (connection-io client) base {:session-id session-id :request-id request-id} params (cond diff --git a/test/github/copilot_sdk/integration_test.clj b/test/github/copilot_sdk/integration_test.clj index b1100e6..d661291 100644 --- a/test/github/copilot_sdk/integration_test.clj +++ b/test/github/copilot_sdk/integration_test.clj @@ -4295,4 +4295,15 @@ (is (thrown? Exception (sdk/handle-pending-tool-call! session - {:request-id "x" :result "a" :error "b"})))))) + {:request-id "x" :result "a" :error "b"}))))) + + (testing "handle-pending-tool-call! rejects non-string :error" + (let [session (sdk/create-session *test-client* {})] + (is (thrown-with-msg? Exception #":error must be a string" + (sdk/handle-pending-tool-call! + session + {:request-id "x" :error {:code 1}}))) + (is (thrown-with-msg? Exception #":error must be a string" + (sdk/handle-pending-tool-call! + session + {:request-id "x" :error 42})))))) From 5986c75d967138737fff1006ff6c76c54816fcc2 Mon Sep 17 00:00:00 2001 From: Karl Krukow Date: Tue, 19 May 2026 14:18:19 +0200 Subject: [PATCH 06/10] fix(review-r2): address Copilot review round 2 - Enforce non-blank :name in ::cloud-repository spec (was string? via shared ::name spec, allowing blanks despite docs) - handle-pending-tool-call! and async variant now throw when neither :result nor :error is supplied (previously fell through to default 'tool returned no result' payload) - Add tests for both new guards Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CHANGELOG.md | 11 +++++++++++ src/github/copilot_sdk/session.clj | 4 ++++ src/github/copilot_sdk/specs.clj | 9 +++++++-- test/github/copilot_sdk/integration_test.clj | 16 +++++++++++++++- 4 files changed, 37 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d5b11ee..051b457 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -42,6 +42,17 @@ All notable changes to this project will be documented in this file. This change event fields include `:display-prompt`, `:reasoning-summary`, `:previous-reasoning-summary`. (upstream PRs #1305, #1307) +### Fixed (post-v1.0.0-beta.4 sync, review iteration) +- `::cloud-repository` spec now enforces non-blank `:name` (was just `string?` + via the shared `::name` spec, allowing blanks despite docs). +- `handle-pending-tool-call!` and ` Date: Tue, 19 May 2026 14:32:40 +0200 Subject: [PATCH 07/10] fix(review-r3): stricter validation in pending-RPC resolvers - :request-id must be a non-blank string across all four pending-RPC resolvers (previously a blank string would pass and produce opaque server-side errors) - handle-pending-permission-request! and async variant now validate :result :kind is a keyword in the documented decision set (:approve-once, :approve-for-session, :approve-for-location, :approve-permanently, :reject) - Add private supported-permission-decision-kinds set and check-pending-* helpers to avoid duplicating validation logic - Add integration tests for blank :request-id and bad :kind shapes Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CHANGELOG.md | 10 ++++ src/github/copilot_sdk/session.clj | 61 ++++++++++++++------ test/github/copilot_sdk/integration_test.clj | 44 +++++++++++++- 3 files changed, 95 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 051b457..c018749 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -50,6 +50,16 @@ All notable changes to this project will be documented in this file. This change default "tool returned no result" payload). - `handle-pending-tool-call!` / `! >!! Date: Tue, 19 May 2026 14:43:40 +0200 Subject: [PATCH 08/10] docs(review-r4): document handler-optional and on-permission-request-optional - create-session, resume-session, --- src/github/copilot_sdk/client.clj | 24 ++++++++++---- src/github/copilot_sdk/tools.clj | 52 +++++++++++++++++++++++++++---- 2 files changed, 64 insertions(+), 12 deletions(-) diff --git a/src/github/copilot_sdk/client.clj b/src/github/copilot_sdk/client.clj index dcecd2b..1dc450c 100644 --- a/src/github/copilot_sdk/client.clj +++ b/src/github/copilot_sdk/client.clj @@ -1618,8 +1618,13 @@ (defn create-session "Create a new conversation session. - Config options (`:on-permission-request` is **required**): - - :on-permission-request - Permission handler function (**required**, e.g. `approve-all`) + Config options (`:on-permission-request` is **optional** since upstream + PR #1308 — omit it to leave permission requests pending for manual + resolution via `session/handle-pending-permission-request!`): + - :on-permission-request - Permission handler function (optional, e.g. `approve-all`). + When omitted, permission requests are surfaced as + `:copilot/permission.requested` events and remain + pending until resolved by the application. - :session-id - Custom session ID - :client-name - Client name to identify the application (included in User-Agent header) - :model - Model to use (e.g., \"gpt-5.4\") @@ -1708,8 +1713,13 @@ (defn resume-session "Resume an existing session by ID. - Config options (`:on-permission-request` is **required**): - - :on-permission-request - Permission handler function (**required**, e.g. `approve-all`) + Config options (`:on-permission-request` is **optional** since upstream + PR #1308 — omit it to leave permission requests pending for manual + resolution via `session/handle-pending-permission-request!`): + - :on-permission-request - Permission handler function (optional, e.g. `approve-all`). + When omitted, permission requests are surfaced as + `:copilot/permission.requested` events and remain + pending until resolved by the application. - :client-name - Client name to identify the application (included in User-Agent header) - :model - Change the model for the resumed session - :tools - Tools exposed to the CLI server @@ -1784,7 +1794,8 @@ (defn result) + - :handler - Function (fn [args invocation] -> result). + **Optional** since upstream PR #1308: when + omitted, the tool is declaration-only and + the runtime emits a + `:copilot/external_tool.requested` event + whenever the LLM calls it. Applications + resolve the pending call by reading the + `:request-id` from the event data and + calling `session/handle-pending-tool-call!` + (or the async ` {:tool-name name @@ -60,10 +79,22 @@ - opts map: - :description - Tool description - :spec - A clojure.spec for the arguments - - :handler - Function (fn [args invocation] -> result) + - :handler - Function (fn [args invocation] -> result). + **Optional** since upstream PR #1308: when + omitted, no `:tool-handler` is installed + and the tool is declaration-only. The + runtime emits a + `:copilot/external_tool.requested` event + on call; applications resolve it via + `session/handle-pending-tool-call!` + (or ` Date: Tue, 19 May 2026 14:55:00 +0200 Subject: [PATCH 09/10] docs(review-r5): use copilot/ alias and double-backticks for <-prefixed names - create-session/resume-session docstrings now reference copilot/handle-pending-permission-request! (the public API name) instead of the internal session/ namespace - define-tool/define-tool-from-spec docstrings reference copilot/handle-pending-tool-call! - Async variants (names starting with '<') are wrapped in double backticks to avoid markdown parsers mis-reading '`<...' as an HTML tag fragment Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- src/github/copilot_sdk/client.clj | 4 ++-- src/github/copilot_sdk/tools.clj | 12 ++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/github/copilot_sdk/client.clj b/src/github/copilot_sdk/client.clj index 1dc450c..c94d5df 100644 --- a/src/github/copilot_sdk/client.clj +++ b/src/github/copilot_sdk/client.clj @@ -1620,7 +1620,7 @@ Config options (`:on-permission-request` is **optional** since upstream PR #1308 — omit it to leave permission requests pending for manual - resolution via `session/handle-pending-permission-request!`): + resolution via `copilot/handle-pending-permission-request!`): - :on-permission-request - Permission handler function (optional, e.g. `approve-all`). When omitted, permission requests are surfaced as `:copilot/permission.requested` events and remain @@ -1715,7 +1715,7 @@ Config options (`:on-permission-request` is **optional** since upstream PR #1308 — omit it to leave permission requests pending for manual - resolution via `session/handle-pending-permission-request!`): + resolution via `copilot/handle-pending-permission-request!`): - :on-permission-request - Permission handler function (optional, e.g. `approve-all`). When omitted, permission requests are surfaced as `:copilot/permission.requested` events and remain diff --git a/src/github/copilot_sdk/tools.clj b/src/github/copilot_sdk/tools.clj index 3732b9e..6ce9fc2 100644 --- a/src/github/copilot_sdk/tools.clj +++ b/src/github/copilot_sdk/tools.clj @@ -19,8 +19,8 @@ whenever the LLM calls it. Applications resolve the pending call by reading the `:request-id` from the event data and - calling `session/handle-pending-tool-call!` - (or the async ` {:tool-name name @@ -86,8 +86,8 @@ runtime emits a `:copilot/external_tool.requested` event on call; applications resolve it via - `session/handle-pending-tool-call!` - (or ` Date: Tue, 19 May 2026 15:07:22 +0200 Subject: [PATCH 10/10] fix(review-r6): add :user-not-available to supported permission kinds Schema cross-check (api.schema.json $defs/PermissionDecision) confirmed six variants in the upstream union: ApproveOnce, ApproveForSession, ApproveForLocation, ApprovePermanently, Reject, UserNotAvailable. - Add :user-not-available to supported-permission-decision-kinds - Update docstring to list the full set and reference PermissionDecision - Add positive integration tests for :user-not-available and :approve-permanently (previously only :approve-once was exercised) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CHANGELOG.md | 11 ++++--- src/github/copilot_sdk/session.clj | 24 ++++++++++----- test/github/copilot_sdk/integration_test.clj | 32 ++++++++++++++++++++ 3 files changed, 54 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c018749..6dc0ff7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -55,11 +55,12 @@ All notable changes to this project will be documented in this file. This change `