diff --git a/.copilot-schema-version b/.copilot-schema-version index feca5b2..73b4678 100644 --- a/.copilot-schema-version +++ b/.copilot-schema-version @@ -1 +1 @@ -1.0.49 \ No newline at end of file +1.0.51 diff --git a/.github/skills/update-upstream/SKILL.md b/.github/skills/update-upstream/SKILL.md index c50c9d5..e1eeec5 100644 --- a/.github/skills/update-upstream/SKILL.md +++ b/.github/skills/update-upstream/SKILL.md @@ -14,13 +14,21 @@ Sync the copilot-sdk-clojure project with upstream [github/copilot-sdk](https:// ### Phase 1: Discovery -1. Run `./update.sh` from the repo root to pull the latest upstream and list releases. -2. Check the current Clojure SDK version in `build.clj` (format: `UPSTREAM.CLJ_PATCH` — see AGENTS.md § Version Management). -3. List upstream commits since our last synced version: +1. **Sync local `main` first.** Recently-merged PRs may have already + ported some upstream changes, and your feature branch should sit on + top of the latest `main` to avoid duplicate work and rebase conflicts + later: + ``` + git checkout main && git pull --ff-only origin main + ``` + If `main` cannot fast-forward, stop and let the maintainer resolve. +2. Run `./update.sh` from the repo root to pull the latest upstream and list releases. +3. Check the current Clojure SDK version in `build.clj` (format: `UPSTREAM.CLJ_PATCH` — see AGENTS.md § Version Management). +4. List upstream commits since our last synced version: ``` cd ../copilot-sdk && git log --oneline ..HEAD -- nodejs/ ``` -4. For each commit, classify: +5. For each commit, classify: - **Port** — Code changes to `nodejs/src/` (types, client, session, generated) - **Skip** — CI/tooling, language-specific (Python/Go/.NET only) @@ -103,12 +111,23 @@ At minimum: ### Phase 8: PR Creation -1. Create a feature branch: `git checkout -b upstream-sync/v` -2. Commit changes in logical commits to make them easy to review commit by commit and with descriptive message and `Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>` -3. Push and create PR with `gh pr create` -4. PR body should include: summary, changes list, validation results, review findings table - -### Phase 9: Reflecing on code review feedback. +1. **Confirm `main` is current before branching.** Run + `git fetch origin main && git checkout main && git pull --ff-only` if + you haven't refreshed since Phase 1. A stale local `main` causes + rebase conflicts later, especially when prior sync PRs squash-merge. +2. Create a feature branch: `git checkout -b upstream-sync/v` +3. Commit changes in logical commits to make them easy to review commit by commit and with descriptive message and `Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>` +4. Push and create PR with `gh pr create` +5. PR body should include: summary, changes list, validation results, review findings table + +If the maintainer asks you to rebase a stale branch onto fresh `main`, +expect that previous round-N sync commits on your branch may already be +present in `origin/main` under squash-merge SHAs. Use `git rebase --skip` +for any commit whose patch is already upstream — Git will print +"patch contents already upstream" for the others and drop them +automatically. + +### Phase 9: Reflecting on code review feedback. Once the PR is created, Copilot Code Review (and possibly humans) will provide code review feedback. diff --git a/CHANGELOG.md b/CHANGELOG.md index b6ad854..d51e161 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,53 @@ All notable changes to this project will be documented in this file. This change ## [Unreleased] +### Changed (post-v1.0.0-beta.4 sync, round 3) +- **`ping` `:timestamp` field type changed in CLI 1.0.51** — Upstream PR #1340 + changed the `ping` RPC result `timestamp` field from epoch-millis number to + an ISO 8601 date-time string (e.g. `"2026-05-21T08:00:00.000Z"`). The SDK + forwards the server value verbatim, so callers of `sdk/ping` will see a + string `:timestamp` against CLI ≥ 1.0.51 and a numeric epoch-millis value + against older CLIs. The `::specs/timestamp` spec accepts both shapes + (`(s/or :iso-string string? :epoch-ms nat-int?)`) so spec instrumentation + passes against either CLI version. The mock test server was updated to + emit the ISO string form, and the ping docstring documents both shapes. + (upstream PR #1340) + +### Added (post-v1.0.0-beta.4 sync, round 3) +- **`:mcp-args` is now optional on MCP stdio server configs** — Following + upstream PR #1347 (`MCPStdioServerConfig.args` made optional across all + SDKs), the `::mcp-local-server` / `::mcp-stdio-server` spec moves + `::mcp-args` from `:req-un` to `:opt-un`. Stdio MCP servers declared with + just `{:mcp-command "..." :mcp-tools [...]}` (no `:mcp-args`) now validate + and forward correctly. (upstream PR #1347) +- **`:time-to-first-token-ms` on `assistant.usage` event data** — The CLI + 1.0.51 wire schema renamed the assistant-usage TTFT property from + `ttftMs` to `timeToFirstTokenMs`, which surfaces as the kebab-case key + `:time-to-first-token-ms` after wire normalization. The + `::assistant.usage-data` spec lists both keys in `:opt-un` so events from + older and newer CLIs both validate; the new key is the canonical name + going forward. The generated wire spec + (`generated/event_specs.clj`) only declares the new field, matching the + current schema. (upstream CLI 1.0.51 schema) +- **Schema bump** — `.copilot-schema-version` advanced from `1.0.49` to + `1.0.51`. Generated wire specs and coercions regenerated. Additive + changes only beyond the rename above: bounded-integer fields previously + typed as `number?` now generate as `integer?` (upstream PR #1329, + "Use 32-bit types for bounded schema integers"). + +### Tracked-but-not-ported (post-v1.0.0-beta.4 sync, round 3) +- **PR #1316** (re-export generated session-event types from `index.ts`) — + Node.js packaging concern only; the Clojure SDK already exposes generated + event specs via the `github.copilot-sdk.generated.event-specs` namespace. +- **PR #1327 `ToolBinaryResult.type` tightened to `"image" | "resource"`** — + Our `::binary-results-for-llm` spec is intentionally permissive + (`(coll-of map?)`). Tightening would require adding a dedicated + `::tool-binary-result` spec with string-valued `:type`; deferred since + the runtime helpers already emit valid values. +- Upstream test stabilization (#1346, #1317, #1314), other-language / + documentation / codegen-only PRs (#1336, #1291, #1331, #1338, #1339, + #1304, #1289, #1313) — no Clojure SDK action required. + ### Added (post-v1.0.0-beta.4 sync, round 2) - **SessionFs SQLite support** — `sessionFs.sqliteQuery` and `sessionFs.sqliteExists` RPCs are now dispatched to a user-supplied provider. The provider-style handler diff --git a/README.md b/README.md index 547d2b2..dc7fae1 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ Add to your `deps.edn`: ```clojure ;; From Maven Central -io.github.copilot-community-sdk/copilot-sdk-clojure {:mvn/version "1.0.0-beta.4.0"} +io.github.copilot-community-sdk/copilot-sdk-clojure {:mvn/version "1.0.0-beta.4.1"} ;; Or git dependency io.github.copilot-community-sdk/copilot-sdk-clojure {:git/url "https://github.com/copilot-community-sdk/copilot-sdk-clojure.git" diff --git a/build.clj b/build.clj index cb407b7..4cca854 100644 --- a/build.clj +++ b/build.clj @@ -7,7 +7,7 @@ (:import [java.io File])) (def lib 'io.github.copilot-community-sdk/copilot-sdk-clojure) -(def version "1.0.0-beta.4.0") +(def version "1.0.0-beta.4.1") (def class-dir "target/classes") (defn- try-sh diff --git a/doc/mcp/overview.md b/doc/mcp/overview.md index f1e9f86..8ab5f94 100644 --- a/doc/mcp/overview.md +++ b/doc/mcp/overview.md @@ -107,7 +107,7 @@ Here's a complete working example using the official [`@modelcontextprotocol/ser | Key | Type | Required | Description | |-----|------|----------|-------------| | `:mcp-command` | string | Yes | Command to execute | -| `:mcp-args` | vector | Yes | Command arguments | +| `:mcp-args` | vector | No | Command arguments (optional since CLI 1.0.51; omit for argument-less commands) | | `:mcp-tools` | vector | Yes | Tools to enable (`["*"]` for all, `[]` for none, or specific tool names) | | `:mcp-server-type` | keyword | No | `:local` or `:stdio` (defaults to local) | | `:mcp-timeout` | number | No | Timeout in milliseconds | diff --git a/schemas/README.md b/schemas/README.md index d546d29..9b29f48 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.49` +Currently pinned version: `1.0.51` diff --git a/schemas/api.schema.json b/schemas/api.schema.json index d5cd13e..0667b40 100644 --- a/schemas/api.schema.json +++ b/schemas/api.schema.json @@ -12,7 +12,7 @@ }, "result": { "$ref": "#/definitions/PingResult", - "description": "Server liveness response, including the echoed message, current timestamp, and protocol version." + "description": "Server liveness response, including the echoed message, current server timestamp, and protocol version." } }, "connect": { @@ -217,6 +217,224 @@ "description": "Remote session connection result." }, "stability": "experimental" + }, + "list": { + "rpcMethod": "sessions.list", + "description": "Lists persisted sessions, optionally filtered by working-directory context.", + "params": { + "$ref": "#/definitions/SessionsListRequest", + "description": "Optional metadata-load limit and context filter applied to the returned sessions." + }, + "result": { + "$ref": "#/definitions/SessionList", + "description": "Persisted sessions matching the filter, ordered most-recently-modified first." + }, + "stability": "experimental" + }, + "findByTaskId": { + "rpcMethod": "sessions.findByTaskId", + "description": "Finds the local session bound to a GitHub task ID, if any.", + "params": { + "$ref": "#/definitions/SessionsFindByTaskIDRequest", + "description": "GitHub task ID to look up." + }, + "result": { + "$ref": "#/definitions/SessionsFindByTaskIDResult", + "description": "ID of the local session bound to the given GitHub task, or omitted when none." + }, + "stability": "experimental" + }, + "findByPrefix": { + "rpcMethod": "sessions.findByPrefix", + "description": "Resolves a UUID prefix to a unique session ID, if exactly one session matches.", + "params": { + "$ref": "#/definitions/SessionsFindByPrefixRequest", + "description": "UUID prefix to resolve to a unique session ID." + }, + "result": { + "$ref": "#/definitions/SessionsFindByPrefixResult", + "description": "Session ID matching the prefix, omitted when no unique match exists." + }, + "stability": "experimental" + }, + "getLastForContext": { + "rpcMethod": "sessions.getLastForContext", + "description": "Returns the most-relevant prior session for a given working-directory context.", + "params": { + "$ref": "#/definitions/SessionsGetLastForContextRequest", + "description": "Optional working-directory context used to score session relevance." + }, + "result": { + "$ref": "#/definitions/SessionsGetLastForContextResult", + "description": "Most-relevant session ID for the supplied context, or omitted when no sessions exist." + }, + "stability": "experimental" + }, + "getEventFilePath": { + "rpcMethod": "sessions.getEventFilePath", + "description": "Computes the absolute path to a session's persisted events.jsonl file.", + "params": { + "$ref": "#/definitions/SessionsGetEventFilePathRequest", + "description": "Session ID whose event-log file path to compute." + }, + "result": { + "$ref": "#/definitions/SessionsGetEventFilePathResult", + "description": "Absolute path to the session's events.jsonl file on disk." + }, + "stability": "experimental" + }, + "getSizes": { + "rpcMethod": "sessions.getSizes", + "description": "Returns the on-disk byte size of each session's workspace directory.", + "params": null, + "result": { + "$ref": "#/definitions/SessionSizes", + "description": "Map of sessionId -> on-disk size in bytes for each session's workspace directory." + }, + "stability": "experimental" + }, + "checkInUse": { + "rpcMethod": "sessions.checkInUse", + "description": "Returns the subset of the supplied session IDs that are currently held by another running process.", + "params": { + "$ref": "#/definitions/SessionsCheckInUseRequest", + "description": "Session IDs to test for live in-use locks." + }, + "result": { + "$ref": "#/definitions/SessionsCheckInUseResult", + "description": "Session IDs from the input set that are currently in use by another process." + }, + "stability": "experimental" + }, + "getPersistedRemoteSteerable": { + "rpcMethod": "sessions.getPersistedRemoteSteerable", + "description": "Returns a session's persisted remote-steerable flag, if any has been recorded.", + "params": { + "$ref": "#/definitions/SessionsGetPersistedRemoteSteerableRequest", + "description": "Session ID to look up the persisted remote-steerable flag for." + }, + "result": { + "$ref": "#/definitions/SessionsGetPersistedRemoteSteerableResult", + "description": "The session's persisted remote-steerable flag, or omitted when no value has been persisted." + }, + "stability": "experimental" + }, + "close": { + "rpcMethod": "sessions.close", + "description": "Closes a session: emits shutdown, flushes pending events, releases the in-use lock, and disposes the active session.", + "params": { + "$ref": "#/definitions/SessionsCloseRequest", + "description": "Session ID to close." + }, + "result": { + "$ref": "#/definitions/SessionsCloseResult", + "description": "Closes a session: emits shutdown, flushes pending events to disk, releases the in-use lock, disposes the active session. Idempotent: succeeds even if the session is not currently active." + }, + "stability": "experimental" + }, + "bulkDelete": { + "rpcMethod": "sessions.bulkDelete", + "description": "Closes, deactivates, and deletes a set of sessions, returning the bytes freed per session.", + "params": { + "$ref": "#/definitions/SessionsBulkDeleteRequest", + "description": "Session IDs to close, deactivate, and delete from disk." + }, + "result": { + "$ref": "#/definitions/SessionBulkDeleteResult", + "description": "Map of sessionId -> bytes freed by removing the session's workspace directory." + }, + "stability": "experimental" + }, + "pruneOld": { + "rpcMethod": "sessions.pruneOld", + "description": "Deletes sessions older than the given threshold, with optional dry-run and exclusion list.", + "params": { + "$ref": "#/definitions/SessionsPruneOldRequest", + "description": "Age threshold and optional flags controlling which old sessions are pruned (or simulated when dryRun is true)." + }, + "result": { + "$ref": "#/definitions/SessionPruneResult", + "description": "Outcome of the prune operation: deleted IDs, dry-run candidates, skipped IDs, total bytes freed, and the dry-run flag." + }, + "stability": "experimental" + }, + "save": { + "rpcMethod": "sessions.save", + "description": "Flushes a session's pending events to disk.", + "params": { + "$ref": "#/definitions/SessionsSaveRequest", + "description": "Session ID whose pending events should be flushed to disk." + }, + "result": { + "$ref": "#/definitions/SessionsSaveResult", + "description": "Flush a session's pending events to disk. No-op when no writer exists for the session (e.g., already closed)." + }, + "stability": "experimental" + }, + "releaseLock": { + "rpcMethod": "sessions.releaseLock", + "description": "Releases the in-use lock held by this process for a session.", + "params": { + "$ref": "#/definitions/SessionsReleaseLockRequest", + "description": "Session ID whose in-use lock should be released." + }, + "result": { + "$ref": "#/definitions/SessionsReleaseLockResult", + "description": "Release the in-use lock held by this process for the given session. No-op when this process does not currently hold a lock for the session." + }, + "stability": "experimental" + }, + "enrichMetadata": { + "rpcMethod": "sessions.enrichMetadata", + "description": "Backfills missing summary and context fields on the supplied session metadata records.", + "params": { + "$ref": "#/definitions/SessionsEnrichMetadataRequest", + "description": "Session metadata records to enrich with summary and context information." + }, + "result": { + "$ref": "#/definitions/SessionEnrichMetadataResult", + "description": "The same metadata records, with summary and context fields backfilled where available." + }, + "stability": "experimental" + }, + "reloadPluginHooks": { + "rpcMethod": "sessions.reloadPluginHooks", + "description": "Reloads user, plugin, and (optionally) repo hooks on the active session.", + "params": { + "$ref": "#/definitions/SessionsReloadPluginHooksRequest", + "description": "Active session ID and an optional flag for deferring repo-level hooks until folder trust." + }, + "result": { + "$ref": "#/definitions/SessionsReloadPluginHooksResult", + "description": "Reload all hooks (user, plugin, optionally repo) and apply them to the active session. Call after installing or removing plugins so their hooks take effect immediately. No-op when no active session matches the given sessionId." + }, + "stability": "experimental" + }, + "loadDeferredRepoHooks": { + "rpcMethod": "sessions.loadDeferredRepoHooks", + "description": "Loads previously-deferred repo-level hooks on the active session, returning queued startup prompts.", + "params": { + "$ref": "#/definitions/SessionsLoadDeferredRepoHooksRequest", + "description": "Active session ID whose deferred repo-level hooks should be loaded." + }, + "result": { + "$ref": "#/definitions/SessionLoadDeferredRepoHooksResult", + "description": "Queued repo-level startup prompts and the total hook command count after loading." + }, + "stability": "experimental" + }, + "setAdditionalPlugins": { + "rpcMethod": "sessions.setAdditionalPlugins", + "description": "Replaces the manager-wide additional plugins registered with the session manager.", + "params": { + "$ref": "#/definitions/SessionsSetAdditionalPluginsRequest", + "description": "Manager-wide additional plugins to register; replaces any previously-configured set." + }, + "result": { + "$ref": "#/definitions/SessionsSetAdditionalPluginsResult", + "description": "Replace the manager-wide additional plugins. New session creations and subsequent hook reloads see the new set; already-running sessions keep their existing hook installation until the next reload." + }, + "stability": "experimental" } } }, @@ -240,7 +458,150 @@ }, "result": { "type": "null" - } + }, + "stability": "experimental" + }, + "send": { + "rpcMethod": "session.send", + "description": "Sends a user message to the session and returns its message ID.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "prompt": { + "type": "string", + "description": "The user message text" + }, + "displayPrompt": { + "type": "string", + "description": "If provided, this is shown in the timeline instead of `prompt`" + }, + "attachments": { + "type": "array", + "items": { + "$ref": "#/definitions/SendAttachment", + "description": "A user message attachment — a file, directory, code selection, blob, or GitHub reference" + }, + "description": "Optional attachments (files, directories, selections, blobs, GitHub references) to include with the message" + }, + "mode": { + "$ref": "#/definitions/SendMode", + "description": "How to deliver the message. `enqueue` (default) appends to the message queue. `immediate` interjects during an in-progress turn." + }, + "prepend": { + "type": "boolean", + "description": "If true, adds the message to the front of the queue instead of the end" + }, + "billable": { + "type": "boolean", + "description": "If false, this message will not trigger a Premium Request Unit charge. User messages default to billable." + }, + "requiredTool": { + "type": "string", + "description": "If set, the request will fail if the named tool is not available when this message is among the user messages at the start of the current exchange" + }, + "source": { + "description": "Optional provenance tag copied to the resulting user.message event. Supported values are `system`, `command-*`, and `schedule-*`." + }, + "agentMode": { + "$ref": "#/definitions/SendAgentMode", + "description": "The UI mode the agent was in when this message was sent. Defaults to the session's current mode." + }, + "requestHeaders": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Custom HTTP headers to include in outbound model requests for this turn. Merged with session-level provider headers; per-turn headers augment and overwrite session-level headers with the same key." + }, + "traceparent": { + "type": "string", + "description": "W3C Trace Context traceparent header for distributed tracing of this agent turn" + }, + "tracestate": { + "type": "string", + "description": "W3C Trace Context tracestate header for distributed tracing" + }, + "wait": { + "type": "boolean", + "description": "If true, await completion of the agentic loop for this message before returning. Defaults to false (fire-and-forget). When true, the result still contains the same `messageId`; the caller can rely on the agent having processed the message before the call resolves." + } + }, + "required": [ + "sessionId", + "prompt" + ], + "additionalProperties": false, + "description": "Parameters for sending a user message to the session", + "title": "SendRequest" + }, + "result": { + "$ref": "#/definitions/SendResult", + "description": "Result of sending a user message" + }, + "stability": "experimental" + }, + "abort": { + "rpcMethod": "session.abort", + "description": "Aborts the current agent turn.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "reason": { + "$ref": "#/definitions/AbortReason", + "description": "Finite reason code describing why the current turn was aborted" + } + }, + "additionalProperties": false, + "description": "Parameters for aborting the current turn", + "title": "AbortRequest", + "required": [ + "sessionId" + ] + }, + "result": { + "$ref": "#/definitions/AbortResult", + "description": "Result of aborting the current turn" + }, + "stability": "experimental" + }, + "shutdown": { + "rpcMethod": "session.shutdown", + "description": "Shuts down the session and persists its final state. Awaits any deferred sessionEnd hooks before resolving so user-supplied hook scripts complete before the runtime tears down.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "type": { + "$ref": "#/definitions/ShutdownType", + "description": "Why the session is being shut down. Defaults to \"routine\" when omitted." + }, + "reason": { + "type": "string", + "description": "Optional human-readable reason. Typically the message of the error that triggered shutdown when type is 'error'." + } + }, + "additionalProperties": false, + "description": "Parameters for shutting down the session", + "title": "ShutdownRequest", + "required": [ + "sessionId" + ] + }, + "result": { + "type": "null" + }, + "stability": "experimental" }, "auth": { "getStatus": { @@ -263,7 +624,36 @@ "result": { "$ref": "#/definitions/SessionAuthStatus", "description": "Authentication status and account metadata for the session." - } + }, + "stability": "experimental" + }, + "setCredentials": { + "rpcMethod": "session.auth.setCredentials", + "description": "Updates the session's auth credentials used for outbound model and API requests.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "credentials": { + "$ref": "#/definitions/AuthInfo", + "description": "The new auth credentials to install on the session. When omitted or `undefined`, the call is a no-op and the session's existing credentials are preserved. The runtime stores the value verbatim and uses it for outbound model/API requests; it does NOT re-validate or re-fetch the associated Copilot user response. Several variants carry secret material; treat this method's params as containing secrets at rest and in transit." + } + }, + "additionalProperties": false, + "description": "New auth credentials to install on the session. Omit to leave credentials unchanged.", + "title": "SessionSetCredentialsParams", + "required": [ + "sessionId" + ] + }, + "result": { + "$ref": "#/definitions/SessionSetCredentialsResult", + "description": "Indicates whether the credential update succeeded." + }, + "stability": "experimental" } }, "model": { @@ -286,8 +676,9 @@ }, "result": { "$ref": "#/definitions/CurrentModel", - "description": "The currently selected model for the session." - } + "description": "The currently selected model and reasoning effort for the session." + }, + "stability": "experimental" }, "switchTo": { "rpcMethod": "session.model.switchTo", @@ -327,7 +718,37 @@ "result": { "$ref": "#/definitions/ModelSwitchToResult", "description": "The model identifier active on the session after the switch." - } + }, + "stability": "experimental" + }, + "setReasoningEffort": { + "rpcMethod": "session.model.setReasoningEffort", + "description": "Updates the session's reasoning effort without changing the selected model.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "reasoningEffort": { + "type": "string", + "description": "Reasoning effort level to apply to the currently selected model. The host is responsible for validating the value against the model's supported levels before calling." + } + }, + "required": [ + "sessionId", + "reasoningEffort" + ], + "additionalProperties": false, + "description": "Reasoning effort level to apply to the currently selected model.", + "title": "ModelSetReasoningEffortRequest" + }, + "result": { + "$ref": "#/definitions/ModelSetReasoningEffortResult", + "description": "Update the session's reasoning effort without changing the selected model. Use `switchTo` instead when you also need to change the model. The runtime stores the effort on the session and applies it to subsequent turns." + }, + "stability": "experimental" } }, "mode": { @@ -351,7 +772,8 @@ "result": { "$ref": "#/definitions/SessionMode", "description": "The session mode the agent is operating in" - } + }, + "stability": "experimental" }, "set": { "rpcMethod": "session.mode.set", @@ -378,7 +800,8 @@ }, "result": { "type": "null" - } + }, + "stability": "experimental" } }, "name": { @@ -402,7 +825,8 @@ "result": { "$ref": "#/definitions/NameGetResult", "description": "The session's friendly name, or null when not yet set." - } + }, + "stability": "experimental" }, "set": { "rpcMethod": "session.name.set", @@ -431,7 +855,37 @@ }, "result": { "type": "null" - } + }, + "stability": "experimental" + }, + "setAuto": { + "rpcMethod": "session.name.setAuto", + "description": "Persists an auto-generated session summary as the session's name when no user-set name exists.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "summary": { + "type": "string", + "description": "Auto-generated session summary. Empty/whitespace-only values are ignored; values are trimmed before persisting." + } + }, + "required": [ + "sessionId", + "summary" + ], + "additionalProperties": false, + "description": "Auto-generated session summary to apply as the session's name when no user-set name exists.", + "title": "NameSetAutoRequest" + }, + "result": { + "$ref": "#/definitions/NameSetAutoResult", + "description": "Indicates whether the auto-generated summary was applied as the session's name." + }, + "stability": "experimental" } }, "plan": { @@ -455,7 +909,8 @@ "result": { "$ref": "#/definitions/PlanReadResult", "description": "Existence, contents, and resolved path of the session plan file." - } + }, + "stability": "experimental" }, "update": { "rpcMethod": "session.plan.update", @@ -482,7 +937,8 @@ }, "result": { "type": "null" - } + }, + "stability": "experimental" }, "delete": { "rpcMethod": "session.plan.delete", @@ -503,7 +959,8 @@ }, "result": { "type": "null" - } + }, + "stability": "experimental" } }, "workspaces": { @@ -526,8 +983,9 @@ }, "result": { "$ref": "#/definitions/WorkspacesGetWorkspaceResult", - "description": "Current workspace metadata for the session, or null when not available." - } + "description": "Current workspace metadata for the session, including its absolute filesystem path when available." + }, + "stability": "experimental" }, "listFiles": { "rpcMethod": "session.workspaces.listFiles", @@ -549,7 +1007,8 @@ "result": { "$ref": "#/definitions/WorkspacesListFilesResult", "description": "Relative paths of files stored in the session workspace files directory." - } + }, + "stability": "experimental" }, "readFile": { "rpcMethod": "session.workspaces.readFile", @@ -577,7 +1036,8 @@ "result": { "$ref": "#/definitions/WorkspacesReadFileResult", "description": "Contents of the requested workspace file as a UTF-8 string." - } + }, + "stability": "experimental" }, "createFile": { "rpcMethod": "session.workspaces.createFile", @@ -609,7 +1069,90 @@ }, "result": { "type": "null" - } + }, + "stability": "experimental" + }, + "listCheckpoints": { + "rpcMethod": "session.workspaces.listCheckpoints", + "description": "Lists workspace checkpoints in chronological order.", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/WorkspacesListCheckpointsResult", + "description": "Workspace checkpoints in chronological order; empty when the workspace is not enabled." + }, + "stability": "experimental" + }, + "readCheckpoint": { + "rpcMethod": "session.workspaces.readCheckpoint", + "description": "Reads the content of a workspace checkpoint by number.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "number": { + "type": "integer", + "minimum": 0, + "description": "Checkpoint number to read" + } + }, + "required": [ + "sessionId", + "number" + ], + "additionalProperties": false, + "description": "Checkpoint number to read.", + "title": "WorkspacesReadCheckpointRequest" + }, + "result": { + "$ref": "#/definitions/WorkspacesReadCheckpointResult", + "description": "Checkpoint content as a UTF-8 string, or null when the checkpoint or workspace is missing." + }, + "stability": "experimental" + }, + "saveLargePaste": { + "rpcMethod": "session.workspaces.saveLargePaste", + "description": "Saves pasted content as a UTF-8 file in the session workspace.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "content": { + "type": "string", + "description": "Pasted content to save as a UTF-8 file" + } + }, + "required": [ + "sessionId", + "content" + ], + "additionalProperties": false, + "description": "Pasted content to save as a UTF-8 file in the session workspace.", + "title": "WorkspacesSaveLargePasteRequest" + }, + "result": { + "$ref": "#/definitions/WorkspacesSaveLargePasteResult", + "description": "Descriptor for the saved paste file, or null when the workspace is unavailable." + }, + "stability": "experimental" } }, "instructions": { @@ -633,7 +1176,8 @@ "result": { "$ref": "#/definitions/InstructionsGetSourcesResult", "description": "Instruction sources loaded for the session, in merge order." - } + }, + "stability": "experimental" } }, "fleet": { @@ -859,6 +1403,104 @@ }, "stability": "experimental" }, + "refresh": { + "rpcMethod": "session.tasks.refresh", + "description": "Refreshes metadata for any detached background shells the runtime knows about.", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/TasksRefreshResult", + "description": "Refresh metadata for any detached background shells the runtime knows about. Use after a long pause to pick up exit/output state for shells running outside the agent loop." + }, + "stability": "experimental" + }, + "waitForPending": { + "rpcMethod": "session.tasks.waitForPending", + "description": "Waits for all in-flight background tasks and any follow-up turns to settle.", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/TasksWaitForPendingResult", + "description": "Wait until all in-flight background tasks (agents + shells) and any follow-up turns scheduled by their completions have settled. Returns when the runtime is fully drained or after an internal timeout (default 10 minutes; configurable via COPILOT_TASK_WAIT_TIMEOUT_SECONDS)." + }, + "stability": "experimental" + }, + "getProgress": { + "rpcMethod": "session.tasks.getProgress", + "description": "Returns progress information for a background task by ID.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "id": { + "type": "string", + "description": "Task identifier (agent ID or shell ID)" + } + }, + "required": [ + "sessionId", + "id" + ], + "additionalProperties": false, + "description": "Identifier of the background task to fetch progress for.", + "title": "TasksGetProgressRequest" + }, + "result": { + "$ref": "#/definitions/TasksGetProgressResult", + "description": "Progress information for the task, or null when no task with that ID is tracked." + }, + "stability": "experimental" + }, + "getCurrentPromotable": { + "rpcMethod": "session.tasks.getCurrentPromotable", + "description": "Returns the first sync-waiting task that can currently be promoted to background mode.", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/TasksGetCurrentPromotableResult", + "description": "The first sync-waiting task that can currently be promoted to background mode." + }, + "stability": "experimental" + }, "promoteToBackground": { "rpcMethod": "session.tasks.promoteToBackground", "description": "Promotes an eligible synchronously-waited task so it continues running in the background.", @@ -888,6 +1530,29 @@ }, "stability": "experimental" }, + "promoteCurrentToBackground": { + "rpcMethod": "session.tasks.promoteCurrentToBackground", + "description": "Atomically promotes the first promotable sync-waiting task to background mode and returns it.", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/TasksPromoteCurrentToBackgroundResult", + "description": "The promoted task as it now exists in background mode, omitted if no promotable task was waiting." + }, + "stability": "experimental" + }, "cancel": { "rpcMethod": "session.tasks.cancel", "description": "Cancels a background task.", @@ -1009,6 +1674,29 @@ }, "stability": "experimental" }, + "getInvoked": { + "rpcMethod": "session.skills.getInvoked", + "description": "Returns the skills that have been invoked during this session.", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/SkillsGetInvokedResult", + "description": "Skills invoked during this session, ordered by invocation time (most recent last)." + }, + "stability": "experimental" + }, "enable": { "rpcMethod": "session.skills.enable", "description": "Enables a skill for the session.", @@ -1087,6 +1775,28 @@ "description": "Diagnostics from reloading skill definitions, with warnings and errors as separate lists." }, "stability": "experimental" + }, + "ensureLoaded": { + "rpcMethod": "session.skills.ensureLoaded", + "description": "Ensures the session's skill definitions have been loaded from disk.", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "type": "null" + }, + "stability": "experimental" } }, "mcp": { @@ -1195,44 +1905,172 @@ }, "stability": "experimental" }, - "oauth": { - "login": { - "rpcMethod": "session.mcp.oauth.login", - "description": "Starts OAuth authentication for a remote MCP server.", - "params": { - "type": "object", - "properties": { - "sessionId": { - "type": "string", - "description": "Target session identifier" - }, - "serverName": { - "type": "string", - "minLength": 1, - "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", - "description": "Name of the remote MCP server to authenticate" - }, - "forceReauth": { - "type": "boolean", - "description": "When true, clears any cached OAuth token for the server and runs a full new authorization. Use when the user explicitly wants to switch accounts or believes their session is stuck." - }, - "clientName": { - "type": "string", - "description": "Optional override for the OAuth client display name shown on the consent screen. Applies to newly registered dynamic clients only — existing registrations keep the name they were created with. When omitted, the runtime applies a neutral fallback; callers driving interactive auth should pass their own surface-specific label so the consent screen matches the product the user sees." - }, - "callbackSuccessMessage": { - "type": "string", - "description": "Optional override for the body text shown on the OAuth loopback callback success page. When omitted, the runtime applies a neutral fallback; callers driving interactive auth should pass surface-specific copy telling the user where to return." - } + "executeSampling": { + "rpcMethod": "session.mcp.executeSampling", + "description": "Runs an MCP sampling inference on behalf of an MCP server.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" }, - "required": [ - "sessionId", - "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" - }, + "requestId": { + "type": "string", + "description": "Caller-provided unique identifier for this sampling execution. Use this same ID with cancelSamplingExecution to cancel the in-flight call. Must be unique within the session for the lifetime of the call." + }, + "serverName": { + "type": "string", + "description": "Name of the MCP server that initiated the sampling request" + }, + "mcpRequestId": { + "type": [ + "string", + "number" + ], + "description": "The original MCP JSON-RPC request ID (string or number). Used by the runtime to correlate the inference with the originating MCP request for telemetry; this is distinct from `requestId` (which is the schema-level cancellation handle)." + }, + "request": { + "$ref": "#/definitions/McpExecuteSamplingRequest", + "description": "Raw MCP CreateMessageRequest params, as received in the `sampling.requested` event. Treated as opaque at the schema layer; the runtime converts the embedded MCP messages into the OpenAI chat-completion shape internally." + } + }, + "required": [ + "sessionId", + "requestId", + "serverName", + "mcpRequestId", + "request" + ], + "additionalProperties": false, + "description": "Identifiers and raw MCP CreateMessageRequest params used to run a sampling inference.", + "title": "McpExecuteSamplingParams" + }, + "result": { + "$ref": "#/definitions/McpSamplingExecutionResult", + "description": "Outcome of an MCP sampling execution: success result, failure error, or cancellation." + }, + "stability": "experimental" + }, + "cancelSamplingExecution": { + "rpcMethod": "session.mcp.cancelSamplingExecution", + "description": "Cancels an in-flight MCP sampling execution by request ID.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "requestId": { + "type": "string", + "description": "The requestId previously passed to executeSampling that should be cancelled" + } + }, + "required": [ + "sessionId", + "requestId" + ], + "additionalProperties": false, + "description": "The requestId previously passed to executeSampling that should be cancelled.", + "title": "McpCancelSamplingExecutionParams" + }, + "result": { + "$ref": "#/definitions/McpCancelSamplingExecutionResult", + "description": "Indicates whether an in-flight sampling execution with the given requestId was found and cancelled." + }, + "stability": "experimental" + }, + "setEnvValueMode": { + "rpcMethod": "session.mcp.setEnvValueMode", + "description": "Sets how environment-variable values supplied to MCP servers are resolved (direct or indirect).", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "mode": { + "$ref": "#/definitions/McpSetEnvValueModeDetails", + "description": "How environment-variable values supplied to MCP servers are resolved. \"direct\" passes literal string values; \"indirect\" treats values as references (e.g. names of environment variables on the host) that the runtime resolves before launch. Defaults to the runtime's startup mode; clients that intentionally launch MCP servers with literal values (e.g. CLI prompt mode and ACP) set this to \"direct\"." + } + }, + "required": [ + "sessionId", + "mode" + ], + "additionalProperties": false, + "description": "Mode controlling how MCP server env values are resolved (`direct` or `indirect`).", + "title": "McpSetEnvValueModeParams" + }, + "result": { + "$ref": "#/definitions/McpSetEnvValueModeResult", + "description": "Env-value mode recorded on the session after the update." + }, + "stability": "experimental" + }, + "removeGitHub": { + "rpcMethod": "session.mcp.removeGitHub", + "description": "Removes the auto-managed `github` MCP server when present.", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/McpRemoveGitHubResult", + "description": "Indicates whether the auto-managed `github` MCP server was removed (false when nothing to remove)." + }, + "stability": "experimental" + }, + "oauth": { + "login": { + "rpcMethod": "session.mcp.oauth.login", + "description": "Starts OAuth authentication for a remote MCP server.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "serverName": { + "type": "string", + "minLength": 1, + "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", + "description": "Name of the remote MCP server to authenticate" + }, + "forceReauth": { + "type": "boolean", + "description": "When true, clears any cached OAuth token for the server and runs a full new authorization. Use when the user explicitly wants to switch accounts or believes their session is stuck." + }, + "clientName": { + "type": "string", + "description": "Optional override for the OAuth client display name shown on the consent screen. Applies to newly registered dynamic clients only — existing registrations keep the name they were created with. When omitted, the runtime applies a neutral fallback; callers driving interactive auth should pass their own surface-specific label so the consent screen matches the product the user sees." + }, + "callbackSuccessMessage": { + "type": "string", + "description": "Optional override for the body text shown on the OAuth loopback callback success page. When omitted, the runtime applies a neutral fallback; callers driving interactive auth should pass surface-specific copy telling the user where to return." + } + }, + "required": [ + "sessionId", + "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", "description": "OAuth authorization URL the caller should open, or empty when cached tokens already authenticated the server." @@ -1266,6 +2104,236 @@ "stability": "experimental" } }, + "options": { + "update": { + "rpcMethod": "session.options.update", + "description": "Patches the genuinely-mutable subset of session options.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "model": { + "type": "string", + "description": "The model ID to use for assistant turns." + }, + "reasoningEffort": { + "type": "string", + "description": "Reasoning effort for the selected model (model-defined enum)." + }, + "clientName": { + "type": "string", + "description": "Identifier of the client driving the session." + }, + "lspClientName": { + "type": "string", + "description": "Identifier sent to LSP-style integrations." + }, + "integrationId": { + "type": "string", + "description": "Stable integration identifier used for analytics and rate-limit attribution." + }, + "featureFlags": { + "type": "object", + "additionalProperties": { + "type": "boolean" + }, + "description": "Map of feature-flag IDs to their boolean enabled state." + }, + "isExperimentalMode": { + "type": "boolean", + "description": "Whether experimental capabilities are enabled." + }, + "provider": { + "description": "Custom model-provider configuration (BYOK). Opaque shape; see `ProviderConfig` in the runtime." + }, + "workingDirectory": { + "type": "string", + "description": "Absolute working-directory path for shell tools." + }, + "availableTools": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Allowlist of tool names available to this session." + }, + "excludedTools": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Denylist of tool names for this session." + }, + "enableScriptSafety": { + "type": "boolean", + "description": "Whether shell-script safety heuristics are enabled." + }, + "shellInitProfile": { + "type": "string", + "description": "Shell init profile (`None` or `NonInteractive`)." + }, + "shellProcessFlags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Per-shell process flags (e.g., `pwsh` arguments)." + }, + "sandboxConfig": { + "description": "Sandbox configuration shape; opaque to SDK consumers. See `SandboxConfig` in the runtime." + }, + "logInteractiveShells": { + "type": "boolean", + "description": "Whether interactive shell sessions are logged." + }, + "envValueMode": { + "$ref": "#/definitions/OptionsUpdateEnvValueMode", + "description": "How env values are passed to MCP servers (`direct` inlines literal values; `indirect` resolves at launch)." + }, + "skillDirectories": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Additional directories to search for skills." + }, + "disabledSkills": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Skill IDs that should be excluded from this session." + }, + "enableOnDemandInstructionDiscovery": { + "type": "boolean", + "description": "Whether to discover custom instructions on demand after successful file views (AGENTS.md / CLAUDE.md / .github/copilot-instructions.md surfacing). Combined with `skipCustomInstructions` and the runtime-side `ON_DEMAND_INSTRUCTIONS` feature flag." + }, + "installedPlugins": { + "type": "array", + "items": { + "$ref": "#/definitions/SessionInstalledPlugin" + }, + "description": "Full set of installed plugins for the session. Replaces the existing list; the runtime invalidates the skills cache only when the list materially changes." + }, + "customAgentsLocalOnly": { + "type": "boolean", + "description": "Whether to default custom agents to local-only execution." + }, + "skipCustomInstructions": { + "type": "boolean", + "description": "Whether to skip loading custom instruction sources." + }, + "disabledInstructionSources": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Instruction source IDs to exclude from the system prompt." + }, + "coauthorEnabled": { + "type": "boolean", + "description": "Whether to include the `Co-authored-by` trailer in commit messages." + }, + "trajectoryFile": { + "type": "string", + "description": "Optional path for trajectory output." + }, + "enableStreaming": { + "type": "boolean", + "description": "Whether to stream model responses." + }, + "copilotUrl": { + "type": "string", + "description": "Override URL for the Copilot API endpoint." + }, + "askUserDisabled": { + "type": "boolean", + "description": "Whether to disable the `ask_user` tool (encourages autonomous behavior)." + }, + "continueOnAutoMode": { + "type": "boolean", + "description": "Whether to allow auto-mode continuation across turns." + }, + "runningInInteractiveMode": { + "type": "boolean", + "description": "Whether the session is running in an interactive UI." + }, + "enableReasoningSummaries": { + "type": "boolean", + "description": "Whether to surface reasoning-summary events from the model." + }, + "agentContext": { + "type": "string", + "description": "Runtime context discriminator (e.g., `cli`, `actions`)." + }, + "eventsLogDirectory": { + "type": "string", + "description": "Override directory for the session-events log. When unset, the runtime's default events log directory is used." + }, + "additionalContentExclusionPolicies": { + "type": "array", + "items": {}, + "description": "Additional content-exclusion policies to merge into the session's policy set. Opaque shape; see `ContentExclusionApiResponse` in the runtime." + }, + "manageScheduleEnabled": { + "type": "boolean", + "description": "Whether to expose the `manage_schedule` tool to the agent. The runtime always owns the per-session schedule registry; this flag only controls tool exposure (typically gated to staff users)." + } + }, + "additionalProperties": false, + "description": "Patch of mutable session options to apply to the running session.", + "title": "SessionUpdateOptionsParams", + "required": [ + "sessionId" + ] + }, + "result": { + "$ref": "#/definitions/SessionUpdateOptionsResult", + "description": "Indicates whether the session options patch was applied successfully." + }, + "stability": "experimental" + } + }, + "lsp": { + "initialize": { + "rpcMethod": "session.lsp.initialize", + "description": "Loads the merged LSP configuration set for the session's working directory.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "workingDirectory": { + "type": "string", + "description": "Working directory used to load project-level LSP configs. Defaults to the session working directory when omitted." + }, + "gitRoot": { + "type": "string", + "description": "Git root used as the boundary when traversing for project-level LSP configs (supports monorepos)." + }, + "force": { + "type": "boolean", + "description": "Force re-initialization even when LSP configs were already loaded for the working directory." + } + }, + "additionalProperties": false, + "description": "Parameters for (re)loading the merged LSP configuration set.", + "title": "LspInitializeRequest", + "required": [ + "sessionId" + ] + }, + "result": { + "type": "null" + }, + "stability": "experimental" + } + }, "extensions": { "list": { "rpcMethod": "session.extensions.list", @@ -1404,7 +2472,31 @@ "result": { "$ref": "#/definitions/HandlePendingToolCallResult", "description": "Indicates whether the external tool call result was handled successfully." - } + }, + "stability": "experimental" + }, + "initializeAndValidate": { + "rpcMethod": "session.tools.initializeAndValidate", + "description": "Resolves, builds, and validates the runtime tool list for the session.", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/ToolsInitializeAndValidateResult", + "description": "Resolve, build, and validate the runtime tool list for this session. Subagent sessions and consumer flows that need an initialized tool set before `send` invoke this. Default base-class implementation is a no-op for sessions that don't support tool validation." + }, + "stability": "experimental" } }, "commands": { @@ -1450,7 +2542,8 @@ "result": { "$ref": "#/definitions/CommandList", "description": "Slash commands available in the session, after applying any include/exclude filters." - } + }, + "stability": "experimental" }, "invoke": { "rpcMethod": "session.commands.invoke", @@ -1482,7 +2575,8 @@ "result": { "$ref": "#/definitions/SlashCommandInvocationResult", "description": "Result of invoking the slash command (text output, prompt to send to the agent, or completion)." - } + }, + "stability": "experimental" }, "handlePendingCommand": { "rpcMethod": "session.commands.handlePendingCommand", @@ -1514,11 +2608,75 @@ "result": { "$ref": "#/definitions/CommandsHandlePendingCommandResult", "description": "Indicates whether the pending client-handled command was completed successfully." - } + }, + "stability": "experimental" + }, + "execute": { + "rpcMethod": "session.commands.execute", + "description": "Executes a slash command synchronously and returns any error.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "commandName": { + "type": "string", + "description": "Name of the slash command to invoke (without the leading '/')." + }, + "args": { + "type": "string", + "description": "Argument string to pass to the command (empty string if none)." + } + }, + "required": [ + "sessionId", + "commandName", + "args" + ], + "additionalProperties": false, + "description": "Slash command name and argument string to execute synchronously.", + "title": "ExecuteCommandParams" + }, + "result": { + "$ref": "#/definitions/ExecuteCommandResult", + "description": "Error message produced while executing the command, if any." + }, + "stability": "experimental" + }, + "enqueue": { + "rpcMethod": "session.commands.enqueue", + "description": "Enqueues a slash command for FIFO processing on the local session.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "command": { + "type": "string", + "description": "Slash-prefixed command string to enqueue, e.g. '/compact' or '/model gpt-4'. Queued FIFO with any in-flight items; if the session is idle, processing kicks off immediately." + } + }, + "required": [ + "sessionId", + "command" + ], + "additionalProperties": false, + "description": "Slash-prefixed command string to enqueue for FIFO processing.", + "title": "EnqueueCommandParams" + }, + "result": { + "$ref": "#/definitions/EnqueueCommandResult", + "description": "Indicates whether the command was accepted into the local execution queue." + }, + "stability": "experimental" }, "respondToQueuedCommand": { "rpcMethod": "session.commands.respondToQueuedCommand", - "description": "Responds to a queued command request from the session.", + "description": "Reports whether the host actually executed a queued command and whether to continue processing.", "params": { "type": "object", "properties": { @@ -1528,11 +2686,11 @@ }, "requestId": { "type": "string", - "description": "Request ID from the queued command event" + "description": "Request ID from the `command.queued` event the host is responding to." }, "result": { "$ref": "#/definitions/QueuedCommandResult", - "description": "Result of the queued command execution" + "description": "Result of the queued command execution." } }, "required": [ @@ -1541,13 +2699,47 @@ "result" ], "additionalProperties": false, - "description": "Queued command request ID and the result indicating whether the client handled it.", + "description": "Queued-command request ID and the result indicating whether the host executed it (and whether to stop processing further queued commands).", "title": "CommandsRespondToQueuedCommandRequest" }, "result": { "$ref": "#/definitions/CommandsRespondToQueuedCommandResult", - "description": "Indicates whether the queued-command response was accepted by the session." - } + "description": "Indicates whether the queued-command response was matched to a pending request." + }, + "stability": "experimental" + } + }, + "telemetry": { + "setFeatureOverrides": { + "rpcMethod": "session.telemetry.setFeatureOverrides", + "description": "Sets feature override key/value pairs to attach to subsequent telemetry events for the session.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "features": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Override key/value pairs to attach to subsequent telemetry events from this session. Replaces any previously-set overrides." + } + }, + "required": [ + "sessionId", + "features" + ], + "additionalProperties": false, + "description": "Feature override key/value pairs to attach to subsequent telemetry events from this session.", + "title": "TelemetrySetFeatureOverridesRequest" + }, + "result": { + "type": "null" + }, + "stability": "experimental" } }, "ui": { @@ -1582,7 +2774,8 @@ "result": { "$ref": "#/definitions/UIElicitationResponse", "description": "The elicitation response (accept with form values, decline, or cancel)" - } + }, + "stability": "experimental" }, "handlePendingElicitation": { "rpcMethod": "session.ui.handlePendingElicitation", @@ -1615,13 +2808,12 @@ "result": { "$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.", + }, + "stability": "experimental" + }, + "handlePendingUserInput": { + "rpcMethod": "session.ui.handlePendingUserInput", + "description": "Resolves a pending `user_input.requested` event with the user's response.", "params": { "type": "object", "properties": { @@ -1631,30 +2823,31 @@ }, "requestId": { "type": "string", - "description": "Request ID of the pending permission request" + "description": "The unique request ID from the user_input.requested event" }, - "result": { - "$ref": "#/definitions/PermissionDecision", - "description": "Decision to apply to a pending permission request." + "response": { + "$ref": "#/definitions/UIUserInputResponse", + "description": "Schema for the `UIUserInputResponse` type." } }, "required": [ "sessionId", "requestId", - "result" + "response" ], "additionalProperties": false, - "description": "Pending permission request ID and the decision to apply (approve/reject and scope).", - "title": "PermissionDecisionRequest" + "description": "Request ID of a pending `user_input.requested` event and the user's response.", + "title": "UIHandlePendingUserInputRequest" }, "result": { - "$ref": "#/definitions/PermissionRequestResult", - "description": "Indicates whether the permission decision was applied; false when the request was already resolved." - } + "$ref": "#/definitions/UIHandlePendingResult", + "description": "Indicates whether the pending UI request was resolved by this call." + }, + "stability": "experimental" }, - "setApproveAll": { - "rpcMethod": "session.permissions.setApproveAll", - "description": "Enables or disables automatic approval of tool permission requests for the session.", + "handlePendingSampling": { + "rpcMethod": "session.ui.handlePendingSampling", + "description": "Resolves a pending `sampling.requested` event with a sampling result, or rejects it.", "params": { "type": "object", "properties": { @@ -1662,93 +2855,32 @@ "type": "string", "description": "Target session identifier" }, - "enabled": { - "type": "boolean", - "description": "Whether to auto-approve all tool permission requests" + "requestId": { + "type": "string", + "description": "The unique request ID from the sampling.requested event" + }, + "response": { + "$ref": "#/definitions/UIHandlePendingSamplingResponse", + "description": "Optional sampling result payload. Omit to reject/cancel the sampling request without providing a result." } }, "required": [ "sessionId", - "enabled" + "requestId" ], "additionalProperties": false, - "description": "Whether to auto-approve all tool permission requests for the rest of the session.", - "title": "PermissionsSetApproveAllRequest" - }, - "result": { - "$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": { - "sessionId": { - "type": "string", - "description": "Target session identifier" - } - }, - "additionalProperties": false, - "description": "No parameters; clears all session-scoped tool permission approvals.", - "title": "PermissionsResetSessionApprovalsRequest", - "required": [ - "sessionId" - ] + "description": "Request ID of a pending `sampling.requested` event and an optional sampling result payload (omit to reject).", + "title": "UIHandlePendingSamplingRequest" }, "result": { - "$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": { - "sessionId": { - "type": "string", - "description": "Target session identifier" - }, - "message": { - "type": "string", - "description": "Human-readable message" - }, - "level": { - "$ref": "#/definitions/SessionLogLevel", - "description": "Log severity level. Determines how the message is displayed in the timeline. Defaults to \"info\"." - }, - "ephemeral": { - "type": "boolean", - "description": "When true, the message is transient and not persisted to the session event log on disk" - }, - "url": { - "type": "string", - "format": "uri", - "description": "Optional URL the user can open in their browser for more details" - } + "$ref": "#/definitions/UIHandlePendingResult", + "description": "Indicates whether the pending UI request was resolved by this call." }, - "required": [ - "sessionId", - "message" - ], - "additionalProperties": false, - "description": "Message text, optional severity level, persistence flag, and optional follow-up URL.", - "title": "LogRequest" + "stability": "experimental" }, - "result": { - "$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.", + "handlePendingAutoModeSwitch": { + "rpcMethod": "session.ui.handlePendingAutoModeSwitch", + "description": "Resolves a pending `auto_mode_switch.requested` event with the user's accept/decline decision.", "params": { "type": "object", "properties": { @@ -1756,37 +2888,33 @@ "type": "string", "description": "Target session identifier" }, - "command": { - "type": "string", - "description": "Shell command to execute" - }, - "cwd": { + "requestId": { "type": "string", - "description": "Working directory (defaults to session working directory)" + "description": "The unique request ID from the auto_mode_switch.requested event" }, - "timeout": { - "type": "integer", - "minimum": 0, - "description": "Timeout in milliseconds (default: 30000)", - "format": "duration" + "response": { + "$ref": "#/definitions/UIAutoModeSwitchResponse", + "description": "User's choice for auto-mode switching: yes (allow this turn), yes_always (allow + persist as setting), or no (decline)." } }, "required": [ "sessionId", - "command" + "requestId", + "response" ], "additionalProperties": false, - "description": "Shell command to run, with optional working directory and timeout in milliseconds.", - "title": "ShellExecRequest" + "description": "Request ID of a pending `auto_mode_switch.requested` event and the user's response.", + "title": "UIHandlePendingAutoModeSwitchRequest" }, "result": { - "$ref": "#/definitions/ShellExecResult", - "description": "Identifier of the spawned process, used to correlate streamed output and exit notifications." - } + "$ref": "#/definitions/UIHandlePendingResult", + "description": "Indicates whether the pending UI request was resolved by this call." + }, + "stability": "experimental" }, - "kill": { - "rpcMethod": "session.shell.kill", - "description": "Sends a signal to a shell process previously started via \"shell.exec\".", + "handlePendingExitPlanMode": { + "rpcMethod": "session.ui.handlePendingExitPlanMode", + "description": "Resolves a pending `exit_plan_mode.requested` event with the user's response.", "params": { "type": "object", "properties": { @@ -1794,33 +2922,33 @@ "type": "string", "description": "Target session identifier" }, - "processId": { + "requestId": { "type": "string", - "description": "Process identifier returned by shell.exec" + "description": "The unique request ID from the exit_plan_mode.requested event" }, - "signal": { - "$ref": "#/definitions/ShellKillSignal", - "description": "Signal to send (default: SIGTERM)" + "response": { + "$ref": "#/definitions/UIExitPlanModeResponse", + "description": "Schema for the `UIExitPlanModeResponse` type." } }, "required": [ "sessionId", - "processId" + "requestId", + "response" ], "additionalProperties": false, - "description": "Identifier of a process previously returned by \"shell.exec\" and the signal to send.", - "title": "ShellKillRequest" + "description": "Request ID of a pending `exit_plan_mode.requested` event and the user's response.", + "title": "UIHandlePendingExitPlanModeRequest" }, "result": { - "$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.", + "$ref": "#/definitions/UIHandlePendingResult", + "description": "Indicates whether the pending UI request was resolved by this call." + }, + "stability": "experimental" + }, + "registerDirectAutoModeSwitchHandler": { + "rpcMethod": "session.ui.registerDirectAutoModeSwitchHandler", + "description": "Registers an in-process handler for auto-mode-switch requests so the server bridge skips dispatch.", "params": { "type": "object", "description": "Identifies the target session.", @@ -1836,14 +2964,14 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/HistoryCompactResult", - "description": "Compaction outcome with the number of tokens and messages removed and the resulting context window breakdown." + "$ref": "#/definitions/UIRegisterDirectAutoModeSwitchHandlerResult", + "description": "Register an in-process handler for `auto_mode_switch.requested` events. The caller still attaches the actual listener via the standard event-subscription mechanism; this registration solely tells the server bridge to skip its own dispatch (so a remote client doesn't race the in-process handler for the same requestId)." }, "stability": "experimental" }, - "truncate": { - "rpcMethod": "session.history.truncate", - "description": "Truncates persisted session history to a specific event.", + "unregisterDirectAutoModeSwitchHandler": { + "rpcMethod": "session.ui.unregisterDirectAutoModeSwitchHandler", + "description": "Unregisters a previously-registered in-process auto-mode-switch handler by its opaque handle.", "params": { "type": "object", "properties": { @@ -1851,55 +2979,81 @@ "type": "string", "description": "Target session identifier" }, - "eventId": { + "handle": { "type": "string", - "description": "Event ID to truncate to. This event and all events after it are removed from the session." + "description": "Handle previously returned by `registerDirectAutoModeSwitchHandler`" } }, "required": [ "sessionId", - "eventId" + "handle" ], "additionalProperties": false, - "description": "Identifier of the event to truncate to; this event and all later events are removed.", - "title": "HistoryTruncateRequest" + "description": "Opaque handle previously returned by `registerDirectAutoModeSwitchHandler` to release.", + "title": "UIUnregisterDirectAutoModeSwitchHandlerRequest" }, "result": { - "$ref": "#/definitions/HistoryTruncateResult", - "description": "Number of events that were removed by the truncation." + "$ref": "#/definitions/UIUnregisterDirectAutoModeSwitchHandlerResult", + "description": "Indicates whether the handle was active and the registration count was decremented." }, "stability": "experimental" } }, - "usage": { - "getMetrics": { - "rpcMethod": "session.usage.getMetrics", - "description": "Gets accumulated usage metrics for the session.", + "permissions": { + "configure": { + "rpcMethod": "session.permissions.configure", + "description": "Replaces selected permission policy fields (rules, paths, URLs, exclusions, allow-all flags) on the session.", "params": { "type": "object", - "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" + }, + "approveAllToolPermissionRequests": { + "type": "boolean", + "description": "If specified, sets whether tool permission requests are auto-approved without prompting. Omit to leave the current value unchanged." + }, + "approveAllReadPermissionRequests": { + "type": "boolean", + "description": "If specified, sets whether path/URL read permission requests are auto-approved. Omit to leave the current value unchanged." + }, + "rules": { + "$ref": "#/definitions/PermissionRulesSet", + "description": "If specified, replaces the session's approved/denied permission rules. Omit to leave the current rules unchanged." + }, + "paths": { + "$ref": "#/definitions/PermissionPathsConfig", + "description": "If specified, replaces the session's path-permission policy. The runtime constructs the appropriate PathManager based on these inputs (rooted at the session's working directory). Omit to leave the current path policy unchanged." + }, + "urls": { + "$ref": "#/definitions/PermissionUrlsConfig", + "description": "If specified, replaces the session's URL-permission policy. The runtime constructs a fresh DefaultUrlManager based on these inputs. Omit to leave the current URL policy unchanged." + }, + "additionalContentExclusionPolicies": { + "type": "array", + "items": { + "$ref": "#/definitions/PermissionsConfigureAdditionalContentExclusionPolicy" + }, + "description": "If specified, replaces the host-supplied GitHub Content Exclusion policies on the session (combined with natively-discovered policies when evaluating tool/file access). Omit to leave the current policies unchanged." } }, + "additionalProperties": false, + "description": "Patch of permission policy fields to apply (omit a field to leave it unchanged).", + "title": "PermissionsConfigureParams", "required": [ "sessionId" - ], - "additionalProperties": false + ] }, "result": { - "$ref": "#/definitions/UsageGetMetricsResult", - "description": "Accumulated session usage metrics, including premium request cost, token counts, model breakdown, and code-change totals." + "$ref": "#/definitions/PermissionsConfigureResult", + "description": "Indicates whether the operation succeeded." }, "stability": "experimental" - } - }, - "remote": { - "enable": { - "rpcMethod": "session.remote.enable", - "description": "Enables remote session export or steering.", + }, + "handlePendingPermissionRequest": { + "rpcMethod": "session.permissions.handlePendingPermissionRequest", + "description": "Provides a decision for a pending tool permission request.", "params": { "type": "object", "properties": { @@ -1907,53 +3061,57 @@ "type": "string", "description": "Target session identifier" }, - "mode": { - "$ref": "#/definitions/RemoteSessionMode", - "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." + "requestId": { + "type": "string", + "description": "Request ID of the pending permission request" + }, + "result": { + "$ref": "#/definitions/PermissionDecision", + "description": "The client's response to the pending permission prompt" } }, - "additionalProperties": false, - "description": "Optional remote session mode (\"off\", \"export\", or \"on\"); defaults to enabling both export and remote steering.", - "title": "RemoteEnableRequest", "required": [ - "sessionId" - ] + "sessionId", + "requestId", + "result" + ], + "additionalProperties": false, + "description": "Pending permission request ID and the decision to apply (approve/reject and scope).", + "title": "PermissionDecisionRequest" }, "result": { - "$ref": "#/definitions/RemoteEnableResult", - "description": "GitHub URL for the session and a flag indicating whether remote steering is enabled." + "$ref": "#/definitions/PermissionRequestResult", + "description": "Indicates whether the permission decision was applied; false when the request was already resolved." }, "stability": "experimental" }, - "disable": { - "rpcMethod": "session.remote.disable", - "description": "Disables remote session export and steering.", + "pendingRequests": { + "rpcMethod": "session.permissions.pendingRequests", + "description": "Reconstructs the set of pending tool permission requests from the session's event history.", "params": { "type": "object", - "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, + "additionalProperties": false, + "description": "No parameters; returns currently-pending permission requests for the session.", + "title": "PermissionsPendingRequestsRequest", "required": [ "sessionId" - ], - "additionalProperties": false + ] }, "result": { - "type": "null" + "$ref": "#/definitions/PendingPermissionRequestList", + "description": "List of pending permission requests reconstructed from event history." }, "stability": "experimental" - } - } - }, - "clientSession": { - "sessionFs": { - "readFile": { - "rpcMethod": "sessionFs.readFile", - "description": "Reads a file from the client-provided session filesystem.", + }, + "setApproveAll": { + "rpcMethod": "session.permissions.setApproveAll", + "description": "Enables or disables automatic approval of tool permission requests for the session.", "params": { "type": "object", "properties": { @@ -1961,27 +3119,32 @@ "type": "string", "description": "Target session identifier" }, - "path": { - "type": "string", - "description": "Path using SessionFs conventions" + "enabled": { + "type": "boolean", + "description": "Whether to auto-approve all tool permission requests" + }, + "source": { + "$ref": "#/definitions/PermissionsSetApproveAllSource", + "description": "Optional source for allow-all telemetry. Defaults to `rpc` when omitted for SDK callers." } }, "required": [ "sessionId", - "path" + "enabled" ], "additionalProperties": false, - "description": "Path of the file to read from the client-provided session filesystem.", - "title": "SessionFsReadFileRequest" + "description": "Allow-all toggle for tool permission requests, with an optional telemetry source.", + "title": "PermissionsSetApproveAllRequest" }, "result": { - "$ref": "#/definitions/SessionFsReadFileResult", - "description": "File content as a UTF-8 string, or a filesystem error if the read failed." - } + "$ref": "#/definitions/PermissionsSetApproveAllResult", + "description": "Indicates whether the operation succeeded." + }, + "stability": "experimental" }, - "writeFile": { - "rpcMethod": "sessionFs.writeFile", - "description": "Writes a file in the client-provided session filesystem.", + "modifyRules": { + "rpcMethod": "session.permissions.modifyRules", + "description": "Adds or removes session-scoped or location-scoped permission rules.", "params": { "type": "object", "properties": { @@ -1989,45 +3152,46 @@ "type": "string", "description": "Target session identifier" }, - "path": { - "type": "string", - "description": "Path using SessionFs conventions" + "scope": { + "$ref": "#/definitions/PermissionsModifyRulesScope", + "description": "Whether the change applies to ephemeral session-scoped rules (cleared at session end) or to location-scoped rules persisted via the location-permissions config file." }, - "content": { - "type": "string", - "description": "Content to write" + "add": { + "type": "array", + "items": { + "$ref": "#/definitions/PermissionRule" + }, + "description": "Rules to add to the scope. Applied before `remove`/`removeAll`." }, - "mode": { - "type": "integer", - "minimum": 0, - "description": "Optional POSIX-style mode for newly created files" + "remove": { + "type": "array", + "items": { + "$ref": "#/definitions/PermissionRule" + }, + "description": "Specific rules to remove from the scope. Ignored when `removeAll` is true." + }, + "removeAll": { + "type": "boolean", + "description": "When true, removes every rule currently in the scope (after any `add` is applied). Useful for clearing the location scope wholesale." } }, "required": [ "sessionId", - "path", - "content" + "scope" ], "additionalProperties": false, - "description": "File path, content to write, and optional mode for the client-provided session filesystem.", - "title": "SessionFsWriteFileRequest" + "description": "Scope and add/remove instructions for modifying session- or location-scoped permission rules.", + "title": "PermissionsModifyRulesParams" }, "result": { - "anyOf": [ - { - "not": {} - }, - { - "$ref": "#/definitions/SessionFsError", - "description": "Describes a filesystem error." - } - ], - "description": "Describes a filesystem error." - } + "$ref": "#/definitions/PermissionsModifyRulesResult", + "description": "Indicates whether the operation succeeded." + }, + "stability": "experimental" }, - "appendFile": { - "rpcMethod": "sessionFs.appendFile", - "description": "Appends content to a file in the client-provided session filesystem.", + "setRequired": { + "rpcMethod": "session.permissions.setRequired", + "description": "Sets whether the client wants permission prompts bridged into session events.", "params": { "type": "object", "properties": { @@ -2035,73 +3199,52 @@ "type": "string", "description": "Target session identifier" }, - "path": { - "type": "string", - "description": "Path using SessionFs conventions" - }, - "content": { - "type": "string", - "description": "Content to append" - }, - "mode": { - "type": "integer", - "minimum": 0, - "description": "Optional POSIX-style mode for newly created files" + "required": { + "type": "boolean", + "description": "Whether the client wants `permission.requested` events bridged from the session-owned permission service. CLI clients that render prompt UI set this to `true` for as long as their listener is mounted; headless callers leave it unset (the default is `false`)." } }, "required": [ "sessionId", - "path", - "content" + "required" ], "additionalProperties": false, - "description": "File path, content to append, and optional mode for the client-provided session filesystem.", - "title": "SessionFsAppendFileRequest" + "description": "Toggles whether permission prompts should be bridged into session events for this client.", + "title": "PermissionsSetRequiredRequest" }, "result": { - "anyOf": [ - { - "not": {} - }, - { - "$ref": "#/definitions/SessionFsError", - "description": "Describes a filesystem error." - } - ], - "description": "Describes a filesystem error." - } + "$ref": "#/definitions/PermissionsSetRequiredResult", + "description": "Indicates whether the operation succeeded." + }, + "stability": "experimental" }, - "exists": { - "rpcMethod": "sessionFs.exists", - "description": "Checks whether a path exists in the client-provided session filesystem.", + "resetSessionApprovals": { + "rpcMethod": "session.permissions.resetSessionApprovals", + "description": "Clears session-scoped tool permission approvals.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" - }, - "path": { - "type": "string", - "description": "Path using SessionFs conventions" } }, - "required": [ - "sessionId", - "path" - ], "additionalProperties": false, - "description": "Path to test for existence in the client-provided session filesystem.", - "title": "SessionFsExistsRequest" + "description": "No parameters; clears all session-scoped tool permission approvals.", + "title": "PermissionsResetSessionApprovalsRequest", + "required": [ + "sessionId" + ] }, "result": { - "$ref": "#/definitions/SessionFsExistsResult", - "description": "Indicates whether the requested path exists in the client-provided session filesystem." - } + "$ref": "#/definitions/PermissionsResetSessionApprovalsResult", + "description": "Indicates whether the operation succeeded." + }, + "stability": "experimental" }, - "stat": { - "rpcMethod": "sessionFs.stat", - "description": "Gets metadata for a path in the client-provided session filesystem.", + "notifyPromptShown": { + "rpcMethod": "session.permissions.notifyPromptShown", + "description": "Notifies the runtime that a permission prompt UI has been shown to the user.", "params": { "type": "object", "properties": { @@ -2109,128 +3252,453 @@ "type": "string", "description": "Target session identifier" }, - "path": { + "message": { "type": "string", - "description": "Path using SessionFs conventions" + "description": "Human-readable description of the prompt the user is being asked to approve. Used by the runtime to fire the registered `permission_prompt` notification hook (e.g. terminal bell, desktop notification)." } }, "required": [ "sessionId", - "path" + "message" ], "additionalProperties": false, - "description": "Path whose metadata should be returned from the client-provided session filesystem.", - "title": "SessionFsStatRequest" + "description": "Notification payload describing the permission prompt that the client just rendered.", + "title": "PermissionPromptShownNotification" }, "result": { - "$ref": "#/definitions/SessionFsStatResult", - "description": "Filesystem metadata for the requested path, or a filesystem error if the stat failed." - } + "$ref": "#/definitions/PermissionsNotifyPromptShownResult", + "description": "Indicates whether the operation succeeded." + }, + "stability": "experimental" }, - "mkdir": { - "rpcMethod": "sessionFs.mkdir", - "description": "Creates a directory in the client-provided session filesystem.", - "params": { - "type": "object", - "properties": { - "sessionId": { - "type": "string", - "description": "Target session identifier" - }, - "path": { - "type": "string", - "description": "Path using SessionFs conventions" - }, - "recursive": { - "type": "boolean", - "description": "Create parent directories as needed" + "paths": { + "list": { + "rpcMethod": "session.permissions.paths.list", + "description": "Returns the session's allowed directories and primary working directory.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } }, - "mode": { - "type": "integer", - "minimum": 0, - "description": "Optional POSIX-style mode for newly created directories" - } + "additionalProperties": false, + "description": "No parameters; returns the session's allow-listed directories.", + "title": "PermissionsPathsListRequest", + "required": [ + "sessionId" + ] }, - "required": [ - "sessionId", - "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": { + "$ref": "#/definitions/PermissionPathsList", + "description": "Snapshot of the session's allow-listed directories and primary working directory." + }, + "stability": "experimental" }, - "result": { - "anyOf": [ - { - "not": {} + "add": { + "rpcMethod": "session.permissions.paths.add", + "description": "Adds a directory to the session's allow-list.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "path": { + "type": "string", + "description": "Directory to add to the allow-list. The runtime resolves and validates the path before adding." + } }, - { - "$ref": "#/definitions/SessionFsError", - "description": "Describes a filesystem error." - } - ], - "description": "Describes a filesystem error." + "required": [ + "sessionId", + "path" + ], + "additionalProperties": false, + "description": "Directory path to add to the session's allowed directories.", + "title": "PermissionPathsAddParams" + }, + "result": { + "$ref": "#/definitions/PermissionsPathsAddResult", + "description": "Indicates whether the operation succeeded." + }, + "stability": "experimental" + }, + "updatePrimary": { + "rpcMethod": "session.permissions.paths.updatePrimary", + "description": "Updates the session's primary working directory used by the permission policy.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "path": { + "type": "string", + "description": "Directory to set as the new primary working directory for the session's permission policy." + } + }, + "required": [ + "sessionId", + "path" + ], + "additionalProperties": false, + "description": "Directory path to set as the session's new primary working directory.", + "title": "PermissionPathsUpdatePrimaryParams" + }, + "result": { + "$ref": "#/definitions/PermissionsPathsUpdatePrimaryResult", + "description": "Indicates whether the operation succeeded." + }, + "stability": "experimental" + }, + "isPathWithinAllowedDirectories": { + "rpcMethod": "session.permissions.paths.isPathWithinAllowedDirectories", + "description": "Reports whether a path falls within any of the session's allowed directories.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "path": { + "type": "string", + "description": "Path to check against the session's allowed directories" + } + }, + "required": [ + "sessionId", + "path" + ], + "additionalProperties": false, + "description": "Path to evaluate against the session's allowed directories.", + "title": "PermissionPathsAllowedCheckParams" + }, + "result": { + "$ref": "#/definitions/PermissionPathsAllowedCheckResult", + "description": "Indicates whether the supplied path is within the session's allowed directories." + }, + "stability": "experimental" + }, + "isPathWithinWorkspace": { + "rpcMethod": "session.permissions.paths.isPathWithinWorkspace", + "description": "Reports whether a path falls within the session's workspace (primary) directory.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "path": { + "type": "string", + "description": "Path to check against the session workspace directory" + } + }, + "required": [ + "sessionId", + "path" + ], + "additionalProperties": false, + "description": "Path to evaluate against the session's workspace (primary) directory.", + "title": "PermissionPathsWorkspaceCheckParams" + }, + "result": { + "$ref": "#/definitions/PermissionPathsWorkspaceCheckResult", + "description": "Indicates whether the supplied path is within the session's workspace directory." + }, + "stability": "experimental" } }, - "readdir": { - "rpcMethod": "sessionFs.readdir", - "description": "Lists entry names in a directory from the client-provided session filesystem.", + "locations": { + "resolve": { + "rpcMethod": "session.permissions.locations.resolve", + "description": "Resolves the permission location key and type for a working directory.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "workingDirectory": { + "type": "string", + "description": "Working directory whose permission location should be resolved" + } + }, + "required": [ + "sessionId", + "workingDirectory" + ], + "additionalProperties": false, + "description": "Working directory to resolve into a location-permissions key.", + "title": "PermissionLocationResolveParams" + }, + "result": { + "$ref": "#/definitions/PermissionLocationResolveResult", + "description": "Resolved location-permissions key and type." + }, + "stability": "experimental" + }, + "apply": { + "rpcMethod": "session.permissions.locations.apply", + "description": "Applies persisted location-scoped tool approvals and allowed directories for a working directory to this session's permission service.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "workingDirectory": { + "type": "string", + "description": "Working directory whose persisted location permissions should be applied" + } + }, + "required": [ + "sessionId", + "workingDirectory" + ], + "additionalProperties": false, + "description": "Working directory to load persisted location permissions for.", + "title": "PermissionLocationApplyParams" + }, + "result": { + "$ref": "#/definitions/PermissionLocationApplyResult", + "description": "Summary of persisted location permissions applied to the session." + }, + "stability": "experimental" + }, + "addToolApproval": { + "rpcMethod": "session.permissions.locations.addToolApproval", + "description": "Persists a tool approval for a permission location and applies its rules to this session's live permission service.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "locationKey": { + "type": "string", + "description": "Location key (git root or cwd) to persist the approval to" + }, + "approval": { + "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetails", + "description": "Tool approval to persist and apply" + } + }, + "required": [ + "sessionId", + "locationKey", + "approval" + ], + "additionalProperties": false, + "description": "Location-scoped tool approval to persist.", + "title": "PermissionLocationAddToolApprovalParams" + }, + "result": { + "$ref": "#/definitions/PermissionsLocationsAddToolApprovalResult", + "description": "Indicates whether the operation succeeded." + }, + "stability": "experimental" + } + }, + "folderTrust": { + "isTrusted": { + "rpcMethod": "session.permissions.folderTrust.isTrusted", + "description": "Reports whether a folder is trusted according to the user's folder trust state.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "path": { + "type": "string", + "description": "Folder path to check" + } + }, + "required": [ + "sessionId", + "path" + ], + "additionalProperties": false, + "description": "Folder path to check for trust.", + "title": "FolderTrustCheckParams" + }, + "result": { + "$ref": "#/definitions/FolderTrustCheckResult", + "description": "Folder trust check result." + }, + "stability": "experimental" + }, + "addTrusted": { + "rpcMethod": "session.permissions.folderTrust.addTrusted", + "description": "Adds a folder to the user's trusted folders list.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "path": { + "type": "string", + "description": "Folder path to mark as trusted" + } + }, + "required": [ + "sessionId", + "path" + ], + "additionalProperties": false, + "description": "Folder path to add to trusted folders.", + "title": "FolderTrustAddParams" + }, + "result": { + "$ref": "#/definitions/PermissionsFolderTrustAddTrustedResult", + "description": "Indicates whether the operation succeeded." + }, + "stability": "experimental" + } + }, + "urls": { + "setUnrestrictedMode": { + "rpcMethod": "session.permissions.urls.setUnrestrictedMode", + "description": "Toggles the runtime's URL-permission policy between unrestricted and restricted modes.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "enabled": { + "type": "boolean", + "description": "Whether to allow access to all URLs without prompting. Toggles the runtime's URL-permission policy in place." + } + }, + "required": [ + "sessionId", + "enabled" + ], + "additionalProperties": false, + "description": "Whether the URL-permission policy should run in unrestricted mode.", + "title": "PermissionUrlsSetUnrestrictedModeParams" + }, + "result": { + "$ref": "#/definitions/PermissionsUrlsSetUnrestrictedModeResult", + "description": "Indicates whether the operation succeeded." + }, + "stability": "experimental" + } + } + }, + "log": { + "rpcMethod": "session.log", + "description": "Emits a user-visible session log event.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "message": { + "type": "string", + "description": "Human-readable message" + }, + "level": { + "$ref": "#/definitions/SessionLogLevel", + "description": "Log severity level. Determines how the message is displayed in the timeline. Defaults to \"info\"." + }, + "type": { + "type": "string", + "description": "Domain category for this log entry (e.g., \"mcp\", \"subscription\", \"policy\", \"model\"). Maps to `infoType`/`warningType`/`errorType` on the emitted event. Defaults to \"notification\"." + }, + "ephemeral": { + "type": "boolean", + "description": "When true, the message is transient and not persisted to the session event log on disk" + }, + "url": { + "type": "string", + "format": "uri", + "description": "Optional URL the user can open in their browser for more details" + }, + "tip": { + "type": "string", + "description": "Optional actionable tip displayed alongside the message. Only honored on `level: \"info\"`." + } + }, + "required": [ + "sessionId", + "message" + ], + "additionalProperties": false, + "description": "Message text, optional severity level, persistence flag, optional follow-up URL, and optional tip.", + "title": "LogRequest" + }, + "result": { + "$ref": "#/definitions/LogResult", + "description": "Identifier of the session event that was emitted for the log message." + }, + "stability": "experimental" + }, + "metadata": { + "snapshot": { + "rpcMethod": "session.metadata.snapshot", + "description": "Returns a snapshot of the session's identifying metadata, mode, agent, and remote info.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" - }, - "path": { - "type": "string", - "description": "Path using SessionFs conventions" } }, "required": [ - "sessionId", - "path" + "sessionId" ], - "additionalProperties": false, - "description": "Directory path whose entries should be listed from the client-provided session filesystem.", - "title": "SessionFsReaddirRequest" + "additionalProperties": false }, "result": { - "$ref": "#/definitions/SessionFsReaddirResult", - "description": "Names of entries in the requested directory, or a filesystem error if the read failed." - } + "$ref": "#/definitions/SessionMetadataSnapshot", + "description": "Point-in-time snapshot of slow-changing session identifier and state fields" + }, + "stability": "experimental" }, - "readdirWithTypes": { - "rpcMethod": "sessionFs.readdirWithTypes", - "description": "Lists directory entries with type information from the client-provided session filesystem.", + "isProcessing": { + "rpcMethod": "session.metadata.isProcessing", + "description": "Reports whether the local session is currently processing user/agent messages.", "params": { "type": "object", + "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" - }, - "path": { - "type": "string", - "description": "Path using SessionFs conventions" } }, "required": [ - "sessionId", - "path" + "sessionId" ], - "additionalProperties": false, - "description": "Directory path whose entries (with type information) should be listed from the client-provided session filesystem.", - "title": "SessionFsReaddirWithTypesRequest" + "additionalProperties": false }, "result": { - "$ref": "#/definitions/SessionFsReaddirWithTypesResult", - "description": "Entries in the requested directory paired with file/directory type information, or a filesystem error if the read failed." - } + "$ref": "#/definitions/MetadataIsProcessingResult", + "description": "Indicates whether the local session is currently processing a turn or background continuation." + }, + "stability": "experimental" }, - "rm": { - "rpcMethod": "sessionFs.rm", - "description": "Removes a file or directory from the client-provided session filesystem.", + "contextInfo": { + "rpcMethod": "session.metadata.contextInfo", + "description": "Returns the token breakdown for the session's current context window for a given model.", "params": { "type": "object", "properties": { @@ -2238,43 +3706,68 @@ "type": "string", "description": "Target session identifier" }, - "path": { - "type": "string", - "description": "Path using SessionFs conventions" + "promptTokenLimit": { + "type": "integer", + "minimum": 0, + "description": "Maximum prompt tokens allowed by the target model. Pass 0 to use the runtime default." }, - "recursive": { - "type": "boolean", - "description": "Remove directories and their contents recursively" + "outputTokenLimit": { + "type": "integer", + "minimum": 0, + "description": "Maximum output tokens allowed by the target model. Pass 0 if unknown." }, - "force": { - "type": "boolean", - "description": "Ignore errors if the path does not exist" + "selectedModel": { + "type": "string", + "description": "Model identifier used for tokenization. Omit to use the session default. Used both for token counting and to compute display values." } }, "required": [ "sessionId", - "path" + "promptTokenLimit", + "outputTokenLimit" ], "additionalProperties": false, - "description": "Path to remove from the client-provided session filesystem, with options for recursive removal and force.", - "title": "SessionFsRmRequest" + "description": "Model identifier and token limits used to compute the context-info breakdown.", + "title": "MetadataContextInfoRequest" }, "result": { - "anyOf": [ - { - "not": {} + "$ref": "#/definitions/MetadataContextInfoResult", + "description": "Token breakdown for the session's current context window, or null if uninitialized." + }, + "stability": "experimental" + }, + "recordContextChange": { + "rpcMethod": "session.metadata.recordContextChange", + "description": "Records a working-directory/git context change and emits a `session.context_changed` event.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" }, - { - "$ref": "#/definitions/SessionFsError", - "description": "Describes a filesystem error." + "context": { + "$ref": "#/definitions/SessionWorkingDirectoryContext", + "description": "Updated working directory and git context. Emitted as the new payload of `session.context_changed`." } + }, + "required": [ + "sessionId", + "context" ], - "description": "Describes a filesystem error." - } + "additionalProperties": false, + "description": "Updated working-directory/git context to record on the session.", + "title": "MetadataRecordContextChangeRequest" + }, + "result": { + "$ref": "#/definitions/MetadataRecordContextChangeResult", + "description": "Notify the session that its working directory context has changed. Emits a `session.context_changed` event so consumers (telemetry, OTel tracker, ACP, the timeline UI) can react. Use this when the host has detected a cwd/branch/repo change outside the session's normal lifecycle (e.g., after a shell command in interactive mode)." + }, + "stability": "experimental" }, - "rename": { - "rpcMethod": "sessionFs.rename", - "description": "Renames or moves a path in the client-provided session filesystem.", + "setWorkingDirectory": { + "rpcMethod": "session.metadata.setWorkingDirectory", + "description": "Updates the session's recorded working directory.", "params": { "type": "object", "properties": { @@ -2282,40 +3775,98 @@ "type": "string", "description": "Target session identifier" }, - "src": { + "workingDirectory": { "type": "string", - "description": "Source path using SessionFs conventions" + "description": "Absolute path to set as the session's working directory. The runtime updates the session's recorded cwd so subsequent operations (shell tools, file lookups, telemetry) anchor to it." + } + }, + "required": [ + "sessionId", + "workingDirectory" + ], + "additionalProperties": false, + "description": "Absolute path to set as the session's new working directory.", + "title": "MetadataSetWorkingDirectoryRequest" + }, + "result": { + "$ref": "#/definitions/MetadataSetWorkingDirectoryResult", + "description": "Update the session's working directory. Used by the host when the user explicitly changes cwd (e.g., the `/cd` slash command). The host is responsible for `process.chdir` and any related side-effects (file index, etc.); this method only updates the session's own recorded path." + }, + "stability": "experimental" + }, + "recomputeContextTokens": { + "rpcMethod": "session.metadata.recomputeContextTokens", + "description": "Re-tokenizes the session's existing messages against a model and returns aggregate token totals.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" }, - "dest": { + "modelId": { "type": "string", - "description": "Destination path using SessionFs conventions" + "description": "Model identifier used for tokenization. The runtime token-counts both chat-context and system-context messages against this model." } }, "required": [ "sessionId", - "src", - "dest" + "modelId" ], "additionalProperties": false, - "description": "Source and destination paths for renaming or moving an entry in the client-provided session filesystem.", - "title": "SessionFsRenameRequest" + "description": "Model identifier to use when re-tokenizing the session's existing messages.", + "title": "MetadataRecomputeContextTokensRequest" }, "result": { - "anyOf": [ - { - "not": {} + "$ref": "#/definitions/MetadataRecomputeContextTokensResult", + "description": "Re-tokenize the session's existing messages against `modelId` and return the token totals. Useful for hosts that want an initial estimate of context usage on session resume, before the next agent turn fires `session.context_info_changed` events. Returns zeros for an empty session." + }, + "stability": "experimental" + } + }, + "shell": { + "exec": { + "rpcMethod": "session.shell.exec", + "description": "Starts a shell command and streams output through session notifications.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" }, - { - "$ref": "#/definitions/SessionFsError", - "description": "Describes a filesystem error." + "command": { + "type": "string", + "description": "Shell command to execute" + }, + "cwd": { + "type": "string", + "description": "Working directory (defaults to session working directory)" + }, + "timeout": { + "type": "integer", + "minimum": 0, + "description": "Timeout in milliseconds (default: 30000)", + "format": "duration" } + }, + "required": [ + "sessionId", + "command" ], - "description": "Describes a filesystem error." - } + "additionalProperties": false, + "description": "Shell command to run, with optional working directory and timeout in milliseconds.", + "title": "ShellExecRequest" + }, + "result": { + "$ref": "#/definitions/ShellExecResult", + "description": "Identifier of the spawned process, used to correlate streamed output and exit notifications." + }, + "stability": "experimental" }, - "sqliteQuery": { - "rpcMethod": "sessionFs.sqliteQuery", - "description": "Executes a SQLite query against the per-session database.", + "kill": { + "rpcMethod": "session.shell.kill", + "description": "Sends a signal to a shell process previously started via \"shell.exec\".", "params": { "type": "object", "properties": { @@ -2323,43 +3874,86 @@ "type": "string", "description": "Target session identifier" }, - "query": { + "processId": { "type": "string", - "description": "SQL query to execute" + "description": "Process identifier returned by shell.exec" }, - "queryType": { - "$ref": "#/definitions/SessionFsSqliteQueryType", - "description": "How to execute the query: 'exec' for DDL/multi-statement (no results), 'query' for SELECT (returns rows), 'run' for INSERT/UPDATE/DELETE (returns rowsAffected)" + "signal": { + "$ref": "#/definitions/ShellKillSignal", + "description": "Signal to send (default: SIGTERM)" + } + }, + "required": [ + "sessionId", + "processId" + ], + "additionalProperties": false, + "description": "Identifier of a process previously returned by \"shell.exec\" and the signal to send.", + "title": "ShellKillRequest" + }, + "result": { + "$ref": "#/definitions/ShellKillResult", + "description": "Indicates whether the signal was delivered; false if the process was unknown or already exited." + }, + "stability": "experimental" + } + }, + "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", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/HistoryCompactResult", + "description": "Compaction outcome with the number of tokens and messages removed, summary text, 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": { + "sessionId": { + "type": "string", + "description": "Target session identifier" }, - "params": { - "type": "object", - "additionalProperties": { - "type": [ - "string", - "number", - "null" - ] - }, - "description": "Optional named bind parameters" + "eventId": { + "type": "string", + "description": "Event ID to truncate to. This event and all events after it are removed from the session." } }, "required": [ "sessionId", - "query", - "queryType" + "eventId" ], "additionalProperties": false, - "description": "SQL query, query type, and optional bind parameters for executing a SQLite query against the per-session database.", - "title": "SessionFsSqliteQueryRequest" + "description": "Identifier of the event to truncate to; this event and all later events are removed.", + "title": "HistoryTruncateRequest" }, "result": { - "$ref": "#/definitions/SessionFsSqliteQueryResult", - "description": "Query results including rows, columns, and rows affected, or a filesystem error if execution failed." - } + "$ref": "#/definitions/HistoryTruncateResult", + "description": "Number of events that were removed by the truncation." + }, + "stability": "experimental" }, - "sqliteExists": { - "rpcMethod": "sessionFs.sqliteExists", - "description": "Checks whether the per-session SQLite database already exists, without creating it.", + "cancelBackgroundCompaction": { + "rpcMethod": "session.history.cancelBackgroundCompaction", + "description": "Cancels any in-progress background compaction on a local session.", "params": { "type": "object", "description": "Identifies the target session.", @@ -2375,3922 +3969,9614 @@ "additionalProperties": false }, "result": { - "$ref": "#/definitions/SessionFsSqliteExistsResult", - "description": "Indicates whether the per-session SQLite database already exists." - } - } - } - }, - "definitions": { - "AccountGetQuotaRequest": { - "anyOf": [ - { - "not": {} + "$ref": "#/definitions/HistoryCancelBackgroundCompactionResult", + "description": "Indicates whether an in-progress background compaction was cancelled." + }, + "stability": "experimental" + }, + "abortManualCompaction": { + "rpcMethod": "session.history.abortManualCompaction", + "description": "Aborts any in-progress manual compaction on a local session.", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/HistoryAbortManualCompactionResult", + "description": "Indicates whether an in-progress manual compaction was aborted." + }, + "stability": "experimental" + }, + "summarizeForHandoff": { + "rpcMethod": "session.history.summarizeForHandoff", + "description": "Produces a markdown summary of the session's conversation context for hand-off scenarios.", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/HistorySummarizeForHandoffResult", + "description": "Markdown summary of the conversation context (empty when not available)." + }, + "stability": "experimental" + } + }, + "queue": { + "pendingItems": { + "rpcMethod": "session.queue.pendingItems", + "description": "Returns the local session's pending user-facing queued items and steering messages.", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/QueuePendingItemsResult", + "description": "Snapshot of the session's pending queued items and immediate-steering messages." + }, + "stability": "experimental" + }, + "removeMostRecent": { + "rpcMethod": "session.queue.removeMostRecent", + "description": "Removes the most recently queued user-facing item (LIFO).", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/QueueRemoveMostRecentResult", + "description": "Indicates whether a user-facing pending item was removed." + }, + "stability": "experimental" + }, + "clear": { + "rpcMethod": "session.queue.clear", + "description": "Clears all pending queued items on the local session.", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "type": "null" + }, + "stability": "experimental" + } + }, + "eventLog": { + "read": { + "rpcMethod": "session.eventLog.read", + "description": "Reads a batch of session events from a cursor, optionally waiting for new events.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "cursor": { + "type": "string", + "description": "Opaque cursor returned by a previous read. Omit on the first call to start from the beginning of the session's persisted history." + }, + "max": { + "type": "integer", + "exclusiveMinimum": true, + "minimum": 0, + "maximum": 1000, + "description": "Maximum number of events to return in this batch (1–1000, default 200)." + }, + "waitMs": { + "type": "integer", + "minimum": 0, + "maximum": 30000, + "description": "Milliseconds to wait for new events when the cursor is at the tail of history. 0 (default) returns immediately even if no events are available. Capped at 30000ms. Ephemeral events that arrive during the wait are delivered in this batch but are NOT replayable on a subsequent read (use a non-zero waitMs in your next call to capture future ephemerals as they happen).", + "format": "duration" + }, + "types": { + "$ref": "#/definitions/EventLogTypes", + "description": "Either '*' to receive all event types, or a non-empty list of event types to receive" + }, + "agentScope": { + "$ref": "#/definitions/EventsAgentScope", + "description": "Agent-scope filter: 'primary' returns only main-agent events plus events whose type starts with 'subagent.' (matching the typed-subscription default behavior); 'all' returns events from all agents (matching wildcard-subscription behavior). Default is 'all' to preserve wildcard semantics for catch-up callers." + } + }, + "additionalProperties": false, + "description": "Cursor, batch size, and optional long-poll/filter parameters for reading session events.", + "title": "EventLogReadRequest", + "required": [ + "sessionId" + ] + }, + "result": { + "$ref": "#/definitions/EventsReadResult", + "description": "Batch of session events returned by a read, with cursor and continuation metadata." + }, + "stability": "experimental" + }, + "tail": { + "rpcMethod": "session.eventLog.tail", + "description": "Returns a snapshot of the current tail cursor without consuming events.", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/EventLogTailResult", + "description": "Snapshot of the current tail cursor without returning any events. Use this when a consumer wants to subscribe to live events going forward without first paginating through the entire persisted history (which would happen if `read` were called without a cursor on a long-lived session)." + }, + "stability": "experimental" + }, + "registerInterest": { + "rpcMethod": "session.eventLog.registerInterest", + "description": "Registers consumer interest in an event type for runtime gating purposes.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "eventType": { + "type": "string", + "description": "The event type the consumer wants the runtime to treat as 'observed' for behavior-switching gating. Some runtime code paths inspect whether any consumer is interested in a specific event type and choose a different implementation accordingly (e.g. `mcp.oauth_required`: when interest is registered the runtime delegates the full interactive OAuth flow to the consumer; when no interest is registered the runtime installs a browserless fallback that silently reuses cached tokens). SDK clients that long-poll events do NOT automatically appear as listeners to these gating checks — they must explicitly call `registerInterest` for each event type they want the runtime to count as having a consumer. Multiple registrations for the same event type from the same or different consumers are tracked independently and must each be released. See: `mcp.oauth_required`, `sampling.requested`, `auto_mode_switch.requested`, `user_input.requested`, `elicitation.requested`, `command.queued`, `exit_plan_mode.requested`." + } + }, + "required": [ + "sessionId", + "eventType" + ], + "additionalProperties": false, + "description": "Event type to register consumer interest for, used by runtime gating logic.", + "title": "RegisterEventInterestParams" + }, + "result": { + "$ref": "#/definitions/RegisterEventInterestResult", + "description": "Opaque handle representing an event-type interest registration." + }, + "stability": "experimental" + }, + "releaseInterest": { + "rpcMethod": "session.eventLog.releaseInterest", + "description": "Releases a consumer's previously-registered interest in an event type.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "handle": { + "type": "string", + "description": "Handle returned by a previous `registerInterest` call. Idempotent: releasing an unknown or already-released handle is a no-op (returns success). When the last outstanding handle for an event type is released, the runtime reverts to its 'no consumer' code path for that event type." + } + }, + "required": [ + "sessionId", + "handle" + ], + "additionalProperties": false, + "description": "Opaque handle previously returned by `registerInterest` to release.", + "title": "ReleaseEventInterestParams" + }, + "result": { + "$ref": "#/definitions/EventLogReleaseInterestResult", + "description": "Indicates whether the operation succeeded." + }, + "stability": "experimental" + } + }, + "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", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/UsageGetMetricsResult", + "description": "Accumulated session usage metrics, including premium request cost, token counts, model breakdown, and code-change totals." + }, + "stability": "experimental" + } + }, + "remote": { + "enable": { + "rpcMethod": "session.remote.enable", + "description": "Enables remote session export or steering.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "mode": { + "$ref": "#/definitions/RemoteSessionMode", + "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", + "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", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "type": "null" + }, + "stability": "experimental" + }, + "notifySteerableChanged": { + "rpcMethod": "session.remote.notifySteerableChanged", + "description": "Persists a remote-steerability change emitted by the host as a session event.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "remoteSteerable": { + "type": "boolean", + "description": "Whether the session now supports remote steering via GitHub. The runtime persists this as a `session.remote_steerable_changed` event so resume/replay sees the up-to-date capability." + } + }, + "required": [ + "sessionId", + "remoteSteerable" + ], + "additionalProperties": false, + "description": "New remote-steerability state to persist as a `session.remote_steerable_changed` event.", + "title": "RemoteNotifySteerableChangedRequest" + }, + "result": { + "$ref": "#/definitions/RemoteNotifySteerableChangedResult", + "description": "Persist a steerability change as a `session.remote_steerable_changed` event. Used by the host (CLI / SDK consumer) when it has just finished enabling or disabling steering on a remote exporter that the runtime does not directly own." + }, + "stability": "experimental" + } + }, + "schedule": { + "list": { + "rpcMethod": "session.schedule.list", + "description": "Lists the session's currently active scheduled prompts.", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/ScheduleList", + "description": "Snapshot of the currently active recurring prompts for this session." + }, + "stability": "experimental" + }, + "stop": { + "rpcMethod": "session.schedule.stop", + "description": "Removes a scheduled prompt by id.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "id": { + "type": "integer", + "exclusiveMinimum": true, + "minimum": 0, + "description": "Id of the scheduled prompt to remove." + } + }, + "required": [ + "sessionId", + "id" + ], + "additionalProperties": false, + "description": "Identifier of the scheduled prompt to remove.", + "title": "ScheduleStopRequest" + }, + "result": { + "$ref": "#/definitions/ScheduleStopResult", + "description": "Remove a scheduled prompt by id. The result entry is omitted if the id was unknown." + }, + "stability": "experimental" + } + } + }, + "clientSession": { + "sessionFs": { + "readFile": { + "rpcMethod": "sessionFs.readFile", + "description": "Reads a file from the client-provided session filesystem.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "path": { + "type": "string", + "description": "Path using SessionFs conventions" + } + }, + "required": [ + "sessionId", + "path" + ], + "additionalProperties": false, + "description": "Path of the file to read from the client-provided session filesystem.", + "title": "SessionFsReadFileRequest" + }, + "result": { + "$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": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "path": { + "type": "string", + "description": "Path using SessionFs conventions" + }, + "content": { + "type": "string", + "description": "Content to write" + }, + "mode": { + "type": "integer", + "minimum": 0, + "description": "Optional POSIX-style mode for newly created files" + } + }, + "required": [ + "sessionId", + "path", + "content" + ], + "additionalProperties": false, + "description": "File path, content to write, and optional mode for the client-provided session filesystem.", + "title": "SessionFsWriteFileRequest" + }, + "result": { + "anyOf": [ + { + "not": {} + }, + { + "$ref": "#/definitions/SessionFsError", + "description": "Describes a filesystem error." + } + ], + "description": "Describes a filesystem error." + } + }, + "appendFile": { + "rpcMethod": "sessionFs.appendFile", + "description": "Appends content to a file in the client-provided session filesystem.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "path": { + "type": "string", + "description": "Path using SessionFs conventions" + }, + "content": { + "type": "string", + "description": "Content to append" + }, + "mode": { + "type": "integer", + "minimum": 0, + "description": "Optional POSIX-style mode for newly created files" + } + }, + "required": [ + "sessionId", + "path", + "content" + ], + "additionalProperties": false, + "description": "File path, content to append, and optional mode for the client-provided session filesystem.", + "title": "SessionFsAppendFileRequest" + }, + "result": { + "anyOf": [ + { + "not": {} + }, + { + "$ref": "#/definitions/SessionFsError", + "description": "Describes a filesystem error." + } + ], + "description": "Describes a filesystem error." + } + }, + "exists": { + "rpcMethod": "sessionFs.exists", + "description": "Checks whether a path exists in the client-provided session filesystem.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "path": { + "type": "string", + "description": "Path using SessionFs conventions" + } + }, + "required": [ + "sessionId", + "path" + ], + "additionalProperties": false, + "description": "Path to test for existence in the client-provided session filesystem.", + "title": "SessionFsExistsRequest" + }, + "result": { + "$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": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "path": { + "type": "string", + "description": "Path using SessionFs conventions" + } + }, + "required": [ + "sessionId", + "path" + ], + "additionalProperties": false, + "description": "Path whose metadata should be returned from the client-provided session filesystem.", + "title": "SessionFsStatRequest" + }, + "result": { + "$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": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "path": { + "type": "string", + "description": "Path using SessionFs conventions" + }, + "recursive": { + "type": "boolean", + "description": "Create parent directories as needed" + }, + "mode": { + "type": "integer", + "minimum": 0, + "description": "Optional POSIX-style mode for newly created directories" + } + }, + "required": [ + "sessionId", + "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": { + "anyOf": [ + { + "not": {} + }, + { + "$ref": "#/definitions/SessionFsError", + "description": "Describes a filesystem error." + } + ], + "description": "Describes a filesystem error." + } + }, + "readdir": { + "rpcMethod": "sessionFs.readdir", + "description": "Lists entry names in a directory from the client-provided session filesystem.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "path": { + "type": "string", + "description": "Path using SessionFs conventions" + } + }, + "required": [ + "sessionId", + "path" + ], + "additionalProperties": false, + "description": "Directory path whose entries should be listed from the client-provided session filesystem.", + "title": "SessionFsReaddirRequest" + }, + "result": { + "$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": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "path": { + "type": "string", + "description": "Path using SessionFs conventions" + } + }, + "required": [ + "sessionId", + "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", + "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": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "path": { + "type": "string", + "description": "Path using SessionFs conventions" + }, + "recursive": { + "type": "boolean", + "description": "Remove directories and their contents recursively" + }, + "force": { + "type": "boolean", + "description": "Ignore errors if the path does not exist" + } + }, + "required": [ + "sessionId", + "path" + ], + "additionalProperties": false, + "description": "Path to remove from the client-provided session filesystem, with options for recursive removal and force.", + "title": "SessionFsRmRequest" + }, + "result": { + "anyOf": [ + { + "not": {} + }, + { + "$ref": "#/definitions/SessionFsError", + "description": "Describes a filesystem error." + } + ], + "description": "Describes a filesystem error." + } + }, + "rename": { + "rpcMethod": "sessionFs.rename", + "description": "Renames or moves a path in the client-provided session filesystem.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "src": { + "type": "string", + "description": "Source path using SessionFs conventions" + }, + "dest": { + "type": "string", + "description": "Destination path using SessionFs conventions" + } + }, + "required": [ + "sessionId", + "src", + "dest" + ], + "additionalProperties": false, + "description": "Source and destination paths for renaming or moving an entry in the client-provided session filesystem.", + "title": "SessionFsRenameRequest" + }, + "result": { + "anyOf": [ + { + "not": {} + }, + { + "$ref": "#/definitions/SessionFsError", + "description": "Describes a filesystem error." + } + ], + "description": "Describes a filesystem error." + } + }, + "sqliteQuery": { + "rpcMethod": "sessionFs.sqliteQuery", + "description": "Executes a SQLite query against the per-session database.", + "params": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + }, + "query": { + "type": "string", + "description": "SQL query to execute" + }, + "queryType": { + "$ref": "#/definitions/SessionFsSqliteQueryType", + "description": "How to execute the query: 'exec' for DDL/multi-statement (no results), 'query' for SELECT (returns rows), 'run' for INSERT/UPDATE/DELETE (returns rowsAffected)" + }, + "params": { + "type": "object", + "additionalProperties": { + "type": [ + "string", + "number", + "null" + ] + }, + "description": "Optional named bind parameters" + } + }, + "required": [ + "sessionId", + "query", + "queryType" + ], + "additionalProperties": false, + "description": "SQL query, query type, and optional bind parameters for executing a SQLite query against the per-session database.", + "title": "SessionFsSqliteQueryRequest" + }, + "result": { + "$ref": "#/definitions/SessionFsSqliteQueryResult", + "description": "Query results including rows, columns, and rows affected, or a filesystem error if execution failed." + } + }, + "sqliteExists": { + "rpcMethod": "sessionFs.sqliteExists", + "description": "Checks whether the per-session SQLite database already exists, without creating it.", + "params": { + "type": "object", + "description": "Identifies the target session.", + "properties": { + "sessionId": { + "type": "string", + "description": "Target session identifier" + } + }, + "required": [ + "sessionId" + ], + "additionalProperties": false + }, + "result": { + "$ref": "#/definitions/SessionFsSqliteExistsResult", + "description": "Indicates whether the per-session SQLite database already exists." + } + } + } + }, + "definitions": { + "AbortReason": { + "type": "string", + "enum": [ + "user_initiated", + "remote_command", + "user_abort" + ], + "description": "Finite reason code describing why the current turn was aborted", + "title": "AbortReason", + "x-enumDescriptions": { + "user_initiated": "The local user requested the abort, for example by pressing Ctrl+C in the CLI.", + "remote_command": "A remote command requested the abort.", + "user_abort": "An MCP server delivered a user.abort notification." + } + }, + "AbortRequest": { + "type": "object", + "properties": { + "reason": { + "$ref": "#/definitions/AbortReason", + "description": "Finite reason code describing why the current turn was aborted" + } + }, + "additionalProperties": false, + "description": "Parameters for aborting the current turn", + "title": "AbortRequest" + }, + "AbortResult": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Whether the abort completed successfully" + }, + "error": { + "type": "string", + "description": "Error message if the abort failed" + } + }, + "required": [ + "success" + ], + "additionalProperties": false, + "description": "Result of aborting the current turn", + "title": "AbortResult" + }, + "AccountGetQuotaRequest": { + "anyOf": [ + { + "not": {} + }, + { + "type": "object", + "properties": { + "gitHubToken": { + "type": "string", + "description": "GitHub token for per-user quota lookup. When provided, resolves this token to determine the user's quota instead of using the global auth." + } + }, + "additionalProperties": false + } + ], + "description": "Optional GitHub token used to look up quota for a specific user instead of the global auth context.", + "title": "AccountGetQuotaRequest" + }, + "AccountGetQuotaResult": { + "type": "object", + "properties": { + "quotaSnapshots": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/AccountQuotaSnapshot" + }, + "description": "Quota snapshots keyed by type (e.g., chat, completions, premium_interactions)" + } + }, + "required": [ + "quotaSnapshots" + ], + "additionalProperties": false, + "description": "Quota usage snapshots for the resolved user, keyed by quota type.", + "title": "AccountGetQuotaResult" + }, + "AccountQuotaSnapshot": { + "type": "object", + "properties": { + "isUnlimitedEntitlement": { + "type": "boolean", + "description": "Whether the user has an unlimited usage entitlement" + }, + "entitlementRequests": { + "type": "integer", + "minimum": -1, + "description": "Number of requests included in the entitlement, or -1 for unlimited entitlements" + }, + "usedRequests": { + "type": "integer", + "minimum": 0, + "description": "Number of requests used so far this period" + }, + "usageAllowedWithExhaustedQuota": { + "type": "boolean", + "description": "Whether usage is still permitted after quota exhaustion" + }, + "remainingPercentage": { + "type": "number", + "description": "Percentage of entitlement remaining" + }, + "overage": { + "type": "number", + "minimum": 0, + "description": "Number of overage requests made this period" + }, + "overageAllowedWithExhaustedQuota": { + "type": "boolean", + "description": "Whether overage is allowed when quota is exhausted" + }, + "resetDate": { + "type": "string", + "format": "date-time", + "description": "Date when the quota resets (ISO 8601 string)" + } + }, + "required": [ + "isUnlimitedEntitlement", + "entitlementRequests", + "usedRequests", + "usageAllowedWithExhaustedQuota", + "remainingPercentage", + "overage", + "overageAllowedWithExhaustedQuota" + ], + "additionalProperties": false, + "title": "AccountQuotaSnapshot", + "description": "Schema for the `AccountQuotaSnapshot` type." + }, + "AgentGetCurrentResult": { + "type": "object", + "properties": { + "agent": { + "$ref": "#/definitions/AgentInfo", + "description": "Currently selected custom agent, or null if using the default agent" + } + }, + "required": [ + "agent" + ], + "additionalProperties": false, + "description": "The currently selected custom agent, or null when using the default agent.", + "title": "AgentGetCurrentResult" + }, + "AgentInfo": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Unique identifier of the custom agent" + }, + "displayName": { + "type": "string", + "description": "Human-readable display name" + }, + "description": { + "type": "string", + "description": "Description of the agent's purpose" + }, + "path": { + "type": "string", + "description": "Absolute local file path of the agent definition. Only set for file-based agents loaded from disk; remote agents do not have a path." + }, + "id": { + "type": "string", + "description": "Stable identifier for selection. For most agents this is the same as `name`; for plugin/builtin agents it may differ. Always populated; defaults to `name` when no distinct id was assigned." + }, + "source": { + "$ref": "#/definitions/AgentInfoSource", + "description": "Where the agent definition was loaded from" + }, + "userInvocable": { + "type": "boolean", + "description": "Whether the agent can be selected directly by the user. Agents marked `false` are subagent-only." + }, + "tools": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Allowed tool names for this agent. Empty array means none; omitted means inherit defaults." + }, + "model": { + "type": "string", + "description": "Preferred model id for this agent. When omitted, inherits the outer agent's model." + }, + "mcpServers": { + "type": "object", + "additionalProperties": {}, + "description": "MCP server configurations attached to this agent, keyed by server name. Server config shape mirrors the MCP `mcpServers` schema." + }, + "skills": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Skill names preloaded into this agent's context. Omitted means none." + } + }, + "required": [ + "name", + "displayName", + "description", + "id" + ], + "additionalProperties": false, + "title": "AgentInfo", + "description": "Schema for the `AgentInfo` type." + }, + "AgentInfoSource": { + "type": "string", + "enum": [ + "user", + "project", + "inherited", + "remote", + "plugin", + "builtin" + ], + "description": "Where the agent definition was loaded from", + "title": "AgentInfoSource", + "x-enumDescriptions": { + "user": "Agent loaded from the user's personal agent configuration.", + "project": "Agent loaded from the current project's repository configuration.", + "inherited": "Agent inherited from a parent project or workspace.", + "remote": "Agent provided by a remote runtime or service.", + "plugin": "Agent contributed by an installed plugin.", + "builtin": "Agent built into the Copilot runtime." + } + }, + "AgentList": { + "type": "object", + "properties": { + "agents": { + "type": "array", + "items": { + "$ref": "#/definitions/AgentInfo" + }, + "description": "Available custom agents" + } + }, + "required": [ + "agents" + ], + "additionalProperties": false, + "description": "Custom agents available to the session.", + "title": "AgentList" + }, + "AgentReloadResult": { + "type": "object", + "properties": { + "agents": { + "type": "array", + "items": { + "$ref": "#/definitions/AgentInfo" + }, + "description": "Reloaded custom agents" + } + }, + "required": [ + "agents" + ], + "additionalProperties": false, + "description": "Custom agents available to the session after reloading definitions from disk.", + "title": "AgentReloadResult" + }, + "AgentSelectRequest": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the custom agent to select" + } + }, + "required": [ + "name" + ], + "additionalProperties": false, + "description": "Name of the custom agent to select for subsequent turns.", + "title": "AgentSelectRequest" + }, + "AgentSelectResult": { + "type": "object", + "properties": { + "agent": { + "$ref": "#/definitions/AgentInfo", + "description": "The newly selected custom agent" + } + }, + "required": [ + "agent" + ], + "additionalProperties": false, + "description": "The newly selected custom agent.", + "title": "AgentSelectResult" + }, + "ApiKeyAuthInfo": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "api-key", + "description": "API-key authentication for non-GitHub LLM providers (e.g. when running BYOM-style)." + }, + "apiKey": { + "type": "string", + "description": "The API key. Treat as a secret." + }, + "host": { + "type": "string", + "description": "Authentication host." + }, + "copilotUser": { + "$ref": "#/definitions/CopilotUserResponse", + "description": "Snapshot of the authenticated user's Copilot subscription info, if known. Mirrors the GitHub API `/copilot_internal/v2/token` user response shape — the runtime trusts this verbatim and does not re-fetch when set." + } + }, + "required": [ + "type", + "apiKey", + "host" + ], + "additionalProperties": false, + "title": "ApiKeyAuthInfo", + "description": "Schema for the `ApiKeyAuthInfo` type." + }, + "AuthInfo": { + "anyOf": [ + { + "$ref": "#/definitions/HMACAuthInfo" + }, + { + "$ref": "#/definitions/EnvAuthInfo" + }, + { + "$ref": "#/definitions/TokenAuthInfo" + }, + { + "$ref": "#/definitions/CopilotApiTokenAuthInfo" + }, + { + "$ref": "#/definitions/UserAuthInfo" + }, + { + "$ref": "#/definitions/GhCliAuthInfo" + }, + { + "$ref": "#/definitions/ApiKeyAuthInfo" + } + ], + "description": "The new auth credentials to install on the session. When omitted or `undefined`, the call is a no-op and the session's existing credentials are preserved. The runtime stores the value verbatim and uses it for outbound model/API requests; it does NOT re-validate or re-fetch the associated Copilot user response. Several variants carry secret material; treat this method's params as containing secrets at rest and in transit.", + "title": "AuthInfo" + }, + "AuthInfoType": { + "type": "string", + "enum": [ + "hmac", + "env", + "user", + "gh-cli", + "api-key", + "token", + "copilot-api-token" + ], + "description": "Authentication type", + "title": "AuthInfoType", + "x-enumDescriptions": { + "hmac": "Authentication provided by a GitHub App HMAC credential.", + "env": "Authentication resolved from environment-provided credentials.", + "user": "Authentication from an interactive user sign-in.", + "gh-cli": "Authentication delegated to the GitHub CLI.", + "api-key": "Authentication from an API key credential.", + "token": "Authentication from a GitHub token.", + "copilot-api-token": "Authentication from a Copilot API token." + } + }, + "CommandList": { + "type": "object", + "properties": { + "commands": { + "type": "array", + "items": { + "$ref": "#/definitions/SlashCommandInfo" + }, + "description": "Commands available in this session" + } + }, + "required": [ + "commands" + ], + "additionalProperties": false, + "description": "Slash commands available in the session, after applying any include/exclude filters.", + "title": "CommandList" + }, + "CommandsHandlePendingCommandRequest": { + "type": "object", + "properties": { + "requestId": { + "type": "string", + "description": "Request ID from the command invocation event" + }, + "error": { + "type": "string", + "description": "Error message if the command handler failed" + } + }, + "required": [ + "requestId" + ], + "additionalProperties": false, + "description": "Pending command request ID and an optional error if the client handler failed.", + "title": "CommandsHandlePendingCommandRequest" + }, + "CommandsHandlePendingCommandResult": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Whether the command was handled successfully" + } + }, + "required": [ + "success" + ], + "additionalProperties": false, + "description": "Indicates whether the pending client-handled command was completed successfully.", + "title": "CommandsHandlePendingCommandResult" + }, + "CommandsInvokeRequest": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Command name. Leading slashes are stripped and the name is matched case-insensitively." + }, + "input": { + "type": "string", + "description": "Raw input after the command name" + } + }, + "required": [ + "name" + ], + "additionalProperties": false, + "description": "Slash command name and optional raw input string to invoke.", + "title": "CommandsInvokeRequest" + }, + "CommandsListRequest": { + "anyOf": [ + { + "not": {} + }, + { + "type": "object", + "properties": { + "includeBuiltins": { + "type": "boolean", + "description": "Include runtime built-in commands" + }, + "includeSkills": { + "type": "boolean", + "description": "Include enabled user-invocable skills and commands" + }, + "includeClientCommands": { + "type": "boolean", + "description": "Include commands registered by protocol clients, including SDK clients and extensions" + } + }, + "additionalProperties": false + } + ], + "description": "Optional filters controlling which command sources to include in the listing.", + "title": "CommandsListRequest" + }, + "CommandsRespondToQueuedCommandRequest": { + "type": "object", + "properties": { + "requestId": { + "type": "string", + "description": "Request ID from the `command.queued` event the host is responding to." + }, + "result": { + "$ref": "#/definitions/QueuedCommandResult", + "description": "Result of the queued command execution." + } + }, + "required": [ + "requestId", + "result" + ], + "additionalProperties": false, + "description": "Queued-command request ID and the result indicating whether the host executed it (and whether to stop processing further queued commands).", + "title": "CommandsRespondToQueuedCommandRequest" + }, + "CommandsRespondToQueuedCommandResult": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Whether a pending queued command with the given request ID was found and resolved. False when the request was already resolved, cancelled, or unknown." + } + }, + "required": [ + "success" + ], + "additionalProperties": false, + "description": "Indicates whether the queued-command response was matched to a pending request.", + "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", + "format": "date-time", + "description": "Session start time as an ISO 8601 string." + }, + "modifiedTime": { + "type": "string", + "format": "date-time", + "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", + "exclusiveMinimum": true, + "minimum": 0, + "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", + "format": "date-time", + "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", + "x-enumDescriptions": { + "remote-session": "Remote CLI session.", + "coding-agent": "GitHub Copilot coding agent session." + } + }, + "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": { + "token": { + "type": "string", + "description": "Connection token; required when the server was started with COPILOT_CONNECTION_TOKEN" + } + }, + "additionalProperties": false, + "description": "Optional connection token presented by the SDK client during the handshake.", + "title": "ConnectRequest", + "visibility": "internal" + }, + "ConnectResult": { + "type": "object", + "properties": { + "ok": { + "type": "boolean", + "const": true, + "description": "Always true on success" + }, + "protocolVersion": { + "type": "integer", + "exclusiveMinimum": true, + "minimum": 0, + "description": "Server protocol version number" + }, + "version": { + "type": "string", + "description": "Server package version" + } + }, + "required": [ + "ok", + "protocolVersion", + "version" + ], + "additionalProperties": false, + "description": "Handshake result reporting the server's protocol version and package version on success.", + "title": "ConnectResult", + "visibility": "internal" + }, + "ContentFilterMode": { + "type": "string", + "enum": [ + "none", + "markdown", + "hidden_characters" + ], + "description": "Controls how MCP tool result content is filtered: none leaves content unchanged, markdown sanitizes HTML while preserving Markdown-friendly output, and hidden_characters removes characters that can hide directives.", + "title": "ContentFilterMode", + "x-enumDescriptions": { + "none": "Leave MCP tool result content unchanged.", + "markdown": "Sanitize HTML while preserving Markdown-friendly output.", + "hidden_characters": "Remove characters that can hide directives." + } + }, + "CopilotApiTokenAuthInfo": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "copilot-api-token", + "description": "Direct Copilot API authentication via the `GITHUB_COPILOT_API_TOKEN` + `COPILOT_API_URL` environment-variable pair. The token itself is read from the environment by the runtime, not carried in this struct." + }, + "host": { + "type": "string", + "const": "https://github.com", + "description": "Authentication host (always the public GitHub host)." + }, + "copilotUser": { + "$ref": "#/definitions/CopilotUserResponse", + "description": "Snapshot of the authenticated user's Copilot subscription info, if known. Mirrors the GitHub API `/copilot_internal/v2/token` user response shape — the runtime trusts this verbatim and does not re-fetch when set." + } + }, + "required": [ + "type", + "host" + ], + "additionalProperties": false, + "title": "CopilotApiTokenAuthInfo", + "description": "Schema for the `CopilotApiTokenAuthInfo` type." + }, + "CopilotUserResponse": { + "type": "object", + "properties": { + "login": { + "type": "string" + }, + "access_type_sku": { + "type": "string" + }, + "analytics_tracking_id": { + "type": "string" + }, + "assigned_date": { + "anyOf": [ + { + "anyOf": [ + { + "not": {} + }, + { + "type": "string" + } + ] + }, + { + "type": "null" + } + ] + }, + "can_signup_for_limited": { + "type": "boolean" + }, + "chat_enabled": { + "type": "boolean" + }, + "copilot_plan": { + "type": "string" + }, + "copilotignore_enabled": { + "type": "boolean" + }, + "endpoints": { + "$ref": "#/definitions/CopilotUserResponseEndpoints", + "description": "Schema for the `CopilotUserResponseEndpoints` type." + }, + "organization_login_list": { + "type": "array", + "items": { + "type": "string" + } + }, + "organization_list": { + "anyOf": [ + { + "anyOf": [ + { + "not": {} + }, + { + "type": "array", + "items": { + "anyOf": [ + { + "type": "object", + "properties": { + "login": { + "anyOf": [ + { + "anyOf": [ + { + "not": {} + }, + { + "type": "string" + } + ] + }, + { + "type": "null" + } + ] + }, + "name": { + "anyOf": [ + { + "anyOf": [ + { + "not": {} + }, + { + "type": "string" + } + ] + }, + { + "type": "null" + } + ] + } + }, + "additionalProperties": false + }, + { + "type": "null" + } + ] + } + } + ] + }, + { + "type": "null" + } + ] + }, + "codex_agent_enabled": { + "type": "boolean" + }, + "is_mcp_enabled": { + "anyOf": [ + { + "anyOf": [ + { + "not": {} + }, + { + "type": "boolean" + } + ] + }, + { + "type": "null" + } + ] + }, + "quota_reset_date": { + "type": "string" + }, + "quota_snapshots": { + "$ref": "#/definitions/CopilotUserResponseQuotaSnapshots", + "description": "Schema for the `CopilotUserResponseQuotaSnapshots` type." + }, + "restricted_telemetry": { + "type": "boolean" + }, + "token_based_billing": { + "type": "boolean" + }, + "quota_reset_date_utc": { + "type": "string" + }, + "limited_user_quotas": { + "type": "object", + "additionalProperties": { + "type": "number" + } + }, + "limited_user_reset_date": { + "type": "string" + }, + "monthly_quotas": { + "type": "object", + "additionalProperties": { + "type": "number" + } + }, + "cloud_session_storage_enabled": { + "type": "boolean" + }, + "cli_remote_control_enabled": { + "type": "boolean" + } + }, + "additionalProperties": false, + "description": "Snapshot of the authenticated user's Copilot subscription info, if known. Mirrors the GitHub API `/copilot_internal/v2/token` user response shape — the runtime trusts this verbatim and does not re-fetch when set.", + "title": "CopilotUserResponse" + }, + "CopilotUserResponseEndpoints": { + "type": "object", + "properties": { + "api": { + "type": "string" + }, + "origin-tracker": { + "type": "string" + }, + "proxy": { + "type": "string" + }, + "telemetry": { + "type": "string" + } + }, + "additionalProperties": false, + "title": "CopilotUserResponseEndpoints", + "description": "Schema for the `CopilotUserResponseEndpoints` type." + }, + "CopilotUserResponseQuotaSnapshots": { + "type": "object", + "properties": { + "chat": { + "$ref": "#/definitions/CopilotUserResponseQuotaSnapshotsChat", + "description": "Schema for the `CopilotUserResponseQuotaSnapshotsChat` type." + }, + "completions": { + "$ref": "#/definitions/CopilotUserResponseQuotaSnapshotsCompletions", + "description": "Schema for the `CopilotUserResponseQuotaSnapshotsCompletions` type." + }, + "premium_interactions": { + "$ref": "#/definitions/CopilotUserResponseQuotaSnapshotsPremiumInteractions", + "description": "Schema for the `CopilotUserResponseQuotaSnapshotsPremiumInteractions` type." + } + }, + "additionalProperties": { + "anyOf": [ + { + "type": "object", + "properties": { + "entitlement": { + "type": "number" + }, + "overage_count": { + "type": "number" + }, + "overage_permitted": { + "type": "boolean" + }, + "percent_remaining": { + "type": "number" + }, + "quota_id": { + "type": "string" + }, + "quota_remaining": { + "type": "number" + }, + "remaining": { + "type": "number" + }, + "unlimited": { + "type": "boolean" + }, + "timestamp_utc": { + "type": "string" + }, + "has_quota": { + "type": "boolean" + }, + "quota_reset_at": { + "type": "number" + }, + "token_based_billing": { + "type": "boolean" + } + }, + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, + "title": "CopilotUserResponseQuotaSnapshots", + "description": "Schema for the `CopilotUserResponseQuotaSnapshots` type." + }, + "CopilotUserResponseQuotaSnapshotsChat": { + "type": "object", + "properties": { + "entitlement": { + "type": "number" + }, + "overage_count": { + "type": "number" + }, + "overage_permitted": { + "type": "boolean" + }, + "percent_remaining": { + "type": "number" + }, + "quota_id": { + "type": "string" + }, + "quota_remaining": { + "type": "number" + }, + "remaining": { + "type": "number" + }, + "unlimited": { + "type": "boolean" + }, + "timestamp_utc": { + "type": "string" + }, + "has_quota": { + "type": "boolean" + }, + "quota_reset_at": { + "type": "number" + }, + "token_based_billing": { + "type": "boolean" + } + }, + "additionalProperties": false, + "title": "CopilotUserResponseQuotaSnapshotsChat", + "description": "Schema for the `CopilotUserResponseQuotaSnapshotsChat` type." + }, + "CopilotUserResponseQuotaSnapshotsCompletions": { + "type": "object", + "properties": { + "entitlement": { + "type": "number" + }, + "overage_count": { + "type": "number" + }, + "overage_permitted": { + "type": "boolean" + }, + "percent_remaining": { + "type": "number" + }, + "quota_id": { + "type": "string" + }, + "quota_remaining": { + "type": "number" + }, + "remaining": { + "type": "number" + }, + "unlimited": { + "type": "boolean" + }, + "timestamp_utc": { + "type": "string" + }, + "has_quota": { + "type": "boolean" + }, + "quota_reset_at": { + "type": "number" + }, + "token_based_billing": { + "type": "boolean" + } + }, + "additionalProperties": false, + "title": "CopilotUserResponseQuotaSnapshotsCompletions", + "description": "Schema for the `CopilotUserResponseQuotaSnapshotsCompletions` type." + }, + "CopilotUserResponseQuotaSnapshotsPremiumInteractions": { + "type": "object", + "properties": { + "entitlement": { + "type": "number" + }, + "overage_count": { + "type": "number" + }, + "overage_permitted": { + "type": "boolean" + }, + "percent_remaining": { + "type": "number" + }, + "quota_id": { + "type": "string" + }, + "quota_remaining": { + "type": "number" + }, + "remaining": { + "type": "number" + }, + "unlimited": { + "type": "boolean" + }, + "timestamp_utc": { + "type": "string" + }, + "has_quota": { + "type": "boolean" + }, + "quota_reset_at": { + "type": "number" + }, + "token_based_billing": { + "type": "boolean" + } + }, + "additionalProperties": false, + "title": "CopilotUserResponseQuotaSnapshotsPremiumInteractions", + "description": "Schema for the `CopilotUserResponseQuotaSnapshotsPremiumInteractions` type." + }, + "CurrentModel": { + "type": "object", + "properties": { + "modelId": { + "type": "string", + "description": "Currently active model identifier" + }, + "reasoningEffort": { + "type": "string", + "description": "Reasoning effort level currently applied to the active model, when one is set. Reads `Session.getReasoningEffort()` synchronously after `getSelectedModel()` resolves so the two values are reported as a snapshot." + } + }, + "additionalProperties": false, + "description": "The currently selected model and reasoning effort for the session.", + "title": "CurrentModel" + }, + "DiscoveredMcpServer": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", + "description": "Server name (config key)" + }, + "type": { + "$ref": "#/definitions/DiscoveredMcpServerType", + "description": "Server transport type: stdio, http, sse, or memory" + }, + "source": { + "$ref": "#/definitions/McpServerSource", + "description": "Configuration source: user, workspace, plugin, or builtin" + }, + "enabled": { + "type": "boolean", + "description": "Whether the server is enabled (not in the disabled list)" + } + }, + "required": [ + "name", + "source", + "enabled" + ], + "additionalProperties": false, + "title": "DiscoveredMcpServer", + "description": "Schema for the `DiscoveredMcpServer` type." + }, + "DiscoveredMcpServerType": { + "type": "string", + "enum": [ + "stdio", + "http", + "sse", + "memory" + ], + "description": "Server transport type: stdio, http, sse, or memory", + "title": "DiscoveredMcpServerType", + "x-enumDescriptions": { + "stdio": "Server communicates over stdio with a local child process.", + "http": "Server communicates over streamable HTTP.", + "sse": "Server communicates over Server-Sent Events.", + "memory": "Server is backed by an in-memory runtime implementation." + } + }, + "EmbeddedBlobResourceContents": { + "type": "object", + "properties": { + "uri": { + "type": "string", + "format": "uri", + "description": "URI identifying the resource" + }, + "mimeType": { + "type": "string", + "description": "MIME type of the blob content" + }, + "blob": { + "type": "string", + "description": "Base64-encoded binary content of the resource", + "contentEncoding": "base64" + } + }, + "required": [ + "uri", + "blob" + ], + "additionalProperties": false, + "title": "EmbeddedBlobResourceContents", + "description": "Schema for the `EmbeddedBlobResourceContents` type." + }, + "EmbeddedTextResourceContents": { + "type": "object", + "properties": { + "uri": { + "type": "string", + "format": "uri", + "description": "URI identifying the resource" + }, + "mimeType": { + "type": "string", + "description": "MIME type of the text content" + }, + "text": { + "type": "string", + "description": "Text content of the resource" + } + }, + "required": [ + "uri", + "text" + ], + "additionalProperties": false, + "title": "EmbeddedTextResourceContents", + "description": "Schema for the `EmbeddedTextResourceContents` type." + }, + "EnqueueCommandParams": { + "type": "object", + "properties": { + "command": { + "type": "string", + "description": "Slash-prefixed command string to enqueue, e.g. '/compact' or '/model gpt-4'. Queued FIFO with any in-flight items; if the session is idle, processing kicks off immediately." + } + }, + "required": [ + "command" + ], + "additionalProperties": false, + "description": "Slash-prefixed command string to enqueue for FIFO processing.", + "title": "EnqueueCommandParams" + }, + "EnqueueCommandResult": { + "type": "object", + "properties": { + "queued": { + "type": "boolean", + "description": "True when the command was accepted into the local execution queue. False when the call targets a session that does not support local command queueing (e.g. remote sessions)." + } + }, + "required": [ + "queued" + ], + "additionalProperties": false, + "description": "Indicates whether the command was accepted into the local execution queue.", + "title": "EnqueueCommandResult" + }, + "EnvAuthInfo": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "env", + "description": "Personal access token (PAT) or server-to-server token sourced from an environment variable." + }, + "host": { + "type": "string", + "description": "Authentication host (e.g. https://github.com or a GHES host)." + }, + "login": { + "type": "string", + "description": "User login associated with the token. Undefined for server-to-server tokens (those starting with `ghs_`)." + }, + "token": { + "type": "string", + "description": "The token value itself. Treat as a secret." + }, + "envVar": { + "type": "string", + "description": "Name of the environment variable the token was sourced from." + }, + "copilotUser": { + "$ref": "#/definitions/CopilotUserResponse", + "description": "Snapshot of the authenticated user's Copilot subscription info, if known. Mirrors the GitHub API `/copilot_internal/v2/token` user response shape — the runtime trusts this verbatim and does not re-fetch when set." + } + }, + "required": [ + "type", + "host", + "token", + "envVar" + ], + "additionalProperties": false, + "title": "EnvAuthInfo", + "description": "Schema for the `EnvAuthInfo` type." + }, + "EventLogReadRequest": { + "type": "object", + "properties": { + "cursor": { + "type": "string", + "description": "Opaque cursor returned by a previous read. Omit on the first call to start from the beginning of the session's persisted history." + }, + "max": { + "type": "integer", + "exclusiveMinimum": true, + "minimum": 0, + "maximum": 1000, + "description": "Maximum number of events to return in this batch (1–1000, default 200)." + }, + "waitMs": { + "type": "integer", + "minimum": 0, + "maximum": 30000, + "description": "Milliseconds to wait for new events when the cursor is at the tail of history. 0 (default) returns immediately even if no events are available. Capped at 30000ms. Ephemeral events that arrive during the wait are delivered in this batch but are NOT replayable on a subsequent read (use a non-zero waitMs in your next call to capture future ephemerals as they happen).", + "format": "duration" + }, + "types": { + "$ref": "#/definitions/EventLogTypes", + "description": "Either '*' to receive all event types, or a non-empty list of event types to receive" + }, + "agentScope": { + "$ref": "#/definitions/EventsAgentScope", + "description": "Agent-scope filter: 'primary' returns only main-agent events plus events whose type starts with 'subagent.' (matching the typed-subscription default behavior); 'all' returns events from all agents (matching wildcard-subscription behavior). Default is 'all' to preserve wildcard semantics for catch-up callers." + } + }, + "additionalProperties": false, + "description": "Cursor, batch size, and optional long-poll/filter parameters for reading session events.", + "title": "EventLogReadRequest" + }, + "EventLogReleaseInterestResult": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Whether the operation succeeded" + } + }, + "required": [ + "success" + ], + "additionalProperties": false, + "description": "Indicates whether the operation succeeded.", + "title": "EventLogReleaseInterestResult" + }, + "EventLogTailResult": { + "type": "object", + "properties": { + "cursor": { + "type": "string", + "description": "Opaque cursor pointing at the current tail of the session's persisted-events history. Pass back to `read` to receive only events that arrive AFTER this snapshot. When the session has no events, this returns the same sentinel as an unset cursor (i.e. equivalent to omitting the cursor on a first read)." + } + }, + "required": [ + "cursor" + ], + "additionalProperties": false, + "description": "Snapshot of the current tail cursor without returning any events. Use this when a consumer wants to subscribe to live events going forward without first paginating through the entire persisted history (which would happen if `read` were called without a cursor on a long-lived session).", + "title": "EventLogTailResult" + }, + "EventLogTypes": { + "anyOf": [ + { + "type": "string", + "const": "*" + }, + { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1 + } + ], + "description": "Either '*' to receive all event types, or a non-empty list of event types to receive", + "title": "EventLogTypes" + }, + "EventsAgentScope": { + "type": "string", + "enum": [ + "primary", + "all" + ], + "description": "Agent-scope filter: 'primary' returns only main-agent events plus events whose type starts with 'subagent.' (matching the typed-subscription default behavior); 'all' returns events from all agents (matching wildcard-subscription behavior). Default is 'all' to preserve wildcard semantics for catch-up callers.", + "title": "EventsAgentScope", + "x-enumDescriptions": { + "primary": "Return main-agent events and typed subagent lifecycle events.", + "all": "Return events from all agents." + } + }, + "EventsCursorStatus": { + "type": "string", + "enum": [ + "ok", + "expired" + ], + "description": "Cursor status: 'ok' means the cursor was applied successfully; 'expired' means the cursor referred to an event that no longer exists in history (e.g. truncated or compacted away) and the read started from the beginning of the remaining history.", + "title": "EventsCursorStatus", + "x-enumDescriptions": { + "ok": "The cursor was applied successfully.", + "expired": "The cursor referred to history that is no longer available." + } + }, + "EventsReadResult": { + "type": "object", + "properties": { + "events": { + "type": "array", + "items": { + "$ref": "session-events.schema.json#/definitions/SessionEvent" + }, + "description": "Events are delivered in two batches per read: persisted events first (in append order), then ephemeral events (in seq order). When `waitMs > 0` and the catch-up batches were empty, post-wait events follow the same two-batch ordering. Persisted and ephemeral events do not interleave within a single read." + }, + "cursor": { + "type": "string", + "description": "Opaque cursor for the next read. Pass back unchanged in the next read.cursor to continue from where this read left off. Always present, even when no events were returned." + }, + "hasMore": { + "type": "boolean", + "description": "True when the read returned `max` events and more events are available immediately. When false, the next read with a non-zero `waitMs` will block until a new event arrives or the wait expires." + }, + "cursorStatus": { + "$ref": "#/definitions/EventsCursorStatus", + "description": "Cursor status: 'ok' means the cursor was applied successfully; 'expired' means the cursor referred to an event that no longer exists in history (e.g. truncated or compacted away) and the read started from the beginning of the remaining history." + } + }, + "required": [ + "events", + "cursor", + "hasMore", + "cursorStatus" + ], + "additionalProperties": false, + "description": "Batch of session events returned by a read, with cursor and continuation metadata.", + "title": "EventsReadResult" + }, + "ExecuteCommandParams": { + "type": "object", + "properties": { + "commandName": { + "type": "string", + "description": "Name of the slash command to invoke (without the leading '/')." + }, + "args": { + "type": "string", + "description": "Argument string to pass to the command (empty string if none)." + } + }, + "required": [ + "commandName", + "args" + ], + "additionalProperties": false, + "description": "Slash command name and argument string to execute synchronously.", + "title": "ExecuteCommandParams" + }, + "ExecuteCommandResult": { + "type": "object", + "properties": { + "error": { + "type": "string", + "description": "Error message produced while executing the command, if any. Omitted when the handler succeeded." + } + }, + "additionalProperties": false, + "description": "Error message produced while executing the command, if any.", + "title": "ExecuteCommandResult" + }, + "Extension": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Source-qualified ID (e.g., 'project:my-ext', 'user:auth-helper')" + }, + "name": { + "type": "string", + "description": "Extension name (directory name)" + }, + "source": { + "$ref": "#/definitions/ExtensionSource", + "description": "Discovery source: project (.github/extensions/) or user (~/.copilot/extensions/)" + }, + "status": { + "$ref": "#/definitions/ExtensionStatus", + "description": "Current status: running, disabled, failed, or starting" + }, + "pid": { + "type": "integer", + "exclusiveMinimum": true, + "minimum": 0, + "maximum": 4294967295, + "description": "Process ID if the extension is running" + } + }, + "required": [ + "id", + "name", + "source", + "status" + ], + "additionalProperties": false, + "title": "Extension", + "description": "Schema for the `Extension` type." + }, + "ExtensionList": { + "type": "object", + "properties": { + "extensions": { + "type": "array", + "items": { + "$ref": "#/definitions/Extension" + }, + "description": "Discovered extensions and their current status" + } + }, + "required": [ + "extensions" + ], + "additionalProperties": false, + "description": "Extensions discovered for the session, with their current status.", + "title": "ExtensionList" + }, + "ExtensionsDisableRequest": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Source-qualified extension ID to disable" + } + }, + "required": [ + "id" + ], + "additionalProperties": false, + "description": "Source-qualified extension identifier to disable for the session.", + "title": "ExtensionsDisableRequest" + }, + "ExtensionsEnableRequest": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Source-qualified extension ID to enable" + } + }, + "required": [ + "id" + ], + "additionalProperties": false, + "description": "Source-qualified extension identifier to enable for the session.", + "title": "ExtensionsEnableRequest" + }, + "ExtensionSource": { + "type": "string", + "enum": [ + "project", + "user" + ], + "description": "Discovery source: project (.github/extensions/) or user (~/.copilot/extensions/)", + "title": "ExtensionSource", + "x-enumDescriptions": { + "project": "Extension discovered from the current project's .github/extensions directory.", + "user": "Extension discovered from the user's ~/.copilot/extensions directory." + } + }, + "ExtensionStatus": { + "type": "string", + "enum": [ + "running", + "disabled", + "failed", + "starting" + ], + "description": "Current status: running, disabled, failed, or starting", + "title": "ExtensionStatus", + "x-enumDescriptions": { + "running": "The extension process is running.", + "disabled": "The extension is installed but disabled.", + "failed": "The extension failed to start or crashed.", + "starting": "The extension process is starting." + } + }, + "ExternalToolResult": { + "anyOf": [ + { + "type": "string", + "description": "Simple string tool result" + }, + { + "$ref": "#/definitions/ExternalToolTextResultForLlm", + "description": "Expanded external tool result payload" + } + ], + "description": "Tool call result (string or expanded result object)", + "title": "ExternalToolResult" + }, + "ExternalToolTextResultForLlm": { + "type": "object", + "properties": { + "textResultForLlm": { + "type": "string", + "description": "Text result returned to the model" + }, + "resultType": { + "type": "string", + "description": "Execution outcome classification. Optional for back-compat; normalized to 'success' (or 'failure' when error is present) when missing or unrecognized." + }, + "error": { + "type": "string", + "description": "Optional error message for failed executions" + }, + "sessionLog": { + "type": "string", + "description": "Detailed log content for timeline display" + }, + "toolTelemetry": { + "type": "object", + "additionalProperties": {}, + "description": "Optional tool-specific telemetry" + }, + "binaryResultsForLlm": { + "type": "array", + "items": { + "$ref": "#/definitions/ExternalToolTextResultForLlmBinaryResultsForLlm", + "description": "Binary result returned by a tool for the model" + }, + "description": "Base64-encoded binary results returned to the model" + }, + "contents": { + "type": "array", + "items": { + "$ref": "#/definitions/ExternalToolTextResultForLlmContent", + "description": "A content block within a tool result, which may be text, terminal output, image, audio, or a resource" + }, + "description": "Structured content blocks from the tool" + } + }, + "required": [ + "textResultForLlm" + ], + "additionalProperties": true, + "description": "Expanded external tool result payload", + "title": "ExternalToolTextResultForLlm" + }, + "ExternalToolTextResultForLlmBinaryResultsForLlm": { + "type": "object", + "properties": { + "type": { + "$ref": "#/definitions/ExternalToolTextResultForLlmBinaryResultsForLlmType", + "description": "Binary result type discriminator. Use \"image\" for images and \"resource\" for other binary data." + }, + "data": { + "type": "string", + "description": "Base64-encoded binary data", + "contentEncoding": "base64" + }, + "mimeType": { + "type": "string", + "description": "MIME type of the binary data" + }, + "description": { + "type": "string", + "description": "Human-readable description of the binary data" + } + }, + "required": [ + "type", + "data", + "mimeType" + ], + "additionalProperties": false, + "description": "Binary result returned by a tool for the model", + "title": "ExternalToolTextResultForLlmBinaryResultsForLlm" + }, + "ExternalToolTextResultForLlmBinaryResultsForLlmType": { + "type": "string", + "enum": [ + "image", + "resource" + ], + "description": "Binary result type discriminator. Use \"image\" for images and \"resource\" for other binary data.", + "title": "ExternalToolTextResultForLlmBinaryResultsForLlmType", + "x-enumDescriptions": { + "image": "Binary image data.", + "resource": "Other binary resource data." + } + }, + "ExternalToolTextResultForLlmContent": { + "anyOf": [ + { + "$ref": "#/definitions/ExternalToolTextResultForLlmContentText", + "description": "Plain text content block" + }, + { + "$ref": "#/definitions/ExternalToolTextResultForLlmContentTerminal", + "description": "Terminal/shell output content block with optional exit code and working directory" + }, + { + "$ref": "#/definitions/ExternalToolTextResultForLlmContentImage", + "description": "Image content block with base64-encoded data" + }, + { + "$ref": "#/definitions/ExternalToolTextResultForLlmContentAudio", + "description": "Audio content block with base64-encoded data" + }, + { + "$ref": "#/definitions/ExternalToolTextResultForLlmContentResourceLink", + "description": "Resource link content block referencing an external resource" + }, + { + "$ref": "#/definitions/ExternalToolTextResultForLlmContentResource", + "description": "Embedded resource content block with inline text or binary data" + } + ], + "description": "A content block within a tool result, which may be text, terminal output, image, audio, or a resource", + "title": "ExternalToolTextResultForLlmContent" + }, + "ExternalToolTextResultForLlmContentAudio": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "audio", + "description": "Content block type discriminator" + }, + "data": { + "type": "string", + "description": "Base64-encoded audio data", + "contentEncoding": "base64" + }, + "mimeType": { + "type": "string", + "description": "MIME type of the audio (e.g., audio/wav, audio/mpeg)" + } + }, + "required": [ + "type", + "data", + "mimeType" + ], + "additionalProperties": false, + "description": "Audio content block with base64-encoded data", + "title": "ExternalToolTextResultForLlmContentAudio" + }, + "ExternalToolTextResultForLlmContentImage": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "image", + "description": "Content block type discriminator" + }, + "data": { + "type": "string", + "description": "Base64-encoded image data", + "contentEncoding": "base64" + }, + "mimeType": { + "type": "string", + "description": "MIME type of the image (e.g., image/png, image/jpeg)" + } + }, + "required": [ + "type", + "data", + "mimeType" + ], + "additionalProperties": false, + "description": "Image content block with base64-encoded data", + "title": "ExternalToolTextResultForLlmContentImage" + }, + "ExternalToolTextResultForLlmContentResource": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "resource", + "description": "Content block type discriminator" + }, + "resource": { + "$ref": "#/definitions/ExternalToolTextResultForLlmContentResourceDetails", + "description": "The embedded resource contents, either text or base64-encoded binary" + } + }, + "required": [ + "type", + "resource" + ], + "additionalProperties": false, + "description": "Embedded resource content block with inline text or binary data", + "title": "ExternalToolTextResultForLlmContentResource" + }, + "ExternalToolTextResultForLlmContentResourceDetails": { + "anyOf": [ + { + "$ref": "#/definitions/EmbeddedTextResourceContents" + }, + { + "$ref": "#/definitions/EmbeddedBlobResourceContents" + } + ], + "description": "The embedded resource contents, either text or base64-encoded binary", + "title": "ExternalToolTextResultForLlmContentResourceDetails" + }, + "ExternalToolTextResultForLlmContentResourceLink": { + "type": "object", + "properties": { + "icons": { + "type": "array", + "items": { + "$ref": "#/definitions/ExternalToolTextResultForLlmContentResourceLinkIcon", + "description": "Icon image for a resource" + }, + "description": "Icons associated with this resource" + }, + "name": { + "type": "string", + "description": "Resource name identifier" + }, + "title": { + "type": "string", + "description": "Human-readable display title for the resource" + }, + "uri": { + "type": "string", + "format": "uri", + "description": "URI identifying the resource" + }, + "description": { + "type": "string", + "description": "Human-readable description of the resource" + }, + "mimeType": { + "type": "string", + "description": "MIME type of the resource content" + }, + "size": { + "type": "integer", + "minimum": 0, + "description": "Size of the resource in bytes" + }, + "type": { + "type": "string", + "const": "resource_link", + "description": "Content block type discriminator" + } + }, + "required": [ + "name", + "uri", + "type" + ], + "additionalProperties": false, + "description": "Resource link content block referencing an external resource", + "title": "ExternalToolTextResultForLlmContentResourceLink" + }, + "ExternalToolTextResultForLlmContentResourceLinkIcon": { + "type": "object", + "properties": { + "src": { + "type": "string", + "description": "URL or path to the icon image" + }, + "mimeType": { + "type": "string", + "description": "MIME type of the icon image" + }, + "sizes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Available icon sizes (e.g., ['16x16', '32x32'])" + }, + "theme": { + "$ref": "#/definitions/ExternalToolTextResultForLlmContentResourceLinkIconTheme", + "description": "Theme variant this icon is intended for" + } + }, + "required": [ + "src" + ], + "additionalProperties": false, + "description": "Icon image for a resource", + "title": "ExternalToolTextResultForLlmContentResourceLinkIcon" + }, + "ExternalToolTextResultForLlmContentResourceLinkIconTheme": { + "type": "string", + "enum": [ + "light", + "dark" + ], + "description": "Theme variant this icon is intended for", + "title": "ExternalToolTextResultForLlmContentResourceLinkIconTheme", + "x-enumDescriptions": { + "light": "Icon intended for light themes.", + "dark": "Icon intended for dark themes." + } + }, + "ExternalToolTextResultForLlmContentTerminal": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "terminal", + "description": "Content block type discriminator" + }, + "text": { + "type": "string", + "description": "Terminal/shell output text" + }, + "exitCode": { + "type": "integer", + "minimum": 0, + "maximum": 4294967295, + "description": "Process exit code, if the command has completed" + }, + "cwd": { + "type": "string", + "description": "Working directory where the command was executed" + } + }, + "required": [ + "type", + "text" + ], + "additionalProperties": false, + "description": "Terminal/shell output content block with optional exit code and working directory", + "title": "ExternalToolTextResultForLlmContentTerminal" + }, + "ExternalToolTextResultForLlmContentText": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text", + "description": "Content block type discriminator" + }, + "text": { + "type": "string", + "description": "The text content" + } + }, + "required": [ + "type", + "text" + ], + "additionalProperties": false, + "description": "Plain text content block", + "title": "ExternalToolTextResultForLlmContentText" + }, + "FilterMapping": { + "anyOf": [ + { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/ContentFilterMode", + "description": "Controls how MCP tool result content is filtered: none leaves content unchanged, markdown sanitizes HTML while preserving Markdown-friendly output, and hidden_characters removes characters that can hide directives." + } + }, + { + "$ref": "#/definitions/ContentFilterMode", + "description": "Controls how MCP tool result content is filtered: none leaves content unchanged, markdown sanitizes HTML while preserving Markdown-friendly output, and hidden_characters removes characters that can hide directives." + } + ], + "description": "Content filtering mode to apply to all tools, or a map of tool name to content filtering mode.", + "title": "FilterMapping" + }, + "FleetStartRequest": { + "type": "object", + "properties": { + "prompt": { + "type": "string", + "description": "Optional user prompt to combine with fleet instructions" + } + }, + "additionalProperties": false, + "description": "Optional user prompt to combine with the fleet orchestration instructions.", + "title": "FleetStartRequest" + }, + "FleetStartResult": { + "type": "object", + "properties": { + "started": { + "type": "boolean", + "description": "Whether fleet mode was successfully activated" + } + }, + "required": [ + "started" + ], + "additionalProperties": false, + "description": "Indicates whether fleet mode was successfully activated.", + "title": "FleetStartResult" + }, + "FolderTrustAddParams": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Folder path to mark as trusted" + } + }, + "required": [ + "path" + ], + "additionalProperties": false, + "description": "Folder path to add to trusted folders.", + "title": "FolderTrustAddParams" + }, + "FolderTrustCheckParams": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Folder path to check" + } + }, + "required": [ + "path" + ], + "additionalProperties": false, + "description": "Folder path to check for trust.", + "title": "FolderTrustCheckParams" + }, + "FolderTrustCheckResult": { + "type": "object", + "properties": { + "trusted": { + "type": "boolean", + "description": "Whether the folder is trusted" + } + }, + "required": [ + "trusted" + ], + "additionalProperties": false, + "description": "Folder trust check result.", + "title": "FolderTrustCheckResult" + }, + "GhCliAuthInfo": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "gh-cli", + "description": "Authentication via the `gh` CLI's saved credentials." + }, + "host": { + "type": "string", + "description": "Authentication host." + }, + "login": { + "type": "string", + "description": "User login as reported by `gh auth status`." + }, + "token": { + "type": "string", + "description": "The token returned by `gh auth token`. Treat as a secret." + }, + "copilotUser": { + "$ref": "#/definitions/CopilotUserResponse", + "description": "Snapshot of the authenticated user's Copilot subscription info, if known. Mirrors the GitHub API `/copilot_internal/v2/token` user response shape — the runtime trusts this verbatim and does not re-fetch when set." + } + }, + "required": [ + "type", + "host", + "login", + "token" + ], + "additionalProperties": false, + "title": "GhCliAuthInfo", + "description": "Schema for the `GhCliAuthInfo` type." + }, + "HandlePendingToolCallRequest": { + "type": "object", + "properties": { + "requestId": { + "type": "string", + "description": "Request ID of the pending tool call" + }, + "result": { + "$ref": "#/definitions/ExternalToolResult", + "description": "Tool call result (string or expanded result object)" + }, + "error": { + "type": "string", + "description": "Error message if the tool call failed" + } + }, + "required": [ + "requestId" + ], + "additionalProperties": false, + "description": "Pending external tool call request ID, with the tool result or an error describing why it failed.", + "title": "HandlePendingToolCallRequest" + }, + "HandlePendingToolCallResult": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Whether the tool call result was handled successfully" + } + }, + "required": [ + "success" + ], + "additionalProperties": false, + "description": "Indicates whether the external tool call result was handled successfully.", + "title": "HandlePendingToolCallResult" + }, + "HistoryAbortManualCompactionResult": { + "type": "object", + "properties": { + "aborted": { + "type": "boolean", + "description": "Whether an in-progress manual compaction was aborted. False when no manual compaction was running, when its abort controller was already aborted, or when the session is remote." + } + }, + "required": [ + "aborted" + ], + "additionalProperties": false, + "description": "Indicates whether an in-progress manual compaction was aborted.", + "title": "HistoryAbortManualCompactionResult" + }, + "HistoryCancelBackgroundCompactionResult": { + "type": "object", + "properties": { + "cancelled": { + "type": "boolean", + "description": "Whether an in-progress background compaction was cancelled. False when no compaction was running, when the session is remote, or when the underlying processor was unavailable." + } + }, + "required": [ + "cancelled" + ], + "additionalProperties": false, + "description": "Indicates whether an in-progress background compaction was cancelled.", + "title": "HistoryCancelBackgroundCompactionResult" + }, + "HistoryCompactContextWindow": { + "type": "object", + "properties": { + "tokenLimit": { + "type": "integer", + "minimum": 0, + "description": "Maximum token count for the model's context window" + }, + "currentTokens": { + "type": "integer", + "minimum": 0, + "description": "Current total tokens in the context window (system + conversation + tool definitions)" + }, + "messagesLength": { + "type": "integer", + "minimum": 0, + "description": "Current number of messages in the conversation" + }, + "systemTokens": { + "type": "integer", + "minimum": 0, + "description": "Token count from system message(s)" + }, + "conversationTokens": { + "type": "integer", + "minimum": 0, + "description": "Token count from non-system messages (user, assistant, tool)" + }, + "toolDefinitionsTokens": { + "type": "integer", + "minimum": 0, + "description": "Token count from tool definitions" + } + }, + "required": [ + "tokenLimit", + "currentTokens", + "messagesLength" + ], + "additionalProperties": false, + "description": "Post-compaction context window usage breakdown", + "title": "HistoryCompactContextWindow" + }, + "HistoryCompactResult": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Whether compaction completed successfully" + }, + "tokensRemoved": { + "type": "integer", + "minimum": 0, + "description": "Number of tokens freed by compaction" + }, + "messagesRemoved": { + "type": "integer", + "minimum": 0, + "description": "Number of messages removed during compaction" + }, + "summaryContent": { + "type": "string", + "description": "Summary text produced by compaction. Omitted when compaction did not produce a summary (e.g. failure path)." + }, + "contextWindow": { + "$ref": "#/definitions/HistoryCompactContextWindow", + "description": "Post-compaction context window usage breakdown" + } + }, + "required": [ + "success", + "tokensRemoved", + "messagesRemoved" + ], + "additionalProperties": false, + "description": "Compaction outcome with the number of tokens and messages removed, summary text, and the resulting context window breakdown.", + "title": "HistoryCompactResult" + }, + "HistorySummarizeForHandoffResult": { + "type": "object", + "properties": { + "summary": { + "type": "string", + "description": "Markdown summary of the conversation context produced by an LLM. Empty string when there are no messages or when the session does not support local summarization." + } + }, + "required": [ + "summary" + ], + "additionalProperties": false, + "description": "Markdown summary of the conversation context (empty when not available).", + "title": "HistorySummarizeForHandoffResult" + }, + "HistoryTruncateRequest": { + "type": "object", + "properties": { + "eventId": { + "type": "string", + "description": "Event ID to truncate to. This event and all events after it are removed from the session." + } + }, + "required": [ + "eventId" + ], + "additionalProperties": false, + "description": "Identifier of the event to truncate to; this event and all later events are removed.", + "title": "HistoryTruncateRequest" + }, + "HistoryTruncateResult": { + "type": "object", + "properties": { + "eventsRemoved": { + "type": "integer", + "minimum": 0, + "description": "Number of events that were removed" + } + }, + "required": [ + "eventsRemoved" + ], + "additionalProperties": false, + "description": "Number of events that were removed by the truncation.", + "title": "HistoryTruncateResult" + }, + "HMACAuthInfo": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "hmac", + "description": "HMAC-based authentication used by GitHub-internal services." + }, + "host": { + "type": "string", + "const": "https://github.com", + "description": "Authentication host. HMAC auth always targets the public GitHub host." + }, + "hmac": { + "type": "string", + "description": "HMAC secret used to sign requests." + }, + "copilotUser": { + "$ref": "#/definitions/CopilotUserResponse", + "description": "Snapshot of the authenticated user's Copilot subscription info, if known. Mirrors the GitHub API `/copilot_internal/v2/token` user response shape — the runtime trusts this verbatim and does not re-fetch when set." + } + }, + "required": [ + "type", + "host", + "hmac" + ], + "additionalProperties": false, + "title": "HMACAuthInfo", + "description": "Schema for the `HMACAuthInfo` type." + }, + "InstalledPlugin": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Plugin name" + }, + "marketplace": { + "type": "string", + "description": "Marketplace the plugin came from (empty string for direct repo installs)" + }, + "version": { + "type": "string", + "description": "Version installed (if available)" + }, + "installed_at": { + "type": "string", + "description": "Installation timestamp" + }, + "enabled": { + "type": "boolean", + "description": "Whether the plugin is currently enabled" + }, + "cache_path": { + "type": "string", + "description": "Path where the plugin is cached locally" + }, + "source": { + "$ref": "#/definitions/InstalledPluginSource", + "description": "Source for direct repo installs (when marketplace is empty)" + } + }, + "required": [ + "name", + "marketplace", + "installed_at", + "enabled" + ], + "additionalProperties": false, + "title": "InstalledPlugin", + "description": "Schema for the `InstalledPlugin` type." + }, + "InstalledPluginSource": { + "anyOf": [ + { + "type": "string", + "pattern": "^[^/]+\\/[^/]+$" + }, + { + "$ref": "#/definitions/InstalledPluginSourceGithub" + }, + { + "$ref": "#/definitions/InstalledPluginSourceUrl" + }, + { + "$ref": "#/definitions/InstalledPluginSourceLocal" + } + ], + "description": "Source for direct repo installs (when marketplace is empty)", + "title": "InstalledPluginSource" + }, + "InstalledPluginSourceGithub": { + "type": "object", + "properties": { + "source": { + "type": "string", + "const": "github", + "description": "Constant value. Always \"github\"." + }, + "repo": { + "type": "string", + "pattern": "^[^/]+\\/[^/]+$" + }, + "ref": { + "type": "string" + }, + "path": { + "type": "string" + } + }, + "required": [ + "source", + "repo" + ], + "additionalProperties": false, + "title": "InstalledPluginSourceGithub", + "description": "Schema for the `InstalledPluginSourceGithub` type." + }, + "InstalledPluginSourceLocal": { + "type": "object", + "properties": { + "source": { + "type": "string", + "const": "local", + "description": "Constant value. Always \"local\"." + }, + "path": { + "type": "string" + } + }, + "required": [ + "source", + "path" + ], + "additionalProperties": false, + "title": "InstalledPluginSourceLocal", + "description": "Schema for the `InstalledPluginSourceLocal` type." + }, + "InstalledPluginSourceUrl": { + "type": "object", + "properties": { + "source": { + "type": "string", + "const": "url", + "description": "Constant value. Always \"url\"." + }, + "url": { + "type": "string", + "format": "uri" + }, + "ref": { + "type": "string" + }, + "path": { + "type": "string" + } + }, + "required": [ + "source", + "url" + ], + "additionalProperties": false, + "title": "InstalledPluginSourceUrl", + "description": "Schema for the `InstalledPluginSourceUrl` type." + }, + "InstructionsGetSourcesResult": { + "type": "object", + "properties": { + "sources": { + "type": "array", + "items": { + "$ref": "#/definitions/InstructionsSources" + }, + "description": "Instruction sources for the session" + } + }, + "required": [ + "sources" + ], + "additionalProperties": false, + "description": "Instruction sources loaded for the session, in merge order.", + "title": "InstructionsGetSourcesResult" + }, + "InstructionsSources": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for this source (used for toggling)" + }, + "label": { + "type": "string", + "description": "Human-readable label" + }, + "sourcePath": { + "type": "string", + "description": "File path relative to repo or absolute for home" + }, + "content": { + "type": "string", + "description": "Raw content of the instruction file" + }, + "type": { + "$ref": "#/definitions/InstructionsSourcesType", + "description": "Category of instruction source — used for merge logic" + }, + "location": { + "$ref": "#/definitions/InstructionsSourcesLocation", + "description": "Where this source lives — used for UI grouping" + }, + "applyTo": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Glob pattern(s) from frontmatter — when set, this instruction applies only to matching files" + }, + "description": { + "type": "string", + "description": "Short description (body after frontmatter) for use in instruction tables" + }, + "defaultDisabled": { + "type": "boolean", + "description": "When true, this source starts disabled and must be toggled on by the user" + } + }, + "required": [ + "id", + "label", + "sourcePath", + "content", + "type", + "location" + ], + "additionalProperties": false, + "title": "InstructionsSources", + "description": "Schema for the `InstructionsSources` type." + }, + "InstructionsSourcesLocation": { + "type": "string", + "enum": [ + "user", + "repository", + "working-directory", + "plugin" + ], + "description": "Where this source lives — used for UI grouping", + "title": "InstructionsSourcesLocation", + "x-enumDescriptions": { + "user": "Instructions live in user-level configuration.", + "repository": "Instructions live in repository-level configuration.", + "working-directory": "Instructions live under the current working directory.", + "plugin": "Instructions live in plugin-provided configuration." + } + }, + "InstructionsSourcesType": { + "type": "string", + "enum": [ + "home", + "repo", + "model", + "vscode", + "nested-agents", + "child-instructions", + "plugin" + ], + "description": "Category of instruction source — used for merge logic", + "title": "InstructionsSourcesType", + "x-enumDescriptions": { + "home": "Instructions loaded from the user's home configuration.", + "repo": "Instructions loaded from repository-scoped files.", + "model": "Instructions loaded from model-specific files.", + "vscode": "Instructions loaded from VS Code instruction files.", + "nested-agents": "Instructions discovered from nested agent files.", + "child-instructions": "Instructions inherited from child instruction files.", + "plugin": "Instructions supplied by an installed plugin." + } + }, + "LogRequest": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Human-readable message" + }, + "level": { + "$ref": "#/definitions/SessionLogLevel", + "description": "Log severity level. Determines how the message is displayed in the timeline. Defaults to \"info\"." + }, + "type": { + "type": "string", + "description": "Domain category for this log entry (e.g., \"mcp\", \"subscription\", \"policy\", \"model\"). Maps to `infoType`/`warningType`/`errorType` on the emitted event. Defaults to \"notification\"." + }, + "ephemeral": { + "type": "boolean", + "description": "When true, the message is transient and not persisted to the session event log on disk" + }, + "url": { + "type": "string", + "format": "uri", + "description": "Optional URL the user can open in their browser for more details" + }, + "tip": { + "type": "string", + "description": "Optional actionable tip displayed alongside the message. Only honored on `level: \"info\"`." + } + }, + "required": [ + "message" + ], + "additionalProperties": false, + "description": "Message text, optional severity level, persistence flag, optional follow-up URL, and optional tip.", + "title": "LogRequest" + }, + "LogResult": { + "type": "object", + "properties": { + "eventId": { + "type": "string", + "format": "uuid", + "description": "The unique identifier of the emitted session event" + } + }, + "required": [ + "eventId" + ], + "additionalProperties": false, + "description": "Identifier of the session event that was emitted for the log message.", + "title": "LogResult" + }, + "LspInitializeRequest": { + "type": "object", + "properties": { + "workingDirectory": { + "type": "string", + "description": "Working directory used to load project-level LSP configs. Defaults to the session working directory when omitted." + }, + "gitRoot": { + "type": "string", + "description": "Git root used as the boundary when traversing for project-level LSP configs (supports monorepos)." + }, + "force": { + "type": "boolean", + "description": "Force re-initialization even when LSP configs were already loaded for the working directory." + } + }, + "additionalProperties": false, + "description": "Parameters for (re)loading the merged LSP configuration set.", + "title": "LspInitializeRequest" + }, + "McpCancelSamplingExecutionParams": { + "type": "object", + "properties": { + "requestId": { + "type": "string", + "description": "The requestId previously passed to executeSampling that should be cancelled" + } + }, + "required": [ + "requestId" + ], + "additionalProperties": false, + "description": "The requestId previously passed to executeSampling that should be cancelled.", + "title": "McpCancelSamplingExecutionParams" + }, + "McpCancelSamplingExecutionResult": { + "type": "object", + "properties": { + "cancelled": { + "type": "boolean", + "description": "True if an in-flight execution with the given requestId was found and signalled to cancel. False when no such execution is in flight (already completed, never started, or cancelled by another caller)." + } + }, + "required": [ + "cancelled" + ], + "additionalProperties": false, + "description": "Indicates whether an in-flight sampling execution with the given requestId was found and cancelled.", + "title": "McpCancelSamplingExecutionResult" + }, + "McpConfigAddRequest": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", + "description": "Unique name for the MCP server" + }, + "config": { + "$ref": "#/definitions/McpServerConfig", + "description": "MCP server configuration (stdio process or remote HTTP/SSE)" + } + }, + "required": [ + "name", + "config" + ], + "additionalProperties": false, + "description": "MCP server name and configuration to add to user configuration.", + "title": "McpConfigAddRequest" + }, + "McpConfigDisableRequest": { + "type": "object", + "properties": { + "names": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "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." + } + }, + "required": [ + "names" + ], + "additionalProperties": false, + "description": "MCP server names to disable for new sessions.", + "title": "McpConfigDisableRequest" + }, + "McpConfigEnableRequest": { + "type": "object", + "properties": { + "names": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "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." + } + }, + "required": [ + "names" + ], + "additionalProperties": false, + "description": "MCP server names to enable for new sessions.", + "title": "McpConfigEnableRequest" + }, + "McpConfigList": { + "type": "object", + "properties": { + "servers": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/McpServerConfig", + "description": "MCP server configuration (stdio process or remote HTTP/SSE)" + }, + "propertyNames": { + "minLength": 1, + "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$" + }, + "description": "All MCP servers from user config, keyed by name" + } + }, + "required": [ + "servers" + ], + "additionalProperties": false, + "description": "User-configured MCP servers, keyed by server name.", + "title": "McpConfigList" + }, + "McpConfigRemoveRequest": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", + "description": "Name of the MCP server to remove" + } + }, + "required": [ + "name" + ], + "additionalProperties": false, + "description": "MCP server name to remove from user configuration.", + "title": "McpConfigRemoveRequest" + }, + "McpConfigUpdateRequest": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", + "description": "Name of the MCP server to update" + }, + "config": { + "$ref": "#/definitions/McpServerConfig", + "description": "MCP server configuration (stdio process or remote HTTP/SSE)" + } + }, + "required": [ + "name", + "config" + ], + "additionalProperties": false, + "description": "MCP server name and replacement configuration to write to user configuration.", + "title": "McpConfigUpdateRequest" + }, + "McpDisableRequest": { + "type": "object", + "properties": { + "serverName": { + "type": "string", + "minLength": 1, + "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", + "description": "Name of the MCP server to disable" + } + }, + "required": [ + "serverName" + ], + "additionalProperties": false, + "description": "Name of the MCP server to disable for the session.", + "title": "McpDisableRequest" + }, + "McpDiscoverRequest": { + "type": "object", + "properties": { + "workingDirectory": { + "type": "string", + "description": "Working directory used as context for discovery (e.g., plugin resolution)" + } + }, + "additionalProperties": false, + "description": "Optional working directory used as context for MCP server discovery.", + "title": "McpDiscoverRequest" + }, + "McpDiscoverResult": { + "type": "object", + "properties": { + "servers": { + "type": "array", + "items": { + "$ref": "#/definitions/DiscoveredMcpServer" + }, + "description": "MCP servers discovered from all sources" + } + }, + "required": [ + "servers" + ], + "additionalProperties": false, + "description": "MCP servers discovered from user, workspace, plugin, and built-in sources.", + "title": "McpDiscoverResult" + }, + "McpEnableRequest": { + "type": "object", + "properties": { + "serverName": { + "type": "string", + "minLength": 1, + "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", + "description": "Name of the MCP server to enable" + } + }, + "required": [ + "serverName" + ], + "additionalProperties": false, + "description": "Name of the MCP server to enable for the session.", + "title": "McpEnableRequest" + }, + "McpExecuteSamplingParams": { + "type": "object", + "properties": { + "requestId": { + "type": "string", + "description": "Caller-provided unique identifier for this sampling execution. Use this same ID with cancelSamplingExecution to cancel the in-flight call. Must be unique within the session for the lifetime of the call." + }, + "serverName": { + "type": "string", + "description": "Name of the MCP server that initiated the sampling request" + }, + "mcpRequestId": { + "type": [ + "string", + "number" + ], + "description": "The original MCP JSON-RPC request ID (string or number). Used by the runtime to correlate the inference with the originating MCP request for telemetry; this is distinct from `requestId` (which is the schema-level cancellation handle)." + }, + "request": { + "$ref": "#/definitions/McpExecuteSamplingRequest", + "description": "Raw MCP CreateMessageRequest params, as received in the `sampling.requested` event. Treated as opaque at the schema layer; the runtime converts the embedded MCP messages into the OpenAI chat-completion shape internally." + } + }, + "required": [ + "requestId", + "serverName", + "mcpRequestId", + "request" + ], + "additionalProperties": false, + "description": "Identifiers and raw MCP CreateMessageRequest params used to run a sampling inference.", + "title": "McpExecuteSamplingParams" + }, + "McpExecuteSamplingRequest": { + "type": "object", + "properties": {}, + "additionalProperties": true, + "description": "Raw MCP CreateMessageRequest params, as received in the `sampling.requested` event. Treated as opaque at the schema layer; the runtime converts the embedded MCP messages into the OpenAI chat-completion shape internally.", + "title": "McpExecuteSamplingRequest" + }, + "McpExecuteSamplingResult": { + "type": "object", + "properties": {}, + "additionalProperties": true, + "description": "MCP CreateMessageResult payload (with optional 'tools' extension), present when action='success'. Treated as opaque at the schema layer; consumers should construct/consume it per the MCP CreateMessageResult shape.", + "title": "McpExecuteSamplingResult" + }, + "McpOauthLoginRequest": { + "type": "object", + "properties": { + "serverName": { + "type": "string", + "minLength": 1, + "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", + "description": "Name of the remote MCP server to authenticate" + }, + "forceReauth": { + "type": "boolean", + "description": "When true, clears any cached OAuth token for the server and runs a full new authorization. Use when the user explicitly wants to switch accounts or believes their session is stuck." + }, + "clientName": { + "type": "string", + "description": "Optional override for the OAuth client display name shown on the consent screen. Applies to newly registered dynamic clients only — existing registrations keep the name they were created with. When omitted, the runtime applies a neutral fallback; callers driving interactive auth should pass their own surface-specific label so the consent screen matches the product the user sees." + }, + "callbackSuccessMessage": { + "type": "string", + "description": "Optional override for the body text shown on the OAuth loopback callback success page. When omitted, the runtime applies a neutral fallback; callers driving interactive auth should pass surface-specific copy telling the user where to return." + } + }, + "required": [ + "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": { + "type": "object", + "properties": { + "authorizationUrl": { + "type": "string", + "format": "uri", + "description": "URL the caller should open in a browser to complete OAuth. Omitted when cached tokens were still valid and no browser interaction was needed — the server is already reconnected in that case. When present, the runtime starts the callback listener before returning and continues the flow in the background; completion is signaled via session.mcp_server_status_changed." + } + }, + "additionalProperties": false, + "description": "OAuth authorization URL the caller should open, or empty when cached tokens already authenticated the server.", + "title": "McpOauthLoginResult" + }, + "McpRemoveGitHubResult": { + "type": "object", + "properties": { + "removed": { + "type": "boolean", + "description": "True when the auto-managed `github` MCP server was removed; false when no removal happened (e.g. user has explicitly configured a `github` server, or the server was not registered)." + } + }, + "required": [ + "removed" + ], + "additionalProperties": false, + "description": "Indicates whether the auto-managed `github` MCP server was removed (false when nothing to remove).", + "title": "McpRemoveGitHubResult" + }, + "McpSamplingExecutionAction": { + "type": "string", + "enum": [ + "success", + "failure", + "cancelled" + ], + "description": "Outcome of the sampling inference. 'success' produced a response; 'failure' encountered an error (including agent-side rejection by content filter or criteria); 'cancelled' the caller cancelled this execution via cancelSamplingExecution.", + "title": "McpSamplingExecutionAction", + "x-enumDescriptions": { + "success": "The sampling inference completed and produced a result.", + "failure": "The sampling inference failed or was rejected.", + "cancelled": "The sampling inference was cancelled before completion." + } + }, + "McpSamplingExecutionResult": { + "type": "object", + "properties": { + "action": { + "$ref": "#/definitions/McpSamplingExecutionAction", + "description": "Outcome of the sampling inference. 'success' produced a response; 'failure' encountered an error (including agent-side rejection by content filter or criteria); 'cancelled' the caller cancelled this execution via cancelSamplingExecution." + }, + "result": { + "$ref": "#/definitions/McpExecuteSamplingResult", + "description": "MCP CreateMessageResult payload (with optional 'tools' extension), present when action='success'. Treated as opaque at the schema layer; consumers should construct/consume it per the MCP CreateMessageResult shape." + }, + "error": { + "type": "string", + "description": "Error description, present when action='failure'." + } + }, + "required": [ + "action" + ], + "additionalProperties": false, + "description": "Outcome of an MCP sampling execution: success result, failure error, or cancellation.", + "title": "McpSamplingExecutionResult" + }, + "McpServer": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", + "description": "Server name (config key)" + }, + "status": { + "$ref": "#/definitions/McpServerStatus", + "description": "Connection status: connected, failed, needs-auth, pending, disabled, or not_configured" + }, + "source": { + "$ref": "#/definitions/McpServerSource", + "description": "Configuration source: user, workspace, plugin, or builtin" + }, + "error": { + "type": "string", + "description": "Error message if the server failed to connect" + } + }, + "required": [ + "name", + "status" + ], + "additionalProperties": false, + "title": "McpServer", + "description": "Schema for the `McpServer` type." + }, + "McpServerConfig": { + "anyOf": [ + { + "$ref": "#/definitions/McpServerConfigStdio", + "description": "Stdio MCP server configuration launched as a child process." + }, + { + "$ref": "#/definitions/McpServerConfigHttp", + "description": "Remote MCP server configuration accessed over HTTP or SSE." + } + ], + "description": "MCP server configuration (stdio process or remote HTTP/SSE)", + "title": "McpServerConfig" + }, + "McpServerConfigHttp": { + "type": "object", + "properties": { + "tools": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Tools to include. Defaults to all tools if not specified." + }, + "type": { + "$ref": "#/definitions/McpServerConfigHttpType", + "description": "Remote transport type. Defaults to \"http\" when omitted." + }, + "isDefaultServer": { + "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", + "description": "Content filtering mode to apply to all tools, or a map of tool name to content filtering mode." + }, + "timeout": { + "type": "integer", + "exclusiveMinimum": true, + "minimum": 0, + "description": "Timeout in milliseconds for tool calls to this server.", + "format": "duration" + }, + "url": { + "type": "string", + "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", + "description": "OAuth client ID for a pre-registered remote MCP OAuth client." + }, + "oauthPublicClient": { + "type": "boolean", + "description": "Whether the configured OAuth client is public and does not require a client secret." + }, + "oauthGrantType": { + "$ref": "#/definitions/McpServerConfigHttpOauthGrantType", + "description": "OAuth grant type to use when authenticating to the remote MCP server." + }, + "auth": { + "$ref": "#/definitions/McpServerConfigHttpAuth", + "description": "Additional authentication configuration for this server." + } + }, + "required": [ + "url" + ], + "additionalProperties": false, + "description": "Remote MCP server configuration accessed over HTTP or SSE.", + "title": "McpServerConfigHttp" + }, + "McpServerConfigHttpAuth": { + "type": "object", + "properties": { + "redirectPort": { + "type": "integer", + "minimum": 1, + "maximum": 65535, + "description": "Fixed port for the OAuth redirect callback server." + } + }, + "additionalProperties": false, + "description": "Additional authentication configuration for this server.", + "title": "McpServerConfigHttpAuth" + }, + "McpServerConfigHttpOauthGrantType": { + "type": "string", + "enum": [ + "authorization_code", + "client_credentials" + ], + "description": "OAuth grant type to use when authenticating to the remote MCP server.", + "title": "McpServerConfigHttpOauthGrantType", + "x-enumDescriptions": { + "authorization_code": "Interactive browser-based authorization code flow with PKCE.", + "client_credentials": "Headless client credentials flow using the configured OAuth client." + } + }, + "McpServerConfigHttpType": { + "type": "string", + "enum": [ + "http", + "sse" + ], + "default": "http", + "description": "Remote transport type. Defaults to \"http\" when omitted.", + "title": "McpServerConfigHttpType", + "x-enumDescriptions": { + "http": "Streamable HTTP transport.", + "sse": "Server-Sent Events transport." + } + }, + "McpServerConfigStdio": { + "type": "object", + "properties": { + "tools": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Tools to include. Defaults to all tools if not specified." + }, + "isDefaultServer": { + "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", + "description": "Content filtering mode to apply to all tools, or a map of tool name to content filtering mode." + }, + "timeout": { + "type": "integer", + "exclusiveMinimum": true, + "minimum": 0, + "description": "Timeout in milliseconds for tool calls to this server.", + "format": "duration" + }, + "command": { + "type": "string", + "description": "Executable command used to start the Stdio MCP server process." + }, + "args": { + "type": "array", + "items": { + "type": "string" + }, + "default": [], + "description": "Command-line arguments passed to the Stdio MCP server process." + }, + "cwd": { + "type": "string", + "description": "Working directory for the Stdio MCP server process." + }, + "env": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Environment variables to pass to the Stdio MCP server process." + } + }, + "required": [ + "command" + ], + "additionalProperties": false, + "description": "Stdio MCP server configuration launched as a child process.", + "title": "McpServerConfigStdio" + }, + "McpServerList": { + "type": "object", + "properties": { + "servers": { + "type": "array", + "items": { + "$ref": "#/definitions/McpServer" + }, + "description": "Configured MCP servers" + } + }, + "required": [ + "servers" + ], + "additionalProperties": false, + "description": "MCP servers configured for the session, with their connection status.", + "title": "McpServerList" + }, + "McpServerSource": { + "type": "string", + "enum": [ + "user", + "workspace", + "plugin", + "builtin" + ], + "description": "Configuration source: user, workspace, plugin, or builtin", + "title": "McpServerSource", + "x-enumDescriptions": { + "user": "Server configured in the user's global MCP configuration.", + "workspace": "Server configured by the current workspace.", + "plugin": "Server contributed by an installed plugin.", + "builtin": "Server bundled with the runtime." + } + }, + "McpServerStatus": { + "type": "string", + "enum": [ + "connected", + "failed", + "needs-auth", + "pending", + "disabled", + "not_configured" + ], + "description": "Connection status: connected, failed, needs-auth, pending, disabled, or not_configured", + "title": "McpServerStatus", + "x-enumDescriptions": { + "connected": "The server is connected and available.", + "failed": "The server failed to connect or initialize.", + "needs-auth": "The server requires authentication before it can connect.", + "pending": "The server connection is still being established.", + "disabled": "The server is configured but disabled.", + "not_configured": "The server is not configured for this session." + } + }, + "McpSetEnvValueModeDetails": { + "type": "string", + "enum": [ + "direct", + "indirect" + ], + "description": "How environment-variable values supplied to MCP servers are resolved. \"direct\" passes literal string values; \"indirect\" treats values as references (e.g. names of environment variables on the host) that the runtime resolves before launch. Defaults to the runtime's startup mode; clients that intentionally launch MCP servers with literal values (e.g. CLI prompt mode and ACP) set this to \"direct\".", + "title": "McpSetEnvValueModeDetails", + "x-enumDescriptions": { + "direct": "Treat MCP server environment values as literal strings.", + "indirect": "Treat MCP server environment values as host-side references to resolve before launch." + } + }, + "McpSetEnvValueModeParams": { + "type": "object", + "properties": { + "mode": { + "$ref": "#/definitions/McpSetEnvValueModeDetails", + "description": "How environment-variable values supplied to MCP servers are resolved. \"direct\" passes literal string values; \"indirect\" treats values as references (e.g. names of environment variables on the host) that the runtime resolves before launch. Defaults to the runtime's startup mode; clients that intentionally launch MCP servers with literal values (e.g. CLI prompt mode and ACP) set this to \"direct\"." + } + }, + "required": [ + "mode" + ], + "additionalProperties": false, + "description": "Mode controlling how MCP server env values are resolved (`direct` or `indirect`).", + "title": "McpSetEnvValueModeParams" + }, + "McpSetEnvValueModeResult": { + "type": "object", + "properties": { + "mode": { + "$ref": "#/definitions/McpSetEnvValueModeDetails", + "description": "Mode recorded on the session after the update" + } + }, + "required": [ + "mode" + ], + "additionalProperties": false, + "description": "Env-value mode recorded on the session after the update.", + "title": "McpSetEnvValueModeResult" + }, + "MetadataContextInfoRequest": { + "type": "object", + "properties": { + "promptTokenLimit": { + "type": "integer", + "minimum": 0, + "description": "Maximum prompt tokens allowed by the target model. Pass 0 to use the runtime default." + }, + "outputTokenLimit": { + "type": "integer", + "minimum": 0, + "description": "Maximum output tokens allowed by the target model. Pass 0 if unknown." + }, + "selectedModel": { + "type": "string", + "description": "Model identifier used for tokenization. Omit to use the session default. Used both for token counting and to compute display values." + } + }, + "required": [ + "promptTokenLimit", + "outputTokenLimit" + ], + "additionalProperties": false, + "description": "Model identifier and token limits used to compute the context-info breakdown.", + "title": "MetadataContextInfoRequest" + }, + "MetadataContextInfoResult": { + "type": "object", + "properties": { + "contextInfo": { + "$ref": "#/definitions/SessionContextInfo", + "description": "Token breakdown for the current context window, or null if the session has not yet been initialized (no system prompt or tool metadata cached)." + } + }, + "required": [ + "contextInfo" + ], + "additionalProperties": false, + "description": "Token breakdown for the session's current context window, or null if uninitialized.", + "title": "MetadataContextInfoResult" + }, + "MetadataIsProcessingResult": { + "type": "object", + "properties": { + "processing": { + "type": "boolean", + "description": "Whether the session is currently processing user/agent messages. False for non-local sessions (which don't run a local agentic loop). Reflects an in-flight turn or background continuation." + } + }, + "required": [ + "processing" + ], + "additionalProperties": false, + "description": "Indicates whether the local session is currently processing a turn or background continuation.", + "title": "MetadataIsProcessingResult" + }, + "MetadataRecomputeContextTokensRequest": { + "type": "object", + "properties": { + "modelId": { + "type": "string", + "description": "Model identifier used for tokenization. The runtime token-counts both chat-context and system-context messages against this model." + } + }, + "required": [ + "modelId" + ], + "additionalProperties": false, + "description": "Model identifier to use when re-tokenizing the session's existing messages.", + "title": "MetadataRecomputeContextTokensRequest" + }, + "MetadataRecomputeContextTokensResult": { + "type": "object", + "properties": { + "totalTokens": { + "type": "integer", + "minimum": 0, + "description": "Sum of tokens across chat-context and system-context messages currently held by the session." + }, + "messagesTokenCount": { + "type": "integer", + "minimum": 0, + "description": "Tokens contributed by user/assistant/tool messages (excludes system/developer prompts)." + }, + "systemTokenCount": { + "type": "integer", + "minimum": 0, + "description": "Tokens contributed by system/developer prompt snapshots." + } + }, + "required": [ + "totalTokens", + "messagesTokenCount", + "systemTokenCount" + ], + "additionalProperties": false, + "description": "Re-tokenize the session's existing messages against `modelId` and return the token totals. Useful for hosts that want an initial estimate of context usage on session resume, before the next agent turn fires `session.context_info_changed` events. Returns zeros for an empty session.", + "title": "MetadataRecomputeContextTokensResult" + }, + "MetadataRecordContextChangeRequest": { + "type": "object", + "properties": { + "context": { + "$ref": "#/definitions/SessionWorkingDirectoryContext", + "description": "Updated working directory and git context. Emitted as the new payload of `session.context_changed`." + } + }, + "required": [ + "context" + ], + "additionalProperties": false, + "description": "Updated working-directory/git context to record on the session.", + "title": "MetadataRecordContextChangeRequest" + }, + "MetadataRecordContextChangeResult": { + "type": "object", + "properties": {}, + "additionalProperties": false, + "description": "Notify the session that its working directory context has changed. Emits a `session.context_changed` event so consumers (telemetry, OTel tracker, ACP, the timeline UI) can react. Use this when the host has detected a cwd/branch/repo change outside the session's normal lifecycle (e.g., after a shell command in interactive mode).", + "title": "MetadataRecordContextChangeResult" + }, + "MetadataSetWorkingDirectoryRequest": { + "type": "object", + "properties": { + "workingDirectory": { + "type": "string", + "description": "Absolute path to set as the session's working directory. The runtime updates the session's recorded cwd so subsequent operations (shell tools, file lookups, telemetry) anchor to it." + } + }, + "required": [ + "workingDirectory" + ], + "additionalProperties": false, + "description": "Absolute path to set as the session's new working directory.", + "title": "MetadataSetWorkingDirectoryRequest" + }, + "MetadataSetWorkingDirectoryResult": { + "type": "object", + "properties": { + "workingDirectory": { + "type": "string", + "description": "Working directory after the update" + } + }, + "required": [ + "workingDirectory" + ], + "additionalProperties": false, + "description": "Update the session's working directory. Used by the host when the user explicitly changes cwd (e.g., the `/cd` slash command). The host is responsible for `process.chdir` and any related side-effects (file index, etc.); this method only updates the session's own recorded path.", + "title": "MetadataSetWorkingDirectoryResult" + }, + "MetadataSnapshotCurrentMode": { + "type": "string", + "enum": [ + "interactive", + "plan", + "autopilot" + ], + "description": "The current agent mode for this session (e.g., 'interactive', 'plan', 'autopilot')", + "title": "MetadataSnapshotCurrentMode", + "x-enumDescriptions": { + "interactive": "The agent is responding interactively to the user.", + "plan": "The agent is preparing a plan before making changes.", + "autopilot": "The agent is working autonomously toward task completion." + } + }, + "MetadataSnapshotRemoteMetadata": { + "type": "object", + "properties": { + "resourceId": { + "type": "string", + "description": "The original resource identifier (task ID or PR node ID), preserved across event-replay reconstructions. Falls back to `sessionId` when absent." + }, + "repository": { + "$ref": "#/definitions/MetadataSnapshotRemoteMetadataRepository", + "description": "The repository the remote session targets." + }, + "pullRequestNumber": { + "type": "integer", + "exclusiveMinimum": true, + "minimum": 0, + "description": "The pull request number the remote session is associated with, if any." + }, + "taskType": { + "$ref": "#/definitions/MetadataSnapshotRemoteMetadataTaskType", + "description": "Whether the remote task originated from Copilot Coding Agent (cca) or a CLI `--remote` invocation." + } + }, + "required": [ + "repository" + ], + "additionalProperties": false, + "description": "Remote-session-specific metadata. Populated only when `isRemote` is true. Fields are immutable for the lifetime of the session.", + "title": "MetadataSnapshotRemoteMetadata" + }, + "MetadataSnapshotRemoteMetadataRepository": { + "type": "object", + "properties": { + "owner": { + "type": "string", + "description": "The GitHub owner (user or organization) of the target repository." + }, + "name": { + "type": "string", + "description": "The GitHub repository name (without owner)." + }, + "branch": { + "type": "string", + "description": "The branch the remote session is operating on." + } + }, + "required": [ + "owner", + "name", + "branch" + ], + "additionalProperties": false, + "description": "The repository the remote session targets.", + "title": "MetadataSnapshotRemoteMetadataRepository" + }, + "MetadataSnapshotRemoteMetadataTaskType": { + "type": "string", + "enum": [ + "cca", + "cli" + ], + "description": "Whether the remote task originated from Copilot Coding Agent (cca) or a CLI `--remote` invocation.", + "title": "MetadataSnapshotRemoteMetadataTaskType", + "x-enumDescriptions": { + "cca": "Remote task originated from Copilot Coding Agent.", + "cli": "Remote task originated from a CLI remote-session invocation." + } + }, + "Model": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Model identifier (e.g., \"claude-sonnet-4.5\")" + }, + "name": { + "type": "string", + "description": "Display name" + }, + "capabilities": { + "$ref": "#/definitions/ModelCapabilities", + "description": "Model capabilities and limits" + }, + "policy": { + "$ref": "#/definitions/ModelPolicy", + "description": "Policy state (if applicable)" + }, + "billing": { + "$ref": "#/definitions/ModelBilling", + "description": "Billing information" + }, + "supportedReasoningEfforts": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Supported reasoning effort levels (only present if model supports reasoning effort)" + }, + "defaultReasoningEffort": { + "type": "string", + "description": "Default reasoning effort level (only present if model supports reasoning effort)" + }, + "modelPickerCategory": { + "$ref": "#/definitions/ModelPickerCategory", + "description": "Model capability category for grouping in the model picker" + }, + "modelPickerPriceCategory": { + "$ref": "#/definitions/ModelPickerPriceCategory", + "description": "Relative cost tier for token-based billing users" + } + }, + "required": [ + "id", + "name", + "capabilities" + ], + "additionalProperties": false, + "title": "Model", + "description": "Schema for the `Model` type." + }, + "ModelBilling": { + "type": "object", + "properties": { + "multiplier": { + "type": "number", + "description": "Billing cost multiplier relative to the base rate" + }, + "tokenPrices": { + "$ref": "#/definitions/ModelBillingTokenPrices", + "description": "Token-level pricing information for this model" + } + }, + "additionalProperties": false, + "description": "Billing information", + "title": "ModelBilling" + }, + "ModelBillingTokenPrices": { + "type": "object", + "properties": { + "inputPrice": { + "type": "integer", + "minimum": 0, + "description": "Price per billing batch of input tokens in nano-AIUs (1 nano-AIU = 0.000000001 AIU, 1 AIU = $0.01 USD)" + }, + "outputPrice": { + "type": "integer", + "minimum": 0, + "description": "Price per billing batch of output tokens in nano-AIUs (1 nano-AIU = 0.000000001 AIU, 1 AIU = $0.01 USD)" + }, + "cachePrice": { + "type": "integer", + "minimum": 0, + "description": "Price per billing batch of cached tokens in nano-AIUs (1 nano-AIU = 0.000000001 AIU, 1 AIU = $0.01 USD)" + }, + "batchSize": { + "type": "integer", + "exclusiveMinimum": true, + "minimum": 0, + "description": "Number of tokens per standard billing batch" + } + }, + "additionalProperties": false, + "description": "Token-level pricing information for this model", + "title": "ModelBillingTokenPrices" + }, + "ModelCapabilities": { + "type": "object", + "properties": { + "supports": { + "$ref": "#/definitions/ModelCapabilitiesSupports", + "description": "Feature flags indicating what the model supports" + }, + "limits": { + "$ref": "#/definitions/ModelCapabilitiesLimits", + "description": "Token limits for prompts, outputs, and context window" + } + }, + "additionalProperties": false, + "description": "Model capabilities and limits", + "title": "ModelCapabilities" + }, + "ModelCapabilitiesLimits": { + "type": "object", + "properties": { + "max_prompt_tokens": { + "type": "integer", + "minimum": 0, + "description": "Maximum number of prompt/input tokens" + }, + "max_output_tokens": { + "type": "integer", + "minimum": 0, + "description": "Maximum number of output/completion tokens" + }, + "max_context_window_tokens": { + "type": "integer", + "minimum": 0, + "description": "Maximum total context window size in tokens" + }, + "vision": { + "$ref": "#/definitions/ModelCapabilitiesLimitsVision", + "description": "Vision-specific limits" + } + }, + "additionalProperties": false, + "description": "Token limits for prompts, outputs, and context window", + "title": "ModelCapabilitiesLimits" + }, + "ModelCapabilitiesLimitsVision": { + "type": "object", + "properties": { + "supported_media_types": { + "type": "array", + "items": { + "type": "string" + }, + "description": "MIME types the model accepts" + }, + "max_prompt_images": { + "type": "integer", + "minimum": 1, + "description": "Maximum number of images per prompt" + }, + "max_prompt_image_size": { + "type": "integer", + "minimum": 0, + "description": "Maximum image size in bytes" + } + }, + "required": [ + "supported_media_types", + "max_prompt_images", + "max_prompt_image_size" + ], + "additionalProperties": false, + "description": "Vision-specific limits", + "title": "ModelCapabilitiesLimitsVision" + }, + "ModelCapabilitiesOverride": { + "type": "object", + "properties": { + "supports": { + "$ref": "#/definitions/ModelCapabilitiesOverrideSupports", + "description": "Feature flags indicating what the model supports" + }, + "limits": { + "$ref": "#/definitions/ModelCapabilitiesOverrideLimits", + "description": "Token limits for prompts, outputs, and context window" + } + }, + "additionalProperties": false, + "description": "Override individual model capabilities resolved by the runtime", + "title": "ModelCapabilitiesOverride" + }, + "ModelCapabilitiesOverrideLimits": { + "type": "object", + "properties": { + "max_prompt_tokens": { + "type": "integer", + "minimum": 0, + "description": "Maximum number of prompt/input tokens" + }, + "max_output_tokens": { + "type": "integer", + "minimum": 0, + "description": "Maximum number of output/completion tokens" + }, + "max_context_window_tokens": { + "type": "integer", + "minimum": 0, + "description": "Maximum total context window size in tokens" + }, + "vision": { + "$ref": "#/definitions/ModelCapabilitiesOverrideLimitsVision", + "description": "Vision-specific limits" + } + }, + "additionalProperties": false, + "description": "Token limits for prompts, outputs, and context window", + "title": "ModelCapabilitiesOverrideLimits" + }, + "ModelCapabilitiesOverrideLimitsVision": { + "type": "object", + "properties": { + "supported_media_types": { + "type": "array", + "items": { + "type": "string" + }, + "description": "MIME types the model accepts" + }, + "max_prompt_images": { + "type": "integer", + "minimum": 1, + "description": "Maximum number of images per prompt" + }, + "max_prompt_image_size": { + "type": "integer", + "minimum": 0, + "description": "Maximum image size in bytes" + } + }, + "additionalProperties": false, + "description": "Vision-specific limits", + "title": "ModelCapabilitiesOverrideLimitsVision" + }, + "ModelCapabilitiesOverrideSupports": { + "type": "object", + "properties": { + "vision": { + "type": "boolean", + "description": "Whether this model supports vision/image input" + }, + "reasoningEffort": { + "type": "boolean", + "description": "Whether this model supports reasoning effort configuration" + } + }, + "additionalProperties": false, + "description": "Feature flags indicating what the model supports", + "title": "ModelCapabilitiesOverrideSupports" + }, + "ModelCapabilitiesSupports": { + "type": "object", + "properties": { + "vision": { + "type": "boolean", + "description": "Whether this model supports vision/image input" + }, + "reasoningEffort": { + "type": "boolean", + "description": "Whether this model supports reasoning effort configuration" + } + }, + "additionalProperties": false, + "description": "Feature flags indicating what the model supports", + "title": "ModelCapabilitiesSupports" + }, + "ModelList": { + "type": "object", + "properties": { + "models": { + "type": "array", + "items": { + "$ref": "#/definitions/Model" + }, + "description": "List of available models with full metadata" + } + }, + "required": [ + "models" + ], + "additionalProperties": false, + "description": "List of Copilot models available to the resolved user, including capabilities and billing metadata.", + "title": "ModelList" + }, + "ModelPickerCategory": { + "type": "string", + "enum": [ + "lightweight", + "versatile", + "powerful" + ], + "description": "Model capability category for grouping in the model picker", + "title": "ModelPickerCategory", + "x-enumDescriptions": { + "lightweight": "Lightweight model category optimized for faster, lower-cost interactions.", + "versatile": "Versatile model category suitable for a broad range of tasks.", + "powerful": "Powerful model category optimized for complex tasks." + } + }, + "ModelPickerPriceCategory": { + "type": "string", + "enum": [ + "low", + "medium", + "high", + "very_high" + ], + "description": "Relative cost tier for token-based billing users", + "title": "ModelPickerPriceCategory", + "x-enumDescriptions": { + "low": "Lowest relative token cost tier.", + "medium": "Medium relative token cost tier.", + "high": "High relative token cost tier.", + "very_high": "Highest relative token cost tier." + } + }, + "ModelPolicy": { + "type": "object", + "properties": { + "state": { + "$ref": "#/definitions/ModelPolicyState", + "description": "Current policy state for this model" + }, + "terms": { + "type": "string", + "description": "Usage terms or conditions for this model" + } + }, + "required": [ + "state" + ], + "additionalProperties": false, + "description": "Policy state (if applicable)", + "title": "ModelPolicy" + }, + "ModelPolicyState": { + "type": "string", + "enum": [ + "enabled", + "disabled", + "unconfigured" + ], + "description": "Current policy state for this model", + "title": "ModelPolicyState", + "x-enumDescriptions": { + "enabled": "The model is enabled by policy.", + "disabled": "The model is disabled by policy.", + "unconfigured": "No explicit policy is configured for the model." + } + }, + "ModelSetReasoningEffortRequest": { + "type": "object", + "properties": { + "reasoningEffort": { + "type": "string", + "description": "Reasoning effort level to apply to the currently selected model. The host is responsible for validating the value against the model's supported levels before calling." + } + }, + "required": [ + "reasoningEffort" + ], + "additionalProperties": false, + "description": "Reasoning effort level to apply to the currently selected model.", + "title": "ModelSetReasoningEffortRequest" + }, + "ModelSetReasoningEffortResult": { + "type": "object", + "properties": { + "reasoningEffort": { + "type": "string", + "description": "Reasoning effort level recorded on the session after the update" + } + }, + "required": [ + "reasoningEffort" + ], + "additionalProperties": false, + "description": "Update the session's reasoning effort without changing the selected model. Use `switchTo` instead when you also need to change the model. The runtime stores the effort on the session and applies it to subsequent turns.", + "title": "ModelSetReasoningEffortResult" + }, + "ModelsListRequest": { + "anyOf": [ + { + "not": {} + }, + { + "type": "object", + "properties": { + "gitHubToken": { + "type": "string", + "description": "GitHub token for per-user model listing. When provided, resolves this token to determine the user's Copilot plan and available models instead of using the global auth." + } + }, + "additionalProperties": false + } + ], + "description": "Optional GitHub token used to list models for a specific user instead of the global auth context.", + "title": "ModelsListRequest" + }, + "ModelSwitchToRequest": { + "type": "object", + "properties": { + "modelId": { + "type": "string", + "description": "Model identifier to switch to" + }, + "reasoningEffort": { + "type": "string", + "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", + "description": "Override individual model capabilities resolved by the runtime" + } + }, + "required": [ + "modelId" + ], + "additionalProperties": false, + "description": "Target model identifier and optional reasoning effort, summary, and capability overrides.", + "title": "ModelSwitchToRequest" + }, + "ModelSwitchToResult": { + "type": "object", + "properties": { + "modelId": { + "type": "string", + "description": "Currently active model identifier after the switch" + } + }, + "additionalProperties": false, + "description": "The model identifier active on the session after the switch.", + "title": "ModelSwitchToResult" + }, + "ModeSetRequest": { + "type": "object", + "properties": { + "mode": { + "$ref": "#/definitions/SessionMode", + "description": "The session mode the agent is operating in" + } + }, + "required": [ + "mode" + ], + "additionalProperties": false, + "description": "Agent interaction mode to apply to the session.", + "title": "ModeSetRequest" + }, + "NameGetResult": { + "type": "object", + "properties": { + "name": { + "type": [ + "string", + "null" + ], + "description": "The session name (user-set or auto-generated), or null if not yet set" + } + }, + "required": [ + "name" + ], + "additionalProperties": false, + "description": "The session's friendly name, or null when not yet set.", + "title": "NameGetResult" + }, + "NameSetAutoRequest": { + "type": "object", + "properties": { + "summary": { + "type": "string", + "description": "Auto-generated session summary. Empty/whitespace-only values are ignored; values are trimmed before persisting." + } + }, + "required": [ + "summary" + ], + "additionalProperties": false, + "description": "Auto-generated session summary to apply as the session's name when no user-set name exists.", + "title": "NameSetAutoRequest" + }, + "NameSetAutoResult": { + "type": "object", + "properties": { + "applied": { + "type": "boolean", + "description": "Whether the auto-generated summary was persisted. False if the session already has a user-set name, the summary normalized to empty, or the session does not have a workspace." + } + }, + "required": [ + "applied" + ], + "additionalProperties": false, + "description": "Indicates whether the auto-generated summary was applied as the session's name.", + "title": "NameSetAutoResult" + }, + "NameSetRequest": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "description": "New session name (1–100 characters, trimmed of leading/trailing whitespace)" + } + }, + "required": [ + "name" + ], + "additionalProperties": false, + "description": "New friendly name to apply to the session.", + "title": "NameSetRequest" + }, + "OptionsUpdateEnvValueMode": { + "type": "string", + "enum": [ + "direct", + "indirect" + ], + "description": "How env values are passed to MCP servers (`direct` inlines literal values; `indirect` resolves at launch).", + "title": "OptionsUpdateEnvValueMode", + "x-enumDescriptions": { + "direct": "Pass MCP server environment values as literal strings.", + "indirect": "Resolve MCP server environment values from host-side references." + } + }, + "PendingPermissionRequest": { + "type": "object", + "properties": { + "requestId": { + "type": "string", + "description": "Unique identifier for the pending permission request" + }, + "request": { + "$ref": "session-events.schema.json#/definitions/PermissionPromptRequest", + "description": "The user-facing permission prompt details (commands, write, read, mcp, url, memory, custom-tool, path, hook)" + } + }, + "required": [ + "requestId", + "request" + ], + "additionalProperties": false, + "title": "PendingPermissionRequest", + "description": "Schema for the `PendingPermissionRequest` type." + }, + "PendingPermissionRequestList": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/definitions/PendingPermissionRequest" + }, + "description": "Pending permission prompts reconstructed from the session's event history. Equivalent to the set of `permission.requested` events that have not yet been followed by a matching `permission.completed` event. Used by clients (e.g. the CLI) to hydrate UI for prompts that were emitted before the client attached to the session." + } + }, + "required": [ + "items" + ], + "additionalProperties": false, + "description": "List of pending permission requests reconstructed from event history.", + "title": "PendingPermissionRequestList" + }, + "PermissionDecision": { + "anyOf": [ + { + "$ref": "#/definitions/PermissionDecisionApproveOnce" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForSession" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForLocation" + }, + { + "$ref": "#/definitions/PermissionDecisionApprovePermanently" + }, + { + "$ref": "#/definitions/PermissionDecisionReject" + }, + { + "$ref": "#/definitions/PermissionDecisionUserNotAvailable" + }, + { + "$ref": "#/definitions/PermissionDecisionApproved" + }, + { + "$ref": "#/definitions/PermissionDecisionApprovedForSession" + }, + { + "$ref": "#/definitions/PermissionDecisionApprovedForLocation" + }, + { + "$ref": "#/definitions/PermissionDecisionCancelled" + }, + { + "$ref": "#/definitions/PermissionDecisionDeniedByRules" + }, + { + "$ref": "#/definitions/PermissionDecisionDeniedNoApprovalRuleAndCouldNotRequestFromUser" + }, + { + "$ref": "#/definitions/PermissionDecisionDeniedInteractivelyByUser" + }, + { + "$ref": "#/definitions/PermissionDecisionDeniedByContentExclusionPolicy" + }, + { + "$ref": "#/definitions/PermissionDecisionDeniedByPermissionRequestHook" + } + ], + "description": "The client's response to the pending permission prompt", + "title": "PermissionDecision" + }, + "PermissionDecisionApproved": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "approved", + "description": "The permission request was approved" + } + }, + "required": [ + "kind" + ], + "additionalProperties": false, + "title": "PermissionDecisionApproved", + "description": "Schema for the `PermissionDecisionApproved` type." + }, + "PermissionDecisionApprovedForLocation": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "approved-for-location", + "description": "Approved and persisted for this project location" + }, + "approval": { + "$ref": "#/definitions/UserToolSessionApproval", + "description": "The approval to persist for this location" + }, + "locationKey": { + "type": "string", + "description": "The location key (git root or cwd) to persist the approval to" + } + }, + "required": [ + "kind", + "approval", + "locationKey" + ], + "additionalProperties": false, + "title": "PermissionDecisionApprovedForLocation", + "description": "Schema for the `PermissionDecisionApprovedForLocation` type." + }, + "PermissionDecisionApprovedForSession": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "approved-for-session", + "description": "Approved and remembered for the rest of the session" + }, + "approval": { + "$ref": "#/definitions/UserToolSessionApproval", + "description": "The approval to add as a session-scoped rule" + } + }, + "required": [ + "kind", + "approval" + ], + "additionalProperties": false, + "title": "PermissionDecisionApprovedForSession", + "description": "Schema for the `PermissionDecisionApprovedForSession` type." + }, + "PermissionDecisionApproveForLocation": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "approve-for-location", + "description": "Approve and persist for this project location" + }, + "approval": { + "$ref": "#/definitions/PermissionDecisionApproveForLocationApproval", + "description": "Approval to persist for this location" + }, + "locationKey": { + "type": "string", + "description": "Location key (git root or cwd) to persist the approval to" + } + }, + "required": [ + "kind", + "approval", + "locationKey" + ], + "additionalProperties": false, + "title": "PermissionDecisionApproveForLocation", + "description": "Schema for the `PermissionDecisionApproveForLocation` type." + }, + "PermissionDecisionApproveForLocationApproval": { + "anyOf": [ + { + "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalCommands" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalRead" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalWrite" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalMcp" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalMcpSampling" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalMemory" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalCustomTool" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalExtensionManagement" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalExtensionPermissionAccess" + } + ], + "description": "Approval to persist for this location", + "title": "PermissionDecisionApproveForLocationApproval" + }, + "PermissionDecisionApproveForLocationApprovalCommands": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "commands", + "description": "Approval scoped to specific command identifiers." + }, + "commandIdentifiers": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Command identifiers covered by this approval." + } + }, + "required": [ + "kind", + "commandIdentifiers" + ], + "additionalProperties": false, + "title": "PermissionDecisionApproveForLocationApprovalCommands", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalCommands` type." + }, + "PermissionDecisionApproveForLocationApprovalCustomTool": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "custom-tool", + "description": "Approval covering a custom tool." + }, + "toolName": { + "type": "string", + "description": "Custom tool name." + } + }, + "required": [ + "kind", + "toolName" + ], + "additionalProperties": false, + "title": "PermissionDecisionApproveForLocationApprovalCustomTool", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalCustomTool` type." + }, + "PermissionDecisionApproveForLocationApprovalExtensionManagement": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "extension-management", + "description": "Approval covering extension lifecycle operations such as enable, disable, or reload." + }, + "operation": { + "type": "string", + "description": "Optional operation identifier; when omitted, the approval covers all extension management operations." + } + }, + "required": [ + "kind" + ], + "additionalProperties": false, + "title": "PermissionDecisionApproveForLocationApprovalExtensionManagement", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalExtensionManagement` type." + }, + "PermissionDecisionApproveForLocationApprovalExtensionPermissionAccess": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "extension-permission-access", + "description": "Approval covering an extension's request to access a permission-gated capability." + }, + "extensionName": { + "type": "string", + "description": "Extension name." + } + }, + "required": [ + "kind", + "extensionName" + ], + "additionalProperties": false, + "title": "PermissionDecisionApproveForLocationApprovalExtensionPermissionAccess", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalExtensionPermissionAccess` type." + }, + "PermissionDecisionApproveForLocationApprovalMcp": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "mcp", + "description": "Approval covering an MCP tool." + }, + "serverName": { + "type": "string", + "description": "MCP server name." + }, + "toolName": { + "type": [ + "string", + "null" + ], + "description": "MCP tool name, or null to cover every tool on the server." + } + }, + "required": [ + "kind", + "serverName", + "toolName" + ], + "additionalProperties": false, + "title": "PermissionDecisionApproveForLocationApprovalMcp", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalMcp` type." + }, + "PermissionDecisionApproveForLocationApprovalMcpSampling": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "mcp-sampling", + "description": "Approval covering MCP sampling requests for a server." + }, + "serverName": { + "type": "string", + "description": "MCP server name." + } + }, + "required": [ + "kind", + "serverName" + ], + "additionalProperties": false, + "title": "PermissionDecisionApproveForLocationApprovalMcpSampling", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalMcpSampling` type." + }, + "PermissionDecisionApproveForLocationApprovalMemory": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "memory", + "description": "Approval covering writes to long-term memory." + } + }, + "required": [ + "kind" + ], + "additionalProperties": false, + "title": "PermissionDecisionApproveForLocationApprovalMemory", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalMemory` type." + }, + "PermissionDecisionApproveForLocationApprovalRead": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "read", + "description": "Approval covering read-only filesystem operations." + } + }, + "required": [ + "kind" + ], + "additionalProperties": false, + "title": "PermissionDecisionApproveForLocationApprovalRead", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalRead` type." + }, + "PermissionDecisionApproveForLocationApprovalWrite": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "write", + "description": "Approval covering filesystem write operations." + } + }, + "required": [ + "kind" + ], + "additionalProperties": false, + "title": "PermissionDecisionApproveForLocationApprovalWrite", + "description": "Schema for the `PermissionDecisionApproveForLocationApprovalWrite` type." + }, + "PermissionDecisionApproveForSession": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "approve-for-session", + "description": "Approve and remember for the rest of the session" + }, + "approval": { + "$ref": "#/definitions/PermissionDecisionApproveForSessionApproval", + "description": "Session-scoped approval to remember (tool prompts only; omitted for path/url prompts)" + }, + "domain": { + "type": "string", + "description": "URL domain to approve for the rest of the session (URL prompts only)" + } + }, + "required": [ + "kind" + ], + "additionalProperties": false, + "title": "PermissionDecisionApproveForSession", + "description": "Schema for the `PermissionDecisionApproveForSession` type." + }, + "PermissionDecisionApproveForSessionApproval": { + "anyOf": [ + { + "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalCommands" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalRead" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalWrite" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalMcp" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalMcpSampling" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalMemory" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalCustomTool" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalExtensionManagement" + }, + { + "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess" + } + ], + "description": "Session-scoped approval to remember (tool prompts only; omitted for path/url prompts)", + "title": "PermissionDecisionApproveForSessionApproval" + }, + "PermissionDecisionApproveForSessionApprovalCommands": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "commands", + "description": "Approval scoped to specific command identifiers." }, - { - "type": "object", - "properties": { - "gitHubToken": { - "type": "string", - "description": "GitHub token for per-user quota lookup. When provided, resolves this token to determine the user's quota instead of using the global auth." - } + "commandIdentifiers": { + "type": "array", + "items": { + "type": "string" }, - "additionalProperties": false + "description": "Command identifiers covered by this approval." } + }, + "required": [ + "kind", + "commandIdentifiers" ], - "description": "Optional GitHub token used to look up quota for a specific user instead of the global auth context.", - "title": "AccountGetQuotaRequest" + "additionalProperties": false, + "title": "PermissionDecisionApproveForSessionApprovalCommands", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalCommands` type." }, - "AccountGetQuotaResult": { + "PermissionDecisionApproveForSessionApprovalCustomTool": { "type": "object", "properties": { - "quotaSnapshots": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/AccountQuotaSnapshot" - }, - "description": "Quota snapshots keyed by type (e.g., chat, completions, premium_interactions)" + "kind": { + "type": "string", + "const": "custom-tool", + "description": "Approval covering a custom tool." + }, + "toolName": { + "type": "string", + "description": "Custom tool name." } }, "required": [ - "quotaSnapshots" + "kind", + "toolName" ], "additionalProperties": false, - "description": "Quota usage snapshots for the resolved user, keyed by quota type.", - "title": "AccountGetQuotaResult" + "title": "PermissionDecisionApproveForSessionApprovalCustomTool", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalCustomTool` type." }, - "AccountQuotaSnapshot": { + "PermissionDecisionApproveForSessionApprovalExtensionManagement": { "type": "object", "properties": { - "isUnlimitedEntitlement": { - "type": "boolean", - "description": "Whether the user has an unlimited usage entitlement" - }, - "entitlementRequests": { - "type": "integer", - "description": "Number of requests included in the entitlement, or -1 for unlimited entitlements" - }, - "usedRequests": { - "type": "integer", - "minimum": 0, - "description": "Number of requests used so far this period" - }, - "usageAllowedWithExhaustedQuota": { - "type": "boolean", - "description": "Whether usage is still permitted after quota exhaustion" - }, - "remainingPercentage": { - "type": "number", - "description": "Percentage of entitlement remaining" - }, - "overage": { - "type": "number", - "minimum": 0, - "description": "Number of overage requests made this period" - }, - "overageAllowedWithExhaustedQuota": { - "type": "boolean", - "description": "Whether overage is allowed when quota is exhausted" + "kind": { + "type": "string", + "const": "extension-management", + "description": "Approval covering extension lifecycle operations such as enable, disable, or reload." }, - "resetDate": { + "operation": { "type": "string", - "format": "date-time", - "description": "Date when the quota resets (ISO 8601 string)" + "description": "Optional operation identifier; when omitted, the approval covers all extension management operations." } }, "required": [ - "isUnlimitedEntitlement", - "entitlementRequests", - "usedRequests", - "usageAllowedWithExhaustedQuota", - "remainingPercentage", - "overage", - "overageAllowedWithExhaustedQuota" + "kind" ], "additionalProperties": false, - "title": "AccountQuotaSnapshot", - "description": "Schema for the `AccountQuotaSnapshot` type." + "title": "PermissionDecisionApproveForSessionApprovalExtensionManagement", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalExtensionManagement` type." }, - "AgentGetCurrentResult": { + "PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess": { "type": "object", "properties": { - "agent": { - "$ref": "#/definitions/AgentInfo", - "description": "Currently selected custom agent, or null if using the default agent" + "kind": { + "type": "string", + "const": "extension-permission-access", + "description": "Approval covering an extension's request to access a permission-gated capability." + }, + "extensionName": { + "type": "string", + "description": "Extension name." } }, "required": [ - "agent" + "kind", + "extensionName" ], "additionalProperties": false, - "description": "The currently selected custom agent, or null when using the default agent.", - "title": "AgentGetCurrentResult" + "title": "PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess` type." }, - "AgentInfo": { + "PermissionDecisionApproveForSessionApprovalMcp": { "type": "object", "properties": { - "name": { + "kind": { "type": "string", - "description": "Unique identifier of the custom agent" + "const": "mcp", + "description": "Approval covering an MCP tool." }, - "displayName": { + "serverName": { "type": "string", - "description": "Human-readable display name" + "description": "MCP server name." }, - "description": { + "toolName": { + "type": [ + "string", + "null" + ], + "description": "MCP tool name, or null to cover every tool on the server." + } + }, + "required": [ + "kind", + "serverName", + "toolName" + ], + "additionalProperties": false, + "title": "PermissionDecisionApproveForSessionApprovalMcp", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalMcp` type." + }, + "PermissionDecisionApproveForSessionApprovalMcpSampling": { + "type": "object", + "properties": { + "kind": { "type": "string", - "description": "Description of the agent's purpose" + "const": "mcp-sampling", + "description": "Approval covering MCP sampling requests for a server." }, - "path": { + "serverName": { "type": "string", - "description": "Absolute local file path of the agent definition. Only set for file-based agents loaded from disk; remote agents do not have a path." + "description": "MCP server name." } }, "required": [ - "name", - "displayName", - "description" + "kind", + "serverName" ], "additionalProperties": false, - "title": "AgentInfo", - "description": "Schema for the `AgentInfo` type." + "title": "PermissionDecisionApproveForSessionApprovalMcpSampling", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalMcpSampling` type." }, - "AgentList": { + "PermissionDecisionApproveForSessionApprovalMemory": { "type": "object", "properties": { - "agents": { - "type": "array", - "items": { - "$ref": "#/definitions/AgentInfo" - }, - "description": "Available custom agents" + "kind": { + "type": "string", + "const": "memory", + "description": "Approval covering writes to long-term memory." } }, "required": [ - "agents" + "kind" ], "additionalProperties": false, - "description": "Custom agents available to the session.", - "title": "AgentList" + "title": "PermissionDecisionApproveForSessionApprovalMemory", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalMemory` type." }, - "AgentReloadResult": { + "PermissionDecisionApproveForSessionApprovalRead": { "type": "object", "properties": { - "agents": { - "type": "array", - "items": { - "$ref": "#/definitions/AgentInfo" - }, - "description": "Reloaded custom agents" + "kind": { + "type": "string", + "const": "read", + "description": "Approval covering read-only filesystem operations." } }, "required": [ - "agents" + "kind" ], "additionalProperties": false, - "description": "Custom agents available to the session after reloading definitions from disk.", - "title": "AgentReloadResult" + "title": "PermissionDecisionApproveForSessionApprovalRead", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalRead` type." }, - "AgentSelectRequest": { + "PermissionDecisionApproveForSessionApprovalWrite": { "type": "object", "properties": { - "name": { + "kind": { "type": "string", - "description": "Name of the custom agent to select" + "const": "write", + "description": "Approval covering filesystem write operations." } }, "required": [ - "name" + "kind" ], "additionalProperties": false, - "description": "Name of the custom agent to select for subsequent turns.", - "title": "AgentSelectRequest" + "title": "PermissionDecisionApproveForSessionApprovalWrite", + "description": "Schema for the `PermissionDecisionApproveForSessionApprovalWrite` type." }, - "AgentSelectResult": { + "PermissionDecisionApproveOnce": { "type": "object", "properties": { - "agent": { - "$ref": "#/definitions/AgentInfo", - "description": "The newly selected custom agent" + "kind": { + "type": "string", + "const": "approve-once", + "description": "Approve this single request only" } }, "required": [ - "agent" + "kind" ], "additionalProperties": false, - "description": "The newly selected custom agent.", - "title": "AgentSelectResult" - }, - "AuthInfoType": { - "type": "string", - "enum": [ - "hmac", - "env", - "user", - "gh-cli", - "api-key", - "token", - "copilot-api-token" - ], - "description": "Authentication type", - "title": "AuthInfoType" + "title": "PermissionDecisionApproveOnce", + "description": "Schema for the `PermissionDecisionApproveOnce` type." }, - "CommandList": { + "PermissionDecisionApprovePermanently": { "type": "object", "properties": { - "commands": { - "type": "array", - "items": { - "$ref": "#/definitions/SlashCommandInfo" - }, - "description": "Commands available in this session" + "kind": { + "type": "string", + "const": "approve-permanently", + "description": "Approve and persist across sessions (URL prompts only)" + }, + "domain": { + "type": "string", + "description": "URL domain to approve permanently" } }, "required": [ - "commands" + "kind", + "domain" ], "additionalProperties": false, - "description": "Slash commands available in the session, after applying any include/exclude filters.", - "title": "CommandList" + "title": "PermissionDecisionApprovePermanently", + "description": "Schema for the `PermissionDecisionApprovePermanently` type." }, - "CommandsHandlePendingCommandRequest": { + "PermissionDecisionCancelled": { "type": "object", "properties": { - "requestId": { + "kind": { "type": "string", - "description": "Request ID from the command invocation event" + "const": "cancelled", + "description": "The permission request was cancelled before a response was used" }, - "error": { + "reason": { "type": "string", - "description": "Error message if the command handler failed" + "description": "Optional explanation of why the request was cancelled" } }, "required": [ - "requestId" + "kind" ], "additionalProperties": false, - "description": "Pending command request ID and an optional error if the client handler failed.", - "title": "CommandsHandlePendingCommandRequest" + "title": "PermissionDecisionCancelled", + "description": "Schema for the `PermissionDecisionCancelled` type." }, - "CommandsHandlePendingCommandResult": { + "PermissionDecisionDeniedByContentExclusionPolicy": { "type": "object", "properties": { - "success": { - "type": "boolean", - "description": "Whether the command was handled successfully" + "kind": { + "type": "string", + "const": "denied-by-content-exclusion-policy", + "description": "Denied by the organization's content exclusion policy" + }, + "path": { + "type": "string", + "description": "File path that triggered the exclusion" + }, + "message": { + "type": "string", + "description": "Human-readable explanation of why the path was excluded" } }, "required": [ - "success" + "kind", + "path", + "message" ], "additionalProperties": false, - "description": "Indicates whether the pending client-handled command was completed successfully.", - "title": "CommandsHandlePendingCommandResult" + "title": "PermissionDecisionDeniedByContentExclusionPolicy", + "description": "Schema for the `PermissionDecisionDeniedByContentExclusionPolicy` type." }, - "CommandsInvokeRequest": { + "PermissionDecisionDeniedByPermissionRequestHook": { "type": "object", "properties": { - "name": { + "kind": { "type": "string", - "description": "Command name. Leading slashes are stripped and the name is matched case-insensitively." + "const": "denied-by-permission-request-hook", + "description": "Denied by a permission request hook registered by an extension or plugin" }, - "input": { + "message": { "type": "string", - "description": "Raw input after the command name" + "description": "Optional message from the hook explaining the denial" + }, + "interrupt": { + "type": "boolean", + "description": "Whether to interrupt the current agent turn" } }, "required": [ - "name" + "kind" ], "additionalProperties": false, - "description": "Slash command name and optional raw input string to invoke.", - "title": "CommandsInvokeRequest" + "title": "PermissionDecisionDeniedByPermissionRequestHook", + "description": "Schema for the `PermissionDecisionDeniedByPermissionRequestHook` type." }, - "CommandsListRequest": { - "anyOf": [ - { - "not": {} + "PermissionDecisionDeniedByRules": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "denied-by-rules", + "description": "Denied because approval rules explicitly blocked it" }, - { - "type": "object", - "properties": { - "includeBuiltins": { - "type": "boolean", - "description": "Include runtime built-in commands" - }, - "includeSkills": { - "type": "boolean", - "description": "Include enabled user-invocable skills and commands" - }, - "includeClientCommands": { - "type": "boolean", - "description": "Include commands registered by protocol clients, including SDK clients and extensions" - } + "rules": { + "type": "array", + "items": { + "$ref": "#/definitions/PermissionRule" }, - "additionalProperties": false + "description": "Rules that denied the request" } + }, + "required": [ + "kind", + "rules" ], - "description": "Optional filters controlling which command sources to include in the listing.", - "title": "CommandsListRequest" + "additionalProperties": false, + "title": "PermissionDecisionDeniedByRules", + "description": "Schema for the `PermissionDecisionDeniedByRules` type." }, - "CommandsRespondToQueuedCommandRequest": { + "PermissionDecisionDeniedInteractivelyByUser": { "type": "object", "properties": { - "requestId": { + "kind": { "type": "string", - "description": "Request ID from the queued command event" + "const": "denied-interactively-by-user", + "description": "Denied by the user during an interactive prompt" }, - "result": { - "$ref": "#/definitions/QueuedCommandResult", - "description": "Result of the queued command execution" + "feedback": { + "type": "string", + "description": "Optional feedback from the user explaining the denial" + }, + "forceReject": { + "type": "boolean", + "description": "Whether to force-reject the current agent turn" } }, "required": [ - "requestId", - "result" + "kind" ], "additionalProperties": false, - "description": "Queued command request ID and the result indicating whether the client handled it.", - "title": "CommandsRespondToQueuedCommandRequest" + "title": "PermissionDecisionDeniedInteractivelyByUser", + "description": "Schema for the `PermissionDecisionDeniedInteractivelyByUser` type." }, - "CommandsRespondToQueuedCommandResult": { + "PermissionDecisionDeniedNoApprovalRuleAndCouldNotRequestFromUser": { "type": "object", "properties": { - "success": { - "type": "boolean", - "description": "Whether the response was accepted (false if the requestId was not found or already resolved)" + "kind": { + "type": "string", + "const": "denied-no-approval-rule-and-could-not-request-from-user", + "description": "Denied because no approval rule matched and user confirmation was unavailable" } }, "required": [ - "success" + "kind" ], "additionalProperties": false, - "description": "Indicates whether the queued-command response was accepted by the session.", - "title": "CommandsRespondToQueuedCommandResult" + "title": "PermissionDecisionDeniedNoApprovalRuleAndCouldNotRequestFromUser", + "description": "Schema for the `PermissionDecisionDeniedNoApprovalRuleAndCouldNotRequestFromUser` type." }, - "ConnectedRemoteSessionMetadata": { + "PermissionDecisionReject": { "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", - "format": "date-time", - "description": "Session start time as an ISO 8601 string." - }, - "modifiedTime": { - "type": "string", - "format": "date-time", - "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", - "format": "date-time", - "description": "Remote session staleness deadline as an ISO 8601 string." + "const": "reject", + "description": "Reject the request" }, - "state": { + "feedback": { "type": "string", - "description": "Remote session state returned by the backing service." + "description": "Optional feedback explaining the rejection" } }, "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" + "title": "PermissionDecisionReject", + "description": "Schema for the `PermissionDecisionReject` type." }, - "ConnectedRemoteSessionMetadataRepository": { + "PermissionDecisionRequest": { "type": "object", "properties": { - "owner": { - "type": "string", - "description": "Repository owner or organization login." - }, - "name": { + "requestId": { "type": "string", - "description": "Repository name." + "description": "Request ID of the pending permission request" }, - "branch": { - "type": "string", - "description": "Branch associated with the remote session." + "result": { + "$ref": "#/definitions/PermissionDecision", + "description": "The client's response to the pending permission prompt" } }, "required": [ - "owner", - "name", - "branch" + "requestId", + "result" ], "additionalProperties": false, - "description": "Repository associated with the connected remote session.", - "title": "ConnectedRemoteSessionMetadataRepository" + "description": "Pending permission request ID and the decision to apply (approve/reject and scope).", + "title": "PermissionDecisionRequest" }, - "ConnectRemoteSessionParams": { + "PermissionDecisionUserNotAvailable": { "type": "object", "properties": { - "sessionId": { + "kind": { "type": "string", - "description": "Session ID to connect to." + "const": "user-not-available", + "description": "No user is available to confirm the request" } }, "required": [ - "sessionId" + "kind" ], "additionalProperties": false, - "description": "Remote session connection parameters.", - "title": "ConnectRemoteSessionParams" + "title": "PermissionDecisionUserNotAvailable", + "description": "Schema for the `PermissionDecisionUserNotAvailable` type." }, - "ConnectRequest": { + "PermissionLocationAddToolApprovalParams": { "type": "object", "properties": { - "token": { + "locationKey": { "type": "string", - "description": "Connection token; required when the server was started with COPILOT_CONNECTION_TOKEN" + "description": "Location key (git root or cwd) to persist the approval to" + }, + "approval": { + "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetails", + "description": "Tool approval to persist and apply" } }, + "required": [ + "locationKey", + "approval" + ], "additionalProperties": false, - "description": "Optional connection token presented by the SDK client during the handshake.", - "title": "ConnectRequest", - "visibility": "internal" + "description": "Location-scoped tool approval to persist.", + "title": "PermissionLocationAddToolApprovalParams" }, - "ConnectResult": { + "PermissionLocationApplyParams": { "type": "object", "properties": { - "ok": { - "type": "boolean", - "const": true, - "description": "Always true on success" - }, - "protocolVersion": { - "type": "integer", - "description": "Server protocol version number" - }, - "version": { + "workingDirectory": { "type": "string", - "description": "Server package version" + "description": "Working directory whose persisted location permissions should be applied" } }, "required": [ - "ok", - "protocolVersion", - "version" + "workingDirectory" ], "additionalProperties": false, - "description": "Handshake result reporting the server's protocol version and package version on success.", - "title": "ConnectResult", - "visibility": "internal" + "description": "Working directory to load persisted location permissions for.", + "title": "PermissionLocationApplyParams" }, - "ContentFilterMode": { - "type": "string", - "enum": [ - "none", - "markdown", - "hidden_characters" + "PermissionLocationApplyResult": { + "type": "object", + "properties": { + "locationKey": { + "type": "string", + "description": "Location key used in the location-permissions store" + }, + "locationType": { + "$ref": "#/definitions/PermissionLocationType", + "description": "Whether the location is a git repo or directory" + }, + "changed": { + "type": "boolean", + "description": "Whether a different location was applied since the previous apply call" + }, + "appliedRuleCount": { + "type": "integer", + "minimum": 0, + "description": "Number of location-scoped rules added to the live permission service" + }, + "appliedDirectoryCount": { + "type": "integer", + "minimum": 0, + "description": "Number of persisted allowed directories added to the live path manager" + }, + "appliedRules": { + "type": "array", + "items": { + "$ref": "#/definitions/PermissionRule" + }, + "description": "Location-scoped rules applied to the live permission service" + } + }, + "required": [ + "locationKey", + "locationType", + "changed", + "appliedRuleCount", + "appliedDirectoryCount", + "appliedRules" ], - "description": "Controls how MCP tool result content is filtered: none leaves content unchanged, markdown sanitizes HTML while preserving Markdown-friendly output, and hidden_characters removes characters that can hide directives.", - "title": "ContentFilterMode" + "additionalProperties": false, + "description": "Summary of persisted location permissions applied to the session.", + "title": "PermissionLocationApplyResult" }, - "CurrentModel": { + "PermissionLocationResolveParams": { "type": "object", "properties": { - "modelId": { + "workingDirectory": { "type": "string", - "description": "Currently active model identifier" + "description": "Working directory whose permission location should be resolved" } }, + "required": [ + "workingDirectory" + ], "additionalProperties": false, - "description": "The currently selected model for the session.", - "title": "CurrentModel" + "description": "Working directory to resolve into a location-permissions key.", + "title": "PermissionLocationResolveParams" }, - "DiscoveredMcpServer": { + "PermissionLocationResolveResult": { "type": "object", "properties": { - "name": { + "locationKey": { "type": "string", - "minLength": 1, - "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", - "description": "Server name (config key)" + "description": "Location key used in the location-permissions store" }, - "type": { - "$ref": "#/definitions/DiscoveredMcpServerType", - "description": "Server transport type: stdio, http, sse, or memory" - }, - "source": { - "$ref": "#/definitions/McpServerSource", - "description": "Configuration source: user, workspace, plugin, or builtin" - }, - "enabled": { - "type": "boolean", - "description": "Whether the server is enabled (not in the disabled list)" + "locationType": { + "$ref": "#/definitions/PermissionLocationType", + "description": "Whether the location is a git repo or directory" } }, "required": [ - "name", - "source", - "enabled" + "locationKey", + "locationType" ], "additionalProperties": false, - "title": "DiscoveredMcpServer", - "description": "Schema for the `DiscoveredMcpServer` type." + "description": "Resolved location-permissions key and type.", + "title": "PermissionLocationResolveResult" }, - "DiscoveredMcpServerType": { + "PermissionLocationType": { "type": "string", "enum": [ - "stdio", - "http", - "sse", - "memory" + "repo", + "dir" ], - "description": "Server transport type: stdio, http, sse, or memory", - "title": "DiscoveredMcpServerType" + "description": "Whether the location is a git repo or directory", + "title": "PermissionLocationType", + "x-enumDescriptions": { + "repo": "The permission location is persisted at the git repository root.", + "dir": "The permission location is persisted at the working directory." + } }, - "EmbeddedBlobResourceContents": { + "PermissionPathsAddParams": { "type": "object", "properties": { - "uri": { - "type": "string", - "description": "URI identifying the resource" - }, - "mimeType": { - "type": "string", - "description": "MIME type of the blob content" - }, - "blob": { + "path": { "type": "string", - "description": "Base64-encoded binary content of the resource", - "contentEncoding": "base64" + "description": "Directory to add to the allow-list. The runtime resolves and validates the path before adding." } }, "required": [ - "uri", - "blob" + "path" ], "additionalProperties": false, - "title": "EmbeddedBlobResourceContents", - "description": "Schema for the `EmbeddedBlobResourceContents` type." + "description": "Directory path to add to the session's allowed directories.", + "title": "PermissionPathsAddParams" }, - "EmbeddedTextResourceContents": { + "PermissionPathsAllowedCheckParams": { "type": "object", "properties": { - "uri": { - "type": "string", - "description": "URI identifying the resource" - }, - "mimeType": { - "type": "string", - "description": "MIME type of the text content" - }, - "text": { + "path": { "type": "string", - "description": "Text content of the resource" + "description": "Path to check against the session's allowed directories" } }, "required": [ - "uri", - "text" + "path" ], "additionalProperties": false, - "title": "EmbeddedTextResourceContents", - "description": "Schema for the `EmbeddedTextResourceContents` type." + "description": "Path to evaluate against the session's allowed directories.", + "title": "PermissionPathsAllowedCheckParams" }, - "Extension": { + "PermissionPathsAllowedCheckResult": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Source-qualified ID (e.g., 'project:my-ext', 'user:auth-helper')" - }, - "name": { - "type": "string", - "description": "Extension name (directory name)" + "allowed": { + "type": "boolean", + "description": "Whether the path is within the session's allowed directories" + } + }, + "required": [ + "allowed" + ], + "additionalProperties": false, + "description": "Indicates whether the supplied path is within the session's allowed directories.", + "title": "PermissionPathsAllowedCheckResult" + }, + "PermissionPathsConfig": { + "type": "object", + "properties": { + "unrestricted": { + "type": "boolean", + "description": "If true, the runtime allows access to all paths without prompting. Equivalent to constructing an UnrestrictedPathManager." }, - "source": { - "$ref": "#/definitions/ExtensionSource", - "description": "Discovery source: project (.github/extensions/) or user (~/.copilot/extensions/)" + "additionalDirectories": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Additional directories to allow tool access to (in addition to the session's working directory). When `unrestricted` is true, these are still pre-populated on the UnrestrictedPathManager so they remain visible via getDirectories() (e.g. for @-mention completion)." }, - "status": { - "$ref": "#/definitions/ExtensionStatus", - "description": "Current status: running, disabled, failed, or starting" + "includeTempDirectory": { + "type": "boolean", + "description": "Whether to include the system temp directory in the allowed list (defaults to true). Ignored when `unrestricted` is true." }, - "pid": { - "type": "integer", - "description": "Process ID if the extension is running" + "workspacePath": { + "type": "string", + "description": "Workspace root path (special-cased to be allowed even before the directory exists). Ignored when `unrestricted` is true." } }, - "required": [ - "id", - "name", - "source", - "status" - ], "additionalProperties": false, - "title": "Extension", - "description": "Schema for the `Extension` type." + "description": "If specified, replaces the session's path-permission policy. The runtime constructs the appropriate PathManager based on these inputs (rooted at the session's working directory). Omit to leave the current path policy unchanged.", + "title": "PermissionPathsConfig" }, - "ExtensionList": { + "PermissionPathsList": { "type": "object", "properties": { - "extensions": { + "directories": { "type": "array", "items": { - "$ref": "#/definitions/Extension" + "type": "string" }, - "description": "Discovered extensions and their current status" + "description": "All directories currently allowed for tool access on this session." + }, + "primary": { + "type": "string", + "description": "The primary working directory for this session." } }, "required": [ - "extensions" + "directories", + "primary" ], "additionalProperties": false, - "description": "Extensions discovered for the session, with their current status.", - "title": "ExtensionList" + "description": "Snapshot of the session's allow-listed directories and primary working directory.", + "title": "PermissionPathsList" }, - "ExtensionsDisableRequest": { + "PermissionPathsUpdatePrimaryParams": { "type": "object", "properties": { - "id": { + "path": { "type": "string", - "description": "Source-qualified extension ID to disable" + "description": "Directory to set as the new primary working directory for the session's permission policy." } }, "required": [ - "id" + "path" ], "additionalProperties": false, - "description": "Source-qualified extension identifier to disable for the session.", - "title": "ExtensionsDisableRequest" + "description": "Directory path to set as the session's new primary working directory.", + "title": "PermissionPathsUpdatePrimaryParams" }, - "ExtensionsEnableRequest": { + "PermissionPathsWorkspaceCheckParams": { "type": "object", "properties": { - "id": { + "path": { "type": "string", - "description": "Source-qualified extension ID to enable" + "description": "Path to check against the session workspace directory" } }, "required": [ - "id" + "path" ], "additionalProperties": false, - "description": "Source-qualified extension identifier to enable for the session.", - "title": "ExtensionsEnableRequest" + "description": "Path to evaluate against the session's workspace (primary) directory.", + "title": "PermissionPathsWorkspaceCheckParams" }, - "ExtensionSource": { - "type": "string", - "enum": [ - "project", - "user" + "PermissionPathsWorkspaceCheckResult": { + "type": "object", + "properties": { + "allowed": { + "type": "boolean", + "description": "Whether the path is within the session workspace directory" + } + }, + "required": [ + "allowed" ], - "description": "Discovery source: project (.github/extensions/) or user (~/.copilot/extensions/)", - "title": "ExtensionSource" + "additionalProperties": false, + "description": "Indicates whether the supplied path is within the session's workspace directory.", + "title": "PermissionPathsWorkspaceCheckResult" }, - "ExtensionStatus": { - "type": "string", - "enum": [ - "running", - "disabled", - "failed", - "starting" + "PermissionPromptShownNotification": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Human-readable description of the prompt the user is being asked to approve. Used by the runtime to fire the registered `permission_prompt` notification hook (e.g. terminal bell, desktop notification)." + } + }, + "required": [ + "message" ], - "description": "Current status: running, disabled, failed, or starting", - "title": "ExtensionStatus" + "additionalProperties": false, + "description": "Notification payload describing the permission prompt that the client just rendered.", + "title": "PermissionPromptShownNotification" }, - "ExternalToolResult": { - "anyOf": [ - { - "type": "string", - "description": "Simple string tool result" - }, - { - "$ref": "#/definitions/ExternalToolTextResultForLlm", - "description": "Expanded external tool result payload" + "PermissionRequestResult": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Whether the permission request was handled successfully" } + }, + "required": [ + "success" ], - "description": "Tool call result (string or expanded result object)", - "title": "ExternalToolResult" + "additionalProperties": false, + "description": "Indicates whether the permission decision was applied; false when the request was already resolved.", + "title": "PermissionRequestResult" }, - "ExternalToolTextResultForLlm": { + "PermissionRule": { "type": "object", "properties": { - "textResultForLlm": { + "kind": { "type": "string", - "description": "Text result returned to the model" + "description": "The rule kind, such as Shell or GitHubMCP" }, - "resultType": { - "type": "string", - "description": "Execution outcome classification. Optional for back-compat; normalized to 'success' (or 'failure' when error is present) when missing or unrecognized." + "argument": { + "type": [ + "string", + "null" + ], + "description": "Argument value matched against the request, or null when the rule kind has no argument (e.g. 'read', 'write', 'memory')." + } + }, + "required": [ + "kind", + "argument" + ], + "additionalProperties": false, + "title": "PermissionRule", + "description": "Schema for the `PermissionRule` type." + }, + "PermissionRulesSet": { + "type": "object", + "properties": { + "approved": { + "type": "array", + "items": { + "$ref": "#/definitions/PermissionRule" + }, + "description": "Rules that auto-approve matching requests" }, - "error": { - "type": "string", - "description": "Optional error message for failed executions" + "denied": { + "type": "array", + "items": { + "$ref": "#/definitions/PermissionRule" + }, + "description": "Rules that auto-deny matching requests" + } + }, + "required": [ + "approved", + "denied" + ], + "additionalProperties": false, + "description": "If specified, replaces the session's approved/denied permission rules. Omit to leave the current rules unchanged.", + "title": "PermissionRulesSet" + }, + "PermissionsConfigureAdditionalContentExclusionPolicy": { + "type": "object", + "properties": { + "rules": { + "type": "array", + "items": { + "$ref": "#/definitions/PermissionsConfigureAdditionalContentExclusionPolicyRule" + } }, - "sessionLog": { - "type": "string", - "description": "Detailed log content for timeline display" + "last_updated_at": { + "type": [ + "string", + "number" + ] }, - "toolTelemetry": { - "type": "object", - "additionalProperties": {}, - "description": "Optional tool-specific telemetry" + "scope": { + "$ref": "#/definitions/PermissionsConfigureAdditionalContentExclusionPolicyScope", + "description": "Allowed values for the `PermissionsConfigureAdditionalContentExclusionPolicyScope` enumeration." + } + }, + "required": [ + "rules", + "last_updated_at", + "scope" + ], + "additionalProperties": true, + "title": "PermissionsConfigureAdditionalContentExclusionPolicy", + "description": "Schema for the `PermissionsConfigureAdditionalContentExclusionPolicy` type." + }, + "PermissionsConfigureAdditionalContentExclusionPolicyRule": { + "type": "object", + "properties": { + "paths": { + "type": "array", + "items": { + "type": "string" + } }, - "binaryResultsForLlm": { + "ifAnyMatch": { "type": "array", "items": { - "$ref": "#/definitions/ExternalToolTextResultForLlmBinaryResultsForLlm", - "description": "Binary result returned by a tool for the model" - }, - "description": "Base64-encoded binary results returned to the model" + "type": "string" + } }, - "contents": { + "ifNoneMatch": { "type": "array", "items": { - "$ref": "#/definitions/ExternalToolTextResultForLlmContent", - "description": "A content block within a tool result, which may be text, terminal output, image, audio, or a resource" - }, - "description": "Structured content blocks from the tool" + "type": "string" + } + }, + "source": { + "$ref": "#/definitions/PermissionsConfigureAdditionalContentExclusionPolicyRuleSource", + "description": "Schema for the `PermissionsConfigureAdditionalContentExclusionPolicyRuleSource` type." } }, "required": [ - "textResultForLlm" + "paths", + "source" ], "additionalProperties": true, - "description": "Expanded external tool result payload", - "title": "ExternalToolTextResultForLlm" + "title": "PermissionsConfigureAdditionalContentExclusionPolicyRule", + "description": "Schema for the `PermissionsConfigureAdditionalContentExclusionPolicyRule` type." }, - "ExternalToolTextResultForLlmBinaryResultsForLlm": { + "PermissionsConfigureAdditionalContentExclusionPolicyRuleSource": { "type": "object", "properties": { + "name": { + "type": "string" + }, "type": { - "$ref": "#/definitions/ExternalToolTextResultForLlmBinaryResultsForLlmType", - "description": "Binary result type discriminator. Use \"image\" for images and \"resource\" for other binary data." + "type": "string" + } + }, + "required": [ + "name", + "type" + ], + "additionalProperties": false, + "title": "PermissionsConfigureAdditionalContentExclusionPolicyRuleSource", + "description": "Schema for the `PermissionsConfigureAdditionalContentExclusionPolicyRuleSource` type." + }, + "PermissionsConfigureAdditionalContentExclusionPolicyScope": { + "type": "string", + "enum": [ + "repo", + "all" + ], + "title": "PermissionsConfigureAdditionalContentExclusionPolicyScope", + "x-enumDescriptions": { + "repo": "The content exclusion policy applies to the current repository.", + "all": "The content exclusion policy applies across all repositories." + }, + "description": "Allowed values for the `PermissionsConfigureAdditionalContentExclusionPolicyScope` enumeration." + }, + "PermissionsConfigureParams": { + "type": "object", + "properties": { + "approveAllToolPermissionRequests": { + "type": "boolean", + "description": "If specified, sets whether tool permission requests are auto-approved without prompting. Omit to leave the current value unchanged." }, - "data": { - "type": "string", - "description": "Base64-encoded binary data", - "contentEncoding": "base64" + "approveAllReadPermissionRequests": { + "type": "boolean", + "description": "If specified, sets whether path/URL read permission requests are auto-approved. Omit to leave the current value unchanged." }, - "mimeType": { - "type": "string", - "description": "MIME type of the binary data" + "rules": { + "$ref": "#/definitions/PermissionRulesSet", + "description": "If specified, replaces the session's approved/denied permission rules. Omit to leave the current rules unchanged." }, - "description": { - "type": "string", - "description": "Human-readable description of the binary data" + "paths": { + "$ref": "#/definitions/PermissionPathsConfig", + "description": "If specified, replaces the session's path-permission policy. The runtime constructs the appropriate PathManager based on these inputs (rooted at the session's working directory). Omit to leave the current path policy unchanged." + }, + "urls": { + "$ref": "#/definitions/PermissionUrlsConfig", + "description": "If specified, replaces the session's URL-permission policy. The runtime constructs a fresh DefaultUrlManager based on these inputs. Omit to leave the current URL policy unchanged." + }, + "additionalContentExclusionPolicies": { + "type": "array", + "items": { + "$ref": "#/definitions/PermissionsConfigureAdditionalContentExclusionPolicy" + }, + "description": "If specified, replaces the host-supplied GitHub Content Exclusion policies on the session (combined with natively-discovered policies when evaluating tool/file access). Omit to leave the current policies unchanged." + } + }, + "additionalProperties": false, + "description": "Patch of permission policy fields to apply (omit a field to leave it unchanged).", + "title": "PermissionsConfigureParams" + }, + "PermissionsConfigureResult": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Whether the operation succeeded" } }, "required": [ - "type", - "data", - "mimeType" + "success" ], "additionalProperties": false, - "description": "Binary result returned by a tool for the model", - "title": "ExternalToolTextResultForLlmBinaryResultsForLlm" + "description": "Indicates whether the operation succeeded.", + "title": "PermissionsConfigureResult" }, - "ExternalToolTextResultForLlmBinaryResultsForLlmType": { - "type": "string", - "enum": [ - "image", - "resource" + "PermissionsFolderTrustAddTrustedResult": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Whether the operation succeeded" + } + }, + "required": [ + "success" ], - "description": "Binary result type discriminator. Use \"image\" for images and \"resource\" for other binary data.", - "title": "ExternalToolTextResultForLlmBinaryResultsForLlmType" + "additionalProperties": false, + "description": "Indicates whether the operation succeeded.", + "title": "PermissionsFolderTrustAddTrustedResult" }, - "ExternalToolTextResultForLlmContent": { + "PermissionsLocationsAddToolApprovalDetails": { "anyOf": [ { - "$ref": "#/definitions/ExternalToolTextResultForLlmContentText", - "description": "Plain text content block" + "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsCommands" }, { - "$ref": "#/definitions/ExternalToolTextResultForLlmContentTerminal", - "description": "Terminal/shell output content block with optional exit code and working directory" + "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsRead" }, { - "$ref": "#/definitions/ExternalToolTextResultForLlmContentImage", - "description": "Image content block with base64-encoded data" + "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsWrite" }, { - "$ref": "#/definitions/ExternalToolTextResultForLlmContentAudio", - "description": "Audio content block with base64-encoded data" + "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsMcp" }, { - "$ref": "#/definitions/ExternalToolTextResultForLlmContentResourceLink", - "description": "Resource link content block referencing an external resource" + "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsMcpSampling" }, { - "$ref": "#/definitions/ExternalToolTextResultForLlmContentResource", - "description": "Embedded resource content block with inline text or binary data" + "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsMemory" + }, + { + "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsCustomTool" + }, + { + "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsExtensionManagement" + }, + { + "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsExtensionPermissionAccess" } ], - "description": "A content block within a tool result, which may be text, terminal output, image, audio, or a resource", - "title": "ExternalToolTextResultForLlmContent" + "description": "Tool approval to persist and apply", + "title": "PermissionsLocationsAddToolApprovalDetails" }, - "ExternalToolTextResultForLlmContentAudio": { + "PermissionsLocationsAddToolApprovalDetailsCommands": { "type": "object", "properties": { - "type": { - "type": "string", - "const": "audio", - "description": "Content block type discriminator" - }, - "data": { + "kind": { "type": "string", - "description": "Base64-encoded audio data", - "contentEncoding": "base64" + "const": "commands", + "description": "Approval scoped to specific command identifiers." }, - "mimeType": { - "type": "string", - "description": "MIME type of the audio (e.g., audio/wav, audio/mpeg)" + "commandIdentifiers": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Command identifiers covered by this approval." } }, "required": [ - "type", - "data", - "mimeType" + "kind", + "commandIdentifiers" ], "additionalProperties": false, - "description": "Audio content block with base64-encoded data", - "title": "ExternalToolTextResultForLlmContentAudio" + "title": "PermissionsLocationsAddToolApprovalDetailsCommands", + "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsCommands` type." }, - "ExternalToolTextResultForLlmContentImage": { + "PermissionsLocationsAddToolApprovalDetailsCustomTool": { "type": "object", "properties": { - "type": { - "type": "string", - "const": "image", - "description": "Content block type discriminator" - }, - "data": { + "kind": { "type": "string", - "description": "Base64-encoded image data", - "contentEncoding": "base64" + "const": "custom-tool", + "description": "Approval covering a custom tool." }, - "mimeType": { + "toolName": { "type": "string", - "description": "MIME type of the image (e.g., image/png, image/jpeg)" + "description": "Custom tool name." } }, "required": [ - "type", - "data", - "mimeType" + "kind", + "toolName" ], "additionalProperties": false, - "description": "Image content block with base64-encoded data", - "title": "ExternalToolTextResultForLlmContentImage" + "title": "PermissionsLocationsAddToolApprovalDetailsCustomTool", + "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsCustomTool` type." }, - "ExternalToolTextResultForLlmContentResource": { + "PermissionsLocationsAddToolApprovalDetailsExtensionManagement": { "type": "object", "properties": { - "type": { + "kind": { "type": "string", - "const": "resource", - "description": "Content block type discriminator" + "const": "extension-management", + "description": "Approval covering extension lifecycle operations such as enable, disable, or reload." }, - "resource": { - "$ref": "#/definitions/ExternalToolTextResultForLlmContentResourceDetails", - "description": "The embedded resource contents, either text or base64-encoded binary" + "operation": { + "type": "string", + "description": "Optional operation identifier; when omitted, the approval covers all extension management operations." } }, "required": [ - "type", - "resource" + "kind" ], "additionalProperties": false, - "description": "Embedded resource content block with inline text or binary data", - "title": "ExternalToolTextResultForLlmContentResource" + "title": "PermissionsLocationsAddToolApprovalDetailsExtensionManagement", + "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsExtensionManagement` type." }, - "ExternalToolTextResultForLlmContentResourceDetails": { - "anyOf": [ - { - "$ref": "#/definitions/EmbeddedTextResourceContents" + "PermissionsLocationsAddToolApprovalDetailsExtensionPermissionAccess": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "extension-permission-access", + "description": "Approval covering an extension's request to access a permission-gated capability." }, - { - "$ref": "#/definitions/EmbeddedBlobResourceContents" + "extensionName": { + "type": "string", + "description": "Extension name." } + }, + "required": [ + "kind", + "extensionName" ], - "description": "The embedded resource contents, either text or base64-encoded binary", - "title": "ExternalToolTextResultForLlmContentResourceDetails" + "additionalProperties": false, + "title": "PermissionsLocationsAddToolApprovalDetailsExtensionPermissionAccess", + "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsExtensionPermissionAccess` type." }, - "ExternalToolTextResultForLlmContentResourceLink": { + "PermissionsLocationsAddToolApprovalDetailsMcp": { "type": "object", "properties": { - "icons": { - "type": "array", - "items": { - "$ref": "#/definitions/ExternalToolTextResultForLlmContentResourceLinkIcon", - "description": "Icon image for a resource" - }, - "description": "Icons associated with this resource" - }, - "name": { - "type": "string", - "description": "Resource name identifier" - }, - "title": { - "type": "string", - "description": "Human-readable display title for the resource" - }, - "uri": { + "kind": { "type": "string", - "description": "URI identifying the resource" + "const": "mcp", + "description": "Approval covering an MCP tool." }, - "description": { + "serverName": { "type": "string", - "description": "Human-readable description of the resource" + "description": "MCP server name." }, - "mimeType": { + "toolName": { + "type": [ + "string", + "null" + ], + "description": "MCP tool name, or null to cover every tool on the server." + } + }, + "required": [ + "kind", + "serverName", + "toolName" + ], + "additionalProperties": false, + "title": "PermissionsLocationsAddToolApprovalDetailsMcp", + "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsMcp` type." + }, + "PermissionsLocationsAddToolApprovalDetailsMcpSampling": { + "type": "object", + "properties": { + "kind": { "type": "string", - "description": "MIME type of the resource content" - }, - "size": { - "type": "number", - "description": "Size of the resource in bytes" + "const": "mcp-sampling", + "description": "Approval covering MCP sampling requests for a server." }, - "type": { + "serverName": { "type": "string", - "const": "resource_link", - "description": "Content block type discriminator" + "description": "MCP server name." } }, "required": [ - "name", - "uri", - "type" + "kind", + "serverName" ], "additionalProperties": false, - "description": "Resource link content block referencing an external resource", - "title": "ExternalToolTextResultForLlmContentResourceLink" + "title": "PermissionsLocationsAddToolApprovalDetailsMcpSampling", + "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsMcpSampling` type." }, - "ExternalToolTextResultForLlmContentResourceLinkIcon": { + "PermissionsLocationsAddToolApprovalDetailsMemory": { "type": "object", "properties": { - "src": { - "type": "string", - "description": "URL or path to the icon image" - }, - "mimeType": { + "kind": { "type": "string", - "description": "MIME type of the icon image" - }, - "sizes": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Available icon sizes (e.g., ['16x16', '32x32'])" - }, - "theme": { - "$ref": "#/definitions/ExternalToolTextResultForLlmContentResourceLinkIconTheme", - "description": "Theme variant this icon is intended for" + "const": "memory", + "description": "Approval covering writes to long-term memory." } }, "required": [ - "src" + "kind" ], "additionalProperties": false, - "description": "Icon image for a resource", - "title": "ExternalToolTextResultForLlmContentResourceLinkIcon" + "title": "PermissionsLocationsAddToolApprovalDetailsMemory", + "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsMemory` type." }, - "ExternalToolTextResultForLlmContentResourceLinkIconTheme": { - "type": "string", - "enum": [ - "light", - "dark" + "PermissionsLocationsAddToolApprovalDetailsRead": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "read", + "description": "Approval covering read-only filesystem operations." + } + }, + "required": [ + "kind" ], - "description": "Theme variant this icon is intended for", - "title": "ExternalToolTextResultForLlmContentResourceLinkIconTheme" + "additionalProperties": false, + "title": "PermissionsLocationsAddToolApprovalDetailsRead", + "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsRead` type." }, - "ExternalToolTextResultForLlmContentTerminal": { + "PermissionsLocationsAddToolApprovalDetailsWrite": { "type": "object", "properties": { - "type": { + "kind": { "type": "string", - "const": "terminal", - "description": "Content block type discriminator" + "const": "write", + "description": "Approval covering filesystem write operations." + } + }, + "required": [ + "kind" + ], + "additionalProperties": false, + "title": "PermissionsLocationsAddToolApprovalDetailsWrite", + "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsWrite` type." + }, + "PermissionsLocationsAddToolApprovalResult": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Whether the operation succeeded" + } + }, + "required": [ + "success" + ], + "additionalProperties": false, + "description": "Indicates whether the operation succeeded.", + "title": "PermissionsLocationsAddToolApprovalResult" + }, + "PermissionsModifyRulesParams": { + "type": "object", + "properties": { + "scope": { + "$ref": "#/definitions/PermissionsModifyRulesScope", + "description": "Whether the change applies to ephemeral session-scoped rules (cleared at session end) or to location-scoped rules persisted via the location-permissions config file." }, - "text": { - "type": "string", - "description": "Terminal/shell output text" + "add": { + "type": "array", + "items": { + "$ref": "#/definitions/PermissionRule" + }, + "description": "Rules to add to the scope. Applied before `remove`/`removeAll`." }, - "exitCode": { - "type": "number", - "description": "Process exit code, if the command has completed" + "remove": { + "type": "array", + "items": { + "$ref": "#/definitions/PermissionRule" + }, + "description": "Specific rules to remove from the scope. Ignored when `removeAll` is true." }, - "cwd": { - "type": "string", - "description": "Working directory where the command was executed" + "removeAll": { + "type": "boolean", + "description": "When true, removes every rule currently in the scope (after any `add` is applied). Useful for clearing the location scope wholesale." } }, "required": [ - "type", - "text" + "scope" ], "additionalProperties": false, - "description": "Terminal/shell output content block with optional exit code and working directory", - "title": "ExternalToolTextResultForLlmContentTerminal" + "description": "Scope and add/remove instructions for modifying session- or location-scoped permission rules.", + "title": "PermissionsModifyRulesParams" }, - "ExternalToolTextResultForLlmContentText": { + "PermissionsModifyRulesResult": { "type": "object", "properties": { - "type": { - "type": "string", - "const": "text", - "description": "Content block type discriminator" - }, - "text": { - "type": "string", - "description": "The text content" + "success": { + "type": "boolean", + "description": "Whether the operation succeeded" } }, "required": [ - "type", - "text" + "success" ], "additionalProperties": false, - "description": "Plain text content block", - "title": "ExternalToolTextResultForLlmContentText" + "description": "Indicates whether the operation succeeded.", + "title": "PermissionsModifyRulesResult" }, - "FilterMapping": { - "anyOf": [ - { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/ContentFilterMode", - "description": "Controls how MCP tool result content is filtered: none leaves content unchanged, markdown sanitizes HTML while preserving Markdown-friendly output, and hidden_characters removes characters that can hide directives." - } - }, - { - "$ref": "#/definitions/ContentFilterMode", - "description": "Controls how MCP tool result content is filtered: none leaves content unchanged, markdown sanitizes HTML while preserving Markdown-friendly output, and hidden_characters removes characters that can hide directives." - } + "PermissionsModifyRulesScope": { + "type": "string", + "enum": [ + "session", + "location" ], - "description": "Content filtering mode to apply to all tools, or a map of tool name to content filtering mode.", - "title": "FilterMapping" + "description": "Whether the change applies to ephemeral session-scoped rules (cleared at session end) or to location-scoped rules persisted via the location-permissions config file.", + "title": "PermissionsModifyRulesScope", + "x-enumDescriptions": { + "session": "Apply the rule change only to this session.", + "location": "Persist the rule change for this project location." + } }, - "FleetStartRequest": { + "PermissionsNotifyPromptShownResult": { "type": "object", "properties": { - "prompt": { - "type": "string", - "description": "Optional user prompt to combine with fleet instructions" + "success": { + "type": "boolean", + "description": "Whether the operation succeeded" } }, + "required": [ + "success" + ], "additionalProperties": false, - "description": "Optional user prompt to combine with the fleet orchestration instructions.", - "title": "FleetStartRequest" + "description": "Indicates whether the operation succeeded.", + "title": "PermissionsNotifyPromptShownResult" }, - "FleetStartResult": { + "PermissionsPathsAddResult": { "type": "object", "properties": { - "started": { + "success": { "type": "boolean", - "description": "Whether fleet mode was successfully activated" + "description": "Whether the operation succeeded" } }, "required": [ - "started" + "success" ], "additionalProperties": false, - "description": "Indicates whether fleet mode was successfully activated.", - "title": "FleetStartResult" + "description": "Indicates whether the operation succeeded.", + "title": "PermissionsPathsAddResult" }, - "HandlePendingToolCallRequest": { + "PermissionsPathsListRequest": { + "type": "object", + "properties": {}, + "additionalProperties": false, + "description": "No parameters; returns the session's allow-listed directories.", + "title": "PermissionsPathsListRequest" + }, + "PermissionsPathsUpdatePrimaryResult": { "type": "object", "properties": { - "requestId": { - "type": "string", - "description": "Request ID of the pending tool call" - }, - "result": { - "$ref": "#/definitions/ExternalToolResult", - "description": "Tool call result (string or expanded result object)" - }, - "error": { - "type": "string", - "description": "Error message if the tool call failed" + "success": { + "type": "boolean", + "description": "Whether the operation succeeded" } }, "required": [ - "requestId" + "success" ], "additionalProperties": false, - "description": "Pending external tool call request ID, with the tool result or an error describing why it failed.", - "title": "HandlePendingToolCallRequest" + "description": "Indicates whether the operation succeeded.", + "title": "PermissionsPathsUpdatePrimaryResult" }, - "HandlePendingToolCallResult": { + "PermissionsPendingRequestsRequest": { + "type": "object", + "properties": {}, + "additionalProperties": false, + "description": "No parameters; returns currently-pending permission requests for the session.", + "title": "PermissionsPendingRequestsRequest" + }, + "PermissionsResetSessionApprovalsRequest": { + "type": "object", + "properties": {}, + "additionalProperties": false, + "description": "No parameters; clears all session-scoped tool permission approvals.", + "title": "PermissionsResetSessionApprovalsRequest" + }, + "PermissionsResetSessionApprovalsResult": { "type": "object", "properties": { "success": { "type": "boolean", - "description": "Whether the tool call result was handled successfully" + "description": "Whether the operation succeeded" } }, "required": [ "success" ], "additionalProperties": false, - "description": "Indicates whether the external tool call result was handled successfully.", - "title": "HandlePendingToolCallResult" + "description": "Indicates whether the operation succeeded.", + "title": "PermissionsResetSessionApprovalsResult" }, - "HistoryCompactContextWindow": { + "PermissionsSetApproveAllRequest": { "type": "object", "properties": { - "tokenLimit": { - "type": "integer", - "minimum": 0, - "description": "Maximum token count for the model's context window" - }, - "currentTokens": { - "type": "integer", - "minimum": 0, - "description": "Current total tokens in the context window (system + conversation + tool definitions)" - }, - "messagesLength": { - "type": "integer", - "minimum": 0, - "description": "Current number of messages in the conversation" - }, - "systemTokens": { - "type": "integer", - "minimum": 0, - "description": "Token count from system message(s)" - }, - "conversationTokens": { - "type": "integer", - "minimum": 0, - "description": "Token count from non-system messages (user, assistant, tool)" + "enabled": { + "type": "boolean", + "description": "Whether to auto-approve all tool permission requests" }, - "toolDefinitionsTokens": { - "type": "integer", - "minimum": 0, - "description": "Token count from tool definitions" + "source": { + "$ref": "#/definitions/PermissionsSetApproveAllSource", + "description": "Optional source for allow-all telemetry. Defaults to `rpc` when omitted for SDK callers." + } + }, + "required": [ + "enabled" + ], + "additionalProperties": false, + "description": "Allow-all toggle for tool permission requests, with an optional telemetry source.", + "title": "PermissionsSetApproveAllRequest" + }, + "PermissionsSetApproveAllResult": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Whether the operation succeeded" } }, "required": [ - "tokenLimit", - "currentTokens", - "messagesLength" + "success" ], "additionalProperties": false, - "description": "Post-compaction context window usage breakdown", - "title": "HistoryCompactContextWindow" + "description": "Indicates whether the operation succeeded.", + "title": "PermissionsSetApproveAllResult" }, - "HistoryCompactResult": { + "PermissionsSetApproveAllSource": { + "type": "string", + "enum": [ + "cli_flag", + "slash_command", + "autopilot_confirmation", + "rpc" + ], + "description": "Optional source for allow-all telemetry. Defaults to `rpc` when omitted for SDK callers.", + "title": "PermissionsSetApproveAllSource", + "x-enumDescriptions": { + "cli_flag": "Allow-all was enabled from a CLI command-line flag.", + "slash_command": "Allow-all was enabled by a slash command.", + "autopilot_confirmation": "Allow-all was enabled by confirming autopilot behavior.", + "rpc": "Allow-all was enabled through an RPC caller." + } + }, + "PermissionsSetRequiredRequest": { "type": "object", "properties": { - "success": { + "required": { "type": "boolean", - "description": "Whether compaction completed successfully" - }, - "tokensRemoved": { - "type": "integer", - "minimum": 0, - "description": "Number of tokens freed by compaction" - }, - "messagesRemoved": { - "type": "integer", - "minimum": 0, - "description": "Number of messages removed during compaction" - }, - "contextWindow": { - "$ref": "#/definitions/HistoryCompactContextWindow", - "description": "Post-compaction context window usage breakdown" + "description": "Whether the client wants `permission.requested` events bridged from the session-owned permission service. CLI clients that render prompt UI set this to `true` for as long as their listener is mounted; headless callers leave it unset (the default is `false`)." } }, "required": [ - "success", - "tokensRemoved", - "messagesRemoved" + "required" ], "additionalProperties": false, - "description": "Compaction outcome with the number of tokens and messages removed and the resulting context window breakdown.", - "title": "HistoryCompactResult" + "description": "Toggles whether permission prompts should be bridged into session events for this client.", + "title": "PermissionsSetRequiredRequest" }, - "HistoryTruncateRequest": { + "PermissionsSetRequiredResult": { "type": "object", "properties": { - "eventId": { - "type": "string", - "description": "Event ID to truncate to. This event and all events after it are removed from the session." + "success": { + "type": "boolean", + "description": "Whether the operation succeeded" } }, "required": [ - "eventId" + "success" ], "additionalProperties": false, - "description": "Identifier of the event to truncate to; this event and all later events are removed.", - "title": "HistoryTruncateRequest" + "description": "Indicates whether the operation succeeded.", + "title": "PermissionsSetRequiredResult" }, - "HistoryTruncateResult": { + "PermissionsUrlsSetUnrestrictedModeResult": { "type": "object", "properties": { - "eventsRemoved": { - "type": "integer", - "minimum": 0, - "description": "Number of events that were removed" + "success": { + "type": "boolean", + "description": "Whether the operation succeeded" } }, "required": [ - "eventsRemoved" + "success" ], "additionalProperties": false, - "description": "Number of events that were removed by the truncation.", - "title": "HistoryTruncateResult" + "description": "Indicates whether the operation succeeded.", + "title": "PermissionsUrlsSetUnrestrictedModeResult" }, - "InstructionsGetSourcesResult": { + "PermissionUrlsConfig": { "type": "object", "properties": { - "sources": { + "unrestricted": { + "type": "boolean", + "description": "If true, the runtime allows access to all URLs without prompting. Initial allow-list is ignored when this is true." + }, + "initialAllowed": { "type": "array", "items": { - "$ref": "#/definitions/InstructionsSources" + "type": "string" }, - "description": "Instruction sources for the session" + "description": "Initial list of allowed URL/domain patterns. Patterns may include path components. Ignored when `unrestricted` is true." } }, - "required": [ - "sources" - ], "additionalProperties": false, - "description": "Instruction sources loaded for the session, in merge order.", - "title": "InstructionsGetSourcesResult" + "description": "If specified, replaces the session's URL-permission policy. The runtime constructs a fresh DefaultUrlManager based on these inputs. Omit to leave the current URL policy unchanged.", + "title": "PermissionUrlsConfig" }, - "InstructionsSources": { + "PermissionUrlsSetUnrestrictedModeParams": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique identifier for this source (used for toggling)" - }, - "label": { - "type": "string", - "description": "Human-readable label" - }, - "sourcePath": { - "type": "string", - "description": "File path relative to repo or absolute for home" - }, - "content": { - "type": "string", - "description": "Raw content of the instruction file" - }, - "type": { - "$ref": "#/definitions/InstructionsSourcesType", - "description": "Category of instruction source — used for merge logic" - }, - "location": { - "$ref": "#/definitions/InstructionsSourcesLocation", - "description": "Where this source lives — used for UI grouping" - }, - "applyTo": { - "type": "string", - "description": "Glob pattern from frontmatter — when set, this instruction applies only to matching files" - }, - "description": { - "type": "string", - "description": "Short description (body after frontmatter) for use in instruction tables" + "enabled": { + "type": "boolean", + "description": "Whether to allow access to all URLs without prompting. Toggles the runtime's URL-permission policy in place." } }, "required": [ - "id", - "label", - "sourcePath", - "content", - "type", - "location" + "enabled" ], "additionalProperties": false, - "title": "InstructionsSources", - "description": "Schema for the `InstructionsSources` type." - }, - "InstructionsSourcesLocation": { - "type": "string", - "enum": [ - "user", - "repository", - "working-directory" - ], - "description": "Where this source lives — used for UI grouping", - "title": "InstructionsSourcesLocation" + "description": "Whether the URL-permission policy should run in unrestricted mode.", + "title": "PermissionUrlsSetUnrestrictedModeParams" }, - "InstructionsSourcesType": { - "type": "string", - "enum": [ - "home", - "repo", - "model", - "vscode", - "nested-agents", - "child-instructions" - ], - "description": "Category of instruction source — used for merge logic", - "title": "InstructionsSourcesType" + "PingRequest": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Optional message to echo back" + } + }, + "additionalProperties": false, + "description": "Optional message to echo back to the caller.", + "title": "PingRequest" }, - "LogRequest": { + "PingResult": { "type": "object", "properties": { "message": { "type": "string", - "description": "Human-readable message" - }, - "level": { - "$ref": "#/definitions/SessionLogLevel", - "description": "Log severity level. Determines how the message is displayed in the timeline. Defaults to \"info\"." - }, - "ephemeral": { - "type": "boolean", - "description": "When true, the message is transient and not persisted to the session event log on disk" + "description": "Echoed message (or default greeting)" }, - "url": { + "timestamp": { "type": "string", - "format": "uri", - "description": "Optional URL the user can open in their browser for more details" + "format": "date-time", + "description": "ISO 8601 timestamp when the server handled the ping" + }, + "protocolVersion": { + "type": "integer", + "exclusiveMinimum": true, + "minimum": 0, + "description": "Server protocol version number" } }, "required": [ - "message" + "message", + "timestamp", + "protocolVersion" ], "additionalProperties": false, - "description": "Message text, optional severity level, persistence flag, and optional follow-up URL.", - "title": "LogRequest" + "description": "Server liveness response, including the echoed message, current server timestamp, and protocol version.", + "title": "PingResult" }, - "LogResult": { + "PlanReadResult": { "type": "object", "properties": { - "eventId": { - "type": "string", - "format": "uuid", - "description": "The unique identifier of the emitted session event" + "exists": { + "type": "boolean", + "description": "Whether the plan file exists in the workspace" + }, + "content": { + "type": [ + "string", + "null" + ], + "description": "The content of the plan file, or null if it does not exist" + }, + "path": { + "type": [ + "string", + "null" + ], + "description": "Absolute file path of the plan file, or null if workspace is not enabled" } }, "required": [ - "eventId" + "exists", + "content", + "path" ], "additionalProperties": false, - "description": "Identifier of the session event that was emitted for the log message.", - "title": "LogResult" + "description": "Existence, contents, and resolved path of the session plan file.", + "title": "PlanReadResult" }, - "McpConfigAddRequest": { + "PlanUpdateRequest": { "type": "object", "properties": { - "name": { + "content": { "type": "string", - "minLength": 1, - "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", - "description": "Unique name for the MCP server" - }, - "config": { - "$ref": "#/definitions/McpServerConfig", - "description": "MCP server configuration (stdio process or remote HTTP/SSE)" + "description": "The new content for the plan file" } }, "required": [ - "name", - "config" + "content" ], "additionalProperties": false, - "description": "MCP server name and configuration to add to user configuration.", - "title": "McpConfigAddRequest" + "description": "Replacement contents to write to the session plan file.", + "title": "PlanUpdateRequest" }, - "McpConfigDisableRequest": { + "Plugin": { "type": "object", "properties": { - "names": { - "type": "array", - "items": { - "type": "string", - "minLength": 1, - "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." + "name": { + "type": "string", + "description": "Plugin name" + }, + "marketplace": { + "type": "string", + "description": "Marketplace the plugin came from" + }, + "version": { + "type": "string", + "description": "Installed version" + }, + "enabled": { + "type": "boolean", + "description": "Whether the plugin is currently enabled" } }, "required": [ - "names" + "name", + "marketplace", + "enabled" ], "additionalProperties": false, - "description": "MCP server names to disable for new sessions.", - "title": "McpConfigDisableRequest" + "title": "Plugin", + "description": "Schema for the `Plugin` type." }, - "McpConfigEnableRequest": { + "PluginList": { "type": "object", "properties": { - "names": { + "plugins": { "type": "array", "items": { - "type": "string", - "minLength": 1, - "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", - "description": "MCP server name used as a configuration key." + "$ref": "#/definitions/Plugin" }, - "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." + "description": "Installed plugins" } }, "required": [ - "names" + "plugins" ], "additionalProperties": false, - "description": "MCP server names to enable for new sessions.", - "title": "McpConfigEnableRequest" + "description": "Plugins installed for the session, with their enabled state and version metadata.", + "title": "PluginList" }, - "McpConfigList": { + "QueuedCommandHandled": { "type": "object", "properties": { - "servers": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/McpServerConfig", - "description": "MCP server configuration (stdio process or remote HTTP/SSE)" - }, - "propertyNames": { - "minLength": 1, - "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$" - }, - "description": "All MCP servers from user config, keyed by name" + "handled": { + "type": "boolean", + "const": true, + "description": "The host actually executed the queued command." + }, + "stopProcessingQueue": { + "type": "boolean", + "description": "When true, the runtime will not process subsequent queued commands until a new request comes in." } }, "required": [ - "servers" + "handled" ], "additionalProperties": false, - "description": "User-configured MCP servers, keyed by server name.", - "title": "McpConfigList" + "title": "QueuedCommandHandled", + "description": "Schema for the `QueuedCommandHandled` type." }, - "McpConfigRemoveRequest": { + "QueuedCommandNotHandled": { "type": "object", "properties": { - "name": { - "type": "string", - "minLength": 1, - "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", - "description": "Name of the MCP server to remove" + "handled": { + "type": "boolean", + "const": false, + "description": "The host did not execute the queued command. Unblocks the queue without claiming the command was processed (e.g. when the handler threw before completing)." } }, "required": [ - "name" + "handled" ], "additionalProperties": false, - "description": "MCP server name to remove from user configuration.", - "title": "McpConfigRemoveRequest" + "title": "QueuedCommandNotHandled", + "description": "Schema for the `QueuedCommandNotHandled` type." }, - "McpConfigUpdateRequest": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", - "description": "Name of the MCP server to update" + "QueuedCommandResult": { + "anyOf": [ + { + "$ref": "#/definitions/QueuedCommandHandled" }, - "config": { - "$ref": "#/definitions/McpServerConfig", - "description": "MCP server configuration (stdio process or remote HTTP/SSE)" + { + "$ref": "#/definitions/QueuedCommandNotHandled" } - }, - "required": [ - "name", - "config" ], - "additionalProperties": false, - "description": "MCP server name and replacement configuration to write to user configuration.", - "title": "McpConfigUpdateRequest" + "description": "Result of the queued command execution.", + "title": "QueuedCommandResult" }, - "McpDisableRequest": { + "QueuePendingItems": { "type": "object", "properties": { - "serverName": { + "kind": { + "$ref": "#/definitions/QueuePendingItemsKind", + "description": "Whether this item is a queued user message or a queued slash command / model change" + }, + "displayText": { "type": "string", - "minLength": 1, - "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", - "description": "Name of the MCP server to disable" + "description": "Human-readable text to display for this queue entry in the UI" } }, "required": [ - "serverName" + "kind", + "displayText" ], "additionalProperties": false, - "description": "Name of the MCP server to disable for the session.", - "title": "McpDisableRequest" + "title": "QueuePendingItems", + "description": "Schema for the `QueuePendingItems` type." }, - "McpDiscoverRequest": { - "type": "object", - "properties": { - "workingDirectory": { - "type": "string", - "description": "Working directory used as context for discovery (e.g., plugin resolution)" - } - }, - "additionalProperties": false, - "description": "Optional working directory used as context for MCP server discovery.", - "title": "McpDiscoverRequest" + "QueuePendingItemsKind": { + "type": "string", + "enum": [ + "message", + "command" + ], + "description": "Whether this item is a queued user message or a queued slash command / model change", + "title": "QueuePendingItemsKind", + "x-enumDescriptions": { + "message": "A queued user message.", + "command": "A queued slash command or model-change command." + } }, - "McpDiscoverResult": { + "QueuePendingItemsResult": { "type": "object", "properties": { - "servers": { + "items": { "type": "array", "items": { - "$ref": "#/definitions/DiscoveredMcpServer" + "$ref": "#/definitions/QueuePendingItems" }, - "description": "MCP servers discovered from all sources" + "description": "Pending queued items in submission order. Includes user messages, queued slash commands, and queued model changes; omits internal system items." + }, + "steeringMessages": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Display text for messages currently in the immediate steering queue (interjections sent during a running turn)." } }, "required": [ - "servers" + "items", + "steeringMessages" ], "additionalProperties": false, - "description": "MCP servers discovered from user, workspace, plugin, and built-in sources.", - "title": "McpDiscoverResult" + "description": "Snapshot of the session's pending queued items and immediate-steering messages.", + "title": "QueuePendingItemsResult" }, - "McpEnableRequest": { + "QueueRemoveMostRecentResult": { "type": "object", "properties": { - "serverName": { - "type": "string", - "minLength": 1, - "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", - "description": "Name of the MCP server to enable" + "removed": { + "type": "boolean", + "description": "True if a user-facing pending item was removed (LIFO across both queues); false when no removable items remained." } }, "required": [ - "serverName" + "removed" ], "additionalProperties": false, - "description": "Name of the MCP server to enable for the session.", - "title": "McpEnableRequest" + "description": "Indicates whether a user-facing pending item was removed.", + "title": "QueueRemoveMostRecentResult" }, - "McpOauthLoginRequest": { + "ReasoningSummary": { + "type": "string", + "enum": [ + "none", + "concise", + "detailed" + ], + "description": "Reasoning summary mode to request for supported model clients", + "title": "ReasoningSummary", + "x-enumDescriptions": { + "none": "Do not request reasoning summaries from the model.", + "concise": "Request a concise summary of the model's reasoning.", + "detailed": "Request a detailed summary of the model's reasoning." + } + }, + "RegisterEventInterestParams": { "type": "object", "properties": { - "serverName": { - "type": "string", - "minLength": 1, - "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", - "description": "Name of the remote MCP server to authenticate" - }, - "forceReauth": { - "type": "boolean", - "description": "When true, clears any cached OAuth token for the server and runs a full new authorization. Use when the user explicitly wants to switch accounts or believes their session is stuck." - }, - "clientName": { - "type": "string", - "description": "Optional override for the OAuth client display name shown on the consent screen. Applies to newly registered dynamic clients only — existing registrations keep the name they were created with. When omitted, the runtime applies a neutral fallback; callers driving interactive auth should pass their own surface-specific label so the consent screen matches the product the user sees." - }, - "callbackSuccessMessage": { + "eventType": { "type": "string", - "description": "Optional override for the body text shown on the OAuth loopback callback success page. When omitted, the runtime applies a neutral fallback; callers driving interactive auth should pass surface-specific copy telling the user where to return." + "description": "The event type the consumer wants the runtime to treat as 'observed' for behavior-switching gating. Some runtime code paths inspect whether any consumer is interested in a specific event type and choose a different implementation accordingly (e.g. `mcp.oauth_required`: when interest is registered the runtime delegates the full interactive OAuth flow to the consumer; when no interest is registered the runtime installs a browserless fallback that silently reuses cached tokens). SDK clients that long-poll events do NOT automatically appear as listeners to these gating checks — they must explicitly call `registerInterest` for each event type they want the runtime to count as having a consumer. Multiple registrations for the same event type from the same or different consumers are tracked independently and must each be released. See: `mcp.oauth_required`, `sampling.requested`, `auto_mode_switch.requested`, `user_input.requested`, `elicitation.requested`, `command.queued`, `exit_plan_mode.requested`." } }, "required": [ - "serverName" + "eventType" ], "additionalProperties": false, - "description": "Remote MCP server name and optional overrides controlling reauthentication, OAuth client display name, and the callback success-page copy.", - "title": "McpOauthLoginRequest" + "description": "Event type to register consumer interest for, used by runtime gating logic.", + "title": "RegisterEventInterestParams" }, - "McpOauthLoginResult": { + "RegisterEventInterestResult": { "type": "object", "properties": { - "authorizationUrl": { + "handle": { "type": "string", - "format": "uri", - "description": "URL the caller should open in a browser to complete OAuth. Omitted when cached tokens were still valid and no browser interaction was needed — the server is already reconnected in that case. When present, the runtime starts the callback listener before returning and continues the flow in the background; completion is signaled via session.mcp_server_status_changed." + "description": "Opaque handle for this registration. Pass to releaseInterest to release. Each call to registerInterest produces a fresh handle, even when the same eventType is registered multiple times." } }, + "required": [ + "handle" + ], "additionalProperties": false, - "description": "OAuth authorization URL the caller should open, or empty when cached tokens already authenticated the server.", - "title": "McpOauthLoginResult" + "description": "Opaque handle representing an event-type interest registration.", + "title": "RegisterEventInterestResult" }, - "McpServer": { + "ReleaseEventInterestParams": { "type": "object", "properties": { - "name": { - "type": "string", - "minLength": 1, - "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", - "description": "Server name (config key)" - }, - "status": { - "$ref": "#/definitions/McpServerStatus", - "description": "Connection status: connected, failed, needs-auth, pending, disabled, or not_configured" - }, - "source": { - "$ref": "#/definitions/McpServerSource", - "description": "Configuration source: user, workspace, plugin, or builtin" - }, - "error": { + "handle": { "type": "string", - "description": "Error message if the server failed to connect" + "description": "Handle returned by a previous `registerInterest` call. Idempotent: releasing an unknown or already-released handle is a no-op (returns success). When the last outstanding handle for an event type is released, the runtime reverts to its 'no consumer' code path for that event type." } }, "required": [ - "name", - "status" + "handle" ], "additionalProperties": false, - "title": "McpServer", - "description": "Schema for the `McpServer` type." - }, - "McpServerConfig": { - "anyOf": [ - { - "$ref": "#/definitions/McpServerConfigStdio", - "description": "Stdio MCP server configuration launched as a child process." - }, - { - "$ref": "#/definitions/McpServerConfigHttp", - "description": "Remote MCP server configuration accessed over HTTP or SSE." - } - ], - "description": "MCP server configuration (stdio process or remote HTTP/SSE)", - "title": "McpServerConfig" + "description": "Opaque handle previously returned by `registerInterest` to release.", + "title": "ReleaseEventInterestParams" }, - "McpServerConfigHttp": { + "RemoteEnableRequest": { "type": "object", "properties": { - "tools": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Tools to include. Defaults to all tools if not specified." - }, - "type": { - "$ref": "#/definitions/McpServerConfigHttpType", - "description": "Remote transport type. Defaults to \"http\" when omitted." - }, - "isDefaultServer": { - "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", - "description": "Content filtering mode to apply to all tools, or a map of tool name to content filtering mode." - }, - "timeout": { - "type": "integer", - "exclusiveMinimum": true, - "minimum": 0, - "description": "Timeout in milliseconds for tool calls to this server.", - "format": "duration" - }, - "url": { - "type": "string", - "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": { + "mode": { + "$ref": "#/definitions/RemoteSessionMode", + "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": { + "type": "object", + "properties": { + "url": { "type": "string", - "description": "OAuth client ID for a pre-registered remote MCP OAuth client." + "format": "uri", + "description": "GitHub frontend URL for this session" }, - "oauthPublicClient": { + "remoteSteerable": { "type": "boolean", - "description": "Whether the configured OAuth client is public and does not require a client secret." - }, - "oauthGrantType": { - "$ref": "#/definitions/McpServerConfigHttpOauthGrantType", - "description": "OAuth grant type to use when authenticating to the remote MCP server." - }, - "auth": { - "$ref": "#/definitions/McpServerConfigHttpAuth", - "description": "Additional authentication configuration for this server." + "description": "Whether remote steering is enabled" } }, "required": [ - "url" + "remoteSteerable" ], "additionalProperties": false, - "description": "Remote MCP server configuration accessed over HTTP or SSE.", - "title": "McpServerConfigHttp" + "description": "GitHub URL for the session and a flag indicating whether remote steering is enabled.", + "title": "RemoteEnableResult" }, - "McpServerConfigHttpAuth": { + "RemoteNotifySteerableChangedRequest": { "type": "object", "properties": { - "redirectPort": { - "type": "integer", - "minimum": 1, - "maximum": 65535, - "description": "Fixed port for the OAuth redirect callback server." + "remoteSteerable": { + "type": "boolean", + "description": "Whether the session now supports remote steering via GitHub. The runtime persists this as a `session.remote_steerable_changed` event so resume/replay sees the up-to-date capability." } }, + "required": [ + "remoteSteerable" + ], "additionalProperties": false, - "description": "Additional authentication configuration for this server.", - "title": "McpServerConfigHttpAuth" + "description": "New remote-steerability state to persist as a `session.remote_steerable_changed` event.", + "title": "RemoteNotifySteerableChangedRequest" }, - "McpServerConfigHttpOauthGrantType": { - "type": "string", - "enum": [ - "authorization_code", - "client_credentials" + "RemoteNotifySteerableChangedResult": { + "type": "object", + "properties": {}, + "additionalProperties": false, + "description": "Persist a steerability change as a `session.remote_steerable_changed` event. Used by the host (CLI / SDK consumer) when it has just finished enabling or disabling steering on a remote exporter that the runtime does not directly own.", + "title": "RemoteNotifySteerableChangedResult" + }, + "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" ], - "description": "OAuth grant type to use when authenticating to the remote MCP server.", - "title": "McpServerConfigHttpOauthGrantType" + "additionalProperties": false, + "description": "Remote session connection result.", + "title": "RemoteSessionConnectionResult" }, - "McpServerConfigHttpType": { + "RemoteSessionMode": { "type": "string", "enum": [ - "http", - "sse" + "off", + "export", + "on" ], - "default": "http", - "description": "Remote transport type. Defaults to \"http\" when omitted.", - "title": "McpServerConfigHttpType" + "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", + "x-enumDescriptions": { + "off": "Disable remote session export and steering.", + "export": "Export session events to GitHub without enabling remote steering.", + "on": "Enable both remote session export and remote steering." + } }, - "McpServerConfigStdio": { + "ScheduleEntry": { "type": "object", "properties": { - "tools": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Tools to include. Defaults to all tools if not specified." - }, - "isDefaultServer": { - "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", - "description": "Content filtering mode to apply to all tools, or a map of tool name to content filtering mode." + "id": { + "type": "integer", + "exclusiveMinimum": true, + "minimum": 0, + "description": "Sequential id assigned by the runtime within the session. Stable across resumes (rebuilt from the event log)." }, - "timeout": { + "intervalMs": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, - "description": "Timeout in milliseconds for tool calls to this server.", + "description": "Interval between scheduled ticks, in milliseconds.", "format": "duration" }, - "command": { + "prompt": { "type": "string", - "description": "Executable command used to start the Stdio MCP server process." + "description": "Prompt text that gets enqueued on every tick." }, - "args": { - "type": "array", - "items": { - "type": "string" - }, - "default": [], - "description": "Command-line arguments passed to the Stdio MCP server process." + "recurring": { + "type": "boolean", + "description": "Whether the schedule re-arms after each tick (`/every`) or fires once (`/after`)." }, - "cwd": { + "displayPrompt": { "type": "string", - "description": "Working directory for the Stdio MCP server process." + "description": "Display-only label for the prompt as shown in the UI (e.g. `/skill-name` for a skill-invocation schedule). The actual enqueued prompt is `prompt`." }, - "env": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "description": "Environment variables to pass to the Stdio MCP server process." + "nextRunAt": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp when the next tick is scheduled to fire." } }, "required": [ - "command" + "id", + "intervalMs", + "prompt", + "recurring", + "nextRunAt" ], "additionalProperties": false, - "description": "Stdio MCP server configuration launched as a child process.", - "title": "McpServerConfigStdio" + "title": "ScheduleEntry", + "description": "Schema for the `ScheduleEntry` type." }, - "McpServerList": { + "ScheduleList": { "type": "object", "properties": { - "servers": { + "entries": { "type": "array", "items": { - "$ref": "#/definitions/McpServer" + "$ref": "#/definitions/ScheduleEntry" }, - "description": "Configured MCP servers" + "description": "Active scheduled prompts, ordered by id." } }, "required": [ - "servers" + "entries" ], "additionalProperties": false, - "description": "MCP servers configured for the session, with their connection status.", - "title": "McpServerList" - }, - "McpServerSource": { - "type": "string", - "enum": [ - "user", - "workspace", - "plugin", - "builtin" - ], - "description": "Configuration source: user, workspace, plugin, or builtin", - "title": "McpServerSource" - }, - "McpServerStatus": { - "type": "string", - "enum": [ - "connected", - "failed", - "needs-auth", - "pending", - "disabled", - "not_configured" - ], - "description": "Connection status: connected, failed, needs-auth, pending, disabled, or not_configured", - "title": "McpServerStatus" + "description": "Snapshot of the currently active recurring prompts for this session.", + "title": "ScheduleList" }, - "Model": { + "ScheduleStopRequest": { "type": "object", "properties": { "id": { - "type": "string", - "description": "Model identifier (e.g., \"claude-sonnet-4.5\")" - }, - "name": { - "type": "string", - "description": "Display name" - }, - "capabilities": { - "$ref": "#/definitions/ModelCapabilities", - "description": "Model capabilities and limits" - }, - "policy": { - "$ref": "#/definitions/ModelPolicy", - "description": "Policy state (if applicable)" - }, - "billing": { - "$ref": "#/definitions/ModelBilling", - "description": "Billing information" - }, - "supportedReasoningEfforts": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Supported reasoning effort levels (only present if model supports reasoning effort)" - }, - "defaultReasoningEffort": { - "type": "string", - "description": "Default reasoning effort level (only present if model supports reasoning effort)" - }, - "modelPickerCategory": { - "$ref": "#/definitions/ModelPickerCategory", - "description": "Model capability category for grouping in the model picker" - }, - "modelPickerPriceCategory": { - "$ref": "#/definitions/ModelPickerPriceCategory", - "description": "Relative cost tier for token-based billing users" + "type": "integer", + "exclusiveMinimum": true, + "minimum": 0, + "description": "Id of the scheduled prompt to remove." } }, "required": [ - "id", - "name", - "capabilities" + "id" ], "additionalProperties": false, - "title": "Model", - "description": "Schema for the `Model` type." + "description": "Identifier of the scheduled prompt to remove.", + "title": "ScheduleStopRequest" }, - "ModelBilling": { + "ScheduleStopResult": { "type": "object", "properties": { - "multiplier": { - "type": "number", - "description": "Billing cost multiplier relative to the base rate" - }, - "tokenPrices": { - "$ref": "#/definitions/ModelBillingTokenPrices", - "description": "Token-level pricing information for this model" + "entry": { + "$ref": "#/definitions/ScheduleEntry", + "description": "The removed entry, or omitted if no entry matched." } }, "additionalProperties": false, - "description": "Billing information", - "title": "ModelBilling" + "description": "Remove a scheduled prompt by id. The result entry is omitted if the id was unknown.", + "title": "ScheduleStopResult" }, - "ModelBillingTokenPrices": { - "type": "object", - "properties": { - "inputPrice": { - "type": "integer", - "description": "Price per billing batch of input tokens in nano-AIUs (1 nano-AIU = 0.000000001 AIU, 1 AIU = $0.01 USD)" - }, - "outputPrice": { - "type": "integer", - "description": "Price per billing batch of output tokens in nano-AIUs (1 nano-AIU = 0.000000001 AIU, 1 AIU = $0.01 USD)" + "SendAgentMode": { + "type": "string", + "enum": [ + "interactive", + "plan", + "autopilot", + "shell" + ], + "description": "The UI mode the agent was in when this message was sent. Defaults to the session's current mode.", + "title": "SendAgentMode", + "x-enumDescriptions": { + "interactive": "The agent is responding interactively to the user.", + "plan": "The agent is preparing a plan before making changes.", + "autopilot": "The agent is working autonomously toward task completion.", + "shell": "The agent is in shell-focused UI mode." + } + }, + "SendAttachment": { + "anyOf": [ + { + "$ref": "#/definitions/SendAttachmentFile", + "description": "File attachment" }, - "cachePrice": { - "type": "integer", - "description": "Price per billing batch of cached tokens in nano-AIUs (1 nano-AIU = 0.000000001 AIU, 1 AIU = $0.01 USD)" + { + "$ref": "#/definitions/SendAttachmentDirectory", + "description": "Directory attachment" }, - "batchSize": { - "type": "integer", - "description": "Number of tokens per standard billing batch" - } - }, - "additionalProperties": false, - "description": "Token-level pricing information for this model", - "title": "ModelBillingTokenPrices" - }, - "ModelCapabilities": { - "type": "object", - "properties": { - "supports": { - "$ref": "#/definitions/ModelCapabilitiesSupports", - "description": "Feature flags indicating what the model supports" + { + "$ref": "#/definitions/SendAttachmentSelection", + "description": "Code selection attachment from an editor" }, - "limits": { - "$ref": "#/definitions/ModelCapabilitiesLimits", - "description": "Token limits for prompts, outputs, and context window" + { + "$ref": "#/definitions/SendAttachmentGithubReference", + "description": "GitHub issue, pull request, or discussion reference" + }, + { + "$ref": "#/definitions/SendAttachmentBlob", + "description": "Blob attachment with inline base64-encoded data" } - }, - "additionalProperties": false, - "description": "Model capabilities and limits", - "title": "ModelCapabilities" + ], + "description": "A user message attachment — a file, directory, code selection, blob, or GitHub reference", + "title": "SendAttachment" }, - "ModelCapabilitiesLimits": { + "SendAttachmentBlob": { "type": "object", "properties": { - "max_prompt_tokens": { - "type": "integer", - "minimum": 0, - "description": "Maximum number of prompt/input tokens" + "type": { + "type": "string", + "const": "blob", + "description": "Attachment type discriminator" }, - "max_output_tokens": { - "type": "integer", - "minimum": 0, - "description": "Maximum number of output/completion tokens" + "data": { + "type": "string", + "description": "Base64-encoded content", + "contentEncoding": "base64" }, - "max_context_window_tokens": { - "type": "integer", - "minimum": 0, - "description": "Maximum total context window size in tokens" + "mimeType": { + "type": "string", + "description": "MIME type of the inline data" }, - "vision": { - "$ref": "#/definitions/ModelCapabilitiesLimitsVision", - "description": "Vision-specific limits" + "displayName": { + "type": "string", + "description": "User-facing display name for the attachment" } }, + "required": [ + "type", + "data", + "mimeType" + ], "additionalProperties": false, - "description": "Token limits for prompts, outputs, and context window", - "title": "ModelCapabilitiesLimits" + "description": "Blob attachment with inline base64-encoded data", + "title": "SendAttachmentBlob" }, - "ModelCapabilitiesLimitsVision": { + "SendAttachmentDirectory": { "type": "object", "properties": { - "supported_media_types": { - "type": "array", - "items": { - "type": "string" - }, - "description": "MIME types the model accepts" + "type": { + "type": "string", + "const": "directory", + "description": "Attachment type discriminator" }, - "max_prompt_images": { - "type": "integer", - "minimum": 1, - "description": "Maximum number of images per prompt" + "path": { + "type": "string", + "description": "Absolute directory path" }, - "max_prompt_image_size": { - "type": "integer", - "minimum": 0, - "description": "Maximum image size in bytes" + "displayName": { + "type": "string", + "description": "User-facing display name for the attachment" } }, "required": [ - "supported_media_types", - "max_prompt_images", - "max_prompt_image_size" + "type", + "path", + "displayName" ], "additionalProperties": false, - "description": "Vision-specific limits", - "title": "ModelCapabilitiesLimitsVision" + "description": "Directory attachment", + "title": "SendAttachmentDirectory" }, - "ModelCapabilitiesOverride": { + "SendAttachmentFile": { "type": "object", "properties": { - "supports": { - "$ref": "#/definitions/ModelCapabilitiesOverrideSupports", - "description": "Feature flags indicating what the model supports" + "type": { + "type": "string", + "const": "file", + "description": "Attachment type discriminator" }, - "limits": { - "$ref": "#/definitions/ModelCapabilitiesOverrideLimits", - "description": "Token limits for prompts, outputs, and context window" + "path": { + "type": "string", + "description": "Absolute file path" + }, + "displayName": { + "type": "string", + "description": "User-facing display name for the attachment" + }, + "lineRange": { + "$ref": "#/definitions/SendAttachmentFileLineRange", + "description": "Optional line range to scope the attachment to a specific section of the file" } }, + "required": [ + "type", + "path", + "displayName" + ], "additionalProperties": false, - "description": "Override individual model capabilities resolved by the runtime", - "title": "ModelCapabilitiesOverride" + "description": "File attachment", + "title": "SendAttachmentFile" }, - "ModelCapabilitiesOverrideLimits": { + "SendAttachmentFileLineRange": { "type": "object", "properties": { - "max_prompt_tokens": { - "type": "integer", - "minimum": 0, - "description": "Maximum number of prompt/input tokens" - }, - "max_output_tokens": { + "start": { "type": "integer", + "exclusiveMinimum": true, "minimum": 0, - "description": "Maximum number of output/completion tokens" + "description": "Start line number (1-based)" }, - "max_context_window_tokens": { + "end": { "type": "integer", + "exclusiveMinimum": true, "minimum": 0, - "description": "Maximum total context window size in tokens" - }, - "vision": { - "$ref": "#/definitions/ModelCapabilitiesOverrideLimitsVision", - "description": "Vision-specific limits" + "description": "End line number (1-based, inclusive)" } }, + "required": [ + "start", + "end" + ], "additionalProperties": false, - "description": "Token limits for prompts, outputs, and context window", - "title": "ModelCapabilitiesOverrideLimits" + "description": "Optional line range to scope the attachment to a specific section of the file", + "title": "SendAttachmentFileLineRange" }, - "ModelCapabilitiesOverrideLimitsVision": { + "SendAttachmentGithubReference": { "type": "object", "properties": { - "supported_media_types": { - "type": "array", - "items": { - "type": "string" - }, - "description": "MIME types the model accepts" - }, - "max_prompt_images": { - "type": "integer", - "minimum": 1, - "description": "Maximum number of images per prompt" + "type": { + "type": "string", + "const": "github_reference", + "description": "Attachment type discriminator" }, - "max_prompt_image_size": { + "number": { "type": "integer", + "exclusiveMinimum": true, "minimum": 0, - "description": "Maximum image size in bytes" - } - }, - "additionalProperties": false, - "description": "Vision-specific limits", - "title": "ModelCapabilitiesOverrideLimitsVision" - }, - "ModelCapabilitiesOverrideSupports": { - "type": "object", - "properties": { - "vision": { - "type": "boolean", - "description": "Whether this model supports vision/image input" + "description": "Issue, pull request, or discussion number" }, - "reasoningEffort": { - "type": "boolean", - "description": "Whether this model supports reasoning effort configuration" + "title": { + "type": "string", + "description": "Title of the referenced item" + }, + "referenceType": { + "$ref": "#/definitions/SendAttachmentGithubReferenceType", + "description": "Type of GitHub reference" + }, + "state": { + "type": "string", + "description": "Current state of the referenced item (e.g., open, closed, merged)" + }, + "url": { + "type": "string", + "format": "uri", + "description": "URL to the referenced item on GitHub" } }, + "required": [ + "type", + "number", + "title", + "referenceType", + "state", + "url" + ], "additionalProperties": false, - "description": "Feature flags indicating what the model supports", - "title": "ModelCapabilitiesOverrideSupports" + "description": "GitHub issue, pull request, or discussion reference", + "title": "SendAttachmentGithubReference" }, - "ModelCapabilitiesSupports": { + "SendAttachmentGithubReferenceType": { + "type": "string", + "enum": [ + "issue", + "pr", + "discussion" + ], + "description": "Type of GitHub reference", + "title": "SendAttachmentGithubReferenceType", + "x-enumDescriptions": { + "issue": "GitHub issue reference.", + "pr": "GitHub pull request reference.", + "discussion": "GitHub discussion reference." + } + }, + "SendAttachmentSelection": { "type": "object", "properties": { - "vision": { - "type": "boolean", - "description": "Whether this model supports vision/image input" + "type": { + "type": "string", + "const": "selection", + "description": "Attachment type discriminator" }, - "reasoningEffort": { - "type": "boolean", - "description": "Whether this model supports reasoning effort configuration" + "filePath": { + "type": "string", + "description": "Absolute path to the file containing the selection" + }, + "displayName": { + "type": "string", + "description": "User-facing display name for the selection" + }, + "text": { + "type": "string", + "description": "The selected text content" + }, + "selection": { + "$ref": "#/definitions/SendAttachmentSelectionDetails", + "description": "Position range of the selection within the file" } }, + "required": [ + "type", + "filePath", + "displayName", + "text", + "selection" + ], "additionalProperties": false, - "description": "Feature flags indicating what the model supports", - "title": "ModelCapabilitiesSupports" + "description": "Code selection attachment from an editor", + "title": "SendAttachmentSelection" }, - "ModelList": { + "SendAttachmentSelectionDetails": { "type": "object", "properties": { - "models": { - "type": "array", - "items": { - "$ref": "#/definitions/Model" - }, - "description": "List of available models with full metadata" + "start": { + "$ref": "#/definitions/SendAttachmentSelectionDetailsStart", + "description": "Start position of the selection" + }, + "end": { + "$ref": "#/definitions/SendAttachmentSelectionDetailsEnd", + "description": "End position of the selection" } }, "required": [ - "models" + "start", + "end" ], "additionalProperties": false, - "description": "List of Copilot models available to the resolved user, including capabilities and billing metadata.", - "title": "ModelList" - }, - "ModelPickerCategory": { - "type": "string", - "enum": [ - "lightweight", - "versatile", - "powerful" - ], - "description": "Model capability category for grouping in the model picker", - "title": "ModelPickerCategory" - }, - "ModelPickerPriceCategory": { - "type": "string", - "enum": [ - "low", - "medium", - "high", - "very_high" - ], - "description": "Relative cost tier for token-based billing users", - "title": "ModelPickerPriceCategory" + "description": "Position range of the selection within the file", + "title": "SendAttachmentSelectionDetails" }, - "ModelPolicy": { + "SendAttachmentSelectionDetailsEnd": { "type": "object", "properties": { - "state": { - "$ref": "#/definitions/ModelPolicyState", - "description": "Current policy state for this model" + "line": { + "type": "integer", + "minimum": 0, + "description": "End line number (0-based)" }, - "terms": { - "type": "string", - "description": "Usage terms or conditions for this model" + "character": { + "type": "integer", + "minimum": 0, + "description": "End character offset within the line (0-based)" } }, "required": [ - "state" + "line", + "character" ], "additionalProperties": false, - "description": "Policy state (if applicable)", - "title": "ModelPolicy" - }, - "ModelPolicyState": { - "type": "string", - "enum": [ - "enabled", - "disabled", - "unconfigured" - ], - "description": "Current policy state for this model", - "title": "ModelPolicyState" + "description": "End position of the selection", + "title": "SendAttachmentSelectionDetailsEnd" }, - "ModelsListRequest": { - "anyOf": [ - { - "not": {} - }, - { - "type": "object", - "properties": { - "gitHubToken": { - "type": "string", - "description": "GitHub token for per-user model listing. When provided, resolves this token to determine the user's Copilot plan and available models instead of using the global auth." - } - }, - "additionalProperties": false + "SendAttachmentSelectionDetailsStart": { + "type": "object", + "properties": { + "line": { + "type": "integer", + "minimum": 0, + "description": "Start line number (0-based)" + }, + "character": { + "type": "integer", + "minimum": 0, + "description": "Start character offset within the line (0-based)" } + }, + "required": [ + "line", + "character" ], - "description": "Optional GitHub token used to list models for a specific user instead of the global auth context.", - "title": "ModelsListRequest" + "additionalProperties": false, + "description": "Start position of the selection", + "title": "SendAttachmentSelectionDetailsStart" }, - "ModelSwitchToRequest": { + "SendMode": { + "type": "string", + "enum": [ + "enqueue", + "immediate" + ], + "description": "How to deliver the message. `enqueue` (default) appends to the message queue. `immediate` interjects during an in-progress turn.", + "title": "SendMode", + "x-enumDescriptions": { + "enqueue": "Append the message to the normal session queue.", + "immediate": "Interject the message during the in-progress turn." + } + }, + "SendRequest": { "type": "object", "properties": { - "modelId": { + "prompt": { "type": "string", - "description": "Model identifier to switch to" + "description": "The user message text" }, - "reasoningEffort": { + "displayPrompt": { "type": "string", - "description": "Reasoning effort level to use for the model. \"none\" disables reasoning." + "description": "If provided, this is shown in the timeline instead of `prompt`" }, - "reasoningSummary": { - "$ref": "#/definitions/ReasoningSummary", - "description": "Reasoning summary mode to request for supported model clients" + "attachments": { + "type": "array", + "items": { + "$ref": "#/definitions/SendAttachment", + "description": "A user message attachment — a file, directory, code selection, blob, or GitHub reference" + }, + "description": "Optional attachments (files, directories, selections, blobs, GitHub references) to include with the message" }, - "modelCapabilities": { - "$ref": "#/definitions/ModelCapabilitiesOverride", - "description": "Override individual model capabilities resolved by the runtime" + "mode": { + "$ref": "#/definitions/SendMode", + "description": "How to deliver the message. `enqueue` (default) appends to the message queue. `immediate` interjects during an in-progress turn." + }, + "prepend": { + "type": "boolean", + "description": "If true, adds the message to the front of the queue instead of the end" + }, + "billable": { + "type": "boolean", + "description": "If false, this message will not trigger a Premium Request Unit charge. User messages default to billable." + }, + "requiredTool": { + "type": "string", + "description": "If set, the request will fail if the named tool is not available when this message is among the user messages at the start of the current exchange" + }, + "source": { + "description": "Optional provenance tag copied to the resulting user.message event. Supported values are `system`, `command-*`, and `schedule-*`." + }, + "agentMode": { + "$ref": "#/definitions/SendAgentMode", + "description": "The UI mode the agent was in when this message was sent. Defaults to the session's current mode." + }, + "requestHeaders": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Custom HTTP headers to include in outbound model requests for this turn. Merged with session-level provider headers; per-turn headers augment and overwrite session-level headers with the same key." + }, + "traceparent": { + "type": "string", + "description": "W3C Trace Context traceparent header for distributed tracing of this agent turn" + }, + "tracestate": { + "type": "string", + "description": "W3C Trace Context tracestate header for distributed tracing" + }, + "wait": { + "type": "boolean", + "description": "If true, await completion of the agentic loop for this message before returning. Defaults to false (fire-and-forget). When true, the result still contains the same `messageId`; the caller can rely on the agent having processed the message before the call resolves." } }, "required": [ - "modelId" + "prompt" ], "additionalProperties": false, - "description": "Target model identifier and optional reasoning effort, summary, and capability overrides.", - "title": "ModelSwitchToRequest" + "description": "Parameters for sending a user message to the session", + "title": "SendRequest" }, - "ModelSwitchToResult": { + "SendResult": { "type": "object", "properties": { - "modelId": { + "messageId": { "type": "string", - "description": "Currently active model identifier after the switch" + "description": "Unique identifier assigned to the message" } }, + "required": [ + "messageId" + ], "additionalProperties": false, - "description": "The model identifier active on the session after the switch.", - "title": "ModelSwitchToResult" + "description": "Result of sending a user message", + "title": "SendResult" }, - "ModeSetRequest": { + "ServerSkill": { "type": "object", "properties": { - "mode": { - "$ref": "#/definitions/SessionMode", - "description": "The session mode the agent is operating in" + "name": { + "type": "string", + "description": "Unique identifier for the skill" + }, + "description": { + "type": "string", + "description": "Description of what the skill does" + }, + "source": { + "$ref": "#/definitions/SkillSource", + "description": "Source location type (e.g., project, personal-copilot, plugin, builtin)" + }, + "userInvocable": { + "type": "boolean", + "description": "Whether the skill can be invoked by the user as a slash command" + }, + "enabled": { + "type": "boolean", + "description": "Whether the skill is currently enabled (based on global config)" + }, + "path": { + "type": "string", + "description": "Absolute path to the skill file" + }, + "projectPath": { + "type": "string", + "description": "The project path this skill belongs to (only for project/inherited skills)" } }, "required": [ - "mode" + "name", + "description", + "source", + "userInvocable", + "enabled" ], "additionalProperties": false, - "description": "Agent interaction mode to apply to the session.", - "title": "ModeSetRequest" + "title": "ServerSkill", + "description": "Schema for the `ServerSkill` type." }, - "NameGetResult": { + "ServerSkillList": { "type": "object", "properties": { - "name": { - "type": [ - "string", - "null" - ], - "description": "The session name (user-set or auto-generated), or null if not yet set" + "skills": { + "type": "array", + "items": { + "$ref": "#/definitions/ServerSkill" + }, + "description": "All discovered skills across all sources" } }, "required": [ - "name" + "skills" ], "additionalProperties": false, - "description": "The session's friendly name, or null when not yet set.", - "title": "NameGetResult" + "description": "Skills discovered across global and project sources.", + "title": "ServerSkillList" }, - "NameSetRequest": { + "SessionAuthStatus": { "type": "object", "properties": { - "name": { + "isAuthenticated": { + "type": "boolean", + "description": "Whether the session has resolved authentication" + }, + "authType": { + "$ref": "#/definitions/AuthInfoType", + "description": "Authentication type" + }, + "host": { "type": "string", - "minLength": 1, - "maxLength": 100, - "description": "New session name (1–100 characters, trimmed of leading/trailing whitespace)" + "format": "uri", + "description": "Authentication host URL" + }, + "login": { + "type": "string", + "description": "Authenticated login/username, if available" + }, + "statusMessage": { + "type": "string", + "description": "Human-readable authentication status description" + }, + "copilotPlan": { + "type": "string", + "description": "Copilot plan tier (e.g., individual_pro, business)" } }, "required": [ - "name" + "isAuthenticated" ], "additionalProperties": false, - "description": "New friendly name to apply to the session.", - "title": "NameSetRequest" + "description": "Authentication status and account metadata for the session.", + "title": "SessionAuthStatus" }, - "PermissionDecision": { - "anyOf": [ - { - "$ref": "#/definitions/PermissionDecisionApproveOnce" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForSession" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForLocation" - }, - { - "$ref": "#/definitions/PermissionDecisionApprovePermanently" - }, - { - "$ref": "#/definitions/PermissionDecisionReject" - }, - { - "$ref": "#/definitions/PermissionDecisionUserNotAvailable" + "SessionBulkDeleteResult": { + "type": "object", + "properties": { + "freedBytes": { + "type": "object", + "additionalProperties": { + "type": "integer", + "minimum": 0 + }, + "description": "Map of sessionId -> bytes freed by removing the session's workspace directory. Sessions whose deletion failed are omitted from this map (failures are logged on the server but not surfaced per-id; check the map for absent IDs to detect them)." } + }, + "required": [ + "freedBytes" ], - "description": "Decision to apply to a pending permission request.", - "title": "PermissionDecision" + "additionalProperties": false, + "description": "Map of sessionId -> bytes freed by removing the session's workspace directory.", + "title": "SessionBulkDeleteResult" }, - "PermissionDecisionApproveForLocation": { + "SessionContext": { "type": "object", "properties": { - "kind": { + "cwd": { "type": "string", - "const": "approve-for-location", - "description": "Approved and persisted for this project location" + "description": "Most recent working directory for this session" }, - "approval": { - "$ref": "#/definitions/PermissionDecisionApproveForLocationApproval", - "description": "The approval to persist for this location" + "gitRoot": { + "type": "string", + "description": "Git repository root, if the cwd was inside a git repo" }, - "locationKey": { + "repository": { "type": "string", - "description": "The location key (git root or cwd) to persist the approval to" + "description": "Repository slug in `owner/name` form, when known" + }, + "hostType": { + "$ref": "#/definitions/SessionContextHostType", + "description": "Repository host type" + }, + "branch": { + "type": "string", + "description": "Active git branch" } }, "required": [ - "kind", - "approval", - "locationKey" + "cwd" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocation", - "description": "Schema for the `PermissionDecisionApproveForLocation` type." + "title": "SessionContext", + "description": "Schema for the `SessionContext` type." }, - "PermissionDecisionApproveForLocationApproval": { + "SessionContextHostType": { + "type": "string", + "enum": [ + "github", + "ado" + ], + "description": "Repository host type", + "title": "SessionContextHostType", + "x-enumDescriptions": { + "github": "Session repository is hosted on GitHub.", + "ado": "Session repository is hosted on Azure DevOps." + } + }, + "SessionContextInfo": { "anyOf": [ { - "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalCommands" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalRead" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalWrite" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalMcp" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalMcpSampling" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalMemory" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalCustomTool" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalExtensionManagement" + "type": "object", + "properties": { + "modelName": { + "type": "string", + "description": "The model used for token counting" + }, + "systemTokens": { + "type": "integer", + "minimum": 0, + "description": "Tokens consumed by the system prompt" + }, + "conversationTokens": { + "type": "integer", + "minimum": 0, + "description": "Tokens consumed by user/assistant/tool messages" + }, + "toolDefinitionsTokens": { + "type": "integer", + "minimum": 0, + "description": "Tokens consumed by tool definitions sent to the model (excludes deferred tools)" + }, + "totalTokens": { + "type": "integer", + "minimum": 0, + "description": "Sum of system, conversation and tool-definition tokens" + }, + "promptTokenLimit": { + "type": "integer", + "minimum": 0, + "description": "Maximum prompt tokens allowed by the model (or DEFAULT_TOKEN_LIMIT if unspecified)" + }, + "compactionThreshold": { + "type": "integer", + "minimum": 0, + "description": "Token count at which background compaction starts (configurable percentage of promptTokenLimit)" + }, + "limit": { + "type": "integer", + "minimum": 0, + "description": "Total context limit for /context display. promptTokenLimit + min(32k or 64k, outputTokenLimit) depending on model." + }, + "bufferTokens": { + "type": "integer", + "minimum": 0, + "description": "Output reserve plus tokens after the buffer-exhaustion blocking threshold (default 95%)" + } + }, + "required": [ + "modelName", + "systemTokens", + "conversationTokens", + "toolDefinitionsTokens", + "totalTokens", + "promptTokenLimit", + "compactionThreshold", + "limit", + "bufferTokens" + ], + "additionalProperties": false, + "description": "Token-usage breakdown for the session's current context window" }, { - "$ref": "#/definitions/PermissionDecisionApproveForLocationApprovalExtensionPermissionAccess" + "type": "null" } ], - "description": "The approval to persist for this location", - "title": "PermissionDecisionApproveForLocationApproval" + "description": "Token breakdown for the current context window, or null if the session has not yet been initialized (no system prompt or tool metadata cached).", + "title": "SessionContextInfo" }, - "PermissionDecisionApproveForLocationApprovalCommands": { + "SessionEnrichMetadataResult": { "type": "object", "properties": { - "kind": { - "type": "string", - "const": "commands", - "description": "Approval scoped to specific command identifiers." - }, - "commandIdentifiers": { + "sessions": { "type": "array", "items": { - "type": "string" + "$ref": "#/definitions/SessionMetadata" }, - "description": "Command identifiers covered by this approval." + "description": "Same records, with summary and context backfilled" } }, "required": [ - "kind", - "commandIdentifiers" + "sessions" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalCommands", - "description": "Schema for the `PermissionDecisionApproveForLocationApprovalCommands` type." + "description": "The same metadata records, with summary and context fields backfilled where available.", + "title": "SessionEnrichMetadataResult" }, - "PermissionDecisionApproveForLocationApprovalCustomTool": { + "SessionFsAppendFileRequest": { "type": "object", "properties": { - "kind": { + "path": { "type": "string", - "const": "custom-tool", - "description": "Approval covering a custom tool." + "description": "Path using SessionFs conventions" }, - "toolName": { - "type": "string", - "description": "Custom tool name." - } - }, - "required": [ - "kind", - "toolName" - ], - "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalCustomTool", - "description": "Schema for the `PermissionDecisionApproveForLocationApprovalCustomTool` type." - }, - "PermissionDecisionApproveForLocationApprovalExtensionManagement": { - "type": "object", - "properties": { - "kind": { + "content": { "type": "string", - "const": "extension-management", - "description": "Approval covering extension lifecycle operations such as enable, disable, or reload." + "description": "Content to append" }, - "operation": { - "type": "string", - "description": "Optional operation identifier; when omitted, the approval covers all extension management operations." + "mode": { + "type": "integer", + "minimum": 0, + "description": "Optional POSIX-style mode for newly created files" } }, "required": [ - "kind" + "path", + "content" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalExtensionManagement", - "description": "Schema for the `PermissionDecisionApproveForLocationApprovalExtensionManagement` type." + "description": "File path, content to append, and optional mode for the client-provided session filesystem.", + "title": "SessionFsAppendFileRequest" }, - "PermissionDecisionApproveForLocationApprovalExtensionPermissionAccess": { + "SessionFsError": { "type": "object", "properties": { - "kind": { - "type": "string", - "const": "extension-permission-access", - "description": "Approval covering an extension's request to access a permission-gated capability." + "code": { + "$ref": "#/definitions/SessionFsErrorCode", + "description": "Error classification" }, - "extensionName": { + "message": { "type": "string", - "description": "Extension name." + "description": "Free-form detail about the error, for logging/diagnostics" } }, "required": [ - "kind", - "extensionName" + "code" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalExtensionPermissionAccess", - "description": "Schema for the `PermissionDecisionApproveForLocationApprovalExtensionPermissionAccess` type." + "description": "Describes a filesystem error.", + "title": "SessionFsError" }, - "PermissionDecisionApproveForLocationApprovalMcp": { - "type": "object", - "properties": { - "kind": { - "type": "string", - "const": "mcp", - "description": "Approval covering an MCP tool." - }, - "serverName": { - "type": "string", - "description": "MCP server name." - }, - "toolName": { - "type": [ - "string", - "null" - ], - "description": "MCP tool name, or null to cover every tool on the server." - } - }, - "required": [ - "kind", - "serverName", - "toolName" + "SessionFsErrorCode": { + "type": "string", + "enum": [ + "ENOENT", + "UNKNOWN" ], - "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalMcp", - "description": "Schema for the `PermissionDecisionApproveForLocationApprovalMcp` type." + "description": "Error classification", + "title": "SessionFsErrorCode", + "x-enumDescriptions": { + "ENOENT": "The requested path does not exist.", + "UNKNOWN": "The filesystem operation failed for an unspecified reason." + } }, - "PermissionDecisionApproveForLocationApprovalMcpSampling": { + "SessionFsExistsRequest": { "type": "object", "properties": { - "kind": { - "type": "string", - "const": "mcp-sampling", - "description": "Approval covering MCP sampling requests for a server." - }, - "serverName": { + "path": { "type": "string", - "description": "MCP server name." + "description": "Path using SessionFs conventions" } }, "required": [ - "kind", - "serverName" + "path" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalMcpSampling", - "description": "Schema for the `PermissionDecisionApproveForLocationApprovalMcpSampling` type." + "description": "Path to test for existence in the client-provided session filesystem.", + "title": "SessionFsExistsRequest" }, - "PermissionDecisionApproveForLocationApprovalMemory": { + "SessionFsExistsResult": { "type": "object", "properties": { - "kind": { - "type": "string", - "const": "memory", - "description": "Approval covering writes to long-term memory." + "exists": { + "type": "boolean", + "description": "Whether the path exists" } }, "required": [ - "kind" + "exists" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalMemory", - "description": "Schema for the `PermissionDecisionApproveForLocationApprovalMemory` type." + "description": "Indicates whether the requested path exists in the client-provided session filesystem.", + "title": "SessionFsExistsResult" }, - "PermissionDecisionApproveForLocationApprovalRead": { + "SessionFsMkdirRequest": { "type": "object", "properties": { - "kind": { + "path": { "type": "string", - "const": "read", - "description": "Approval covering read-only filesystem operations." + "description": "Path using SessionFs conventions" + }, + "recursive": { + "type": "boolean", + "description": "Create parent directories as needed" + }, + "mode": { + "type": "integer", + "minimum": 0, + "description": "Optional POSIX-style mode for newly created directories" } }, "required": [ - "kind" + "path" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalRead", - "description": "Schema for the `PermissionDecisionApproveForLocationApprovalRead` type." + "description": "Directory path to create in the client-provided session filesystem, with options for recursive creation and POSIX mode.", + "title": "SessionFsMkdirRequest" }, - "PermissionDecisionApproveForLocationApprovalWrite": { + "SessionFsReaddirRequest": { "type": "object", "properties": { - "kind": { + "path": { "type": "string", - "const": "write", - "description": "Approval covering filesystem write operations." + "description": "Path using SessionFs conventions" } }, "required": [ - "kind" + "path" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForLocationApprovalWrite", - "description": "Schema for the `PermissionDecisionApproveForLocationApprovalWrite` type." + "description": "Directory path whose entries should be listed from the client-provided session filesystem.", + "title": "SessionFsReaddirRequest" }, - "PermissionDecisionApproveForSession": { + "SessionFsReaddirResult": { "type": "object", "properties": { - "kind": { - "type": "string", - "const": "approve-for-session", - "description": "Approved and remembered for the rest of the session" - }, - "approval": { - "$ref": "#/definitions/PermissionDecisionApproveForSessionApproval", - "description": "The approval to add as a session-scoped rule" + "entries": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Entry names in the directory" }, - "domain": { - "type": "string", - "description": "The URL domain to approve for this session" + "error": { + "$ref": "#/definitions/SessionFsError", + "description": "Describes a filesystem error." } }, "required": [ - "kind" + "entries" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSession", - "description": "Schema for the `PermissionDecisionApproveForSession` type." - }, - "PermissionDecisionApproveForSessionApproval": { - "anyOf": [ - { - "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalCommands" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalRead" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalWrite" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalMcp" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalMcpSampling" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalMemory" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalCustomTool" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalExtensionManagement" - }, - { - "$ref": "#/definitions/PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess" - } - ], - "description": "The approval to add as a session-scoped rule", - "title": "PermissionDecisionApproveForSessionApproval" + "description": "Names of entries in the requested directory, or a filesystem error if the read failed.", + "title": "SessionFsReaddirResult" }, - "PermissionDecisionApproveForSessionApprovalCommands": { + "SessionFsReaddirWithTypesEntry": { "type": "object", "properties": { - "kind": { + "name": { "type": "string", - "const": "commands", - "description": "Approval scoped to specific command identifiers." + "description": "Entry name" }, - "commandIdentifiers": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Command identifiers covered by this approval." + "type": { + "$ref": "#/definitions/SessionFsReaddirWithTypesEntryType", + "description": "Entry type" } }, "required": [ - "kind", - "commandIdentifiers" + "name", + "type" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalCommands", - "description": "Schema for the `PermissionDecisionApproveForSessionApprovalCommands` type." + "title": "SessionFsReaddirWithTypesEntry", + "description": "Schema for the `SessionFsReaddirWithTypesEntry` type." }, - "PermissionDecisionApproveForSessionApprovalCustomTool": { + "SessionFsReaddirWithTypesEntryType": { + "type": "string", + "enum": [ + "file", + "directory" + ], + "description": "Entry type", + "title": "SessionFsReaddirWithTypesEntryType", + "x-enumDescriptions": { + "file": "The entry is a file.", + "directory": "The entry is a directory." + } + }, + "SessionFsReaddirWithTypesRequest": { "type": "object", "properties": { - "kind": { - "type": "string", - "const": "custom-tool", - "description": "Approval covering a custom tool." - }, - "toolName": { + "path": { "type": "string", - "description": "Custom tool name." + "description": "Path using SessionFs conventions" } }, "required": [ - "kind", - "toolName" + "path" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalCustomTool", - "description": "Schema for the `PermissionDecisionApproveForSessionApprovalCustomTool` type." + "description": "Directory path whose entries (with type information) should be listed from the client-provided session filesystem.", + "title": "SessionFsReaddirWithTypesRequest" }, - "PermissionDecisionApproveForSessionApprovalExtensionManagement": { + "SessionFsReaddirWithTypesResult": { "type": "object", "properties": { - "kind": { - "type": "string", - "const": "extension-management", - "description": "Approval covering extension lifecycle operations such as enable, disable, or reload." + "entries": { + "type": "array", + "items": { + "$ref": "#/definitions/SessionFsReaddirWithTypesEntry" + }, + "description": "Directory entries with type information" }, - "operation": { - "type": "string", - "description": "Optional operation identifier; when omitted, the approval covers all extension management operations." + "error": { + "$ref": "#/definitions/SessionFsError", + "description": "Describes a filesystem error." } }, "required": [ - "kind" + "entries" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalExtensionManagement", - "description": "Schema for the `PermissionDecisionApproveForSessionApprovalExtensionManagement` type." + "description": "Entries in the requested directory paired with file/directory type information, or a filesystem error if the read failed.", + "title": "SessionFsReaddirWithTypesResult" }, - "PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess": { + "SessionFsReadFileRequest": { "type": "object", "properties": { - "kind": { - "type": "string", - "const": "extension-permission-access", - "description": "Approval covering an extension's request to access a permission-gated capability." - }, - "extensionName": { + "path": { "type": "string", - "description": "Extension name." + "description": "Path using SessionFs conventions" } }, "required": [ - "kind", - "extensionName" + "path" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess", - "description": "Schema for the `PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess` type." + "description": "Path of the file to read from the client-provided session filesystem.", + "title": "SessionFsReadFileRequest" }, - "PermissionDecisionApproveForSessionApprovalMcp": { + "SessionFsReadFileResult": { "type": "object", "properties": { - "kind": { - "type": "string", - "const": "mcp", - "description": "Approval covering an MCP tool." - }, - "serverName": { + "content": { "type": "string", - "description": "MCP server name." + "description": "File content as UTF-8 string" }, - "toolName": { - "type": [ - "string", - "null" - ], - "description": "MCP tool name, or null to cover every tool on the server." + "error": { + "$ref": "#/definitions/SessionFsError", + "description": "Describes a filesystem error." } }, "required": [ - "kind", - "serverName", - "toolName" + "content" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalMcp", - "description": "Schema for the `PermissionDecisionApproveForSessionApprovalMcp` type." + "description": "File content as a UTF-8 string, or a filesystem error if the read failed.", + "title": "SessionFsReadFileResult" }, - "PermissionDecisionApproveForSessionApprovalMcpSampling": { + "SessionFsRenameRequest": { "type": "object", "properties": { - "kind": { + "src": { "type": "string", - "const": "mcp-sampling", - "description": "Approval covering MCP sampling requests for a server." + "description": "Source path using SessionFs conventions" }, - "serverName": { + "dest": { "type": "string", - "description": "MCP server name." + "description": "Destination path using SessionFs conventions" } }, "required": [ - "kind", - "serverName" + "src", + "dest" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalMcpSampling", - "description": "Schema for the `PermissionDecisionApproveForSessionApprovalMcpSampling` type." + "description": "Source and destination paths for renaming or moving an entry in the client-provided session filesystem.", + "title": "SessionFsRenameRequest" }, - "PermissionDecisionApproveForSessionApprovalMemory": { + "SessionFsRmRequest": { "type": "object", "properties": { - "kind": { + "path": { "type": "string", - "const": "memory", - "description": "Approval covering writes to long-term memory." + "description": "Path using SessionFs conventions" + }, + "recursive": { + "type": "boolean", + "description": "Remove directories and their contents recursively" + }, + "force": { + "type": "boolean", + "description": "Ignore errors if the path does not exist" } }, "required": [ - "kind" + "path" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalMemory", - "description": "Schema for the `PermissionDecisionApproveForSessionApprovalMemory` type." + "description": "Path to remove from the client-provided session filesystem, with options for recursive removal and force.", + "title": "SessionFsRmRequest" }, - "PermissionDecisionApproveForSessionApprovalRead": { + "SessionFsSetProviderCapabilities": { "type": "object", "properties": { - "kind": { - "type": "string", - "const": "read", - "description": "Approval covering read-only filesystem operations." + "sqlite": { + "type": "boolean", + "description": "Whether the provider supports SQLite query/exists operations" } }, - "required": [ - "kind" - ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalRead", - "description": "Schema for the `PermissionDecisionApproveForSessionApprovalRead` type." + "description": "Optional capabilities declared by the provider", + "title": "SessionFsSetProviderCapabilities" }, - "PermissionDecisionApproveForSessionApprovalWrite": { + "SessionFsSetProviderConventions": { + "type": "string", + "enum": [ + "windows", + "posix" + ], + "description": "Path conventions used by this filesystem", + "title": "SessionFsSetProviderConventions", + "x-enumDescriptions": { + "windows": "Paths use Windows path conventions.", + "posix": "Paths use POSIX path conventions." + } + }, + "SessionFsSetProviderRequest": { "type": "object", "properties": { - "kind": { + "initialCwd": { "type": "string", - "const": "write", - "description": "Approval covering filesystem write operations." + "description": "Initial working directory for sessions" + }, + "sessionStatePath": { + "type": "string", + "description": "Path within each session's SessionFs where the runtime stores files for that session" + }, + "conventions": { + "$ref": "#/definitions/SessionFsSetProviderConventions", + "description": "Path conventions used by this filesystem" + }, + "capabilities": { + "$ref": "#/definitions/SessionFsSetProviderCapabilities", + "description": "Optional capabilities declared by the provider" } }, "required": [ - "kind" + "initialCwd", + "sessionStatePath", + "conventions" ], "additionalProperties": false, - "title": "PermissionDecisionApproveForSessionApprovalWrite", - "description": "Schema for the `PermissionDecisionApproveForSessionApprovalWrite` type." + "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" }, - "PermissionDecisionApproveOnce": { + "SessionFsSetProviderResult": { "type": "object", "properties": { - "kind": { - "type": "string", - "const": "approve-once", - "description": "The permission request was approved for this one instance" + "success": { + "type": "boolean", + "description": "Whether the provider was set successfully" } }, "required": [ - "kind" + "success" ], "additionalProperties": false, - "title": "PermissionDecisionApproveOnce", - "description": "Schema for the `PermissionDecisionApproveOnce` type." + "description": "Indicates whether the calling client was registered as the session filesystem provider.", + "title": "SessionFsSetProviderResult" }, - "PermissionDecisionApprovePermanently": { + "SessionFsSqliteExistsResult": { "type": "object", "properties": { - "kind": { - "type": "string", - "const": "approve-permanently", - "description": "Approved and persisted across sessions" - }, - "domain": { - "type": "string", - "description": "The URL domain to approve permanently" + "exists": { + "type": "boolean", + "description": "Whether the session database already exists" } }, "required": [ - "kind", - "domain" + "exists" ], "additionalProperties": false, - "title": "PermissionDecisionApprovePermanently", - "description": "Schema for the `PermissionDecisionApprovePermanently` type." + "description": "Indicates whether the per-session SQLite database already exists.", + "title": "SessionFsSqliteExistsResult" }, - "PermissionDecisionReject": { + "SessionFsSqliteQueryRequest": { "type": "object", "properties": { - "kind": { + "query": { "type": "string", - "const": "reject", - "description": "Denied by the user during an interactive prompt" + "description": "SQL query to execute" }, - "feedback": { - "type": "string", - "description": "Optional feedback from the user explaining the denial" + "queryType": { + "$ref": "#/definitions/SessionFsSqliteQueryType", + "description": "How to execute the query: 'exec' for DDL/multi-statement (no results), 'query' for SELECT (returns rows), 'run' for INSERT/UPDATE/DELETE (returns rowsAffected)" + }, + "params": { + "type": "object", + "additionalProperties": { + "type": [ + "string", + "number", + "null" + ] + }, + "description": "Optional named bind parameters" } }, "required": [ - "kind" + "query", + "queryType" ], "additionalProperties": false, - "title": "PermissionDecisionReject", - "description": "Schema for the `PermissionDecisionReject` type." + "description": "SQL query, query type, and optional bind parameters for executing a SQLite query against the per-session database.", + "title": "SessionFsSqliteQueryRequest" }, - "PermissionDecisionRequest": { + "SessionFsSqliteQueryResult": { "type": "object", "properties": { - "requestId": { - "type": "string", - "description": "Request ID of the pending permission request" + "rows": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": {} + }, + "description": "For SELECT: array of row objects. For others: empty array." }, - "result": { - "$ref": "#/definitions/PermissionDecision", - "description": "Decision to apply to a pending permission request." + "columns": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Column names from the result set" + }, + "rowsAffected": { + "type": "integer", + "minimum": 0, + "description": "Number of rows affected (for INSERT/UPDATE/DELETE)" + }, + "lastInsertRowid": { + "type": "integer", + "description": "SQLite last_insert_rowid() value for INSERT." + }, + "error": { + "$ref": "#/definitions/SessionFsError", + "description": "Describes a filesystem error." } }, "required": [ - "requestId", - "result" + "rows", + "columns", + "rowsAffected" ], "additionalProperties": false, - "description": "Pending permission request ID and the decision to apply (approve/reject and scope).", - "title": "PermissionDecisionRequest" + "description": "Query results including rows, columns, and rows affected, or a filesystem error if execution failed.", + "title": "SessionFsSqliteQueryResult" }, - "PermissionDecisionUserNotAvailable": { + "SessionFsSqliteQueryType": { + "type": "string", + "enum": [ + "exec", + "query", + "run" + ], + "description": "How to execute the query: 'exec' for DDL/multi-statement (no results), 'query' for SELECT (returns rows), 'run' for INSERT/UPDATE/DELETE (returns rowsAffected)", + "title": "SessionFsSqliteQueryType", + "x-enumDescriptions": { + "exec": "Execute DDL or multi-statement SQL without returning rows.", + "query": "Execute a SELECT-style query and return rows.", + "run": "Execute INSERT, UPDATE, or DELETE SQL and return affected-row metadata." + } + }, + "SessionFsStatRequest": { "type": "object", "properties": { - "kind": { + "path": { "type": "string", - "const": "user-not-available", - "description": "Denied because user confirmation was unavailable" + "description": "Path using SessionFs conventions" } }, "required": [ - "kind" + "path" ], "additionalProperties": false, - "title": "PermissionDecisionUserNotAvailable", - "description": "Schema for the `PermissionDecisionUserNotAvailable` type." + "description": "Path whose metadata should be returned from the client-provided session filesystem.", + "title": "SessionFsStatRequest" }, - "PermissionRequestResult": { + "SessionFsStatResult": { "type": "object", "properties": { - "success": { + "isFile": { "type": "boolean", - "description": "Whether the permission request was handled successfully" + "description": "Whether the path is a file" + }, + "isDirectory": { + "type": "boolean", + "description": "Whether the path is a directory" + }, + "size": { + "type": "integer", + "minimum": 0, + "description": "File size in bytes" + }, + "mtime": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp of last modification" + }, + "birthtime": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp of creation" + }, + "error": { + "$ref": "#/definitions/SessionFsError", + "description": "Describes a filesystem error." } }, "required": [ - "success" + "isFile", + "isDirectory", + "size", + "mtime", + "birthtime" ], "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" + "description": "Filesystem metadata for the requested path, or a filesystem error if the stat failed.", + "title": "SessionFsStatResult" }, - "PermissionsResetSessionApprovalsResult": { + "SessionFsWriteFileRequest": { "type": "object", "properties": { - "success": { - "type": "boolean", - "description": "Whether the operation succeeded" + "path": { + "type": "string", + "description": "Path using SessionFs conventions" + }, + "content": { + "type": "string", + "description": "Content to write" + }, + "mode": { + "type": "integer", + "minimum": 0, + "description": "Optional POSIX-style mode for newly created files" } }, "required": [ - "success" + "path", + "content" ], "additionalProperties": false, - "description": "Indicates whether the operation succeeded.", - "title": "PermissionsResetSessionApprovalsResult" + "description": "File path, content to write, and optional mode for the client-provided session filesystem.", + "title": "SessionFsWriteFileRequest" }, - "PermissionsSetApproveAllRequest": { + "SessionInstalledPlugin": { "type": "object", "properties": { + "name": { + "type": "string", + "description": "Plugin name" + }, + "marketplace": { + "type": "string", + "description": "Marketplace the plugin came from (empty string for direct repo installs)" + }, + "version": { + "type": "string", + "description": "Installed version, if known" + }, + "installed_at": { + "type": "string", + "description": "Installation timestamp (ISO-8601)" + }, "enabled": { "type": "boolean", - "description": "Whether to auto-approve all tool permission requests" + "description": "Whether the plugin is currently enabled" + }, + "cache_path": { + "type": "string", + "description": "Path where the plugin is cached locally" + }, + "source": { + "$ref": "#/definitions/SessionInstalledPluginSource", + "description": "Source descriptor for direct repo installs (when marketplace is empty)" } }, "required": [ + "name", + "marketplace", + "installed_at", "enabled" ], "additionalProperties": false, - "description": "Whether to auto-approve all tool permission requests for the rest of the session.", - "title": "PermissionsSetApproveAllRequest" + "title": "SessionInstalledPlugin", + "description": "Schema for the `SessionInstalledPlugin` type." }, - "PermissionsSetApproveAllResult": { - "type": "object", - "properties": { - "success": { - "type": "boolean", - "description": "Whether the operation succeeded" + "SessionInstalledPluginSource": { + "anyOf": [ + { + "type": "string", + "pattern": "^[^/]+\\/[^/]+$" + }, + { + "$ref": "#/definitions/SessionInstalledPluginSourceGithub" + }, + { + "$ref": "#/definitions/SessionInstalledPluginSourceUrl" + }, + { + "$ref": "#/definitions/SessionInstalledPluginSourceLocal" } - }, - "required": [ - "success" ], - "additionalProperties": false, - "description": "Indicates whether the operation succeeded.", - "title": "PermissionsSetApproveAllResult" + "description": "Source descriptor for direct repo installs (when marketplace is empty)", + "title": "SessionInstalledPluginSource" }, - "PingRequest": { + "SessionInstalledPluginSourceGithub": { "type": "object", "properties": { - "message": { + "source": { "type": "string", - "description": "Optional message to echo back" + "const": "github", + "description": "Constant value. Always \"github\"." + }, + "repo": { + "type": "string", + "pattern": "^[^/]+\\/[^/]+$" + }, + "ref": { + "type": "string" + }, + "path": { + "type": "string" } }, + "required": [ + "source", + "repo" + ], "additionalProperties": false, - "description": "Optional message to echo back to the caller.", - "title": "PingRequest" + "title": "SessionInstalledPluginSourceGithub", + "description": "Schema for the `SessionInstalledPluginSourceGithub` type." }, - "PingResult": { + "SessionInstalledPluginSourceLocal": { "type": "object", "properties": { - "message": { + "source": { "type": "string", - "description": "Echoed message (or default greeting)" - }, - "timestamp": { - "type": "integer", - "description": "Server timestamp in milliseconds" + "const": "local", + "description": "Constant value. Always \"local\"." }, - "protocolVersion": { - "type": "integer", - "description": "Server protocol version number" + "path": { + "type": "string" } }, "required": [ - "message", - "timestamp", - "protocolVersion" + "source", + "path" ], "additionalProperties": false, - "description": "Server liveness response, including the echoed message, current timestamp, and protocol version.", - "title": "PingResult" + "title": "SessionInstalledPluginSourceLocal", + "description": "Schema for the `SessionInstalledPluginSourceLocal` type." }, - "PlanReadResult": { + "SessionInstalledPluginSourceUrl": { "type": "object", "properties": { - "exists": { - "type": "boolean", - "description": "Whether the plan file exists in the workspace" + "source": { + "type": "string", + "const": "url", + "description": "Constant value. Always \"url\"." }, - "content": { - "type": [ - "string", - "null" - ], - "description": "The content of the plan file, or null if it does not exist" + "url": { + "type": "string", + "format": "uri" + }, + "ref": { + "type": "string" }, "path": { - "type": [ - "string", - "null" - ], - "description": "Absolute file path of the plan file, or null if workspace is not enabled" + "type": "string" } }, "required": [ - "exists", - "content", - "path" + "source", + "url" ], "additionalProperties": false, - "description": "Existence, contents, and resolved path of the session plan file.", - "title": "PlanReadResult" + "title": "SessionInstalledPluginSourceUrl", + "description": "Schema for the `SessionInstalledPluginSourceUrl` type." }, - "PlanUpdateRequest": { + "SessionList": { "type": "object", "properties": { - "content": { - "type": "string", - "description": "The new content for the plan file" + "sessions": { + "type": "array", + "items": { + "$ref": "#/definitions/SessionMetadata" + }, + "description": "Sessions ordered most-recently-modified first" } }, "required": [ - "content" + "sessions" ], "additionalProperties": false, - "description": "Replacement contents to write to the session plan file.", - "title": "PlanUpdateRequest" + "description": "Persisted sessions matching the filter, ordered most-recently-modified first.", + "title": "SessionList" }, - "Plugin": { + "SessionListFilter": { "type": "object", "properties": { - "name": { + "cwd": { "type": "string", - "description": "Plugin name" + "description": "Match sessions whose context.cwd equals this value" }, - "marketplace": { + "gitRoot": { "type": "string", - "description": "Marketplace the plugin came from" + "description": "Match sessions whose context.gitRoot equals this value" }, - "version": { + "repository": { "type": "string", - "description": "Installed version" + "description": "Match sessions whose context.repository equals this value" }, - "enabled": { - "type": "boolean", - "description": "Whether the plugin is currently enabled" + "branch": { + "type": "string", + "description": "Match sessions whose context.branch equals this value" } }, - "required": [ - "name", - "marketplace", - "enabled" - ], "additionalProperties": false, - "title": "Plugin", - "description": "Schema for the `Plugin` type." + "description": "Optional filter applied to the returned sessions", + "title": "SessionListFilter" }, - "PluginList": { + "SessionLoadDeferredRepoHooksResult": { "type": "object", "properties": { - "plugins": { + "startupPrompts": { "type": "array", "items": { - "$ref": "#/definitions/Plugin" + "type": "string" }, - "description": "Installed plugins" + "description": "Repo-level startup prompts queued from repo hook configs. Empty on resume, when no repo configs were pending, or when disableAllHooks is set." + }, + "hookCount": { + "type": "integer", + "minimum": 0, + "description": "Total hook command count (user + plugin + repo) loaded for the session by this call. Captured atomically with startupPrompts so callers don't need to read a separate counter." } }, "required": [ - "plugins" + "startupPrompts", + "hookCount" ], "additionalProperties": false, - "description": "Plugins installed for the session, with their enabled state and version metadata.", - "title": "PluginList" + "description": "Queued repo-level startup prompts and the total hook command count after loading.", + "title": "SessionLoadDeferredRepoHooksResult" }, - "QueuedCommandHandled": { + "SessionLogLevel": { + "type": "string", + "enum": [ + "info", + "warning", + "error" + ], + "description": "Log severity level. Determines how the message is displayed in the timeline. Defaults to \"info\".", + "title": "SessionLogLevel", + "x-enumDescriptions": { + "info": "Informational message.", + "warning": "Warning message that may require attention.", + "error": "Error message describing a failure." + } + }, + "SessionMetadata": { "type": "object", "properties": { - "handled": { - "type": "boolean", - "const": true, - "description": "The command was handled" + "sessionId": { + "type": "string", + "description": "Stable session identifier" }, - "stopProcessingQueue": { + "startTime": { + "type": "string", + "description": "Session creation time as an ISO 8601 timestamp" + }, + "modifiedTime": { + "type": "string", + "description": "Last-modified time of the session's persisted state, as ISO 8601" + }, + "summary": { + "type": "string", + "description": "Short summary of the session, when one has been derived" + }, + "name": { + "type": "string", + "description": "Optional human-friendly name set via /rename" + }, + "isRemote": { "type": "boolean", - "description": "If true, stop processing remaining queued items" + "description": "True for remote (GitHub) sessions; false for local" + }, + "context": { + "$ref": "#/definitions/SessionContext", + "description": "Schema for the `SessionContext` type." + }, + "mcTaskId": { + "type": "string", + "description": "GitHub task ID, when this local session is bound to one. Only present for local sessions exported to remote control." } }, "required": [ - "handled" + "sessionId", + "startTime", + "modifiedTime", + "isRemote" ], "additionalProperties": false, - "title": "QueuedCommandHandled", - "description": "Schema for the `QueuedCommandHandled` type." + "title": "SessionMetadata", + "description": "Schema for the `SessionMetadata` type." }, - "QueuedCommandNotHandled": { + "SessionMetadataSnapshot": { "type": "object", "properties": { - "handled": { + "sessionId": { + "type": "string", + "description": "The unique identifier of the session" + }, + "startTime": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp of when the session started" + }, + "modifiedTime": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp of when the session's persisted state was last modified on disk. For new sessions, equals startTime. For resumed sessions, reflects the previous modification time at construction." + }, + "isRemote": { "type": "boolean", - "const": false, - "description": "The command was not handled" + "description": "Whether this is a remote session (i.e., one whose runtime executes elsewhere and is steered through this process)" + }, + "alreadyInUse": { + "type": "boolean", + "description": "True when the session was detected to be in use by another process at construction time. Local consumers may surface a confirmation prompt before fully attaching. Always false for new sessions." + }, + "workspacePath": { + "type": [ + "string", + "null" + ], + "description": "Absolute path to the session's workspace directory on disk, or null if the session has no associated workspace" + }, + "initialName": { + "type": "string", + "description": "User-provided name supplied at session construction (via `--name`), if any. Immutable after construction." + }, + "remoteMetadata": { + "$ref": "#/definitions/MetadataSnapshotRemoteMetadata", + "description": "Remote-session-specific metadata. Populated only when `isRemote` is true. Fields are immutable for the lifetime of the session." + }, + "summary": { + "type": "string", + "description": "Short human-readable summary of the session, if known. Omitted when no summary has been generated." + }, + "workingDirectory": { + "type": "string", + "description": "Absolute path to the session's current working directory" + }, + "currentMode": { + "$ref": "#/definitions/MetadataSnapshotCurrentMode", + "description": "The current agent mode for this session (e.g., 'interactive', 'plan', 'autopilot')" + }, + "selectedModel": { + "type": "string", + "description": "Currently selected model identifier, if any" + }, + "workspace": { + "$ref": "#/definitions/WorkspaceSummary", + "description": "Public-facing workspace metadata for this session, or null if the session has no associated workspace. Excludes runtime-internal fields (GitHub IDs, summary count, internal flags)." } }, "required": [ - "handled" + "sessionId", + "startTime", + "modifiedTime", + "isRemote", + "alreadyInUse", + "workspacePath", + "workingDirectory", + "currentMode", + "workspace" ], "additionalProperties": false, - "title": "QueuedCommandNotHandled", - "description": "Schema for the `QueuedCommandNotHandled` type." - }, - "QueuedCommandResult": { - "anyOf": [ - { - "$ref": "#/definitions/QueuedCommandHandled" - }, - { - "$ref": "#/definitions/QueuedCommandNotHandled" - } - ], - "description": "Result of the queued command execution", - "title": "QueuedCommandResult" + "description": "Point-in-time snapshot of slow-changing session identifier and state fields", + "title": "SessionMetadataSnapshot" }, - "ReasoningSummary": { + "SessionMode": { "type": "string", "enum": [ - "none", - "concise", - "detailed" + "interactive", + "plan", + "autopilot" ], - "description": "Reasoning summary mode to request for supported model clients", - "title": "ReasoningSummary" + "description": "The session mode the agent is operating in", + "title": "SessionMode", + "x-enumDescriptions": { + "interactive": "The agent is responding interactively to the user.", + "plan": "The agent is preparing a plan before making changes.", + "autopilot": "The agent is working autonomously toward task completion." + } }, - "RemoteEnableRequest": { + "SessionPruneResult": { "type": "object", "properties": { - "mode": { - "$ref": "#/definitions/RemoteSessionMode", - "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." + "deleted": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Session IDs that were deleted (always empty in dry-run mode)" + }, + "candidates": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Session IDs that would be deleted in dry-run mode (always empty otherwise)" + }, + "skipped": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Session IDs that were skipped (e.g., named sessions)" + }, + "freedBytes": { + "type": "integer", + "minimum": 0, + "description": "Total bytes freed (actual when not dry-run, projected when dry-run)" + }, + "dryRun": { + "type": "boolean", + "description": "True when no deletions were actually performed" } }, + "required": [ + "deleted", + "candidates", + "skipped", + "freedBytes", + "dryRun" + ], "additionalProperties": false, - "description": "Optional remote session mode (\"off\", \"export\", or \"on\"); defaults to enabling both export and remote steering.", - "title": "RemoteEnableRequest" + "description": "Outcome of the prune operation: deleted IDs, dry-run candidates, skipped IDs, total bytes freed, and the dry-run flag.", + "title": "SessionPruneResult" }, - "RemoteEnableResult": { + "SessionsBulkDeleteRequest": { "type": "object", "properties": { - "url": { - "type": "string", - "format": "uri", - "description": "GitHub frontend URL for this session" - }, - "remoteSteerable": { - "type": "boolean", - "description": "Whether remote steering is enabled" + "sessionIds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Session IDs to close, deactivate, and delete from disk" } }, "required": [ - "remoteSteerable" + "sessionIds" ], "additionalProperties": false, - "description": "GitHub URL for the session and a flag indicating whether remote steering is enabled.", - "title": "RemoteEnableResult" + "description": "Session IDs to close, deactivate, and delete from disk.", + "title": "SessionsBulkDeleteRequest" }, - "RemoteSessionConnectionResult": { + "SessionsCheckInUseRequest": { "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." + "sessionIds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Session IDs to test for live in-use locks" } }, "required": [ - "sessionId", - "metadata" + "sessionIds" ], "additionalProperties": false, - "description": "Remote session connection result.", - "title": "RemoteSessionConnectionResult" + "description": "Session IDs to test for live in-use locks.", + "title": "SessionsCheckInUseRequest" }, - "RemoteSessionMode": { - "type": "string", - "enum": [ - "off", - "export", - "on" + "SessionsCheckInUseResult": { + "type": "object", + "properties": { + "inUse": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Session IDs from the input set that are currently held by another running process via an alive lock file" + } + }, + "required": [ + "inUse" ], - "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" + "additionalProperties": false, + "description": "Session IDs from the input set that are currently in use by another process.", + "title": "SessionsCheckInUseResult" }, - "ServerSkill": { + "SessionsCloseRequest": { "type": "object", "properties": { - "name": { - "type": "string", - "description": "Unique identifier for the skill" - }, - "description": { - "type": "string", - "description": "Description of what the skill does" - }, - "source": { - "$ref": "#/definitions/SkillSource", - "description": "Source location type (e.g., project, personal-copilot, plugin, builtin)" - }, - "userInvocable": { - "type": "boolean", - "description": "Whether the skill can be invoked by the user as a slash command" - }, - "enabled": { - "type": "boolean", - "description": "Whether the skill is currently enabled (based on global config)" - }, - "path": { - "type": "string", - "description": "Absolute path to the skill file" - }, - "projectPath": { + "sessionId": { "type": "string", - "description": "The project path this skill belongs to (only for project/inherited skills)" + "description": "Session ID to close" } }, "required": [ - "name", - "description", - "source", - "userInvocable", - "enabled" + "sessionId" ], "additionalProperties": false, - "title": "ServerSkill", - "description": "Schema for the `ServerSkill` type." + "description": "Session ID to close.", + "title": "SessionsCloseRequest" }, - "ServerSkillList": { + "SessionsCloseResult": { + "type": "object", + "properties": {}, + "additionalProperties": false, + "description": "Closes a session: emits shutdown, flushes pending events to disk, releases the in-use lock, disposes the active session. Idempotent: succeeds even if the session is not currently active.", + "title": "SessionsCloseResult" + }, + "SessionsEnrichMetadataRequest": { "type": "object", "properties": { - "skills": { + "sessions": { "type": "array", "items": { - "$ref": "#/definitions/ServerSkill" + "$ref": "#/definitions/SessionMetadata" }, - "description": "All discovered skills across all sources" + "description": "Session metadata records to enrich. Records that already have summary and context are returned unchanged." } }, "required": [ - "skills" + "sessions" ], "additionalProperties": false, - "description": "Skills discovered across global and project sources.", - "title": "ServerSkillList" + "description": "Session metadata records to enrich with summary and context information.", + "title": "SessionsEnrichMetadataRequest" }, - "SessionAuthStatus": { + "SessionSetCredentialsParams": { "type": "object", "properties": { - "isAuthenticated": { + "credentials": { + "$ref": "#/definitions/AuthInfo", + "description": "The new auth credentials to install on the session. When omitted or `undefined`, the call is a no-op and the session's existing credentials are preserved. The runtime stores the value verbatim and uses it for outbound model/API requests; it does NOT re-validate or re-fetch the associated Copilot user response. Several variants carry secret material; treat this method's params as containing secrets at rest and in transit." + } + }, + "additionalProperties": false, + "description": "New auth credentials to install on the session. Omit to leave credentials unchanged.", + "title": "SessionSetCredentialsParams" + }, + "SessionSetCredentialsResult": { + "type": "object", + "properties": { + "success": { "type": "boolean", - "description": "Whether the session has resolved authentication" - }, - "authType": { - "$ref": "#/definitions/AuthInfoType", - "description": "Authentication type" - }, - "host": { - "type": "string", - "format": "uri", - "description": "Authentication host URL" - }, - "login": { - "type": "string", - "description": "Authenticated login/username, if available" - }, - "statusMessage": { - "type": "string", - "description": "Human-readable authentication status description" - }, - "copilotPlan": { - "type": "string", - "description": "Copilot plan tier (e.g., individual_pro, business)" + "description": "Whether the operation succeeded" } }, "required": [ - "isAuthenticated" + "success" ], "additionalProperties": false, - "description": "Authentication status and account metadata for the session.", - "title": "SessionAuthStatus" + "description": "Indicates whether the credential update succeeded.", + "title": "SessionSetCredentialsResult" }, - "SessionFsAppendFileRequest": { + "SessionsFindByPrefixRequest": { "type": "object", "properties": { - "path": { - "type": "string", - "description": "Path using SessionFs conventions" - }, - "content": { + "prefix": { "type": "string", - "description": "Content to append" - }, - "mode": { - "type": "integer", - "minimum": 0, - "description": "Optional POSIX-style mode for newly created files" + "description": "UUID prefix (>=7 hex chars, <36 chars). Returns the unique session ID, or undefined when there is no match or the prefix matches multiple sessions." } }, "required": [ - "path", - "content" + "prefix" ], "additionalProperties": false, - "description": "File path, content to append, and optional mode for the client-provided session filesystem.", - "title": "SessionFsAppendFileRequest" + "description": "UUID prefix to resolve to a unique session ID.", + "title": "SessionsFindByPrefixRequest" }, - "SessionFsError": { + "SessionsFindByPrefixResult": { "type": "object", "properties": { - "code": { - "$ref": "#/definitions/SessionFsErrorCode", - "description": "Error classification" - }, - "message": { + "sessionId": { "type": "string", - "description": "Free-form detail about the error, for logging/diagnostics" + "description": "Omitted when no unique session matches the prefix (no match or ambiguous)" } }, - "required": [ - "code" - ], "additionalProperties": false, - "description": "Describes a filesystem error.", - "title": "SessionFsError" - }, - "SessionFsErrorCode": { - "type": "string", - "enum": [ - "ENOENT", - "UNKNOWN" - ], - "description": "Error classification", - "title": "SessionFsErrorCode" + "description": "Session ID matching the prefix, omitted when no unique match exists.", + "title": "SessionsFindByPrefixResult" }, - "SessionFsExistsRequest": { + "SessionsFindByTaskIDRequest": { "type": "object", "properties": { - "path": { + "taskId": { "type": "string", - "description": "Path using SessionFs conventions" + "description": "GitHub task ID to look up" } }, "required": [ - "path" + "taskId" ], "additionalProperties": false, - "description": "Path to test for existence in the client-provided session filesystem.", - "title": "SessionFsExistsRequest" + "description": "GitHub task ID to look up.", + "title": "SessionsFindByTaskIDRequest" }, - "SessionFsExistsResult": { + "SessionsFindByTaskIDResult": { "type": "object", "properties": { - "exists": { - "type": "boolean", - "description": "Whether the path exists" + "sessionId": { + "type": "string", + "description": "Omitted when no local session is bound to that GitHub task" } }, - "required": [ - "exists" - ], "additionalProperties": false, - "description": "Indicates whether the requested path exists in the client-provided session filesystem.", - "title": "SessionFsExistsResult" + "description": "ID of the local session bound to the given GitHub task, or omitted when none.", + "title": "SessionsFindByTaskIDResult" }, - "SessionFsMkdirRequest": { + "SessionsForkRequest": { "type": "object", "properties": { - "path": { + "sessionId": { "type": "string", - "description": "Path using SessionFs conventions" + "description": "Source session ID to fork from" }, - "recursive": { - "type": "boolean", - "description": "Create parent directories as needed" + "toEventId": { + "type": "string", + "description": "Optional event ID boundary. When provided, the fork includes only events before this ID (exclusive). When omitted, all events are included." }, - "mode": { - "type": "integer", - "minimum": 0, - "description": "Optional POSIX-style mode for newly created directories" + "name": { + "type": "string", + "description": "Optional friendly name to assign to the forked session." } }, "required": [ - "path" + "sessionId" ], "additionalProperties": false, - "description": "Directory path to create in the client-provided session filesystem, with options for recursive creation and POSIX mode.", - "title": "SessionFsMkdirRequest" + "description": "Source session identifier to fork from, optional event-ID boundary, and optional friendly name for the new session.", + "title": "SessionsForkRequest" }, - "SessionFsReaddirRequest": { + "SessionsForkResult": { "type": "object", "properties": { - "path": { + "sessionId": { "type": "string", - "description": "Path using SessionFs conventions" + "description": "The new forked session's ID" + }, + "name": { + "type": "string", + "description": "Friendly name assigned to the forked session, if any." } }, "required": [ - "path" + "sessionId" ], "additionalProperties": false, - "description": "Directory path whose entries should be listed from the client-provided session filesystem.", - "title": "SessionFsReaddirRequest" + "description": "Identifier and optional friendly name assigned to the newly forked session.", + "title": "SessionsForkResult" }, - "SessionFsReaddirResult": { + "SessionsGetEventFilePathRequest": { "type": "object", "properties": { - "entries": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Entry names in the directory" - }, - "error": { - "$ref": "#/definitions/SessionFsError", - "description": "Describes a filesystem error." + "sessionId": { + "type": "string", + "description": "Session ID whose event-log file path to compute" } }, "required": [ - "entries" + "sessionId" ], "additionalProperties": false, - "description": "Names of entries in the requested directory, or a filesystem error if the read failed.", - "title": "SessionFsReaddirResult" + "description": "Session ID whose event-log file path to compute.", + "title": "SessionsGetEventFilePathRequest" }, - "SessionFsReaddirWithTypesEntry": { + "SessionsGetEventFilePathResult": { "type": "object", "properties": { - "name": { + "filePath": { "type": "string", - "description": "Entry name" - }, - "type": { - "$ref": "#/definitions/SessionFsReaddirWithTypesEntryType", - "description": "Entry type" + "description": "Absolute path to the session's events.jsonl file" } }, "required": [ - "name", - "type" + "filePath" ], "additionalProperties": false, - "title": "SessionFsReaddirWithTypesEntry", - "description": "Schema for the `SessionFsReaddirWithTypesEntry` type." + "description": "Absolute path to the session's events.jsonl file on disk.", + "title": "SessionsGetEventFilePathResult" }, - "SessionFsReaddirWithTypesEntryType": { - "type": "string", - "enum": [ - "file", - "directory" - ], - "description": "Entry type", - "title": "SessionFsReaddirWithTypesEntryType" + "SessionsGetLastForContextRequest": { + "type": "object", + "properties": { + "context": { + "$ref": "#/definitions/SessionContext", + "description": "Optional working-directory context used to score session relevance. When omitted the most-recently-modified session wins." + } + }, + "additionalProperties": false, + "description": "Optional working-directory context used to score session relevance.", + "title": "SessionsGetLastForContextRequest" }, - "SessionFsReaddirWithTypesRequest": { + "SessionsGetLastForContextResult": { "type": "object", "properties": { - "path": { + "sessionId": { "type": "string", - "description": "Path using SessionFs conventions" + "description": "Most-relevant session ID for the supplied context, or omitted when no sessions exist" } }, - "required": [ - "path" - ], "additionalProperties": false, - "description": "Directory path whose entries (with type information) should be listed from the client-provided session filesystem.", - "title": "SessionFsReaddirWithTypesRequest" + "description": "Most-relevant session ID for the supplied context, or omitted when no sessions exist.", + "title": "SessionsGetLastForContextResult" }, - "SessionFsReaddirWithTypesResult": { + "SessionsGetPersistedRemoteSteerableRequest": { "type": "object", "properties": { - "entries": { - "type": "array", - "items": { - "$ref": "#/definitions/SessionFsReaddirWithTypesEntry" - }, - "description": "Directory entries with type information" - }, - "error": { - "$ref": "#/definitions/SessionFsError", - "description": "Describes a filesystem error." + "sessionId": { + "type": "string", + "description": "Session ID to look up the persisted remote-steerable flag for" } }, "required": [ - "entries" + "sessionId" ], "additionalProperties": false, - "description": "Entries in the requested directory paired with file/directory type information, or a filesystem error if the read failed.", - "title": "SessionFsReaddirWithTypesResult" + "description": "Session ID to look up the persisted remote-steerable flag for.", + "title": "SessionsGetPersistedRemoteSteerableRequest" }, - "SessionFsReadFileRequest": { + "SessionsGetPersistedRemoteSteerableResult": { "type": "object", "properties": { - "path": { - "type": "string", - "description": "Path using SessionFs conventions" + "remoteSteerable": { + "type": "boolean", + "description": "The session's persisted remote-steerable flag if recorded; omitted when no value has been persisted" } }, - "required": [ - "path" - ], "additionalProperties": false, - "description": "Path of the file to read from the client-provided session filesystem.", - "title": "SessionFsReadFileRequest" + "description": "The session's persisted remote-steerable flag, or omitted when no value has been persisted.", + "title": "SessionsGetPersistedRemoteSteerableResult" }, - "SessionFsReadFileResult": { + "SessionSizes": { "type": "object", "properties": { - "content": { - "type": "string", - "description": "File content as UTF-8 string" - }, - "error": { - "$ref": "#/definitions/SessionFsError", - "description": "Describes a filesystem error." + "sizes": { + "type": "object", + "additionalProperties": { + "type": "integer", + "minimum": 0 + }, + "description": "Map of sessionId -> on-disk size in bytes for the session's workspace directory" } }, "required": [ - "content" + "sizes" ], "additionalProperties": false, - "description": "File content as a UTF-8 string, or a filesystem error if the read failed.", - "title": "SessionFsReadFileResult" + "description": "Map of sessionId -> on-disk size in bytes for each session's workspace directory.", + "title": "SessionSizes" }, - "SessionFsRenameRequest": { - "type": "object", - "properties": { - "src": { - "type": "string", - "description": "Source path using SessionFs conventions" + "SessionsListRequest": { + "anyOf": [ + { + "not": {} }, - "dest": { + { + "type": "object", + "properties": { + "metadataLimit": { + "type": "integer", + "minimum": 0, + "description": "When provided, only the first N sessions (sorted by modification time, newest first) load full metadata; remaining sessions return basic info only. Use 0 to return only basic info for every session." + }, + "filter": { + "$ref": "#/definitions/SessionListFilter", + "description": "Optional filter applied to the returned sessions" + } + }, + "additionalProperties": false, + "description": "Optional metadata-load limit and context filter applied to the returned sessions." + } + ], + "description": "Optional metadata-load limit and context filter applied to the returned sessions.", + "title": "SessionsListRequest" + }, + "SessionsLoadDeferredRepoHooksRequest": { + "type": "object", + "properties": { + "sessionId": { "type": "string", - "description": "Destination path using SessionFs conventions" + "description": "Active session ID whose deferred repo-level hooks should be loaded" } }, "required": [ - "src", - "dest" + "sessionId" ], "additionalProperties": false, - "description": "Source and destination paths for renaming or moving an entry in the client-provided session filesystem.", - "title": "SessionFsRenameRequest" + "description": "Active session ID whose deferred repo-level hooks should be loaded.", + "title": "SessionsLoadDeferredRepoHooksRequest" }, - "SessionFsRmRequest": { + "SessionsPruneOldRequest": { "type": "object", "properties": { - "path": { - "type": "string", - "description": "Path using SessionFs conventions" + "olderThanDays": { + "type": "integer", + "minimum": 0, + "description": "Delete sessions whose modifiedTime is at least this many days old" }, - "recursive": { + "dryRun": { "type": "boolean", - "description": "Remove directories and their contents recursively" + "description": "When true, only report what would be deleted without performing any deletion" }, - "force": { + "includeNamed": { "type": "boolean", - "description": "Ignore errors if the path does not exist" + "description": "When true, named sessions (set via /rename) are also eligible for pruning" + }, + "excludeSessionIds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Session IDs that should never be considered for pruning" } }, "required": [ - "path" + "olderThanDays" ], "additionalProperties": false, - "description": "Path to remove from the client-provided session filesystem, with options for recursive removal and force.", - "title": "SessionFsRmRequest" + "description": "Age threshold and optional flags controlling which old sessions are pruned (or simulated when dryRun is true).", + "title": "SessionsPruneOldRequest" }, - "SessionFsSetProviderCapabilities": { + "SessionsReleaseLockRequest": { "type": "object", "properties": { - "sqlite": { - "type": "boolean", - "description": "Whether the provider supports SQLite query/exists operations" + "sessionId": { + "type": "string", + "description": "Session ID whose in-use lock should be released" } }, + "required": [ + "sessionId" + ], "additionalProperties": false, - "description": "Optional capabilities declared by the provider", - "title": "SessionFsSetProviderCapabilities" + "description": "Session ID whose in-use lock should be released.", + "title": "SessionsReleaseLockRequest" }, - "SessionFsSetProviderConventions": { - "type": "string", - "enum": [ - "windows", - "posix" - ], - "description": "Path conventions used by this filesystem", - "title": "SessionFsSetProviderConventions" + "SessionsReleaseLockResult": { + "type": "object", + "properties": {}, + "additionalProperties": false, + "description": "Release the in-use lock held by this process for the given session. No-op when this process does not currently hold a lock for the session.", + "title": "SessionsReleaseLockResult" }, - "SessionFsSetProviderRequest": { + "SessionsReloadPluginHooksRequest": { "type": "object", "properties": { - "initialCwd": { - "type": "string", - "description": "Initial working directory for sessions" - }, - "sessionStatePath": { + "sessionId": { "type": "string", - "description": "Path within each session's SessionFs where the runtime stores files for that session" - }, - "conventions": { - "$ref": "#/definitions/SessionFsSetProviderConventions", - "description": "Path conventions used by this filesystem" + "description": "Active session ID to reload hooks for" }, - "capabilities": { - "$ref": "#/definitions/SessionFsSetProviderCapabilities", - "description": "Optional capabilities declared by the provider" + "deferRepoHooks": { + "type": "boolean", + "description": "When true, skip repo-level hooks. Use before folder trust is confirmed; loadDeferredRepoHooks loads them post-trust." } }, "required": [ - "initialCwd", - "sessionStatePath", - "conventions" + "sessionId" ], "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" + "description": "Active session ID and an optional flag for deferring repo-level hooks until folder trust.", + "title": "SessionsReloadPluginHooksRequest" }, - "SessionFsSetProviderResult": { + "SessionsReloadPluginHooksResult": { + "type": "object", + "properties": {}, + "additionalProperties": false, + "description": "Reload all hooks (user, plugin, optionally repo) and apply them to the active session. Call after installing or removing plugins so their hooks take effect immediately. No-op when no active session matches the given sessionId.", + "title": "SessionsReloadPluginHooksResult" + }, + "SessionsSaveRequest": { "type": "object", "properties": { - "success": { - "type": "boolean", - "description": "Whether the provider was set successfully" + "sessionId": { + "type": "string", + "description": "Session ID whose pending events should be flushed to disk" } }, "required": [ - "success" + "sessionId" ], "additionalProperties": false, - "description": "Indicates whether the calling client was registered as the session filesystem provider.", - "title": "SessionFsSetProviderResult" + "description": "Session ID whose pending events should be flushed to disk.", + "title": "SessionsSaveRequest" }, - "SessionFsSqliteExistsResult": { + "SessionsSaveResult": { + "type": "object", + "properties": {}, + "additionalProperties": false, + "description": "Flush a session's pending events to disk. No-op when no writer exists for the session (e.g., already closed).", + "title": "SessionsSaveResult" + }, + "SessionsSetAdditionalPluginsRequest": { "type": "object", "properties": { - "exists": { - "type": "boolean", - "description": "Whether the session database already exists" + "plugins": { + "type": "array", + "items": { + "$ref": "#/definitions/InstalledPlugin" + }, + "description": "Manager-wide additional plugins to register. Replaces any previously-configured set. Pass an empty array to clear." } }, "required": [ - "exists" + "plugins" ], "additionalProperties": false, - "description": "Indicates whether the per-session SQLite database already exists.", - "title": "SessionFsSqliteExistsResult" + "description": "Manager-wide additional plugins to register; replaces any previously-configured set.", + "title": "SessionsSetAdditionalPluginsRequest" }, - "SessionFsSqliteQueryRequest": { + "SessionsSetAdditionalPluginsResult": { + "type": "object", + "properties": {}, + "additionalProperties": false, + "description": "Replace the manager-wide additional plugins. New session creations and subsequent hook reloads see the new set; already-running sessions keep their existing hook installation until the next reload.", + "title": "SessionsSetAdditionalPluginsResult" + }, + "SessionUpdateOptionsParams": { "type": "object", "properties": { - "query": { + "model": { "type": "string", - "description": "SQL query to execute" + "description": "The model ID to use for assistant turns." }, - "queryType": { - "$ref": "#/definitions/SessionFsSqliteQueryType", - "description": "How to execute the query: 'exec' for DDL/multi-statement (no results), 'query' for SELECT (returns rows), 'run' for INSERT/UPDATE/DELETE (returns rowsAffected)" + "reasoningEffort": { + "type": "string", + "description": "Reasoning effort for the selected model (model-defined enum)." }, - "params": { + "clientName": { + "type": "string", + "description": "Identifier of the client driving the session." + }, + "lspClientName": { + "type": "string", + "description": "Identifier sent to LSP-style integrations." + }, + "integrationId": { + "type": "string", + "description": "Stable integration identifier used for analytics and rate-limit attribution." + }, + "featureFlags": { "type": "object", "additionalProperties": { - "type": [ - "string", - "number", - "null" - ] + "type": "boolean" }, - "description": "Optional named bind parameters" - } - }, - "required": [ - "query", - "queryType" - ], - "additionalProperties": false, - "description": "SQL query, query type, and optional bind parameters for executing a SQLite query against the per-session database.", - "title": "SessionFsSqliteQueryRequest" - }, - "SessionFsSqliteQueryResult": { - "type": "object", - "properties": { - "rows": { + "description": "Map of feature-flag IDs to their boolean enabled state." + }, + "isExperimentalMode": { + "type": "boolean", + "description": "Whether experimental capabilities are enabled." + }, + "provider": { + "description": "Custom model-provider configuration (BYOK). Opaque shape; see `ProviderConfig` in the runtime." + }, + "workingDirectory": { + "type": "string", + "description": "Absolute working-directory path for shell tools." + }, + "availableTools": { "type": "array", "items": { - "type": "object", - "additionalProperties": {} + "type": "string" }, - "description": "For SELECT: array of row objects. For others: empty array." + "description": "Allowlist of tool names available to this session." }, - "columns": { + "excludedTools": { "type": "array", "items": { "type": "string" }, - "description": "Column names from the result set" + "description": "Denylist of tool names for this session." }, - "rowsAffected": { - "type": "integer", - "minimum": 0, - "description": "Number of rows affected (for INSERT/UPDATE/DELETE)" + "enableScriptSafety": { + "type": "boolean", + "description": "Whether shell-script safety heuristics are enabled." }, - "lastInsertRowid": { - "type": "number", - "description": "Last inserted row ID (for INSERT)" + "shellInitProfile": { + "type": "string", + "description": "Shell init profile (`None` or `NonInteractive`)." }, - "error": { - "$ref": "#/definitions/SessionFsError", - "description": "Describes a filesystem error." - } - }, - "required": [ - "rows", - "columns", - "rowsAffected" - ], - "additionalProperties": false, - "description": "Query results including rows, columns, and rows affected, or a filesystem error if execution failed.", - "title": "SessionFsSqliteQueryResult" - }, - "SessionFsSqliteQueryType": { - "type": "string", - "enum": [ - "exec", - "query", - "run" - ], - "description": "How to execute the query: 'exec' for DDL/multi-statement (no results), 'query' for SELECT (returns rows), 'run' for INSERT/UPDATE/DELETE (returns rowsAffected)", - "title": "SessionFsSqliteQueryType" - }, - "SessionFsStatRequest": { - "type": "object", - "properties": { - "path": { + "shellProcessFlags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Per-shell process flags (e.g., `pwsh` arguments)." + }, + "sandboxConfig": { + "description": "Sandbox configuration shape; opaque to SDK consumers. See `SandboxConfig` in the runtime." + }, + "logInteractiveShells": { + "type": "boolean", + "description": "Whether interactive shell sessions are logged." + }, + "envValueMode": { + "$ref": "#/definitions/OptionsUpdateEnvValueMode", + "description": "How env values are passed to MCP servers (`direct` inlines literal values; `indirect` resolves at launch)." + }, + "skillDirectories": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Additional directories to search for skills." + }, + "disabledSkills": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Skill IDs that should be excluded from this session." + }, + "enableOnDemandInstructionDiscovery": { + "type": "boolean", + "description": "Whether to discover custom instructions on demand after successful file views (AGENTS.md / CLAUDE.md / .github/copilot-instructions.md surfacing). Combined with `skipCustomInstructions` and the runtime-side `ON_DEMAND_INSTRUCTIONS` feature flag." + }, + "installedPlugins": { + "type": "array", + "items": { + "$ref": "#/definitions/SessionInstalledPlugin" + }, + "description": "Full set of installed plugins for the session. Replaces the existing list; the runtime invalidates the skills cache only when the list materially changes." + }, + "customAgentsLocalOnly": { + "type": "boolean", + "description": "Whether to default custom agents to local-only execution." + }, + "skipCustomInstructions": { + "type": "boolean", + "description": "Whether to skip loading custom instruction sources." + }, + "disabledInstructionSources": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Instruction source IDs to exclude from the system prompt." + }, + "coauthorEnabled": { + "type": "boolean", + "description": "Whether to include the `Co-authored-by` trailer in commit messages." + }, + "trajectoryFile": { "type": "string", - "description": "Path using SessionFs conventions" - } - }, - "required": [ - "path" - ], - "additionalProperties": false, - "description": "Path whose metadata should be returned from the client-provided session filesystem.", - "title": "SessionFsStatRequest" - }, - "SessionFsStatResult": { - "type": "object", - "properties": { - "isFile": { + "description": "Optional path for trajectory output." + }, + "enableStreaming": { "type": "boolean", - "description": "Whether the path is a file" + "description": "Whether to stream model responses." }, - "isDirectory": { + "copilotUrl": { + "type": "string", + "description": "Override URL for the Copilot API endpoint." + }, + "askUserDisabled": { "type": "boolean", - "description": "Whether the path is a directory" + "description": "Whether to disable the `ask_user` tool (encourages autonomous behavior)." }, - "size": { - "type": "integer", - "minimum": 0, - "description": "File size in bytes" + "continueOnAutoMode": { + "type": "boolean", + "description": "Whether to allow auto-mode continuation across turns." + }, + "runningInInteractiveMode": { + "type": "boolean", + "description": "Whether the session is running in an interactive UI." }, - "mtime": { + "enableReasoningSummaries": { + "type": "boolean", + "description": "Whether to surface reasoning-summary events from the model." + }, + "agentContext": { "type": "string", - "format": "date-time", - "description": "ISO 8601 timestamp of last modification" + "description": "Runtime context discriminator (e.g., `cli`, `actions`)." }, - "birthtime": { + "eventsLogDirectory": { "type": "string", - "format": "date-time", - "description": "ISO 8601 timestamp of creation" + "description": "Override directory for the session-events log. When unset, the runtime's default events log directory is used." }, - "error": { - "$ref": "#/definitions/SessionFsError", - "description": "Describes a filesystem error." + "additionalContentExclusionPolicies": { + "type": "array", + "items": {}, + "description": "Additional content-exclusion policies to merge into the session's policy set. Opaque shape; see `ContentExclusionApiResponse` in the runtime." + }, + "manageScheduleEnabled": { + "type": "boolean", + "description": "Whether to expose the `manage_schedule` tool to the agent. The runtime always owns the per-session schedule registry; this flag only controls tool exposure (typically gated to staff users)." } }, - "required": [ - "isFile", - "isDirectory", - "size", - "mtime", - "birthtime" - ], "additionalProperties": false, - "description": "Filesystem metadata for the requested path, or a filesystem error if the stat failed.", - "title": "SessionFsStatResult" + "description": "Patch of mutable session options to apply to the running session.", + "title": "SessionUpdateOptionsParams" }, - "SessionFsWriteFileRequest": { + "SessionUpdateOptionsResult": { "type": "object", "properties": { - "path": { - "type": "string", - "description": "Path using SessionFs conventions" - }, - "content": { - "type": "string", - "description": "Content to write" - }, - "mode": { - "type": "integer", - "minimum": 0, - "description": "Optional POSIX-style mode for newly created files" + "success": { + "type": "boolean", + "description": "Whether the operation succeeded" } }, "required": [ - "path", - "content" + "success" ], "additionalProperties": false, - "description": "File path, content to write, and optional mode for the client-provided session filesystem.", - "title": "SessionFsWriteFileRequest" - }, - "SessionLogLevel": { - "type": "string", - "enum": [ - "info", - "warning", - "error" - ], - "description": "Log severity level. Determines how the message is displayed in the timeline. Defaults to \"info\".", - "title": "SessionLogLevel" - }, - "SessionMode": { - "type": "string", - "enum": [ - "interactive", - "plan", - "autopilot" - ], - "description": "The session mode the agent is operating in", - "title": "SessionMode" + "description": "Indicates whether the session options patch was applied successfully.", + "title": "SessionUpdateOptionsResult" }, - "SessionsForkRequest": { + "SessionWorkingDirectoryContext": { "type": "object", "properties": { - "sessionId": { + "cwd": { "type": "string", - "description": "Source session ID to fork from" + "description": "Current working directory path" }, - "toEventId": { + "gitRoot": { "type": "string", - "description": "Optional event ID boundary. When provided, the fork includes only events before this ID (exclusive). When omitted, all events are included." + "description": "Root directory of the git repository, resolved via git rev-parse" }, - "name": { + "repository": { "type": "string", - "description": "Optional friendly name to assign to the forked session." - } - }, - "required": [ - "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": { - "type": "object", - "properties": { - "sessionId": { + "description": "Repository identifier derived from the git remote URL (\"owner/name\" for GitHub, \"org/project/repo\" for Azure DevOps)" + }, + "hostType": { + "$ref": "#/definitions/SessionWorkingDirectoryContextHostType", + "description": "Hosting platform type of the repository" + }, + "repositoryHost": { "type": "string", - "description": "The new forked session's ID" + "description": "Raw host string from the git remote URL (e.g. \"github.com\", \"dev.azure.com\")" }, - "name": { + "branch": { "type": "string", - "description": "Friendly name assigned to the forked session, if any." + "description": "Current git branch name" + }, + "headCommit": { + "type": "string", + "description": "Head commit of the current git branch" + }, + "baseCommit": { + "type": "string", + "description": "Merge-base commit SHA (fork point from the remote default branch)" } }, "required": [ - "sessionId" + "cwd" ], "additionalProperties": false, - "description": "Identifier and optional friendly name assigned to the newly forked session.", - "title": "SessionsForkResult" + "description": "Updated working directory and git context. Emitted as the new payload of `session.context_changed`.", + "title": "SessionWorkingDirectoryContext" + }, + "SessionWorkingDirectoryContextHostType": { + "type": "string", + "enum": [ + "github", + "ado" + ], + "description": "Hosting platform type of the repository", + "title": "SessionWorkingDirectoryContextHostType", + "x-enumDescriptions": { + "github": "The working directory repository is hosted on GitHub.", + "ado": "The working directory repository is hosted on Azure DevOps." + } }, "ShellExecRequest": { "type": "object", @@ -6374,7 +13660,41 @@ "SIGINT" ], "description": "Signal to send (default: SIGTERM)", - "title": "ShellKillSignal" + "title": "ShellKillSignal", + "x-enumDescriptions": { + "SIGTERM": "Request graceful process termination.", + "SIGKILL": "Forcefully terminate the process.", + "SIGINT": "Send an interrupt signal to the process." + } + }, + "ShutdownRequest": { + "type": "object", + "properties": { + "type": { + "$ref": "#/definitions/ShutdownType", + "description": "Why the session is being shut down. Defaults to \"routine\" when omitted." + }, + "reason": { + "type": "string", + "description": "Optional human-readable reason. Typically the message of the error that triggered shutdown when type is 'error'." + } + }, + "additionalProperties": false, + "description": "Parameters for shutting down the session", + "title": "ShutdownRequest" + }, + "ShutdownType": { + "type": "string", + "enum": [ + "routine", + "error" + ], + "description": "Why the session is being shut down. Defaults to \"routine\" when omitted.", + "title": "ShutdownType", + "x-enumDescriptions": { + "routine": "The session is shutting down normally.", + "error": "The session is shutting down because of an error." + } }, "Skill": { "type": "object", @@ -6402,6 +13722,10 @@ "path": { "type": "string", "description": "Absolute path to the skill file" + }, + "pluginName": { + "type": "string", + "description": "Name of the plugin that provides the skill, when source is 'plugin'" } }, "required": [ @@ -6503,6 +13827,62 @@ "description": "Name of the skill to enable for the session.", "title": "SkillsEnableRequest" }, + "SkillsGetInvokedResult": { + "type": "object", + "properties": { + "skills": { + "type": "array", + "items": { + "$ref": "#/definitions/SkillsInvokedSkill" + }, + "description": "Skills invoked during this session, ordered by invocation time (most recent last)" + } + }, + "required": [ + "skills" + ], + "additionalProperties": false, + "description": "Skills invoked during this session, ordered by invocation time (most recent last).", + "title": "SkillsGetInvokedResult" + }, + "SkillsInvokedSkill": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Unique identifier for the skill" + }, + "path": { + "type": "string", + "description": "Path to the SKILL.md file" + }, + "content": { + "type": "string", + "description": "Full content of the skill file" + }, + "allowedTools": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Tools that should be auto-approved when this skill is active, captured at invocation time" + }, + "invokedAtTurn": { + "type": "integer", + "minimum": 0, + "description": "Turn number when the skill was invoked" + } + }, + "required": [ + "name", + "path", + "content", + "invokedAtTurn" + ], + "additionalProperties": false, + "title": "SkillsInvokedSkill", + "description": "Schema for the `SkillsInvokedSkill` type." + }, "SkillsLoadDiagnostics": { "type": "object", "properties": { @@ -6541,7 +13921,16 @@ "builtin" ], "description": "Source location type (e.g., project, personal-copilot, plugin, builtin)", - "title": "SkillSource" + "title": "SkillSource", + "x-enumDescriptions": { + "project": "Skill defined in the current project's skill directories.", + "inherited": "Skill discovered from a parent directory in the current workspace tree.", + "personal-copilot": "Skill defined in the user's Copilot skill directory.", + "personal-agents": "Skill defined in the user's personal agents skill directory.", + "plugin": "Skill provided by an installed plugin.", + "custom": "Skill loaded from a configured custom skill directory.", + "builtin": "Skill bundled with the runtime." + } }, "SlashCommandAgentPromptResult": { "type": "object", @@ -6679,7 +14068,10 @@ "directory" ], "description": "Optional completion hint for the input (e.g. 'directory' for filesystem path completion)", - "title": "SlashCommandInputCompletion" + "title": "SlashCommandInputCompletion", + "x-enumDescriptions": { + "directory": "Input should complete filesystem directories." + } }, "SlashCommandInvocationResult": { "anyOf": [ @@ -6691,6 +14083,9 @@ }, { "$ref": "#/definitions/SlashCommandCompletedResult" + }, + { + "$ref": "#/definitions/SlashCommandSelectSubcommandResult" } ], "description": "Result of invoking the slash command (text output, prompt to send to the agent, or completion).", @@ -6704,7 +14099,74 @@ "client" ], "description": "Coarse command category for grouping and behavior: runtime built-in, skill-backed command, or SDK/client-owned command", - "title": "SlashCommandKind" + "title": "SlashCommandKind", + "x-enumDescriptions": { + "builtin": "Command implemented by the runtime.", + "skill": "Command backed by a skill.", + "client": "Command registered by an SDK client or extension." + } + }, + "SlashCommandSelectSubcommandOption": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Subcommand name to invoke" + }, + "description": { + "type": "string", + "description": "Human-readable description of the subcommand" + }, + "group": { + "type": "string", + "description": "Optional group label for organizing options" + } + }, + "required": [ + "name", + "description" + ], + "additionalProperties": false, + "title": "SlashCommandSelectSubcommandOption", + "description": "Schema for the `SlashCommandSelectSubcommandOption` type." + }, + "SlashCommandSelectSubcommandResult": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "select-subcommand", + "description": "Select subcommand result discriminator" + }, + "command": { + "type": "string", + "description": "Parent command name that requires subcommand selection" + }, + "title": { + "type": "string", + "description": "Human-readable title for the selection UI" + }, + "options": { + "type": "array", + "items": { + "$ref": "#/definitions/SlashCommandSelectSubcommandOption" + }, + "description": "Available subcommand options for the client to present" + }, + "runtimeSettingsChanged": { + "type": "boolean", + "description": "True when the invocation mutated user runtime settings; consumers caching settings should refresh" + } + }, + "required": [ + "kind", + "command", + "title", + "options" + ], + "additionalProperties": false, + "title": "SlashCommandSelectSubcommandResult", + "description": "Schema for the `SlashCommandSelectSubcommandResult` type." }, "SlashCommandTextResult": { "type": "object", @@ -6775,6 +14237,7 @@ }, "activeTimeMs": { "type": "integer", + "minimum": 0, "description": "Accumulated active execution time in milliseconds", "format": "duration" }, @@ -6835,6 +14298,34 @@ "title": "TaskAgentInfo", "description": "Schema for the `TaskAgentInfo` type." }, + "TaskAgentProgress": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "agent", + "description": "Progress kind" + }, + "recentActivity": { + "type": "array", + "items": { + "$ref": "#/definitions/TaskProgressLine" + }, + "description": "Recent tool execution events converted to display lines" + }, + "latestIntent": { + "type": "string", + "description": "The most recent intent reported by the agent" + } + }, + "required": [ + "type", + "recentActivity" + ], + "additionalProperties": false, + "title": "TaskAgentProgress", + "description": "Schema for the `TaskAgentProgress` type." + }, "TaskExecutionMode": { "type": "string", "enum": [ @@ -6842,7 +14333,11 @@ "background" ], "description": "Whether task execution is synchronously awaited or managed in the background", - "title": "TaskExecutionMode" + "title": "TaskExecutionMode", + "x-enumDescriptions": { + "sync": "The task was started with synchronous waiting.", + "background": "The task is managed in the background." + } }, "TaskInfo": { "anyOf": [ @@ -6868,11 +14363,51 @@ } }, "required": [ - "tasks" + "tasks" + ], + "additionalProperties": false, + "description": "Background tasks currently tracked by the session.", + "title": "TaskList" + }, + "TaskProgress": { + "anyOf": [ + { + "anyOf": [ + { + "$ref": "#/definitions/TaskAgentProgress" + }, + { + "$ref": "#/definitions/TaskShellProgress" + } + ] + }, + { + "type": "null" + } + ], + "description": "Progress information for the task, discriminated by type. Returns null when no task with this ID is currently tracked.", + "title": "TaskProgress" + }, + "TaskProgressLine": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Display message, e.g., \"▸ bash\", \"✓ edit src/foo.ts\"" + }, + "timestamp": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp when this event occurred" + } + }, + "required": [ + "message", + "timestamp" ], "additionalProperties": false, - "description": "Background tasks currently tracked by the session.", - "title": "TaskList" + "title": "TaskProgressLine", + "description": "Schema for the `TaskProgressLine` type." }, "TasksCancelRequest": { "type": "object", @@ -6904,6 +14439,48 @@ "description": "Indicates whether the background task was successfully cancelled.", "title": "TasksCancelResult" }, + "TasksGetCurrentPromotableResult": { + "type": "object", + "properties": { + "task": { + "$ref": "#/definitions/TaskInfo", + "description": "The first sync-waiting task (agent first, then shell) that can currently be promoted to background mode. Omitted if no such task exists. The returned task is guaranteed to have executionMode='sync' and canPromoteToBackground=true at the time of the call." + } + }, + "additionalProperties": false, + "description": "The first sync-waiting task that can currently be promoted to background mode.", + "title": "TasksGetCurrentPromotableResult" + }, + "TasksGetProgressRequest": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Task identifier (agent ID or shell ID)" + } + }, + "required": [ + "id" + ], + "additionalProperties": false, + "description": "Identifier of the background task to fetch progress for.", + "title": "TasksGetProgressRequest" + }, + "TasksGetProgressResult": { + "type": "object", + "properties": { + "progress": { + "$ref": "#/definitions/TaskProgress", + "description": "Progress information for the task, discriminated by type. Returns null when no task with this ID is currently tracked." + } + }, + "required": [ + "progress" + ], + "additionalProperties": false, + "description": "Progress information for the task, or null when no task with that ID is tracked.", + "title": "TasksGetProgressResult" + }, "TaskShellInfo": { "type": "object", "properties": { @@ -6956,6 +14533,9 @@ }, "pid": { "type": "integer", + "exclusiveMinimum": true, + "minimum": 0, + "maximum": 4294967295, "description": "Process ID when available" } }, @@ -6979,7 +14559,51 @@ "detached" ], "description": "Whether the shell runs inside a managed PTY session or as an independent background process", - "title": "TaskShellInfoAttachmentMode" + "title": "TaskShellInfoAttachmentMode", + "x-enumDescriptions": { + "attached": "The shell runs in a managed PTY session.", + "detached": "The shell runs as an independent background process." + } + }, + "TaskShellProgress": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "shell", + "description": "Progress kind" + }, + "recentOutput": { + "type": "string", + "description": "Recent stdout/stderr lines from the running shell command" + }, + "pid": { + "type": "integer", + "exclusiveMinimum": true, + "minimum": 0, + "maximum": 4294967295, + "description": "Process ID when available" + } + }, + "required": [ + "type", + "recentOutput" + ], + "additionalProperties": false, + "title": "TaskShellProgress", + "description": "Schema for the `TaskShellProgress` type." + }, + "TasksPromoteCurrentToBackgroundResult": { + "type": "object", + "properties": { + "task": { + "$ref": "#/definitions/TaskInfo", + "description": "The promoted task as it now exists in background mode, omitted if no promotable task was waiting. Atomic operation: avoids the race window of getCurrentPromotable + promoteToBackground." + } + }, + "additionalProperties": false, + "description": "The promoted task as it now exists in background mode, omitted if no promotable task was waiting.", + "title": "TasksPromoteCurrentToBackgroundResult" }, "TasksPromoteToBackgroundRequest": { "type": "object", @@ -7011,6 +14635,13 @@ "description": "Indicates whether the task was successfully promoted to background mode.", "title": "TasksPromoteToBackgroundResult" }, + "TasksRefreshResult": { + "type": "object", + "properties": {}, + "additionalProperties": false, + "description": "Refresh metadata for any detached background shells the runtime knows about. Use after a long pause to pick up exit/output state for shells running outside the agent loop.", + "title": "TasksRefreshResult" + }, "TasksRemoveRequest": { "type": "object", "properties": { @@ -7142,7 +14773,69 @@ "cancelled" ], "description": "Current lifecycle status of the task", - "title": "TaskStatus" + "title": "TaskStatus", + "x-enumDescriptions": { + "running": "The task is actively executing.", + "idle": "The task is waiting for additional input.", + "completed": "The task finished successfully.", + "failed": "The task finished with an error.", + "cancelled": "The task was cancelled before completion." + } + }, + "TasksWaitForPendingResult": { + "type": "object", + "properties": {}, + "additionalProperties": false, + "description": "Wait until all in-flight background tasks (agents + shells) and any follow-up turns scheduled by their completions have settled. Returns when the runtime is fully drained or after an internal timeout (default 10 minutes; configurable via COPILOT_TASK_WAIT_TIMEOUT_SECONDS).", + "title": "TasksWaitForPendingResult" + }, + "TelemetrySetFeatureOverridesRequest": { + "type": "object", + "properties": { + "features": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Override key/value pairs to attach to subsequent telemetry events from this session. Replaces any previously-set overrides." + } + }, + "required": [ + "features" + ], + "additionalProperties": false, + "description": "Feature override key/value pairs to attach to subsequent telemetry events from this session.", + "title": "TelemetrySetFeatureOverridesRequest" + }, + "TokenAuthInfo": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "token", + "description": "SDK-side token authentication; the host configured the token directly via the SDK." + }, + "host": { + "type": "string", + "description": "Authentication host." + }, + "token": { + "type": "string", + "description": "The token value itself. Treat as a secret." + }, + "copilotUser": { + "$ref": "#/definitions/CopilotUserResponse", + "description": "Snapshot of the authenticated user's Copilot subscription info, if known. Mirrors the GitHub API `/copilot_internal/v2/token` user response shape — the runtime trusts this verbatim and does not re-fetch when set." + } + }, + "required": [ + "type", + "host", + "token" + ], + "additionalProperties": false, + "title": "TokenAuthInfo", + "description": "Schema for the `TokenAuthInfo` type." }, "Tool": { "type": "object", @@ -7195,6 +14888,13 @@ "description": "Built-in tools available for the requested model, with their parameters and instructions.", "title": "ToolList" }, + "ToolsInitializeAndValidateResult": { + "type": "object", + "properties": {}, + "additionalProperties": false, + "description": "Resolve, build, and validate the runtime tool list for this session. Subagent sessions and consumer flows that need an initialized tool set before `send` invoke this. Default base-class implementation is a no-op for sessions that don't support tool validation.", + "title": "ToolsInitializeAndValidateResult" + }, "ToolsListRequest": { "type": "object", "properties": { @@ -7207,6 +14907,21 @@ "description": "Optional model identifier whose tool overrides should be applied to the listing.", "title": "ToolsListRequest" }, + "UIAutoModeSwitchResponse": { + "type": "string", + "enum": [ + "yes", + "yes_always", + "no" + ], + "description": "User's choice for auto-mode switching: yes (allow this turn), yes_always (allow + persist as setting), or no (decline).", + "title": "UIAutoModeSwitchResponse", + "x-enumDescriptions": { + "yes": "Allow the automatic mode switch for this turn.", + "yes_always": "Allow this mode switch and persist the preference.", + "no": "Decline the automatic mode switch." + } + }, "UIElicitationArrayAnyOfField": { "type": "object", "properties": { @@ -7224,11 +14939,13 @@ "description": "Help text describing the field." }, "minItems": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Minimum number of items the user must select." }, "maxItems": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Maximum number of items the user may select." }, "items": { @@ -7306,11 +15023,13 @@ "description": "Help text describing the field." }, "minItems": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Minimum number of items the user must select." }, "maxItems": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Maximum number of items the user may select." }, "items": { @@ -7425,7 +15144,12 @@ "cancel" ], "description": "The user's response: accept (submitted), decline (rejected), or cancel (dismissed)", - "title": "UIElicitationResponseAction" + "title": "UIElicitationResponseAction", + "x-enumDescriptions": { + "accept": "The user submitted the requested form values.", + "decline": "The user explicitly declined to provide the requested input.", + "cancel": "The user dismissed the elicitation request." + } }, "UIElicitationResponseContent": { "type": "object", @@ -7586,7 +15310,11 @@ "integer" ], "description": "Numeric type accepted by the field.", - "title": "UIElicitationSchemaPropertyNumberType" + "title": "UIElicitationSchemaPropertyNumberType", + "x-enumDescriptions": { + "number": "Any JSON number.", + "integer": "Integer JSON number." + } }, "UIElicitationSchemaPropertyString": { "type": "object", @@ -7605,11 +15333,13 @@ "description": "Help text describing the field." }, "minLength": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Minimum number of characters required." }, "maxLength": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Maximum number of characters allowed." }, "format": { @@ -7637,7 +15367,13 @@ "date-time" ], "description": "Optional format hint that constrains the accepted input.", - "title": "UIElicitationSchemaPropertyStringFormat" + "title": "UIElicitationSchemaPropertyStringFormat", + "x-enumDescriptions": { + "email": "Email address string format.", + "uri": "URI string format.", + "date": "Calendar date string format.", + "date-time": "Date-time string format." + } }, "UIElicitationStringEnumField": { "type": "object", @@ -7738,6 +15474,70 @@ "title": "UIElicitationStringOneOfFieldOneOf", "description": "Schema for the `UIElicitationStringOneOfFieldOneOf` type." }, + "UIExitPlanModeAction": { + "type": "string", + "enum": [ + "exit_only", + "interactive", + "autopilot", + "autopilot_fleet" + ], + "description": "The action the user selected. Defaults to 'autopilot' when autoApproveEdits is true, otherwise 'interactive'.", + "title": "UIExitPlanModeAction", + "x-enumDescriptions": { + "exit_only": "Exit plan mode without starting implementation.", + "interactive": "Exit plan mode and continue interactively.", + "autopilot": "Exit plan mode and continue in autopilot mode.", + "autopilot_fleet": "Exit plan mode and continue in autopilot mode with parallel subagent execution." + } + }, + "UIExitPlanModeResponse": { + "type": "object", + "properties": { + "approved": { + "type": "boolean", + "description": "Whether the plan was approved." + }, + "selectedAction": { + "$ref": "#/definitions/UIExitPlanModeAction", + "description": "The action the user selected. Defaults to 'autopilot' when autoApproveEdits is true, otherwise 'interactive'." + }, + "autoApproveEdits": { + "type": "boolean", + "description": "Whether subsequent edits should be auto-approved without confirmation." + }, + "feedback": { + "type": "string", + "description": "Feedback from the user when they declined the plan or requested changes." + } + }, + "required": [ + "approved" + ], + "additionalProperties": false, + "title": "UIExitPlanModeResponse", + "description": "Schema for the `UIExitPlanModeResponse` type." + }, + "UIHandlePendingAutoModeSwitchRequest": { + "type": "object", + "properties": { + "requestId": { + "type": "string", + "description": "The unique request ID from the auto_mode_switch.requested event" + }, + "response": { + "$ref": "#/definitions/UIAutoModeSwitchResponse", + "description": "User's choice for auto-mode switching: yes (allow this turn), yes_always (allow + persist as setting), or no (decline)." + } + }, + "required": [ + "requestId", + "response" + ], + "additionalProperties": false, + "description": "Request ID of a pending `auto_mode_switch.requested` event and the user's response.", + "title": "UIHandlePendingAutoModeSwitchRequest" + }, "UIHandlePendingElicitationRequest": { "type": "object", "properties": { @@ -7751,12 +15551,158 @@ } }, "required": [ - "requestId", - "result" + "requestId", + "result" + ], + "additionalProperties": false, + "description": "Pending elicitation request ID and the user's response (accept/decline/cancel + form values).", + "title": "UIHandlePendingElicitationRequest" + }, + "UIHandlePendingExitPlanModeRequest": { + "type": "object", + "properties": { + "requestId": { + "type": "string", + "description": "The unique request ID from the exit_plan_mode.requested event" + }, + "response": { + "$ref": "#/definitions/UIExitPlanModeResponse", + "description": "Schema for the `UIExitPlanModeResponse` type." + } + }, + "required": [ + "requestId", + "response" + ], + "additionalProperties": false, + "description": "Request ID of a pending `exit_plan_mode.requested` event and the user's response.", + "title": "UIHandlePendingExitPlanModeRequest" + }, + "UIHandlePendingResult": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "True if the request was still pending and was resolved by this call. False if the request ID was unknown, already resolved by another client (e.g. GitHub), expired, or otherwise no longer pending." + } + }, + "required": [ + "success" + ], + "additionalProperties": false, + "description": "Indicates whether the pending UI request was resolved by this call.", + "title": "UIHandlePendingResult" + }, + "UIHandlePendingSamplingRequest": { + "type": "object", + "properties": { + "requestId": { + "type": "string", + "description": "The unique request ID from the sampling.requested event" + }, + "response": { + "$ref": "#/definitions/UIHandlePendingSamplingResponse", + "description": "Optional sampling result payload. Omit to reject/cancel the sampling request without providing a result." + } + }, + "required": [ + "requestId" + ], + "additionalProperties": false, + "description": "Request ID of a pending `sampling.requested` event and an optional sampling result payload (omit to reject).", + "title": "UIHandlePendingSamplingRequest" + }, + "UIHandlePendingSamplingResponse": { + "type": "object", + "properties": {}, + "additionalProperties": true, + "description": "Optional sampling result payload. Omit to reject/cancel the sampling request without providing a result.", + "title": "UIHandlePendingSamplingResponse" + }, + "UIHandlePendingUserInputRequest": { + "type": "object", + "properties": { + "requestId": { + "type": "string", + "description": "The unique request ID from the user_input.requested event" + }, + "response": { + "$ref": "#/definitions/UIUserInputResponse", + "description": "Schema for the `UIUserInputResponse` type." + } + }, + "required": [ + "requestId", + "response" + ], + "additionalProperties": false, + "description": "Request ID of a pending `user_input.requested` event and the user's response.", + "title": "UIHandlePendingUserInputRequest" + }, + "UIRegisterDirectAutoModeSwitchHandlerResult": { + "type": "object", + "properties": { + "handle": { + "type": "string", + "description": "Opaque handle representing the registration. Pass this same handle to `unregisterDirectAutoModeSwitchHandler` when the in-process handler is no longer active. Multiple registrations are reference-counted; the server bridge will only dispatch auto-mode-switch requests when no handles are active." + } + }, + "required": [ + "handle" + ], + "additionalProperties": false, + "description": "Register an in-process handler for `auto_mode_switch.requested` events. The caller still attaches the actual listener via the standard event-subscription mechanism; this registration solely tells the server bridge to skip its own dispatch (so a remote client doesn't race the in-process handler for the same requestId).", + "title": "UIRegisterDirectAutoModeSwitchHandlerResult" + }, + "UIUnregisterDirectAutoModeSwitchHandlerRequest": { + "type": "object", + "properties": { + "handle": { + "type": "string", + "description": "Handle previously returned by `registerDirectAutoModeSwitchHandler`" + } + }, + "required": [ + "handle" + ], + "additionalProperties": false, + "description": "Opaque handle previously returned by `registerDirectAutoModeSwitchHandler` to release.", + "title": "UIUnregisterDirectAutoModeSwitchHandlerRequest" + }, + "UIUnregisterDirectAutoModeSwitchHandlerResult": { + "type": "object", + "properties": { + "unregistered": { + "type": "boolean", + "description": "True if the handle was active and decremented the counter; false if the handle was unknown." + } + }, + "required": [ + "unregistered" + ], + "additionalProperties": false, + "description": "Indicates whether the handle was active and the registration count was decremented.", + "title": "UIUnregisterDirectAutoModeSwitchHandlerResult" + }, + "UIUserInputResponse": { + "type": "object", + "properties": { + "answer": { + "type": "string", + "description": "The user's answer text" + }, + "wasFreeform": { + "type": "boolean", + "description": "True if the user typed a freeform response, false if they selected a presented choice. Used by telemetry to differentiate between free text input and choice selection." + } + }, + "required": [ + "answer", + "wasFreeform" ], "additionalProperties": false, - "description": "Pending elicitation request ID and the user's response (accept/decline/cancel + form values).", - "title": "UIHandlePendingElicitationRequest" + "title": "UIUserInputResponse", + "description": "Schema for the `UIUserInputResponse` type." }, "UsageGetMetricsResult": { "type": "object", @@ -7771,7 +15717,7 @@ "description": "Raw count of user-initiated API requests" }, "totalNanoAiu": { - "type": "integer", + "type": "number", "minimum": 0, "description": "Session-wide accumulated nano-AI units cost" }, @@ -7783,14 +15729,15 @@ "description": "Session-wide per-token-type accumulated token counts" }, "totalApiDurationMs": { - "type": "number", + "type": "integer", "minimum": 0, "description": "Total time spent in model API calls (milliseconds)", "format": "duration" }, "sessionStartTime": { - "type": "integer", - "description": "Session start timestamp (epoch milliseconds)" + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp when the session started" }, "codeChanges": { "$ref": "#/definitions/UsageMetricsCodeChanges", @@ -7832,153 +15779,414 @@ "description": "Accumulated session usage metrics, including premium request cost, token counts, model breakdown, and code-change totals.", "title": "UsageGetMetricsResult" }, - "UsageMetricsCodeChanges": { + "UsageMetricsCodeChanges": { + "type": "object", + "properties": { + "linesAdded": { + "type": "integer", + "minimum": 0, + "description": "Total lines of code added" + }, + "linesRemoved": { + "type": "integer", + "minimum": 0, + "description": "Total lines of code removed" + }, + "filesModifiedCount": { + "type": "integer", + "minimum": 0, + "description": "Number of distinct files modified" + }, + "filesModified": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Distinct file paths modified during the session" + } + }, + "required": [ + "linesAdded", + "linesRemoved", + "filesModifiedCount", + "filesModified" + ], + "additionalProperties": false, + "description": "Aggregated code change metrics", + "title": "UsageMetricsCodeChanges" + }, + "UsageMetricsModelMetric": { + "type": "object", + "properties": { + "requests": { + "$ref": "#/definitions/UsageMetricsModelMetricRequests", + "description": "Request count and cost metrics for this model" + }, + "usage": { + "$ref": "#/definitions/UsageMetricsModelMetricUsage", + "description": "Token usage metrics for this model" + }, + "totalNanoAiu": { + "type": "number", + "minimum": 0, + "description": "Accumulated nano-AI units cost for this model" + }, + "tokenDetails": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/UsageMetricsModelMetricTokenDetail" + }, + "description": "Token count details per type" + } + }, + "required": [ + "requests", + "usage" + ], + "additionalProperties": false, + "title": "UsageMetricsModelMetric", + "description": "Schema for the `UsageMetricsModelMetric` type." + }, + "UsageMetricsModelMetricRequests": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "minimum": 0, + "description": "Number of API requests made with this model" + }, + "cost": { + "type": "number", + "description": "User-initiated premium request cost (with multiplier applied)" + } + }, + "required": [ + "count", + "cost" + ], + "additionalProperties": false, + "description": "Request count and cost metrics for this model", + "title": "UsageMetricsModelMetricRequests" + }, + "UsageMetricsModelMetricTokenDetail": { + "type": "object", + "properties": { + "tokenCount": { + "type": "integer", + "minimum": 0, + "description": "Accumulated token count for this token type" + } + }, + "required": [ + "tokenCount" + ], + "additionalProperties": false, + "title": "UsageMetricsModelMetricTokenDetail", + "description": "Schema for the `UsageMetricsModelMetricTokenDetail` type." + }, + "UsageMetricsModelMetricUsage": { + "type": "object", + "properties": { + "inputTokens": { + "type": "integer", + "minimum": 0, + "description": "Total input tokens consumed" + }, + "outputTokens": { + "type": "integer", + "minimum": 0, + "description": "Total output tokens produced" + }, + "cacheReadTokens": { + "type": "integer", + "minimum": 0, + "description": "Total tokens read from prompt cache" + }, + "cacheWriteTokens": { + "type": "integer", + "minimum": 0, + "description": "Total tokens written to prompt cache" + }, + "reasoningTokens": { + "type": "integer", + "minimum": 0, + "description": "Total output tokens used for reasoning" + } + }, + "required": [ + "inputTokens", + "outputTokens", + "cacheReadTokens", + "cacheWriteTokens" + ], + "additionalProperties": false, + "description": "Token usage metrics for this model", + "title": "UsageMetricsModelMetricUsage" + }, + "UsageMetricsTokenDetail": { + "type": "object", + "properties": { + "tokenCount": { + "type": "integer", + "minimum": 0, + "description": "Accumulated token count for this token type" + } + }, + "required": [ + "tokenCount" + ], + "additionalProperties": false, + "title": "UsageMetricsTokenDetail", + "description": "Schema for the `UsageMetricsTokenDetail` type." + }, + "UserAuthInfo": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "user", + "description": "OAuth user authentication. The token itself is held in the runtime's secret token store (keyed by host+login) and is NOT carried in this struct." + }, + "host": { + "type": "string", + "description": "Authentication host." + }, + "login": { + "type": "string", + "description": "OAuth user login." + }, + "copilotUser": { + "$ref": "#/definitions/CopilotUserResponse", + "description": "Snapshot of the authenticated user's Copilot subscription info, if known. Mirrors the GitHub API `/copilot_internal/v2/token` user response shape — the runtime trusts this verbatim and does not re-fetch when set." + } + }, + "required": [ + "type", + "host", + "login" + ], + "additionalProperties": false, + "title": "UserAuthInfo", + "description": "Schema for the `UserAuthInfo` type." + }, + "UserToolSessionApproval": { + "anyOf": [ + { + "$ref": "#/definitions/UserToolSessionApprovalCommands" + }, + { + "$ref": "#/definitions/UserToolSessionApprovalRead" + }, + { + "$ref": "#/definitions/UserToolSessionApprovalWrite" + }, + { + "$ref": "#/definitions/UserToolSessionApprovalMcp" + }, + { + "$ref": "#/definitions/UserToolSessionApprovalMemory" + }, + { + "$ref": "#/definitions/UserToolSessionApprovalCustomTool" + }, + { + "$ref": "#/definitions/UserToolSessionApprovalExtensionManagement" + }, + { + "$ref": "#/definitions/UserToolSessionApprovalExtensionPermissionAccess" + } + ], + "description": "The approval to add as a session-scoped rule", + "title": "UserToolSessionApproval" + }, + "UserToolSessionApprovalCommands": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "commands", + "description": "Command approval kind" + }, + "commandIdentifiers": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Command identifiers approved by the user" + } + }, + "required": [ + "kind", + "commandIdentifiers" + ], + "additionalProperties": false, + "title": "UserToolSessionApprovalCommands", + "description": "Schema for the `UserToolSessionApprovalCommands` type." + }, + "UserToolSessionApprovalCustomTool": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "custom-tool", + "description": "Custom tool approval kind" + }, + "toolName": { + "type": "string", + "description": "Custom tool name" + } + }, + "required": [ + "kind", + "toolName" + ], + "additionalProperties": false, + "title": "UserToolSessionApprovalCustomTool", + "description": "Schema for the `UserToolSessionApprovalCustomTool` type." + }, + "UserToolSessionApprovalExtensionManagement": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "extension-management", + "description": "Extension management approval kind" + }, + "operation": { + "type": "string", + "description": "Optional operation identifier" + } + }, + "required": [ + "kind" + ], + "additionalProperties": false, + "title": "UserToolSessionApprovalExtensionManagement", + "description": "Schema for the `UserToolSessionApprovalExtensionManagement` type." + }, + "UserToolSessionApprovalExtensionPermissionAccess": { "type": "object", "properties": { - "linesAdded": { - "type": "integer", - "description": "Total lines of code added" - }, - "linesRemoved": { - "type": "integer", - "description": "Total lines of code removed" + "kind": { + "type": "string", + "const": "extension-permission-access", + "description": "Extension permission access approval kind" }, - "filesModifiedCount": { - "type": "integer", - "description": "Number of distinct files modified" + "extensionName": { + "type": "string", + "description": "Extension name" } }, "required": [ - "linesAdded", - "linesRemoved", - "filesModifiedCount" + "kind", + "extensionName" ], "additionalProperties": false, - "description": "Aggregated code change metrics", - "title": "UsageMetricsCodeChanges" + "title": "UserToolSessionApprovalExtensionPermissionAccess", + "description": "Schema for the `UserToolSessionApprovalExtensionPermissionAccess` type." }, - "UsageMetricsModelMetric": { + "UserToolSessionApprovalMcp": { "type": "object", "properties": { - "requests": { - "$ref": "#/definitions/UsageMetricsModelMetricRequests", - "description": "Request count and cost metrics for this model" - }, - "usage": { - "$ref": "#/definitions/UsageMetricsModelMetricUsage", - "description": "Token usage metrics for this model" + "kind": { + "type": "string", + "const": "mcp", + "description": "MCP tool approval kind" }, - "totalNanoAiu": { - "type": "integer", - "minimum": 0, - "description": "Accumulated nano-AI units cost for this model" + "serverName": { + "type": "string", + "description": "MCP server name" }, - "tokenDetails": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/UsageMetricsModelMetricTokenDetail" - }, - "description": "Token count details per type" + "toolName": { + "type": [ + "string", + "null" + ], + "description": "Optional MCP tool name, or null for all tools on the server" } }, "required": [ - "requests", - "usage" + "kind", + "serverName", + "toolName" ], "additionalProperties": false, - "title": "UsageMetricsModelMetric", - "description": "Schema for the `UsageMetricsModelMetric` type." + "title": "UserToolSessionApprovalMcp", + "description": "Schema for the `UserToolSessionApprovalMcp` type." }, - "UsageMetricsModelMetricRequests": { + "UserToolSessionApprovalMemory": { "type": "object", "properties": { - "count": { - "type": "integer", - "description": "Number of API requests made with this model" - }, - "cost": { - "type": "number", - "description": "User-initiated premium request cost (with multiplier applied)" + "kind": { + "type": "string", + "const": "memory", + "description": "Memory approval kind" } }, "required": [ - "count", - "cost" + "kind" ], "additionalProperties": false, - "description": "Request count and cost metrics for this model", - "title": "UsageMetricsModelMetricRequests" + "title": "UserToolSessionApprovalMemory", + "description": "Schema for the `UserToolSessionApprovalMemory` type." }, - "UsageMetricsModelMetricTokenDetail": { + "UserToolSessionApprovalRead": { "type": "object", "properties": { - "tokenCount": { - "type": "integer", - "minimum": 0, - "description": "Accumulated token count for this token type" + "kind": { + "type": "string", + "const": "read", + "description": "Read approval kind" } }, "required": [ - "tokenCount" + "kind" ], "additionalProperties": false, - "title": "UsageMetricsModelMetricTokenDetail", - "description": "Schema for the `UsageMetricsModelMetricTokenDetail` type." + "title": "UserToolSessionApprovalRead", + "description": "Schema for the `UserToolSessionApprovalRead` type." }, - "UsageMetricsModelMetricUsage": { + "UserToolSessionApprovalWrite": { "type": "object", "properties": { - "inputTokens": { - "type": "integer", - "minimum": 0, - "description": "Total input tokens consumed" - }, - "outputTokens": { - "type": "integer", - "minimum": 0, - "description": "Total output tokens produced" - }, - "cacheReadTokens": { - "type": "integer", - "minimum": 0, - "description": "Total tokens read from prompt cache" - }, - "cacheWriteTokens": { - "type": "integer", - "minimum": 0, - "description": "Total tokens written to prompt cache" - }, - "reasoningTokens": { - "type": "integer", - "minimum": 0, - "description": "Total output tokens used for reasoning" + "kind": { + "type": "string", + "const": "write", + "description": "Write approval kind" } }, "required": [ - "inputTokens", - "outputTokens", - "cacheReadTokens", - "cacheWriteTokens" + "kind" ], "additionalProperties": false, - "description": "Token usage metrics for this model", - "title": "UsageMetricsModelMetricUsage" + "title": "UserToolSessionApprovalWrite", + "description": "Schema for the `UserToolSessionApprovalWrite` type." }, - "UsageMetricsTokenDetail": { + "WorkspacesCheckpoints": { "type": "object", "properties": { - "tokenCount": { + "number": { "type": "integer", "minimum": 0, - "description": "Accumulated token count for this token type" + "description": "Checkpoint number assigned by the workspace manager" + }, + "title": { + "type": "string", + "description": "Human-readable checkpoint title" + }, + "filename": { + "type": "string", + "description": "Filename of the checkpoint within the workspace checkpoints directory" } }, "required": [ - "tokenCount" + "number", + "title", + "filename" ], "additionalProperties": false, - "title": "UsageMetricsTokenDetail", - "description": "Schema for the `UsageMetricsTokenDetail` type." + "title": "WorkspacesCheckpoints", + "description": "Schema for the `WorkspacesCheckpoints` type." }, "WorkspacesCreateFileRequest": { "type": "object", @@ -8010,7 +16218,7 @@ "properties": { "id": { "type": "string", - "format": "uuid" + "minLength": 1 }, "cwd": { "type": "string" @@ -8022,11 +16230,8 @@ "type": "string" }, "host_type": { - "type": "string", - "enum": [ - "github", - "ado" - ] + "$ref": "#/definitions/WorkspacesWorkspaceDetailsHostType", + "description": "Allowed values for the `WorkspacesWorkspaceDetailsHostType` enumeration." }, "branch": { "type": "string" @@ -8076,15 +16281,37 @@ } ], "description": "Current workspace metadata, or null if not available" + }, + "path": { + "type": "string", + "description": "Absolute filesystem path to the workspace directory. Omitted when the session has no workspace (e.g. remote sessions)." } }, "required": [ "workspace" ], "additionalProperties": false, - "description": "Current workspace metadata for the session, or null when not available.", + "description": "Current workspace metadata for the session, including its absolute filesystem path when available.", "title": "WorkspacesGetWorkspaceResult" }, + "WorkspacesListCheckpointsResult": { + "type": "object", + "properties": { + "checkpoints": { + "type": "array", + "items": { + "$ref": "#/definitions/WorkspacesCheckpoints" + }, + "description": "Workspace checkpoints in chronological order. Empty when workspace is not enabled." + } + }, + "required": [ + "checkpoints" + ], + "additionalProperties": false, + "description": "Workspace checkpoints in chronological order; empty when the workspace is not enabled.", + "title": "WorkspacesListCheckpointsResult" + }, "WorkspacesListFilesResult": { "type": "object", "properties": { @@ -8103,6 +16330,40 @@ "description": "Relative paths of files stored in the session workspace files directory.", "title": "WorkspacesListFilesResult" }, + "WorkspacesReadCheckpointRequest": { + "type": "object", + "properties": { + "number": { + "type": "integer", + "minimum": 0, + "description": "Checkpoint number to read" + } + }, + "required": [ + "number" + ], + "additionalProperties": false, + "description": "Checkpoint number to read.", + "title": "WorkspacesReadCheckpointRequest" + }, + "WorkspacesReadCheckpointResult": { + "type": "object", + "properties": { + "content": { + "type": [ + "string", + "null" + ], + "description": "Checkpoint content as a UTF-8 string, or null when the checkpoint or workspace is missing" + } + }, + "required": [ + "content" + ], + "additionalProperties": false, + "description": "Checkpoint content as a UTF-8 string, or null when the checkpoint or workspace is missing.", + "title": "WorkspacesReadCheckpointResult" + }, "WorkspacesReadFileRequest": { "type": "object", "properties": { @@ -8132,6 +16393,148 @@ "additionalProperties": false, "description": "Contents of the requested workspace file as a UTF-8 string.", "title": "WorkspacesReadFileResult" + }, + "WorkspacesSaveLargePasteRequest": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "Pasted content to save as a UTF-8 file" + } + }, + "required": [ + "content" + ], + "additionalProperties": false, + "description": "Pasted content to save as a UTF-8 file in the session workspace.", + "title": "WorkspacesSaveLargePasteRequest" + }, + "WorkspacesSaveLargePasteResult": { + "type": "object", + "properties": { + "saved": { + "anyOf": [ + { + "type": "object", + "properties": { + "filePath": { + "type": "string", + "description": "Absolute filesystem path to the saved paste file" + }, + "filename": { + "type": "string", + "description": "Filename within the workspace files directory" + }, + "sizeBytes": { + "type": "integer", + "minimum": 0, + "description": "Size of the saved file in bytes" + } + }, + "required": [ + "filePath", + "filename", + "sizeBytes" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ], + "description": "Saved-paste descriptor, or null when the workspace is unavailable (e.g. CCA runtime, non-infinite sessions, remote sessions)" + } + }, + "required": [ + "saved" + ], + "additionalProperties": false, + "description": "Descriptor for the saved paste file, or null when the workspace is unavailable.", + "title": "WorkspacesSaveLargePasteResult" + }, + "WorkspaceSummary": { + "anyOf": [ + { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "description": "Workspace identifier (1:1 with sessionId)" + }, + "cwd": { + "type": "string", + "description": "Current working directory at session start" + }, + "git_root": { + "type": "string", + "description": "Resolved git root for cwd, if any" + }, + "repository": { + "type": "string", + "description": "Repository identifier in 'owner/repo' or 'org/project/repo' format, if any" + }, + "host_type": { + "$ref": "#/definitions/WorkspaceSummaryHostType", + "description": "Repository host type, if known" + }, + "branch": { + "type": "string", + "description": "Branch checked out at session start, if any" + }, + "name": { + "type": "string", + "description": "Display name for the session, if set" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp when the workspace was created" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp when the workspace was last updated" + } + }, + "required": [ + "id" + ], + "additionalProperties": false, + "description": "Public-facing projection of workspace metadata for SDK / TUI consumers" + }, + { + "type": "null" + } + ], + "description": "Public-facing workspace metadata for this session, or null if the session has no associated workspace. Excludes runtime-internal fields (GitHub IDs, summary count, internal flags).", + "title": "WorkspaceSummary" + }, + "WorkspaceSummaryHostType": { + "type": "string", + "enum": [ + "github", + "ado" + ], + "description": "Repository host type, if known", + "title": "WorkspaceSummaryHostType", + "x-enumDescriptions": { + "github": "Workspace summary repository is hosted on GitHub.", + "ado": "Workspace summary repository is hosted on Azure DevOps." + } + }, + "WorkspacesWorkspaceDetailsHostType": { + "type": "string", + "enum": [ + "github", + "ado" + ], + "title": "WorkspacesWorkspaceDetailsHostType", + "x-enumDescriptions": { + "github": "Workspace repository is hosted on GitHub.", + "ado": "Workspace repository is hosted on Azure DevOps." + }, + "description": "Allowed values for the `WorkspacesWorkspaceDetailsHostType` enumeration." } } } diff --git a/schemas/session-events.schema.json b/schemas/session-events.schema.json index d908951..62fecfd 100644 --- a/schemas/session-events.schema.json +++ b/schemas/session-events.schema.json @@ -78,7 +78,12 @@ "user_abort" ], "description": "Finite reason code describing why the current turn was aborted", - "title": "AbortReason" + "title": "AbortReason", + "x-enumDescriptions": { + "user_initiated": "The local user requested the abort, for example by pressing Ctrl+C in the CLI.", + "remote_command": "A remote command requested the abort.", + "user_abort": "An MCP server delivered a user.abort notification." + } }, "AssistantIntentData": { "type": "object", @@ -191,7 +196,8 @@ "description": "Generation phase for phased-output models (e.g., thinking vs. response phases)" }, "outputTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Actual output token count from the API response (completion_tokens), used for accurate token accounting" }, "interactionId": { @@ -209,7 +215,8 @@ }, "anthropicAdvisorModel": { "type": "string", - "description": "Anthropic advisor model ID used for this response, for timeline display on replay" + "description": "Anthropic advisor model ID used for this response, for timeline display on replay", + "stability": "experimental" }, "turnId": { "type": "string", @@ -492,7 +499,11 @@ "custom" ], "description": "Tool call type: \"function\" for standard tool calls, \"custom\" for grammar-based tool calls. Defaults to \"function\" when absent.", - "title": "AssistantMessageToolRequestType" + "title": "AssistantMessageToolRequestType", + "x-enumDescriptions": { + "function": "Standard function-style tool call.", + "custom": "Custom grammar-based tool call." + } }, "AssistantReasoningData": { "type": "object", @@ -648,7 +659,8 @@ "type": "object", "properties": { "totalResponseSizeBytes": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Cumulative total bytes received from the streaming response so far" } }, @@ -866,7 +878,13 @@ "ws:/responses" ], "description": "API endpoint used for this model call, matching CAPI supported_endpoints vocabulary", - "title": "AssistantUsageApiEndpoint" + "title": "AssistantUsageApiEndpoint", + "x-enumDescriptions": { + "/chat/completions": "Chat Completions API endpoint.", + "/v1/messages": "Anthropic Messages API endpoint.", + "/responses": "Responses API endpoint.", + "ws:/responses": "WebSocket Responses API endpoint." + } }, "AssistantUsageCopilotUsage": { "type": "object", @@ -881,6 +899,7 @@ }, "totalNanoAiu": { "type": "number", + "minimum": 0, "description": "Total cost in nano-AI units for this request" } }, @@ -890,21 +909,25 @@ ], "additionalProperties": false, "description": "Per-request cost and usage data from the CAPI copilot_usage response field", - "title": "AssistantUsageCopilotUsage" + "title": "AssistantUsageCopilotUsage", + "visibility": "internal" }, "AssistantUsageCopilotUsageTokenDetail": { "type": "object", "properties": { "batchSize": { - "type": "number", + "type": "integer", + "exclusiveMinimum": 0, "description": "Number of tokens in this billing batch" }, "costPerBatch": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Cost per batch of tokens" }, "tokenCount": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total token count for this entry" }, "tokenType": { @@ -930,41 +953,50 @@ "description": "Model identifier used for this API call" }, "inputTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Number of input tokens consumed" }, "outputTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Number of output tokens produced" }, "cacheReadTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Number of tokens read from prompt cache" }, "cacheWriteTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Number of tokens written to prompt cache" }, "reasoningTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Number of output tokens used for reasoning (e.g., chain-of-thought)" }, "cost": { "type": "number", - "description": "Model multiplier cost for billing purposes" + "description": "Model multiplier cost for billing purposes", + "stability": "experimental" }, "duration": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Duration of the API call in milliseconds", "format": "duration" }, - "ttftMs": { - "type": "number", + "timeToFirstTokenMs": { + "type": "integer", + "minimum": 0, "description": "Time to first token in milliseconds. Only available for streaming requests", "format": "duration" }, "interTokenLatencyMs": { "type": "number", + "minimum": 0, "description": "Average inter-token latency in milliseconds. Only available for streaming requests", "format": "duration" }, @@ -994,7 +1026,8 @@ "additionalProperties": { "$ref": "#/definitions/AssistantUsageQuotaSnapshot" }, - "description": "Per-quota resource usage snapshots, keyed by quota identifier" + "description": "Per-quota resource usage snapshots, keyed by quota identifier", + "visibility": "internal" }, "copilotUsage": { "$ref": "#/definitions/AssistantUsageCopilotUsage", @@ -1073,36 +1106,49 @@ "properties": { "isUnlimitedEntitlement": { "type": "boolean", - "description": "Whether the user has an unlimited usage entitlement" + "description": "Whether the user has an unlimited usage entitlement", + "visibility": "internal" }, "entitlementRequests": { - "type": "number", - "description": "Total requests allowed by the entitlement" + "type": "integer", + "minimum": -1, + "description": "Total requests allowed by the entitlement", + "visibility": "internal" }, "usedRequests": { - "type": "number", - "description": "Number of requests already consumed" + "type": "integer", + "minimum": 0, + "description": "Number of requests already consumed", + "visibility": "internal" }, "usageAllowedWithExhaustedQuota": { "type": "boolean", - "description": "Whether usage is still permitted after quota exhaustion" + "description": "Whether usage is still permitted after quota exhaustion", + "visibility": "internal" }, "overage": { "type": "number", - "description": "Number of requests over the entitlement limit" + "minimum": 0, + "description": "Number of requests over the entitlement limit", + "visibility": "internal" }, "overageAllowedWithExhaustedQuota": { "type": "boolean", - "description": "Whether overage is allowed when quota is exhausted" + "description": "Whether overage is allowed when quota is exhausted", + "visibility": "internal" }, "remainingPercentage": { "type": "number", - "description": "Percentage of quota remaining (0.0 to 1.0)" + "minimum": 0, + "maximum": 100, + "description": "Percentage of quota remaining (0 to 100)", + "visibility": "internal" }, "resetDate": { "type": "string", "format": "date-time", - "description": "Date when the quota resets" + "description": "Date when the quota resets", + "visibility": "internal" } }, "required": [ @@ -1206,8 +1252,10 @@ "description": "The rate limit error code that triggered this request" }, "retryAfterSeconds": { - "type": "number", - "description": "Seconds until the rate limit resets, when known. Lets clients render a humanized reset time alongside the prompt." + "type": "integer", + "minimum": 0, + "description": "Seconds until the rate limit resets, when known. Lets clients render a humanized reset time alongside the prompt.", + "format": "duration" } }, "required": [ @@ -1281,7 +1329,12 @@ "no" ], "description": "The user's auto-mode-switch choice", - "title": "AutoModeSwitchResponse" + "title": "AutoModeSwitchResponse", + "x-enumDescriptions": { + "yes": "Switch models for this request.", + "yes_always": "Switch models now and keep using the replacement automatically.", + "no": "Do not switch models." + } }, "BackgroundTasksChangedData": { "type": "object", @@ -1756,19 +1809,23 @@ "type": "object", "properties": { "inputTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Input tokens consumed by the compaction LLM call" }, "outputTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Output tokens produced by the compaction LLM call" }, "cacheReadTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Cached input tokens reused in the compaction LLM call" }, "cacheWriteTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Tokens written to prompt cache in the compaction LLM call" }, "copilotUsage": { @@ -1776,7 +1833,8 @@ "description": "Per-request cost and usage data from the CAPI copilot_usage response field" }, "duration": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Duration of the compaction LLM call in milliseconds", "format": "duration" }, @@ -1802,6 +1860,7 @@ }, "totalNanoAiu": { "type": "number", + "minimum": 0, "description": "Total cost in nano-AI units for this request" } }, @@ -1811,21 +1870,25 @@ ], "additionalProperties": false, "description": "Per-request cost and usage data from the CAPI copilot_usage response field", - "title": "CompactionCompleteCompactionTokensUsedCopilotUsage" + "title": "CompactionCompleteCompactionTokensUsedCopilotUsage", + "visibility": "internal" }, "CompactionCompleteCompactionTokensUsedCopilotUsageTokenDetail": { "type": "object", "properties": { "batchSize": { - "type": "number", + "type": "integer", + "exclusiveMinimum": 0, "description": "Number of tokens in this billing batch" }, "costPerBatch": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Cost per batch of tokens" }, "tokenCount": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total token count for this entry" }, "tokenType": { @@ -1855,23 +1918,28 @@ "description": "Error message if compaction failed" }, "preCompactionTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total tokens in conversation before compaction" }, "postCompactionTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total tokens in conversation after compaction" }, "preCompactionMessagesLength": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Number of messages before compaction" }, "messagesRemoved": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Number of messages removed during compaction" }, "tokensRemoved": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Number of tokens removed during compaction" }, "summaryContent": { @@ -1879,7 +1947,8 @@ "description": "LLM-generated summary of the compacted conversation history" }, "checkpointNumber": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Checkpoint snapshot number created for recovery" }, "checkpointPath": { @@ -1895,15 +1964,18 @@ "description": "GitHub request tracing ID (x-github-request-id header) for the compaction LLM call" }, "systemTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Token count from system message(s) after compaction" }, "conversationTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Token count from non-system messages (user, assistant, tool) after compaction" }, "toolDefinitionsTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Token count from tool definitions after compaction" } }, @@ -1972,15 +2044,18 @@ "type": "object", "properties": { "systemTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Token count from system message(s) at compaction start" }, "conversationTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Token count from non-system messages (user, assistant, tool) at compaction start" }, "toolDefinitionsTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Token count from tool definitions at compaction start" } }, @@ -2379,7 +2454,12 @@ "cancel" ], "description": "The user action: \"accept\" (submitted form), \"decline\" (explicitly refused), or \"cancel\" (dismissed)", - "title": "ElicitationCompletedAction" + "title": "ElicitationCompletedAction", + "x-enumDescriptions": { + "accept": "The user submitted the requested form.", + "decline": "The user explicitly declined the request.", + "cancel": "The user dismissed the request." + } }, "ElicitationCompletedContent": { "anyOf": [ @@ -2587,7 +2667,11 @@ "url" ], "description": "Elicitation mode; \"form\" for structured input, \"url\" for browser-based. Defaults to \"form\" when absent.", - "title": "ElicitationRequestedMode" + "title": "ElicitationRequestedMode", + "x-enumDescriptions": { + "form": "Structured form-based elicitation.", + "url": "Browser URL-based elicitation." + } }, "ElicitationRequestedSchema": { "type": "object", @@ -2623,6 +2707,7 @@ "properties": { "uri": { "type": "string", + "format": "uri", "description": "URI identifying the resource" }, "mimeType": { @@ -2648,6 +2733,7 @@ "properties": { "uri": { "type": "string", + "format": "uri", "description": "URI identifying the resource" }, "mimeType": { @@ -2692,6 +2778,8 @@ }, "statusCode": { "type": "integer", + "minimum": 0, + "maximum": 999, "description": "HTTP status code from the upstream request, if applicable" }, "providerCallId": { @@ -2775,7 +2863,13 @@ "autopilot_fleet" ], "description": "Exit plan mode action", - "title": "ExitPlanModeAction" + "title": "ExitPlanModeAction", + "x-enumDescriptions": { + "exit_only": "Exit plan mode without starting implementation.", + "interactive": "Exit plan mode and continue in interactive mode.", + "autopilot": "Exit plan mode and continue autonomously.", + "autopilot_fleet": "Exit plan mode and continue with parallel autonomous workers." + } }, "ExitPlanModeCompletedData": { "type": "object", @@ -3070,7 +3164,11 @@ "user" ], "description": "Discovery source", - "title": "ExtensionsLoadedExtensionSource" + "title": "ExtensionsLoadedExtensionSource", + "x-enumDescriptions": { + "project": "Extension discovered from the current project.", + "user": "Extension discovered from the user's extension directory." + } }, "ExtensionsLoadedExtensionStatus": { "type": "string", @@ -3081,7 +3179,13 @@ "starting" ], "description": "Current status: running, disabled, failed, or starting", - "title": "ExtensionsLoadedExtensionStatus" + "title": "ExtensionsLoadedExtensionStatus", + "x-enumDescriptions": { + "running": "The extension process is running.", + "disabled": "The extension is installed but disabled.", + "failed": "The extension failed to start or crashed.", + "starting": "The extension process is starting." + } }, "ExternalToolCompletedData": { "type": "object", @@ -3375,7 +3479,11 @@ "local" ], "description": "Origin type of the session being handed off", - "title": "HandoffSourceType" + "title": "HandoffSourceType", + "x-enumDescriptions": { + "remote": "The handoff originated from a remote session.", + "local": "The handoff originated from a local session." + } }, "HookEndData": { "type": "object", @@ -4002,7 +4110,13 @@ "builtin" ], "description": "Configuration source: user, workspace, plugin, or builtin", - "title": "McpServerSource" + "title": "McpServerSource", + "x-enumDescriptions": { + "user": "Server configured in the user's global MCP configuration.", + "workspace": "Server configured by the current workspace.", + "plugin": "Server contributed by an installed plugin.", + "builtin": "Server bundled with the runtime." + } }, "McpServerStatus": { "type": "string", @@ -4015,7 +4129,15 @@ "not_configured" ], "description": "Connection status: connected, failed, needs-auth, pending, disabled, or not_configured", - "title": "McpServerStatus" + "title": "McpServerStatus", + "x-enumDescriptions": { + "connected": "The server is connected and available.", + "failed": "The server failed to connect or initialize.", + "needs-auth": "The server requires authentication before it can connect.", + "pending": "The server connection is still being established.", + "disabled": "The server is configured but disabled.", + "not_configured": "The server is not configured for this session." + } }, "McpServerStatusChangedData": { "type": "object", @@ -4188,10 +4310,13 @@ }, "statusCode": { "type": "integer", + "minimum": 0, + "maximum": 999, "description": "HTTP status code from the failed request" }, "durationMs": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Duration of the failed API call in milliseconds", "format": "duration" }, @@ -4275,7 +4400,12 @@ "mcp_sampling" ], "description": "Where the failed model call originated", - "title": "ModelCallFailureSource" + "title": "ModelCallFailureSource", + "x-enumDescriptions": { + "top_level": "Model call from the top-level agent.", + "subagent": "Model call from a sub-agent.", + "mcp_sampling": "Model call from MCP sampling." + } }, "ModelChangeData": { "type": "object", @@ -5065,7 +5195,12 @@ "write" ], "description": "Underlying permission kind that needs path approval", - "title": "PermissionPromptRequestPathAccessKind" + "title": "PermissionPromptRequestPathAccessKind", + "x-enumDescriptions": { + "read": "Read access to a filesystem path.", + "shell": "Shell command access involving a filesystem path.", + "write": "Write access to a filesystem path." + } }, "PermissionPromptRequestRead": { "type": "object", @@ -5523,7 +5658,11 @@ ], "description": "Whether this is a store or vote memory operation", "default": "store", - "title": "PermissionRequestMemoryAction" + "title": "PermissionRequestMemoryAction", + "x-enumDescriptions": { + "store": "Store a new memory.", + "vote": "Vote on an existing memory." + } }, "PermissionRequestMemoryDirection": { "type": "string", @@ -5532,7 +5671,11 @@ "downvote" ], "description": "Vote direction (vote only)", - "title": "PermissionRequestMemoryDirection" + "title": "PermissionRequestMemoryDirection", + "x-enumDescriptions": { + "upvote": "Vote that the memory is useful or accurate.", + "downvote": "Vote that the memory is incorrect or outdated." + } }, "PermissionRequestRead": { "type": "object", @@ -5788,7 +5931,7 @@ "string", "null" ], - "description": "Optional rule argument matched against the request" + "description": "Argument value matched against the request, or null when the rule kind has no argument (e.g. 'read', 'write', 'memory')." } }, "required": [ @@ -5876,7 +6019,12 @@ "delete" ], "description": "The type of operation performed on the plan file", - "title": "PlanChangedOperation" + "title": "PlanChangedOperation", + "x-enumDescriptions": { + "create": "The plan file was created.", + "update": "The plan file was updated.", + "delete": "The plan file was deleted." + } }, "ReasoningSummary": { "type": "string", @@ -5886,7 +6034,12 @@ "detailed" ], "description": "Reasoning summary mode used for model calls, if applicable (e.g. \"none\", \"concise\", \"detailed\")", - "title": "ReasoningSummary" + "title": "ReasoningSummary", + "x-enumDescriptions": { + "none": "Do not request reasoning summaries from the model.", + "concise": "Request a concise summary of the model's reasoning.", + "detailed": "Request a detailed summary of the model's reasoning." + } }, "RemoteSteerableChangedData": { "type": "object", @@ -5966,7 +6119,8 @@ "description": "ISO 8601 timestamp when the session was resumed" }, "eventCount": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total number of persisted events in the session at the time of resume" }, "selectedModel": { @@ -6716,17 +6870,24 @@ "autopilot" ], "description": "The session mode the agent is operating in", - "title": "SessionMode" + "title": "SessionMode", + "x-enumDescriptions": { + "interactive": "The agent is responding interactively to the user.", + "plan": "The agent is preparing a plan before making changes.", + "autopilot": "The agent is working autonomously toward task completion." + } }, "ShutdownCodeChanges": { "type": "object", "properties": { "linesAdded": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total number of lines added during the session" }, "linesRemoved": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total number of lines removed during the session" }, "filesModified": { @@ -6759,11 +6920,15 @@ }, "totalPremiumRequests": { "type": "number", - "description": "Total number of premium API requests used during the session" + "minimum": 0, + "description": "Total number of premium API requests used during the session", + "visibility": "internal" }, "totalNanoAiu": { "type": "number", - "description": "Session-wide accumulated nano-AI units cost" + "minimum": 0, + "description": "Session-wide accumulated nano-AI units cost", + "stability": "experimental" }, "tokenDetails": { "type": "object", @@ -6773,12 +6938,14 @@ "description": "Session-wide per-token-type accumulated token counts" }, "totalApiDurationMs": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Cumulative time spent in API calls during the session, in milliseconds", "format": "duration" }, "sessionStartTime": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Unix timestamp (milliseconds) when the session started" }, "codeChanges": { @@ -6797,19 +6964,23 @@ "description": "Model that was selected at the time of shutdown" }, "currentTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total tokens in context window at shutdown" }, "systemTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "System message token count at shutdown" }, "conversationTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Non-system message token count at shutdown" }, "toolDefinitionsTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Tool definitions token count at shutdown" } }, @@ -6892,7 +7063,9 @@ }, "totalNanoAiu": { "type": "number", - "description": "Accumulated nano-AI units cost for this model" + "minimum": 0, + "description": "Accumulated nano-AI units cost for this model", + "stability": "experimental" }, "tokenDetails": { "type": "object", @@ -6914,12 +7087,15 @@ "type": "object", "properties": { "count": { - "type": "number", - "description": "Total number of API requests made to this model" + "type": "integer", + "minimum": 0, + "description": "Total number of API requests made to this model", + "stability": "experimental" }, "cost": { "type": "number", - "description": "Cumulative cost multiplier for requests to this model" + "description": "Cumulative cost multiplier for requests to this model", + "stability": "experimental" } }, "required": [ @@ -6934,7 +7110,8 @@ "type": "object", "properties": { "tokenCount": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Accumulated token count for this token type" } }, @@ -6949,23 +7126,28 @@ "type": "object", "properties": { "inputTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total input tokens consumed across all requests to this model" }, "outputTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total output tokens produced across all requests to this model" }, "cacheReadTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total tokens read from prompt cache across all requests" }, "cacheWriteTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total tokens written to prompt cache across all requests" }, "reasoningTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total reasoning tokens produced across all requests to this model" } }, @@ -6983,7 +7165,8 @@ "type": "object", "properties": { "tokenCount": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Accumulated token count for this token type" } }, @@ -7001,7 +7184,11 @@ "error" ], "description": "Whether the session ended normally (\"routine\") or due to a crash/fatal error (\"error\")", - "title": "ShutdownType" + "title": "ShutdownType", + "x-enumDescriptions": { + "routine": "The session ended normally.", + "error": "The session ended because of a crash or fatal error." + } }, "SkillInvokedData": { "type": "object", @@ -7226,7 +7413,16 @@ "builtin" ], "description": "Source location type (e.g., project, personal-copilot, plugin, builtin)", - "title": "SkillSource" + "title": "SkillSource", + "x-enumDescriptions": { + "project": "Skill defined in the current project's skill directories.", + "inherited": "Skill discovered from a parent directory in the current workspace tree.", + "personal-copilot": "Skill defined in the user's Copilot skill directory.", + "personal-agents": "Skill defined in the user's personal agents skill directory.", + "plugin": "Skill provided by an installed plugin.", + "custom": "Skill loaded from a configured custom skill directory.", + "builtin": "Skill bundled with the runtime." + } }, "SnapshotRewindData": { "type": "object", @@ -7236,7 +7432,8 @@ "description": "Event ID that was rewound to; this event and all after it were removed" }, "eventsRemoved": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Number of events that were removed by the rewind" } }, @@ -7312,7 +7509,8 @@ "description": "Unique identifier for the session" }, "version": { - "type": "number", + "type": "integer", + "exclusiveMinimum": 0, "description": "Schema version number for the session event format" }, "producer": { @@ -7442,15 +7640,18 @@ "description": "Model used by the sub-agent" }, "totalToolCalls": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total number of tool calls made by the sub-agent" }, "totalTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total tokens (input + output) consumed by the sub-agent" }, "durationMs": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Wall-clock duration of the sub-agent execution in milliseconds", "format": "duration" } @@ -7603,15 +7804,18 @@ "description": "Model used by the sub-agent (if any model calls succeeded before failure)" }, "totalToolCalls": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total number of tool calls made before the sub-agent failed" }, "totalTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total tokens (input + output) consumed before the sub-agent failed" }, "durationMs": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Wall-clock duration of the sub-agent execution in milliseconds", "format": "duration" } @@ -7963,7 +8167,11 @@ "developer" ], "description": "Message role: \"system\" for system prompts, \"developer\" for developer-injected instructions", - "title": "SystemMessageRole" + "title": "SystemMessageRole", + "x-enumDescriptions": { + "system": "System prompt message.", + "developer": "Developer instruction message." + } }, "SystemNotification": { "anyOf": [ @@ -8035,7 +8243,11 @@ "failed" ], "description": "Whether the agent completed successfully or failed", - "title": "SystemNotificationAgentCompletedStatus" + "title": "SystemNotificationAgentCompletedStatus", + "x-enumDescriptions": { + "completed": "The agent completed successfully.", + "failed": "The agent failed." + } }, "SystemNotificationAgentIdle": { "type": "object", @@ -8225,7 +8437,9 @@ "description": "Unique identifier of the shell session" }, "exitCode": { - "type": "number", + "type": "integer", + "minimum": 0, + "maximum": 4294967295, "description": "Exit code of the shell command, if available" }, "description": { @@ -8546,6 +8760,7 @@ }, "uri": { "type": "string", + "format": "uri", "description": "URI identifying the resource" }, "description": { @@ -8557,7 +8772,8 @@ "description": "MIME type of the resource content" }, "size": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Size of the resource in bytes" }, "type": { @@ -8612,7 +8828,11 @@ "dark" ], "description": "Theme variant this icon is intended for", - "title": "ToolExecutionCompleteContentResourceLinkIconTheme" + "title": "ToolExecutionCompleteContentResourceLinkIconTheme", + "x-enumDescriptions": { + "light": "Icon intended for light themes.", + "dark": "Icon intended for dark themes." + } }, "ToolExecutionCompleteContentTerminal": { "type": "object", @@ -8627,7 +8847,9 @@ "description": "Terminal/shell output text" }, "exitCode": { - "type": "number", + "type": "integer", + "minimum": 0, + "maximum": 4294967295, "description": "Process exit code, if the command has completed" }, "cwd": { @@ -9216,31 +9438,38 @@ "type": "object", "properties": { "tokenLimit": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Maximum token count for the model's context window" }, "preTruncationTokensInMessages": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total tokens in conversation messages before truncation" }, "preTruncationMessagesLength": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Number of conversation messages before truncation" }, "postTruncationTokensInMessages": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Total tokens in conversation messages after truncation" }, "postTruncationMessagesLength": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Number of conversation messages after truncation" }, "tokensRemovedDuringTruncation": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Number of tokens removed by truncation" }, "messagesRemovedDuringTruncation": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Number of messages removed by truncation" }, "performedBy": { @@ -9320,27 +9549,33 @@ "type": "object", "properties": { "tokenLimit": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Maximum token count for the model's context window" }, "currentTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Current number of tokens in the context window" }, "messagesLength": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Current number of messages in the conversation" }, "systemTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Token count from system message(s)" }, "conversationTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Token count from non-system messages (user, assistant, tool)" }, "toolDefinitionsTokens": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Token count from tool definitions" }, "isInitial": { @@ -9592,7 +9827,13 @@ "shell" ], "description": "The agent mode that was active when this message was sent", - "title": "UserMessageAgentMode" + "title": "UserMessageAgentMode", + "x-enumDescriptions": { + "interactive": "The agent is responding interactively to the user.", + "plan": "The agent is preparing a plan before making changes.", + "autopilot": "The agent is working autonomously toward task completion.", + "shell": "The agent is in shell-focused UI mode." + } }, "UserMessageAttachment": { "anyOf": [ @@ -9711,11 +9952,13 @@ "type": "object", "properties": { "start": { - "type": "number", + "type": "integer", + "exclusiveMinimum": 0, "description": "Start line number (1-based)" }, "end": { - "type": "number", + "type": "integer", + "exclusiveMinimum": 0, "description": "End line number (1-based, inclusive)" } }, @@ -9736,7 +9979,8 @@ "description": "Attachment type discriminator" }, "number": { - "type": "number", + "type": "integer", + "exclusiveMinimum": 0, "description": "Issue, pull request, or discussion number" }, "title": { @@ -9777,7 +10021,12 @@ "discussion" ], "description": "Type of GitHub reference", - "title": "UserMessageAttachmentGithubReferenceType" + "title": "UserMessageAttachmentGithubReferenceType", + "x-enumDescriptions": { + "issue": "GitHub issue reference.", + "pr": "GitHub pull request reference.", + "discussion": "GitHub discussion reference." + } }, "UserMessageAttachmentSelection": { "type": "object", @@ -9839,11 +10088,13 @@ "type": "object", "properties": { "line": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "End line number (0-based)" }, "character": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "End character offset within the line (0-based)" } }, @@ -9859,11 +10110,13 @@ "type": "object", "properties": { "line": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Start line number (0-based)" }, "character": { - "type": "number", + "type": "integer", + "minimum": 0, "description": "Start character offset within the line (0-based)" } }, @@ -9906,7 +10159,7 @@ "items": { "type": "string" }, - "description": "Path-backed native document attachments that stayed on the tagged_files path flow because native upload would exceed the request size limit" + "description": "Path-backed native document attachments that stayed on the tagged_files path flow because native upload could not read them or would exceed the request size limit" }, "source": { "type": "string", @@ -10312,7 +10565,11 @@ "ado" ], "description": "Hosting platform type of the repository (github or ado)", - "title": "WorkingDirectoryContextHostType" + "title": "WorkingDirectoryContextHostType", + "x-enumDescriptions": { + "github": "Repository is hosted on GitHub.", + "ado": "Repository is hosted on Azure DevOps." + } }, "WorkspaceFileChangedData": { "type": "object", @@ -10395,7 +10652,11 @@ "update" ], "description": "Whether the file was newly created or updated", - "title": "WorkspaceFileChangedOperation" + "title": "WorkspaceFileChangedOperation", + "x-enumDescriptions": { + "create": "The workspace file was created.", + "update": "The workspace file was updated." + } } }, "$schema": "http://json-schema.org/draft-07/schema#", diff --git a/src/github/copilot_sdk.clj b/src/github/copilot_sdk.clj index f62e193..ae64749 100644 --- a/src/github/copilot_sdk.clj +++ b/src/github/copilot_sdk.clj @@ -346,7 +346,11 @@ (defn ping "Ping the server to check connectivity. - Returns {:message :timestamp :protocol-version}" + Returns {:message :timestamp :protocol-version}. + + `:timestamp` is an ISO 8601 date-time string on CLI ≥ 1.0.51 + (upstream PR #1340). Earlier CLI versions returned a numeric + epoch-millis value." ([client] (client/ping client)) ([client message] diff --git a/src/github/copilot_sdk/client.clj b/src/github/copilot_sdk/client.clj index 970b09f..8619383 100644 --- a/src/github/copilot_sdk/client.clj +++ b/src/github/copilot_sdk/client.clj @@ -1112,7 +1112,11 @@ (defn ping "Ping the server to check connectivity. - Returns {:message :timestamp :protocol-version}." + Returns {:message :timestamp :protocol-version}. + + `:timestamp` is an ISO 8601 date-time string (e.g. \"2026-05-21T08:00:00Z\") + on CLI ≥ 1.0.51 (upstream PR #1340). Earlier CLI versions returned a + numeric epoch-millis value; the SDK forwards whatever the server sends." ([client] (ping client nil)) ([client message] diff --git a/src/github/copilot_sdk/generated/event_specs.clj b/src/github/copilot_sdk/generated/event_specs.clj index 7a283be..28d01bc 100644 --- a/src/github/copilot_sdk/generated/event_specs.clj +++ b/src/github/copilot_sdk/generated/event_specs.clj @@ -51,13 +51,13 @@ (s/def :github.copilot-sdk.generated.event-specs/branch clojure.core/string?) -(s/def :github.copilot-sdk.generated.event-specs/cache-read-tokens clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/cache-read-tokens clojure.core/integer?) -(s/def :github.copilot-sdk.generated.event-specs/cache-write-tokens clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/cache-write-tokens clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/cause clojure.core/string?) -(s/def :github.copilot-sdk.generated.event-specs/checkpoint-number clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/checkpoint-number clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/checkpoint-path clojure.core/string?) @@ -73,13 +73,13 @@ (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 [v943] (or (s/valid? clojure.core/string? v943) (s/valid? clojure.core/map? v943))))) +(s/def :github.copilot-sdk.generated.event-specs/content (s/spec (fn [v942] (or (s/valid? clojure.core/string? v942) (s/valid? clojure.core/map? v942))))) -(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/context (s/spec (fn [v940] (or (s/valid? clojure.core/map? v940) (s/valid? clojure.core/string? v940))))) (s/def :github.copilot-sdk.generated.event-specs/continue-pending-work clojure.core/boolean?) -(s/def :github.copilot-sdk.generated.event-specs/conversation-tokens clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/conversation-tokens clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/copilot-usage clojure.core/map?) @@ -89,7 +89,7 @@ (s/def :github.copilot-sdk.generated.event-specs/current-model clojure.core/string?) -(s/def :github.copilot-sdk.generated.event-specs/current-tokens clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/current-tokens clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/cwd clojure.core/string?) @@ -103,9 +103,9 @@ (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 clojure.core/integer?) -(s/def :github.copilot-sdk.generated.event-specs/duration-ms clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/duration-ms clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/elicitation-source clojure.core/string?) @@ -115,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 [v938] (or (s/valid? clojure.core/string? v938) (s/valid? clojure.core/map? v938))))) +(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-code clojure.core/string?) @@ -127,9 +127,9 @@ (s/def :github.copilot-sdk.generated.event-specs/errors (s/coll-of clojure.core/string?)) -(s/def :github.copilot-sdk.generated.event-specs/event-count clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/event-count clojure.core/integer?) -(s/def :github.copilot-sdk.generated.event-specs/events-removed clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/events-removed clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/extensions (s/coll-of clojure.core/map?)) @@ -149,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 [v939] (or (s/valid? clojure.core/string? v939) (s/valid? clojure.core/integer? v939))))) +(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/info-type clojure.core/string?) @@ -157,7 +157,7 @@ (s/def :github.copilot-sdk.generated.event-specs/input clojure.core/any?) -(s/def :github.copilot-sdk.generated.event-specs/input-tokens clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/input-tokens clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/intent clojure.core/string?) @@ -185,11 +185,11 @@ (s/def :github.copilot-sdk.generated.event-specs/message-id clojure.core/string?) -(s/def :github.copilot-sdk.generated.event-specs/messages-length clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/messages-length clojure.core/integer?) -(s/def :github.copilot-sdk.generated.event-specs/messages-removed clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/messages-removed clojure.core/integer?) -(s/def :github.copilot-sdk.generated.event-specs/messages-removed-during-truncation clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/messages-removed-during-truncation clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/metadata clojure.core/map?) @@ -207,11 +207,11 @@ (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 [v942] (or (s/valid? #{"delete" "update" "create"} v942) (s/valid? #{"update" "create"} v942))))) +(s/def :github.copilot-sdk.generated.event-specs/operation (s/spec (fn [v941] (or (s/valid? #{"delete" "update" "create"} v941) (s/valid? #{"update" "create"} v941))))) (s/def :github.copilot-sdk.generated.event-specs/output clojure.core/any?) -(s/def :github.copilot-sdk.generated.event-specs/output-tokens clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/output-tokens clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/parent-agent-task-id clojure.core/string?) @@ -237,19 +237,19 @@ (s/def :github.copilot-sdk.generated.event-specs/plugin-version clojure.core/string?) -(s/def :github.copilot-sdk.generated.event-specs/post-compaction-tokens clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/post-compaction-tokens clojure.core/integer?) -(s/def :github.copilot-sdk.generated.event-specs/post-truncation-messages-length clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/post-truncation-messages-length clojure.core/integer?) -(s/def :github.copilot-sdk.generated.event-specs/post-truncation-tokens-in-messages clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/post-truncation-tokens-in-messages clojure.core/integer?) -(s/def :github.copilot-sdk.generated.event-specs/pre-compaction-messages-length clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/pre-compaction-messages-length clojure.core/integer?) -(s/def :github.copilot-sdk.generated.event-specs/pre-compaction-tokens clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/pre-compaction-tokens clojure.core/integer?) -(s/def :github.copilot-sdk.generated.event-specs/pre-truncation-messages-length clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/pre-truncation-messages-length clojure.core/integer?) -(s/def :github.copilot-sdk.generated.event-specs/pre-truncation-tokens-in-messages clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/pre-truncation-tokens-in-messages clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/previous-mode #{"interactive" "autopilot" "plan"}) @@ -275,7 +275,7 @@ (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 (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-effort (s/spec (fn [v939] (or (s/valid? clojure.core/string? v939) (s/valid? clojure.core/any? v939))))) (s/def :github.copilot-sdk.generated.event-specs/reasoning-id clojure.core/string?) @@ -285,7 +285,7 @@ (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?) +(s/def :github.copilot-sdk.generated.event-specs/reasoning-tokens clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/recommended-action #{"interactive" "autopilot_fleet" "exit_only" "autopilot"}) @@ -295,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 [v937] (or (s/valid? clojure.core/map? v937) (s/valid? clojure.core/string? v937))))) +(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-host clojure.core/string?) @@ -307,11 +307,11 @@ (s/def :github.copilot-sdk.generated.event-specs/response #{"yes_always" "yes" "no"}) -(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/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/resume-time clojure.core/string?) -(s/def :github.copilot-sdk.generated.event-specs/retry-after-seconds clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/retry-after-seconds clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/role #{"developer" "system"}) @@ -327,7 +327,7 @@ (s/def :github.copilot-sdk.generated.event-specs/session-id clojure.core/string?) -(s/def :github.copilot-sdk.generated.event-specs/session-start-time clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/session-start-time clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/session-was-active clojure.core/boolean?) @@ -335,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 [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 (s/spec (fn [v943] (or (s/valid? clojure.core/string? v943) (s/valid? #{"top_level" "subagent" "mcp_sampling"} v943))))) (s/def :github.copilot-sdk.generated.event-specs/source-type #{"remote" "local"}) @@ -359,7 +359,9 @@ (s/def :github.copilot-sdk.generated.event-specs/supported-native-document-mime-types (s/coll-of clojure.core/string?)) -(s/def :github.copilot-sdk.generated.event-specs/system-tokens clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/system-tokens clojure.core/integer?) + +(s/def :github.copilot-sdk.generated.event-specs/time-to-first-token-ms clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/timestamp clojure.core/string?) @@ -369,15 +371,15 @@ (s/def :github.copilot-sdk.generated.event-specs/token-details clojure.core/map?) -(s/def :github.copilot-sdk.generated.event-specs/token-limit clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/token-limit clojure.core/integer?) -(s/def :github.copilot-sdk.generated.event-specs/tokens-removed clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/tokens-removed clojure.core/integer?) -(s/def :github.copilot-sdk.generated.event-specs/tokens-removed-during-truncation clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/tokens-removed-during-truncation clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/tool-call-id clojure.core/string?) -(s/def :github.copilot-sdk.generated.event-specs/tool-definitions-tokens clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/tool-definitions-tokens clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/tool-name clojure.core/string?) @@ -387,17 +389,17 @@ (s/def :github.copilot-sdk.generated.event-specs/tools (s/nilable (s/coll-of clojure.core/string?))) -(s/def :github.copilot-sdk.generated.event-specs/total-api-duration-ms clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/total-api-duration-ms clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/total-nano-aiu clojure.core/number?) (s/def :github.copilot-sdk.generated.event-specs/total-premium-requests clojure.core/number?) -(s/def :github.copilot-sdk.generated.event-specs/total-response-size-bytes clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/total-response-size-bytes clojure.core/integer?) -(s/def :github.copilot-sdk.generated.event-specs/total-tokens clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/total-tokens clojure.core/integer?) -(s/def :github.copilot-sdk.generated.event-specs/total-tool-calls clojure.core/number?) +(s/def :github.copilot-sdk.generated.event-specs/total-tool-calls clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/traceparent clojure.core/string?) @@ -405,11 +407,9 @@ (s/def :github.copilot-sdk.generated.event-specs/transformed-content clojure.core/string?) -(s/def :github.copilot-sdk.generated.event-specs/ttft-ms clojure.core/number?) - (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 [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/type (s/spec (fn [v944] (or (s/valid? #{"session.start"} v944) (s/valid? #{"session.resume"} v944) (s/valid? #{"session.remote_steerable_changed"} v944) (s/valid? #{"session.error"} v944) (s/valid? #{"session.idle"} v944) (s/valid? #{"session.title_changed"} v944) (s/valid? #{"session.schedule_created"} v944) (s/valid? #{"session.schedule_cancelled"} v944) (s/valid? #{"session.info"} v944) (s/valid? #{"session.warning"} v944) (s/valid? #{"session.model_change"} v944) (s/valid? #{"session.mode_changed"} v944) (s/valid? #{"session.plan_changed"} v944) (s/valid? #{"session.workspace_file_changed"} v944) (s/valid? #{"session.handoff"} v944) (s/valid? #{"session.truncation"} v944) (s/valid? #{"session.snapshot_rewind"} v944) (s/valid? #{"session.shutdown"} v944) (s/valid? #{"session.context_changed"} v944) (s/valid? #{"session.usage_info"} v944) (s/valid? #{"session.compaction_start"} v944) (s/valid? #{"session.compaction_complete"} v944) (s/valid? #{"session.task_complete"} v944) (s/valid? #{"user.message"} v944) (s/valid? #{"pending_messages.modified"} v944) (s/valid? #{"assistant.turn_start"} v944) (s/valid? #{"assistant.intent"} v944) (s/valid? #{"assistant.reasoning"} v944) (s/valid? #{"assistant.reasoning_delta"} v944) (s/valid? #{"assistant.streaming_delta"} v944) (s/valid? #{"assistant.message"} v944) (s/valid? #{"assistant.message_start"} v944) (s/valid? #{"assistant.message_delta"} v944) (s/valid? #{"assistant.turn_end"} v944) (s/valid? #{"assistant.usage"} v944) (s/valid? #{"model.call_failure"} v944) (s/valid? #{"abort"} v944) (s/valid? #{"tool.user_requested"} v944) (s/valid? #{"tool.execution_start"} v944) (s/valid? #{"tool.execution_partial_result"} v944) (s/valid? #{"tool.execution_progress"} v944) (s/valid? #{"tool.execution_complete"} v944) (s/valid? #{"skill.invoked"} v944) (s/valid? #{"subagent.started"} v944) (s/valid? #{"subagent.completed"} v944) (s/valid? #{"subagent.failed"} v944) (s/valid? #{"subagent.selected"} v944) (s/valid? #{"subagent.deselected"} v944) (s/valid? #{"hook.start"} v944) (s/valid? #{"hook.end"} v944) (s/valid? #{"system.message"} v944) (s/valid? #{"system.notification"} v944) (s/valid? #{"permission.requested"} v944) (s/valid? #{"permission.completed"} v944) (s/valid? #{"user_input.requested"} v944) (s/valid? #{"user_input.completed"} v944) (s/valid? #{"elicitation.requested"} v944) (s/valid? #{"elicitation.completed"} v944) (s/valid? #{"sampling.requested"} v944) (s/valid? #{"sampling.completed"} v944) (s/valid? #{"mcp.oauth_required"} v944) (s/valid? #{"mcp.oauth_completed"} v944) (s/valid? #{"session.custom_notification"} v944) (s/valid? #{"external_tool.requested"} v944) (s/valid? #{"external_tool.completed"} v944) (s/valid? #{"command.queued"} v944) (s/valid? #{"command.execute"} v944) (s/valid? #{"command.completed"} v944) (s/valid? #{"auto_mode_switch.requested"} v944) (s/valid? #{"auto_mode_switch.completed"} v944) (s/valid? #{"commands.changed"} v944) (s/valid? #{"capabilities.changed"} v944) (s/valid? #{"exit_plan_mode.requested"} v944) (s/valid? #{"exit_plan_mode.completed"} v944) (s/valid? #{"session.tools_updated"} v944) (s/valid? #{"session.background_tasks_changed"} v944) (s/valid? #{"session.skills_loaded"} v944) (s/valid? #{"session.custom_agents_updated"} v944) (s/valid? #{"session.mcp_servers_loaded"} v944) (s/valid? #{"session.mcp_server_status_changed"} v944) (s/valid? #{"session.extensions_loaded"} v944))))) (s/def :github.copilot-sdk.generated.event-specs/ui clojure.core/map?) @@ -417,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 [v946] (or (s/valid? clojure.core/number? v946) (s/valid? clojure.core/integer? v946))))) +(s/def :github.copilot-sdk.generated.event-specs/version clojure.core/integer?) (s/def :github.copilot-sdk.generated.event-specs/warning-type clojure.core/string?) @@ -445,7 +445,7 @@ (s/def :github.copilot-sdk.generated.event-specs/assistant.turn_start-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/turn-id] :opt-un [:github.copilot-sdk.generated.event-specs/interaction-id])) -(s/def :github.copilot-sdk.generated.event-specs/assistant.usage-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/model] :opt-un [:github.copilot-sdk.generated.event-specs/api-call-id :github.copilot-sdk.generated.event-specs/api-endpoint :github.copilot-sdk.generated.event-specs/cache-read-tokens :github.copilot-sdk.generated.event-specs/cache-write-tokens :github.copilot-sdk.generated.event-specs/copilot-usage :github.copilot-sdk.generated.event-specs/cost :github.copilot-sdk.generated.event-specs/duration :github.copilot-sdk.generated.event-specs/initiator :github.copilot-sdk.generated.event-specs/input-tokens :github.copilot-sdk.generated.event-specs/inter-token-latency-ms :github.copilot-sdk.generated.event-specs/output-tokens :github.copilot-sdk.generated.event-specs/parent-tool-call-id :github.copilot-sdk.generated.event-specs/provider-call-id :github.copilot-sdk.generated.event-specs/quota-snapshots :github.copilot-sdk.generated.event-specs/reasoning-effort :github.copilot-sdk.generated.event-specs/reasoning-tokens :github.copilot-sdk.generated.event-specs/ttft-ms])) +(s/def :github.copilot-sdk.generated.event-specs/assistant.usage-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/model] :opt-un [:github.copilot-sdk.generated.event-specs/api-call-id :github.copilot-sdk.generated.event-specs/api-endpoint :github.copilot-sdk.generated.event-specs/cache-read-tokens :github.copilot-sdk.generated.event-specs/cache-write-tokens :github.copilot-sdk.generated.event-specs/copilot-usage :github.copilot-sdk.generated.event-specs/cost :github.copilot-sdk.generated.event-specs/duration :github.copilot-sdk.generated.event-specs/initiator :github.copilot-sdk.generated.event-specs/input-tokens :github.copilot-sdk.generated.event-specs/inter-token-latency-ms :github.copilot-sdk.generated.event-specs/output-tokens :github.copilot-sdk.generated.event-specs/parent-tool-call-id :github.copilot-sdk.generated.event-specs/provider-call-id :github.copilot-sdk.generated.event-specs/quota-snapshots :github.copilot-sdk.generated.event-specs/reasoning-effort :github.copilot-sdk.generated.event-specs/reasoning-tokens :github.copilot-sdk.generated.event-specs/time-to-first-token-ms])) (s/def :github.copilot-sdk.generated.event-specs/auto_mode_switch.completed-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/request-id :github.copilot-sdk.generated.event-specs/response])) diff --git a/src/github/copilot_sdk/specs.clj b/src/github/copilot_sdk/specs.clj index 085597b..f0671fb 100644 --- a/src/github/copilot_sdk/specs.clj +++ b/src/github/copilot_sdk/specs.clj @@ -23,7 +23,12 @@ (set/difference (set (keys m)) allowed-keys)) (s/def ::non-blank-string (s/and string? (complement clojure.string/blank?))) -(s/def ::timestamp string?) +;; ::timestamp accepts both ISO 8601 strings (CLI ≥ 1.0.51, upstream PR #1340) +;; and numeric epoch-millis (older CLIs). Used by event timestamps and ping +;; results; the SDK forwards the server value verbatim. Consumers needing a +;; java.time.Instant should branch on the form: parse the string with +;; Instant/parse, or convert the number with Instant/ofEpochMilli. +(s/def ::timestamp (s/or :iso-string string? :epoch-ms nat-int?)) (s/def ::session-id ::non-blank-string) (s/def ::workspace-path (s/nilable ::non-blank-string)) (s/def ::instant #(instance? java.time.Instant %)) @@ -293,8 +298,8 @@ (s/def ::mcp-headers (s/map-of string? string?)) (s/def ::mcp-local-server - (s/keys :req-un [::mcp-command ::mcp-args ::mcp-tools] - :opt-un [::mcp-server-type ::mcp-timeout ::env ::cwd])) + (s/keys :req-un [::mcp-command ::mcp-tools] + :opt-un [::mcp-args ::mcp-server-type ::mcp-timeout ::env ::cwd])) (s/def ::mcp-remote-server (s/keys :req-un [::mcp-server-type ::mcp-url ::mcp-tools] @@ -1036,6 +1041,10 @@ (s/def ::input-tokens nat-int?) (s/def ::inter-token-latency-ms nat-int?) (s/def ::quota-snapshots map?) +;; :time-to-first-token-ms — schema renamed from :ttft-ms in CLI 1.0.51 wire schema +;; (property "ttftMs" → "timeToFirstTokenMs"). Both keys remain listed as :opt-un so +;; events from older CLI versions still validate; the new wire field is preferred. +(s/def ::time-to-first-token-ms nat-int?) (s/def ::ttft-ms nat-int?) (s/def ::copilot-usage map?) @@ -1054,7 +1063,7 @@ ::initiator ::input-tokens ::inter-token-latency-ms ::output-tokens ::parent-tool-call-id ::provider-call-id ::quota-snapshots ::reasoning-effort ::reasoning-tokens - ::ttft-ms])) + ::time-to-first-token-ms ::ttft-ms])) (s/def ::mcp-server-name string?) (s/def ::mcp-tool-name string?) diff --git a/test/github/copilot_sdk/e2e_test.clj b/test/github/copilot_sdk/e2e_test.clj index 6a6f6aa..f6a1105 100644 --- a/test/github/copilot_sdk/e2e_test.clj +++ b/test/github/copilot_sdk/e2e_test.clj @@ -68,7 +68,10 @@ (is (= :connected (sdk/state *e2e-client*))) (let [result (sdk/ping *e2e-client*)] (is (number? (:protocol-version result))) - (is (number? (:timestamp result))))))) + ;; Upstream PR #1340 / CLI 1.0.51 changed timestamp to ISO 8601 string. + (is (string? (:timestamp result))) + (is (some? (java.time.Instant/parse (:timestamp result))) + ":timestamp parses as ISO 8601 instant on real CLI ≥ 1.0.51"))))) (deftest ^:e2e test-e2e-create-session (when-e2e diff --git a/test/github/copilot_sdk/integration_test.clj b/test/github/copilot_sdk/integration_test.clj index 940f54b..f33fba2 100644 --- a/test/github/copilot_sdk/integration_test.clj +++ b/test/github/copilot_sdk/integration_test.clj @@ -161,7 +161,21 @@ (testing "Ping returns protocol version" (let [result (sdk/ping *test-client*)] (is (= 2 (:protocol-version result))) - (is (number? (:timestamp result)))))) + ;; Upstream PR #1340 / CLI 1.0.51 changed timestamp from epoch number + ;; to ISO 8601 string (`timestamp: string, format: date-time`). + (is (string? (:timestamp result))) + (is (some? (java.time.Instant/parse (:timestamp result))) + ":timestamp parses as ISO 8601 instant"))) + (testing "::specs/timestamp accepts both ISO string (CLI ≥ 1.0.51) and epoch-millis number (older CLIs)" + (is (s/valid? :github.copilot-sdk.specs/timestamp "2026-05-21T08:00:00.000Z")) + (is (s/valid? :github.copilot-sdk.specs/timestamp (System/currentTimeMillis)) + "System/currentTimeMillis-sized long validates as epoch-ms") + (is (s/valid? :github.copilot-sdk.specs/timestamp 1700000000000) + "representative epoch-ms long validates") + (is (not (s/valid? :github.copilot-sdk.specs/timestamp -1)) + "epoch-ms must be non-negative") + (is (not (s/valid? :github.copilot-sdk.specs/timestamp 1.5)) + "epoch-ms must be an integer, not arbitrary number"))) (deftest test-get-status (testing "Get CLI status returns version and protocol" @@ -3704,7 +3718,14 @@ {:mcp-command "node" :mcp-args ["server.js"] :mcp-tools ["read"]})) (is (s/valid? :github.copilot-sdk.specs/mcp-stdio-server {:mcp-command "node" :mcp-args ["server.js"] :mcp-tools ["read"] - :mcp-server-type :stdio})))) + :mcp-server-type :stdio})) + (testing "upstream PR #1347: :mcp-args is optional" + (is (s/valid? :github.copilot-sdk.specs/mcp-stdio-server + {:mcp-command "true" :mcp-tools ["read"]}) + ":mcp-args may be omitted (upstream PR #1347)") + (is (s/valid? :github.copilot-sdk.specs/mcp-stdio-server + {:mcp-command "node" :mcp-tools ["read"] :mcp-server-type :stdio}) + ":mcp-args optional with explicit :stdio type")))) (deftest test-mcp-http-server-spec (testing "::mcp-http-server spec validates remote/http configs" @@ -4059,6 +4080,25 @@ {:model "gpt-5" :api-endpoint 42})) ":api-endpoint must be a string if present"))) +;; --- assistant.usage :time-to-first-token-ms (upstream CLI 1.0.51 schema) -- + +(deftest test-assistant-usage-time-to-first-token-ms + (testing "assistant.usage-data accepts :time-to-first-token-ms (renamed from :ttft-ms)" + (is (s/valid? :github.copilot-sdk.specs/assistant.usage-data + {:model "gpt-5" :time-to-first-token-ms 250})) + (is (not (s/valid? :github.copilot-sdk.specs/assistant.usage-data + {:model "gpt-5" :time-to-first-token-ms -1})) + ":time-to-first-token-ms must be a non-negative integer") + (is (not (s/valid? :github.copilot-sdk.specs/assistant.usage-data + {:model "gpt-5" :time-to-first-token-ms "fast"})) + ":time-to-first-token-ms must be an integer") + (testing "legacy :ttft-ms key still accepted for backward compatibility (older CLIs)" + (is (s/valid? :github.copilot-sdk.specs/assistant.usage-data + {:model "gpt-5" :ttft-ms 250})) + (is (s/valid? :github.copilot-sdk.specs/assistant.usage-data + {:model "gpt-5" :ttft-ms 250 :time-to-first-token-ms 250}) + "both keys may coexist during CLI version transition")))) + ;; --- Memory permission event data specs (CLI 1.0.22) ----------------------- (deftest test-memory-permission-event-specs diff --git a/test/github/copilot_sdk/mock_server.clj b/test/github/copilot_sdk/mock_server.clj index 9775b33..5748689 100644 --- a/test/github/copilot_sdk/mock_server.clj +++ b/test/github/copilot_sdk/mock_server.clj @@ -95,7 +95,7 @@ (defn- handle-ping [server params] {:message (:message params) - :timestamp (System/currentTimeMillis) + :timestamp (.toString (java.time.Instant/now)) :protocolVersion PROTOCOL_VERSION}) (defn- handle-connect