{ "$schema": "https://json-schema.org/draft/2019-09/schema", "title": "CopilotApi", "description": "Describes all JSON-RPC methods exposed by the Copilot CLI server. SDK codegen tools consume this to produce typed client wrappers.", "server": { "ping": { "rpcMethod": "ping", "description": "Checks server responsiveness and returns protocol information.", "params": { "$ref": "#/definitions/PingRequest", "description": "Optional message to echo back to the caller." }, "result": { "$ref": "#/definitions/PingResult", "description": "Server liveness response, including the echoed message, current server timestamp, and protocol version." } }, "connect": { "rpcMethod": "connect", "description": "Performs the SDK server connection handshake and validates the optional connection token. Marked internal because this is JSON-RPC transport plumbing invoked automatically by an SDK client's own `connect()` wrapper, not a user-facing method. Stays internal as long as the SDK client owns the handshake; would only become public if the SDK ever exposed the raw schema surface to consumers without a connection wrapper.", "params": { "$ref": "#/definitions/ConnectRequest", "description": "Optional connection token presented by the SDK client during the handshake.", "visibility": "internal" }, "result": { "$ref": "#/definitions/ConnectResult", "description": "Handshake result reporting the server's protocol version and package version on success.", "visibility": "internal" }, "visibility": "internal" }, "models": { "list": { "rpcMethod": "models.list", "description": "Lists Copilot models available to the authenticated user.", "params": { "$ref": "#/definitions/ModelsListRequest", "description": "Optional GitHub token used to list models for a specific user instead of the global auth context." }, "result": { "$ref": "#/definitions/ModelList", "description": "List of Copilot models available to the resolved user, including capabilities and billing metadata." } } }, "tools": { "list": { "rpcMethod": "tools.list", "description": "Lists built-in tools available for a model.", "params": { "$ref": "#/definitions/ToolsListRequest", "description": "Optional model identifier whose tool overrides should be applied to the listing." }, "result": { "$ref": "#/definitions/ToolList", "description": "Built-in tools available for the requested model, with their parameters and instructions." } } }, "account": { "getQuota": { "rpcMethod": "account.getQuota", "description": "Gets Copilot quota usage for the authenticated user or supplied GitHub token.", "params": { "$ref": "#/definitions/AccountGetQuotaRequest", "description": "Optional GitHub token used to look up quota for a specific user instead of the global auth context." }, "result": { "$ref": "#/definitions/AccountGetQuotaResult", "description": "Quota usage snapshots for the resolved user, keyed by quota type." } } }, "secrets": { "addFilterValues": { "rpcMethod": "secrets.addFilterValues", "description": "Registers secret values for redaction in session logs and exports. The SDK calls this to inject dynamically generated secret values (e.g., OIDC tokens).", "params": { "$ref": "#/definitions/SecretsAddFilterValuesRequest", "description": "Secret values to add to the redaction filter." }, "result": { "$ref": "#/definitions/SecretsAddFilterValuesResult", "description": "Confirmation that the secret values were registered." } } }, "mcp": { "config": { "list": { "rpcMethod": "mcp.config.list", "description": "Lists MCP servers from user configuration.", "params": null, "result": { "$ref": "#/definitions/McpConfigList", "description": "User-configured MCP servers, keyed by server name." } }, "add": { "rpcMethod": "mcp.config.add", "description": "Adds an MCP server to user configuration.", "params": { "$ref": "#/definitions/McpConfigAddRequest", "description": "MCP server name and configuration to add to user configuration." }, "result": { "type": "null" } }, "update": { "rpcMethod": "mcp.config.update", "description": "Updates an MCP server in user configuration.", "params": { "$ref": "#/definitions/McpConfigUpdateRequest", "description": "MCP server name and replacement configuration to write to user configuration." }, "result": { "type": "null" } }, "remove": { "rpcMethod": "mcp.config.remove", "description": "Removes an MCP server from user configuration.", "params": { "$ref": "#/definitions/McpConfigRemoveRequest", "description": "MCP server name to remove from user configuration." }, "result": { "type": "null" } }, "enable": { "rpcMethod": "mcp.config.enable", "description": "Enables MCP servers in user configuration for new sessions.", "params": { "$ref": "#/definitions/McpConfigEnableRequest", "description": "MCP server names to enable for new sessions." }, "result": { "type": "null" } }, "disable": { "rpcMethod": "mcp.config.disable", "description": "Disables MCP servers in user configuration for new sessions.", "params": { "$ref": "#/definitions/McpConfigDisableRequest", "description": "MCP server names to disable for new sessions." }, "result": { "type": "null" } }, "reload": { "rpcMethod": "mcp.config.reload", "description": "Drops this runtime process's in-memory MCP server-definition cache so the next MCP config read observes disk.", "params": null, "result": { "type": "null" } } }, "discover": { "rpcMethod": "mcp.discover", "description": "Discovers MCP servers from user, workspace, plugin, and builtin sources.", "params": { "$ref": "#/definitions/McpDiscoverRequest", "description": "Optional working directory used as context for MCP server discovery." }, "result": { "$ref": "#/definitions/McpDiscoverResult", "description": "MCP servers discovered from user, workspace, plugin, and built-in sources." } } }, "plugins": { "list": { "rpcMethod": "plugins.list", "description": "Lists plugins installed in user/global state.", "params": null, "result": { "$ref": "#/definitions/PluginListResult", "description": "Plugins installed in user/global state." }, "stability": "experimental" }, "install": { "rpcMethod": "plugins.install", "description": "Installs a plugin from a marketplace, GitHub repo, URL, or local path.", "params": { "$ref": "#/definitions/PluginsInstallRequest", "description": "Plugin source and optional working directory for relative-path resolution." }, "result": { "$ref": "#/definitions/PluginInstallResult", "description": "Result of installing a plugin." }, "stability": "experimental" }, "uninstall": { "rpcMethod": "plugins.uninstall", "description": "Uninstalls an installed plugin.", "params": { "$ref": "#/definitions/PluginsUninstallRequest", "description": "Name (or spec) of the plugin to uninstall." }, "result": { "type": "null" }, "stability": "experimental" }, "update": { "rpcMethod": "plugins.update", "description": "Updates an installed plugin to its latest published version.", "params": { "$ref": "#/definitions/PluginsUpdateRequest", "description": "Name (or spec) of the plugin to update." }, "result": { "$ref": "#/definitions/PluginUpdateResult", "description": "Result of updating a single plugin." }, "stability": "experimental" }, "updateAll": { "rpcMethod": "plugins.updateAll", "description": "Updates every installed plugin to its latest published version.", "params": null, "result": { "$ref": "#/definitions/PluginUpdateAllResult", "description": "Result of updating all installed plugins." }, "stability": "experimental" }, "enable": { "rpcMethod": "plugins.enable", "description": "Enables installed plugins for new sessions.", "params": { "$ref": "#/definitions/PluginsEnableRequest", "description": "Plugin names (or specs) to enable." }, "result": { "type": "null" }, "stability": "experimental" }, "disable": { "rpcMethod": "plugins.disable", "description": "Disables installed plugins for new sessions.", "params": { "$ref": "#/definitions/PluginsDisableRequest", "description": "Plugin names (or specs) to disable." }, "result": { "type": "null" }, "stability": "experimental" }, "marketplaces": { "list": { "rpcMethod": "plugins.marketplaces.list", "description": "Lists all registered marketplaces (defaults + user-added).", "params": null, "result": { "$ref": "#/definitions/MarketplaceListResult", "description": "All registered marketplaces, including built-in defaults." }, "stability": "experimental" }, "add": { "rpcMethod": "plugins.marketplaces.add", "description": "Registers a new marketplace from a source (owner/repo, URL, or local path).", "params": { "$ref": "#/definitions/PluginsMarketplacesAddRequest", "description": "Marketplace source to register." }, "result": { "$ref": "#/definitions/MarketplaceAddResult", "description": "Result of registering a new marketplace." }, "stability": "experimental" }, "remove": { "rpcMethod": "plugins.marketplaces.remove", "description": "Removes a previously-registered marketplace. When the marketplace has dependent plugins and `force` is not set, the marketplace is left intact and the result lists the dependents so the caller can decide whether to retry with `force=true`.", "params": { "$ref": "#/definitions/PluginsMarketplacesRemoveRequest", "description": "Name of the marketplace to remove and an optional force flag." }, "result": { "$ref": "#/definitions/MarketplaceRemoveResult", "description": "Outcome of the remove attempt, including dependent-plugin info when applicable." }, "stability": "experimental" }, "browse": { "rpcMethod": "plugins.marketplaces.browse", "description": "Lists plugins advertised by a registered marketplace.", "params": { "$ref": "#/definitions/PluginsMarketplacesBrowseRequest", "description": "Name of the marketplace whose plugin catalog to fetch." }, "result": { "$ref": "#/definitions/MarketplaceBrowseResult", "description": "Plugins advertised by the marketplace." }, "stability": "experimental" }, "refresh": { "rpcMethod": "plugins.marketplaces.refresh", "description": "Re-fetches one or all registered marketplace catalogs.", "params": { "$ref": "#/definitions/PluginsMarketplacesRefreshRequest", "description": "Optional marketplace name; omit to refresh all." }, "result": { "$ref": "#/definitions/MarketplaceRefreshResult", "description": "Result of refreshing one or more marketplace catalogs." }, "stability": "experimental" } } }, "skills": { "config": { "setDisabledSkills": { "rpcMethod": "skills.config.setDisabledSkills", "description": "Replaces the global list of disabled skills.", "params": { "$ref": "#/definitions/SkillsConfigSetDisabledSkillsRequest", "description": "Skill names to mark as disabled in global configuration, replacing any previous list." }, "result": { "type": "null" } } }, "discover": { "rpcMethod": "skills.discover", "description": "Discovers skills across global and project sources.", "params": { "$ref": "#/definitions/SkillsDiscoverRequest", "description": "Optional project paths and additional skill directories to include in discovery." }, "result": { "$ref": "#/definitions/ServerSkillList", "description": "Skills discovered across global and project sources." } } }, "agents": { "discover": { "rpcMethod": "agents.discover", "description": "Discovers custom agents across user, project, plugin, and remote sources.", "params": { "$ref": "#/definitions/AgentsDiscoverRequest", "description": "Optional project paths to include in agent discovery." }, "result": { "$ref": "#/definitions/ServerAgentList", "description": "Agents discovered across user, project, plugin, and remote sources." }, "stability": "experimental" } }, "instructions": { "discover": { "rpcMethod": "instructions.discover", "description": "Discovers instruction sources across user, repository, and plugin sources.", "params": { "$ref": "#/definitions/InstructionsDiscoverRequest", "description": "Optional project paths to include in instruction discovery." }, "result": { "$ref": "#/definitions/ServerInstructionSourceList", "description": "Instruction sources discovered across user, repository, and plugin sources." }, "stability": "experimental" } }, "user": { "settings": { "reload": { "rpcMethod": "user.settings.reload", "description": "Drops this runtime process's in-memory user settings cache so the next settings read observes disk.", "params": null, "result": { "type": "null" } } } }, "runtime": { "shutdown": { "rpcMethod": "runtime.shutdown", "description": "Gracefully shuts down an SDK-owned runtime. The response is sent only after cleanup completes; callers may then terminate the owned runtime process.", "params": null, "result": { "type": "null" } } }, "sessionFs": { "setProvider": { "rpcMethod": "sessionFs.setProvider", "description": "Registers an SDK client as the session filesystem provider.", "params": { "$ref": "#/definitions/SessionFsSetProviderRequest", "description": "Initial working directory, session-state path layout, and path conventions used to register the calling SDK client as the session filesystem provider." }, "result": { "$ref": "#/definitions/SessionFsSetProviderResult", "description": "Indicates whether the calling client was registered as the session filesystem provider." } } }, "sessions": { "open": { "rpcMethod": "sessions.open", "description": "Creates or resumes a local session and returns the opened session ID.", "params": { "$ref": "#/definitions/SessionOpenParams", "description": "Open a session by creating, resuming, attaching, connecting to a remote, or handing off." }, "result": { "$ref": "#/definitions/SessionOpenResult", "description": "Result of opening a session." }, "stability": "experimental" }, "fork": { "rpcMethod": "sessions.fork", "description": "Creates a new session by forking persisted history from an existing session.", "params": { "$ref": "#/definitions/SessionsForkRequest", "description": "Source session identifier to fork from, optional event-ID boundary, and optional friendly name for the new session." }, "result": { "$ref": "#/definitions/SessionsForkResult", "description": "Identifier and optional friendly name assigned to the newly forked session." }, "stability": "experimental" }, "connect": { "rpcMethod": "sessions.connect", "description": "Connects to an existing remote session and exposes it as an SDK session.", "params": { "$ref": "#/definitions/ConnectRemoteSessionParams", "description": "Remote session connection parameters." }, "result": { "$ref": "#/definitions/RemoteSessionConnectionResult", "description": "Remote session connection result." }, "stability": "experimental" }, "list": { "rpcMethod": "sessions.list", "description": "Lists sessions, optionally filtered by source and working-directory context. Returned entries are discriminated by `isRemote`: local entries carry only the lightweight `LocalSessionMetadataValue` shape; remote entries carry the full `RemoteSessionMetadataValue` shape (repository, PR number, taskType, etc.).", "params": { "$ref": "#/definitions/SessionsListRequest", "description": "Optional source filter, metadata-load limit, and context filter applied to the returned sessions." }, "result": { "$ref": "#/definitions/SessionList", "description": "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. Internal: filesystem paths are only meaningful in-process (CLI and runtime share a filesystem). Currently used by the CLI's contribution-graph feature to read historical events directly. Remote SDK consumers must not depend on this; a proper event-query API would replace it if the contribution graph ever needed to work over the wire.", "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", "visibility": "internal" }, "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. Internal: this is CLI-specific book-keeping used by `--continue` / `--resume` to inherit the prior session's remote-steerable preference. SDK consumers that want similar behavior should manage their own persistence around start/stop calls rather than relying on this runtime-side flag.", "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", "visibility": "internal" }, "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 enriched metadata records, with summary and context fields backfilled where available. Sessions confirmed empty and unnamed are omitted." }, "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" }, "getBoardEntryCount": { "rpcMethod": "sessions.getBoardEntryCount", "description": "Gets the dynamic-context board entry count associated with a session, when available. Internal: this exists solely so CLI telemetry events (`rem_spawn_gate`, `rem_consolidation_complete`) can pair START / END board counts around the detached rem-agent spawn. \"Dynamic context board\" is a runtime-internal concept that is not part of the public SDK contract; the long-term plan is to relocate the telemetry emission into the runtime so this method can be deleted entirely.", "params": { "$ref": "#/definitions/SessionsGetBoardEntryCountRequest", "description": "Session ID whose board entry count should be returned." }, "result": { "$ref": "#/definitions/SessionsGetBoardEntryCountResult", "description": "Dynamic-context board entry count, when available." }, "stability": "experimental", "visibility": "internal" }, "startRemoteControl": { "rpcMethod": "sessions.startRemoteControl", "description": "Attaches the runtime-managed remote-control singleton to a session, awaiting initial setup. If remote control is already attached to a different session, the singleton is transferred (preserving the underlying Mission Control connection). Returns the final status.", "params": { "$ref": "#/definitions/SessionsStartRemoteControlRequest", "description": "Parameters for attaching the remote-control singleton to a session." }, "result": { "$ref": "#/definitions/RemoteControlStatusResult", "description": "Wrapper for the singleton's current status." }, "stability": "experimental" }, "transferRemoteControl": { "rpcMethod": "sessions.transferRemoteControl", "description": "Atomically rebinds the remote-control singleton to a different session, preserving the underlying Mission Control connection. When `expectedFromSessionId` is provided and does not match the singleton's current `attachedSessionId`, the transfer is rejected with `transferred: false` and the current status is returned unchanged.", "params": { "$ref": "#/definitions/SessionsTransferRemoteControlRequest", "description": "Parameters for atomically rebinding the remote-control singleton." }, "result": { "$ref": "#/definitions/RemoteControlTransferResult", "description": "Outcome of a transferRemoteControl call." }, "stability": "experimental" }, "setRemoteControlSteering": { "rpcMethod": "sessions.setRemoteControlSteering", "description": "Patches the steering state of the active remote-control singleton. When remote control is off, this is a no-op and the off status is returned. Today only `enabled: true` is actionable on the underlying exporter; passing `false` is reserved for future use.", "params": { "$ref": "#/definitions/SessionsSetRemoteControlSteeringRequest", "description": "Patch for the singleton's steering state." }, "result": { "$ref": "#/definitions/RemoteControlStatusResult", "description": "Wrapper for the singleton's current status." }, "stability": "experimental" }, "stopRemoteControl": { "rpcMethod": "sessions.stopRemoteControl", "description": "Stops the remote-control singleton. When `expectedSessionId` is provided and does not match the singleton's current `attachedSessionId`, the stop is rejected with `stopped: false` and the current status is returned unchanged (unless `force` is set, in which case the singleton is unconditionally torn down).", "params": { "$ref": "#/definitions/SessionsStopRemoteControlRequest", "description": "Parameters for stopping the remote-control singleton." }, "result": { "$ref": "#/definitions/RemoteControlStopResult", "description": "Outcome of a stopRemoteControl call." }, "stability": "experimental" }, "getRemoteControlStatus": { "rpcMethod": "sessions.getRemoteControlStatus", "description": "Returns the current state of the remote-control singleton, including the attached session id and frontend URL when active.", "params": null, "result": { "$ref": "#/definitions/RemoteControlStatusResult", "description": "Wrapper for the singleton's current status." }, "stability": "experimental" }, "pollSpawnedSessions": { "rpcMethod": "sessions.pollSpawnedSessions", "description": "Cursor-based long-poll for sessions spawned by the runtime (e.g. in response to a Mission Control `start_session` command). The cursor is an opaque token; pass it back to receive only spawn events that occurred AFTER the cursor was issued. Omit the cursor on the first call to receive any events buffered since the runtime started. Internal: this is a CLI background-daemon plumbing primitive. SDK consumers that need to react to runtime-spawned sessions should subscribe to a higher-level event stream rather than driving a long-poll loop.", "params": { "$ref": "#/definitions/SessionsPollSpawnedSessionsRequest", "description": "Cursor and optional long-poll wait for polling runtime-spawned sessions." }, "result": { "$ref": "#/definitions/PollSpawnedSessionsResult", "description": "Batch of spawn events plus a cursor for follow-up polls." }, "stability": "experimental", "visibility": "internal" }, "registerExtensionToolsOnSession": { "rpcMethod": "sessions.registerExtensionToolsOnSession", "description": "Registers extension-provided tools on the given session, gated by an optional `enabled` callback. Returns an opaque unsubscribe function the caller must invoke to deregister the tools when the extension is torn down. Marked internal because `loader`, `enabled`, and the returned `unsubscribe` are in-process handles that cannot cross the JSON-RPC boundary. Disappears once extension discovery / launch / tool registration are owned by the runtime: SDK consumers will pass pure config (search paths, disabled ids) via `SessionOptions` and the runtime will resolve, launch, register, and tear down extensions itself.", "params": { "$ref": "#/definitions/RegisterExtensionToolsParams", "description": "Params to attach an extension loader's tools to a session.", "visibility": "internal" }, "result": { "$ref": "#/definitions/RegisterExtensionToolsResult", "description": "Handle for releasing the extension tool registration.", "visibility": "internal" }, "stability": "experimental", "visibility": "internal" }, "configureSessionExtensions": { "rpcMethod": "sessions.configureSessionExtensions", "description": "Attaches (or detaches) an in-process ExtensionController delegate for the given session, used by shared-API surfaces that need to query or modify the session's extension state. Pass `controller: undefined` to detach. Marked internal because the controller is an in-process object that cannot cross the JSON-RPC boundary. Disappears alongside `registerExtensionToolsOnSession`: once the runtime owns extension management, the public surface exposes list/enable/disable/reload as dedicated RPCs served by the runtime.", "params": { "$ref": "#/definitions/ConfigureSessionExtensionsParams", "description": "Params to attach or detach an in-process ExtensionController delegate.", "visibility": "internal" }, "result": { "type": "null" }, "stability": "experimental", "visibility": "internal" } }, "agentRegistry": { "spawn": { "rpcMethod": "agentRegistry.spawn", "description": "Spawns a managed-server child with the supplied configuration and returns a discriminated-union result. The caller (typically the CLI controller) is responsible for attaching to the spawned child and sending any follow-up prompt. When the controller-local spawn gate is closed the server returns JSON-RPC MethodNotFound.", "params": { "$ref": "#/definitions/AgentRegistrySpawnRequest", "description": "Inputs to spawn a managed-server child via the controller's spawn delegate." }, "result": { "$ref": "#/definitions/AgentRegistrySpawnResult", "description": "Outcome of an agentRegistry.spawn call." }, "stability": "experimental" } } }, "session": { "suspend": { "rpcMethod": "session.suspend", "description": "Suspends the session while preserving persisted state for later resume.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "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/Attachment", "description": "A user message attachment — a file, directory, code selection, blob, GitHub reference, or extension-supplied context payload" }, "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": { "type": "string", "pattern": "^(system|command-.*|schedule-\\d+)$", "description": "Optional provenance tag copied to the resulting user.message event. Must match one of three forms: the literal `system`, `command-` for messages originating from a command (e.g. slash command, Mission Control command), or `schedule-` for messages originating from a scheduled job.", "visibility": "internal" }, "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": { "rpcMethod": "session.auth.getStatus", "description": "Gets authentication status and account metadata for the session.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "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" } }, "canvas": { "list": { "rpcMethod": "session.canvas.list", "description": "Lists canvases declared 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/CanvasList", "description": "Declared canvases available in this session." }, "stability": "experimental" }, "listOpen": { "rpcMethod": "session.canvas.listOpen", "description": "Lists currently open canvas instances for the live session.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/CanvasListOpenResult", "description": "Live open-canvas snapshot." }, "stability": "experimental" }, "open": { "rpcMethod": "session.canvas.open", "description": "Opens or focuses a canvas instance.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "extensionId": { "type": "string", "description": "Owning provider identifier. Optional when the canvasId is unique across providers; required to disambiguate when multiple providers register the same canvasId." }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier" }, "instanceId": { "type": "string", "description": "Caller-supplied stable instance identifier" }, "input": { "description": "Canvas open input", "x-opaque-json": true } }, "required": [ "sessionId", "canvasId", "instanceId" ], "additionalProperties": false, "description": "Canvas open parameters.", "title": "CanvasOpenRequest" }, "result": { "$ref": "#/definitions/OpenCanvasInstance", "description": "Open canvas instance snapshot." }, "stability": "experimental" }, "close": { "rpcMethod": "session.canvas.close", "description": "Closes an open canvas instance.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "instanceId": { "type": "string", "description": "Open canvas instance identifier" } }, "required": [ "sessionId", "instanceId" ], "additionalProperties": false, "description": "Canvas close parameters.", "title": "CanvasCloseRequest" }, "result": { "type": "null" }, "stability": "experimental" }, "action": { "invoke": { "rpcMethod": "session.canvas.action.invoke", "description": "Invokes an action on an open canvas instance.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "instanceId": { "type": "string", "description": "Open canvas instance identifier" }, "actionName": { "type": "string", "description": "Action name to invoke" }, "input": { "description": "Action input", "x-opaque-json": true } }, "required": [ "sessionId", "instanceId", "actionName" ], "additionalProperties": false, "description": "Canvas action invocation parameters.", "title": "CanvasActionInvokeRequest" }, "result": { "$ref": "#/definitions/CanvasActionInvokeResult", "description": "Canvas action invocation result." }, "stability": "experimental" } } }, "model": { "getCurrent": { "rpcMethod": "session.model.getCurrent", "description": "Gets the currently selected model for the session.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/CurrentModel", "description": "The currently selected model, reasoning effort, and context tier for the session. The context tier reflects `Session.getContextTier()`, restored from the session journal on resume." }, "stability": "experimental" }, "switchTo": { "rpcMethod": "session.model.switchTo", "description": "Switches the session to a model and optional reasoning configuration.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "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" }, "contextTier": { "$ref": "#/definitions/ContextTier", "description": "Explicit context tier for the selected model. `\"default\"` / `\"long_context\"` apply the requested tier; omit this field to use normal model behavior with no explicit tier." } }, "required": [ "sessionId", "modelId" ], "additionalProperties": false, "description": "Target model identifier and optional reasoning effort, summary, capability overrides, and context tier.", "title": "ModelSwitchToRequest" }, "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" }, "list": { "rpcMethod": "session.model.list", "description": "Lists models available to this session using its own auth and integration context. Connected hosts (CLI TUI, GitHub App) should call this through the session client so remote sessions return the remote CLI's available models rather than the caller's.", "params": { "anyOf": [ { "not": {} }, { "type": "object", "properties": { "skipCache": { "type": "boolean", "description": "If true, bypasses the per-session model list cache and re-fetches from CAPI." } }, "additionalProperties": false } ], "description": "Optional listing options.", "title": "ModelListRequest", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ] }, "result": { "$ref": "#/definitions/SessionModelList", "description": "The list of models available to this session." }, "stability": "experimental" } }, "mode": { "get": { "rpcMethod": "session.mode.get", "description": "Gets the current agent interaction mode.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/SessionMode", "description": "The session mode the agent is operating in" }, "stability": "experimental" }, "set": { "rpcMethod": "session.mode.set", "description": "Sets the current agent interaction mode.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "mode": { "$ref": "#/definitions/SessionMode", "description": "The session mode the agent is operating in" } }, "required": [ "sessionId", "mode" ], "additionalProperties": false, "description": "Agent interaction mode to apply to the session.", "title": "ModeSetRequest" }, "result": { "type": "null" }, "stability": "experimental" } }, "name": { "get": { "rpcMethod": "session.name.get", "description": "Gets the session's friendly name.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/NameGetResult", "description": "The session's friendly name, or null when not yet set." }, "stability": "experimental" }, "set": { "rpcMethod": "session.name.set", "description": "Sets the session's friendly name.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "New session name (1–100 characters, trimmed of leading/trailing whitespace)" } }, "required": [ "sessionId", "name" ], "additionalProperties": false, "description": "New friendly name to apply to the session.", "title": "NameSetRequest" }, "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": { "read": { "rpcMethod": "session.plan.read", "description": "Reads the session plan file from the workspace.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/PlanReadResult", "description": "Existence, contents, and resolved path of the session plan file." }, "stability": "experimental" }, "update": { "rpcMethod": "session.plan.update", "description": "Writes new content to the session plan file.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "content": { "type": "string", "description": "The new content for the plan file" } }, "required": [ "sessionId", "content" ], "additionalProperties": false, "description": "Replacement contents to write to the session plan file.", "title": "PlanUpdateRequest" }, "result": { "type": "null" }, "stability": "experimental" }, "delete": { "rpcMethod": "session.plan.delete", "description": "Deletes the session plan file from the workspace.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "type": "null" }, "stability": "experimental" }, "readSqlTodos": { "rpcMethod": "session.plan.readSqlTodos", "description": "Reads todo rows from the session SQL database for plan rendering.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/PlanReadSqlTodosResult", "description": "Todo rows read from the session SQL database. Empty when no session database is available." }, "stability": "experimental" }, "readSqlTodosWithDependencies": { "rpcMethod": "session.plan.readSqlTodosWithDependencies", "description": "Reads todo rows AND dependency edges from the session SQL database for structured progress UI. Same defensive behavior as readSqlTodos — returns empty arrays when the database, tables, or columns aren't available. Clients should call this on session start and after every `session.todos_changed` event to refresh structured-UI rendering.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/PlanReadSqlTodosWithDependenciesResult", "description": "Todo rows + dependency edges read from the session SQL database." }, "stability": "experimental" } }, "workspaces": { "getWorkspace": { "rpcMethod": "session.workspaces.getWorkspace", "description": "Gets current workspace metadata for the session.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/WorkspacesGetWorkspaceResult", "description": "Current workspace metadata for the session, including its absolute filesystem path when available." }, "stability": "experimental" }, "listFiles": { "rpcMethod": "session.workspaces.listFiles", "description": "Lists files stored in the session workspace files directory.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/WorkspacesListFilesResult", "description": "Relative paths of files stored in the session workspace files directory." }, "stability": "experimental" }, "readFile": { "rpcMethod": "session.workspaces.readFile", "description": "Reads a file from the session workspace files directory.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "path": { "type": "string", "description": "Relative path within the workspace files directory" } }, "required": [ "sessionId", "path" ], "additionalProperties": false, "description": "Relative path of the workspace file to read.", "title": "WorkspacesReadFileRequest" }, "result": { "$ref": "#/definitions/WorkspacesReadFileResult", "description": "Contents of the requested workspace file as a UTF-8 string." }, "stability": "experimental" }, "createFile": { "rpcMethod": "session.workspaces.createFile", "description": "Creates or overwrites a file in the session workspace files directory.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "path": { "type": "string", "description": "Relative path within the workspace files directory" }, "content": { "type": "string", "description": "File content to write as a UTF-8 string" } }, "required": [ "sessionId", "path", "content" ], "additionalProperties": false, "description": "Relative path and UTF-8 content for the workspace file to create or overwrite.", "title": "WorkspacesCreateFileRequest" }, "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" }, "diff": { "rpcMethod": "session.workspaces.diff", "description": "Computes a diff for the session workspace.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "mode": { "$ref": "#/definitions/WorkspaceDiffMode", "description": "Diff mode requested by the client." } }, "required": [ "sessionId", "mode" ], "additionalProperties": false, "description": "Parameters for computing a workspace diff.", "title": "WorkspacesDiffRequest" }, "result": { "$ref": "#/definitions/WorkspaceDiffResult", "description": "Workspace diff result for the requested mode." }, "stability": "experimental" } }, "instructions": { "getSources": { "rpcMethod": "session.instructions.getSources", "description": "Gets instruction sources loaded for the session.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/InstructionsGetSourcesResult", "description": "Instruction sources loaded for the session, in merge order." }, "stability": "experimental" } }, "fleet": { "start": { "rpcMethod": "session.fleet.start", "description": "Starts fleet mode by submitting the fleet orchestration prompt to the session.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "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", "required": [ "sessionId" ] }, "result": { "$ref": "#/definitions/FleetStartResult", "description": "Indicates whether fleet mode was successfully activated." }, "stability": "experimental" } }, "agent": { "list": { "rpcMethod": "session.agent.list", "description": "Lists custom agents available to the session.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/AgentList", "description": "Custom agents available to the session." }, "stability": "experimental" }, "getCurrent": { "rpcMethod": "session.agent.getCurrent", "description": "Gets the currently selected custom agent for the session.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/AgentGetCurrentResult", "description": "The currently selected custom agent, or null when using the default agent." }, "stability": "experimental" }, "select": { "rpcMethod": "session.agent.select", "description": "Selects a custom agent for subsequent turns in the session.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "name": { "type": "string", "description": "Name of the custom agent to select" } }, "required": [ "sessionId", "name" ], "additionalProperties": false, "description": "Name of the custom agent to select for subsequent turns.", "title": "AgentSelectRequest" }, "result": { "$ref": "#/definitions/AgentSelectResult", "description": "The newly selected custom agent." }, "stability": "experimental" }, "deselect": { "rpcMethod": "session.agent.deselect", "description": "Clears the selected custom agent and returns the session to the default agent.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "type": "null" }, "stability": "experimental" }, "reload": { "rpcMethod": "session.agent.reload", "description": "Reloads custom agent definitions and returns the refreshed list.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/AgentReloadResult", "description": "Custom agents available to the session after reloading definitions from disk." }, "stability": "experimental" } }, "tasks": { "startAgent": { "rpcMethod": "session.tasks.startAgent", "description": "Starts a background agent task in the session.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "agentType": { "type": "string", "description": "Type of agent to start (e.g., 'explore', 'task', 'general-purpose')" }, "prompt": { "type": "string", "description": "Task prompt for the agent" }, "name": { "type": "string", "description": "Short name for the agent, used to generate a human-readable ID" }, "description": { "type": "string", "description": "Short description of the task" }, "model": { "type": "string", "description": "Optional model override" } }, "required": [ "sessionId", "agentType", "prompt", "name" ], "additionalProperties": false, "description": "Agent type, prompt, name, and optional description and model override for the new task.", "title": "TasksStartAgentRequest" }, "result": { "$ref": "#/definitions/TasksStartAgentResult", "description": "Identifier assigned to the newly started background agent task." }, "stability": "experimental" }, "list": { "rpcMethod": "session.tasks.list", "description": "Lists background tasks tracked by the session.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/TaskList", "description": "Background tasks currently tracked by the session." }, "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.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "id": { "type": "string", "description": "Task identifier" } }, "required": [ "sessionId", "id" ], "additionalProperties": false, "description": "Identifier of the task to promote to background mode.", "title": "TasksPromoteToBackgroundRequest" }, "result": { "$ref": "#/definitions/TasksPromoteToBackgroundResult", "description": "Indicates whether the task was successfully promoted to background mode." }, "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.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "id": { "type": "string", "description": "Task identifier" } }, "required": [ "sessionId", "id" ], "additionalProperties": false, "description": "Identifier of the background task to cancel.", "title": "TasksCancelRequest" }, "result": { "$ref": "#/definitions/TasksCancelResult", "description": "Indicates whether the background task was successfully cancelled." }, "stability": "experimental" }, "remove": { "rpcMethod": "session.tasks.remove", "description": "Removes a completed or cancelled background task from tracking.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "id": { "type": "string", "description": "Task identifier" } }, "required": [ "sessionId", "id" ], "additionalProperties": false, "description": "Identifier of the completed or cancelled task to remove from tracking.", "title": "TasksRemoveRequest" }, "result": { "$ref": "#/definitions/TasksRemoveResult", "description": "Indicates whether the task was removed. False when the task does not exist or is still running/idle." }, "stability": "experimental" }, "sendMessage": { "rpcMethod": "session.tasks.sendMessage", "description": "Sends a message to a background agent task.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "id": { "type": "string", "description": "Agent task identifier" }, "message": { "type": "string", "description": "Message content to send to the agent" }, "fromAgentId": { "type": "string", "description": "Agent ID of the sender, if sent on behalf of another agent" } }, "required": [ "sessionId", "id", "message" ], "additionalProperties": false, "description": "Identifier of the target agent task, message content, and optional sender agent ID.", "title": "TasksSendMessageRequest" }, "result": { "$ref": "#/definitions/TasksSendMessageResult", "description": "Indicates whether the message was delivered, with an error message when delivery failed." }, "stability": "experimental" } }, "skills": { "list": { "rpcMethod": "session.skills.list", "description": "Lists skills available to the session.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/SkillList", "description": "Skills available to the session, with their enabled state." }, "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.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "name": { "type": "string", "description": "Name of the skill to enable" } }, "required": [ "sessionId", "name" ], "additionalProperties": false, "description": "Name of the skill to enable for the session.", "title": "SkillsEnableRequest" }, "result": { "type": "null" }, "stability": "experimental" }, "disable": { "rpcMethod": "session.skills.disable", "description": "Disables a skill for the session.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "name": { "type": "string", "description": "Name of the skill to disable" } }, "required": [ "sessionId", "name" ], "additionalProperties": false, "description": "Name of the skill to disable for the session.", "title": "SkillsDisableRequest" }, "result": { "type": "null" }, "stability": "experimental" }, "reload": { "rpcMethod": "session.skills.reload", "description": "Reloads skill definitions for the session.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/SkillsLoadDiagnostics", "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": { "list": { "rpcMethod": "session.mcp.list", "description": "Lists MCP servers configured for the session, their connection status, and host-level state. The host-level state (disabled/filtered servers, failed/needs-auth/pending connections, mcp3p policy, full config) is empty/zero when no MCP host has been initialized 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/McpServerList", "description": "MCP servers configured for the session, with their connection status and host-level state." }, "stability": "experimental" }, "listTools": { "rpcMethod": "session.mcp.listTools", "description": "Lists the tools exposed by a connected MCP server on this session's host.", "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 connected MCP server whose tools to list." } }, "required": [ "sessionId", "serverName" ], "additionalProperties": false, "description": "Server name whose tool list should be returned.", "title": "McpListToolsRequest" }, "result": { "$ref": "#/definitions/McpListToolsResult", "description": "Tools exposed by the connected MCP server. Throws when the server is not connected." }, "stability": "experimental" }, "enable": { "rpcMethod": "session.mcp.enable", "description": "Enables an MCP server for the session.", "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 MCP server to enable" } }, "required": [ "sessionId", "serverName" ], "additionalProperties": false, "description": "Name of the MCP server to enable for the session.", "title": "McpEnableRequest" }, "result": { "type": "null" }, "stability": "experimental" }, "disable": { "rpcMethod": "session.mcp.disable", "description": "Disables an MCP server for the session.", "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 MCP server to disable" } }, "required": [ "sessionId", "serverName" ], "additionalProperties": false, "description": "Name of the MCP server to disable for the session.", "title": "McpDisableRequest" }, "result": { "type": "null" }, "stability": "experimental" }, "reload": { "rpcMethod": "session.mcp.reload", "description": "Reloads MCP server connections for the session.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "type": "null" }, "stability": "experimental" }, "reloadWithConfig": { "rpcMethod": "session.mcp.reloadWithConfig", "description": "Reloads MCP server connections for the session with an explicit host-provided configuration.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "config": { "description": "Opaque runtime MCP reload configuration. Marked internal: an in-process runtime shape (reloadMcpServers throws over the wire).", "visibility": "internal", "x-opaque-json": true } }, "required": [ "sessionId", "config" ], "additionalProperties": false, "description": "Opaque MCP reload configuration.", "title": "McpReloadWithConfigRequest", "visibility": "internal" }, "result": { "$ref": "#/definitions/McpStartServersResult", "description": "MCP server startup filtering result." }, "stability": "experimental", "visibility": "internal" }, "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" }, "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).", "x-opaque-json": true }, "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" }, "configureGitHub": { "rpcMethod": "session.mcp.configureGitHub", "description": "Configures the built-in GitHub MCP server for the session's current auth context.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "authInfo": { "description": "Opaque runtime auth info for GitHub MCP configuration. Marked internal: an in-process runtime shape (configureGitHubMcp is a no-op over the wire).", "visibility": "internal", "x-opaque-json": true } }, "required": [ "sessionId", "authInfo" ], "additionalProperties": false, "description": "Opaque auth info used to configure GitHub MCP.", "title": "McpConfigureGitHubRequest", "visibility": "internal" }, "result": { "$ref": "#/definitions/McpConfigureGitHubResult", "description": "Result of configuring GitHub MCP." }, "stability": "experimental", "visibility": "internal" }, "startServer": { "rpcMethod": "session.mcp.startServer", "description": "Starts an individual MCP server on the session's host.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "serverName": { "type": "string", "description": "Name of the MCP server to start" }, "config": { "description": "Opaque server configuration (MCPServerConfig). Marked internal: an in-process runtime shape supplied only by in-process CLI callers.", "visibility": "internal", "x-opaque-json": true } }, "required": [ "sessionId", "serverName", "config" ], "additionalProperties": false, "description": "Server name and opaque configuration for an individual MCP server start.", "title": "McpStartServerRequest", "visibility": "internal" }, "result": { "type": "null" }, "stability": "experimental", "visibility": "internal" }, "restartServer": { "rpcMethod": "session.mcp.restartServer", "description": "Restarts an individual MCP server on the session's host (stops then starts).", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "serverName": { "type": "string", "description": "Name of the MCP server to restart" }, "config": { "description": "Opaque server configuration (MCPServerConfig). Marked internal: an in-process runtime shape supplied only by in-process CLI callers.", "visibility": "internal", "x-opaque-json": true } }, "required": [ "sessionId", "serverName", "config" ], "additionalProperties": false, "description": "Server name and opaque configuration for an individual MCP server restart.", "title": "McpRestartServerRequest", "visibility": "internal" }, "result": { "type": "null" }, "stability": "experimental", "visibility": "internal" }, "stopServer": { "rpcMethod": "session.mcp.stopServer", "description": "Stops an individual MCP server on the session's host.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "serverName": { "type": "string", "description": "Name of the MCP server to stop" } }, "required": [ "sessionId", "serverName" ], "additionalProperties": false, "description": "Server name for an individual MCP server stop.", "title": "McpStopServerRequest" }, "result": { "type": "null" }, "stability": "experimental" }, "registerExternalClient": { "rpcMethod": "session.mcp.registerExternalClient", "description": "Registers a pre-connected external MCP client (e.g. IDE) on the session's host. The caller retains lifecycle ownership of the client and transport. Marked internal because the `client` and `transport` arguments are in-process MCP SDK instances that cannot be serialized across the JSON-RPC boundary; once the CLI moves on top of the SDK, external clients will be expressed as transport configs the runtime can construct itself.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "serverName": { "type": "string", "description": "Logical server name for the external client" }, "client": { "description": "In-process MCP Client instance. Marked internal: cannot be serialized across the JSON-RPC boundary.", "visibility": "internal", "x-opaque-json": true }, "transport": { "description": "In-process MCP Transport instance. Marked internal: cannot be serialized across the JSON-RPC boundary.", "visibility": "internal", "x-opaque-json": true }, "config": { "description": "In-process server config (MCPServerConfig) paired with the in-process client/transport. Marked internal alongside its companions.", "visibility": "internal", "x-opaque-json": true } }, "required": [ "sessionId", "serverName", "client", "transport", "config" ], "additionalProperties": false, "description": "Registration parameters for an external MCP client.", "title": "McpRegisterExternalClientRequest", "visibility": "internal" }, "result": { "type": "null" }, "stability": "experimental", "visibility": "internal" }, "unregisterExternalClient": { "rpcMethod": "session.mcp.unregisterExternalClient", "description": "Unregisters a previously registered external MCP client by server name. Marked internal as the paired companion of `registerExternalClient`: only in-process callers that registered a client this way can meaningfully unregister it. Disappears alongside `registerExternalClient`: once external clients are described to the runtime as config rather than handed in as instances, lifecycle (including deregistration) is owned entirely by the runtime.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "serverName": { "type": "string", "description": "Server name of the external client to unregister" } }, "required": [ "sessionId", "serverName" ], "additionalProperties": false, "description": "Server name identifying the external client to remove.", "title": "McpUnregisterExternalClientRequest", "visibility": "internal" }, "result": { "type": "null" }, "stability": "experimental", "visibility": "internal" }, "isServerRunning": { "rpcMethod": "session.mcp.isServerRunning", "description": "Checks whether a named MCP server is currently running on the session's host.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "serverName": { "type": "string", "description": "Name of the MCP server to check" } }, "required": [ "sessionId", "serverName" ], "additionalProperties": false, "description": "Server name to check running status for.", "title": "McpIsServerRunningRequest" }, "result": { "$ref": "#/definitions/McpIsServerRunningResult", "description": "Whether the named MCP server is running." }, "stability": "experimental" }, "oauth": { "respond": { "rpcMethod": "session.mcp.oauth.respond", "description": "Responds to a pending MCP OAuth provider request. Marked internal because the `provider` argument is an in-process OAuthClientProvider instance that cannot be carried over the wire; the public OAuth surface will route the response through a wire-clean handshake once the CLI moves on top of the SDK.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "requestId": { "type": "string", "description": "OAuth request identifier from mcp.oauth_required" }, "provider": { "description": "In-process OAuthClientProvider instance, or omitted to deny. Marked internal: cannot be serialized across the JSON-RPC boundary.", "visibility": "internal", "x-opaque-json": true } }, "required": [ "sessionId", "requestId" ], "additionalProperties": false, "description": "MCP OAuth request id and optional provider response.", "title": "McpOauthRespondRequest", "visibility": "internal" }, "result": { "$ref": "#/definitions/McpOauthRespondResult", "description": "Empty result after recording the MCP OAuth response." }, "stability": "experimental", "visibility": "internal" }, "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." }, "stability": "experimental" } }, "apps": { "readResource": { "rpcMethod": "session.mcp.apps.readResource", "description": "Fetch an MCP resource (typically a `ui://` MCP App bundle, per SEP-1865) from a connected server. Requires the `mcp-apps` session capability.", "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 MCP server hosting the resource" }, "uri": { "type": "string", "description": "Resource URI (typically ui://...)" } }, "required": [ "sessionId", "serverName", "uri" ], "additionalProperties": false, "description": "MCP server and resource URI to fetch.", "title": "McpAppsReadResourceRequest" }, "result": { "$ref": "#/definitions/McpAppsReadResourceResult", "description": "Resource contents returned by the MCP server." }, "stability": "experimental" }, "listTools": { "rpcMethod": "session.mcp.apps.listTools", "description": "List tools that an MCP App view is allowed to call (SEP-1865 visibility filter). Returns tools whose `_meta.ui.visibility` is unset (default `[\"model\",\"app\"]`) or includes `\"app\"`.", "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": "MCP server hosting the app" }, "originServerName": { "type": "string", "minLength": 1, "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", "description": "**Required.** Server whose ui:// view issued the request. Per SEP-1865 ('callable by the app from this server only'), the call is rejected when this differs from `serverName`, and rejected outright when missing." } }, "required": [ "sessionId", "serverName", "originServerName" ], "additionalProperties": false, "description": "MCP server to list app-callable tools for.", "title": "McpAppsListToolsRequest" }, "result": { "$ref": "#/definitions/McpAppsListToolsResult", "description": "App-callable tools from the named MCP server." }, "stability": "experimental" }, "callTool": { "rpcMethod": "session.mcp.apps.callTool", "description": "Call an MCP tool from an MCP App view (SEP-1865). Enforces the visibility check that prevents an app iframe from invoking model-only tools. Returns the standard MCP `CallToolResult`.", "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": "MCP server hosting the tool" }, "toolName": { "type": "string", "description": "MCP tool name" }, "arguments": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "Tool arguments" }, "originServerName": { "type": "string", "minLength": 1, "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", "description": "**Required.** Server whose ui:// view issued the request. Per SEP-1865 ('callable by the app from this server only'), the call is rejected when this differs from `serverName`, and rejected outright when missing." } }, "required": [ "sessionId", "serverName", "toolName", "originServerName" ], "additionalProperties": false, "description": "MCP server, tool name, and arguments to invoke from an MCP App view.", "title": "McpAppsCallToolRequest" }, "result": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "Standard MCP CallToolResult" }, "stability": "experimental" }, "setHostContext": { "rpcMethod": "session.mcp.apps.setHostContext", "description": "Replace the host context returned to MCP App guests on `ui/initialize`. Hosts use this to advertise theme, locale, or other metadata to the guest UI.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "context": { "$ref": "#/definitions/McpAppsSetHostContextDetails", "description": "Host context advertised to MCP App guests" } }, "required": [ "sessionId", "context" ], "additionalProperties": false, "description": "Host context to advertise to MCP App guests.", "title": "McpAppsSetHostContextRequest" }, "result": { "type": "null" }, "stability": "experimental" }, "getHostContext": { "rpcMethod": "session.mcp.apps.getHostContext", "description": "Read the current host context advertised to MCP App guests.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/McpAppsHostContext", "description": "Current host context advertised to MCP App guests." }, "stability": "experimental" }, "diagnose": { "rpcMethod": "session.mcp.apps.diagnose", "description": "Diagnose MCP Apps wiring for a specific MCP server. Reports the session capability, feature-flag state, advertised extension, and how many tools have `_meta.ui` populated.", "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": "MCP server to probe" } }, "required": [ "sessionId", "serverName" ], "additionalProperties": false, "description": "MCP server to diagnose MCP Apps wiring for.", "title": "McpAppsDiagnoseRequest" }, "result": { "$ref": "#/definitions/McpAppsDiagnoseResult", "description": "Diagnostic snapshot of MCP Apps wiring for the named server." }, "stability": "experimental" } } }, "plugins": { "list": { "rpcMethod": "session.plugins.list", "description": "Lists plugins installed for the session.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/PluginList", "description": "Plugins installed for the session, with their enabled state and version metadata." }, "stability": "experimental" }, "reload": { "rpcMethod": "session.plugins.reload", "description": "Reloads the session's plugin set, refreshing MCP servers, custom agents, hooks, and skills cache so SDK-driven changes via `server.plugins.*` take effect immediately.", "params": { "anyOf": [ { "not": {} }, { "type": "object", "properties": { "reloadMcp": { "type": "boolean", "description": "Reload MCP server connections after refreshing plugins. Defaults to true." }, "reloadCustomAgents": { "type": "boolean", "description": "Re-run custom-agent discovery after refreshing plugins. Defaults to true." }, "reloadHooks": { "type": "boolean", "description": "Re-load user, plugin, and (subject to `deferRepoHooks`) repo hooks. Defaults to true. Has no effect when the host has not registered a hook reloader (e.g. remote sessions)." }, "deferRepoHooks": { "type": "boolean", "description": "When true, skip repo-level hooks during the hook reload. Use before folder trust is confirmed; load them post-trust via `sessions.loadDeferredRepoHooks`." } }, "additionalProperties": false } ], "description": "Optional flags controlling which side effects the reload performs.", "title": "PluginsReloadRequest", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ] }, "result": { "type": "null" }, "stability": "experimental" } }, "provider": { "getEndpoint": { "rpcMethod": "session.provider.getEndpoint", "description": "Returns the provider endpoint and credentials the session is currently configured to talk to, so the caller can make inference calls directly against the same backend the session uses.", "params": { "anyOf": [ { "not": {} }, { "type": "object", "properties": { "modelId": { "type": "string", "description": "Model identifier the caller intends to use against the returned endpoint. Used to pick the correct wire shape. Omit to use whichever model the session is currently using." } }, "additionalProperties": false } ], "description": "Optional model identifier to scope the endpoint snapshot to.", "title": "ProviderGetEndpointRequest", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ] }, "result": { "$ref": "#/definitions/ProviderEndpoint", "description": "A snapshot of the provider endpoint the session is currently configured to talk to." }, "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." }, "modelCapabilitiesOverrides": { "$ref": "#/definitions/ModelCapabilitiesOverride", "description": "Per-property model capability overrides for the selected model." }, "reasoningEffort": { "type": "string", "description": "Reasoning effort for the selected model (model-defined enum)." }, "reasoningSummary": { "$ref": "#/definitions/OptionsUpdateReasoningSummary", "description": "Reasoning summary mode for supported model clients." }, "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": { "$ref": "#/definitions/ProviderConfig", "description": "Custom model-provider configuration (BYOK)." }, "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." }, "toolFilterPrecedence": { "$ref": "#/definitions/OptionsUpdateToolFilterPrecedence", "description": "Controls how availableTools (allowlist) and excludedTools (denylist) combine when both are set." }, "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": { "$ref": "#/definitions/SandboxConfig", "description": "Resolved sandbox configuration." }, "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." }, "suppressCustomAgentPrompt": { "type": "boolean", "description": "When true, the selected custom agent's prompt is not injected into the user message (skill context is still injected). Used by automation triggers where the agent prompt is already in the problem statement." }, "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": { "$ref": "#/definitions/OptionsUpdateAdditionalContentExclusionPolicy" }, "description": "Additional content-exclusion policies to merge into the session's policy set.", "stability": "experimental" }, "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)." }, "sessionCapabilities": { "type": "array", "items": { "$ref": "#/definitions/SessionCapability", "description": "Session capability id" }, "description": "Replaces the session's capability set with the given list. Use to enable or disable capabilities mid-session (e.g., remove `memory` for reproducible scripted runs). Omit the field to leave the existing capability set unchanged." }, "skipEmbeddingRetrieval": { "type": "boolean", "description": "Whether to skip embedding retrieval pipeline initialization and execution." }, "organizationCustomInstructions": { "type": "string", "description": "Organization-level custom instructions to inject into the system prompt." }, "enableFileHooks": { "type": "boolean", "description": "Whether to enable loading of `.github/hooks/` filesystem hooks. Separate from the SDK callback hook mechanism." }, "enableHostGitOperations": { "type": "boolean", "description": "Whether to enable host git operations (context resolution, child repo scanning, git info in system prompt)." }, "enableSessionStore": { "type": "boolean", "description": "Whether to enable cross-session store writes and reads." }, "enableSkills": { "type": "boolean", "description": "Whether to enable skill directory scanning and loading. Falls back to enableConfigDiscovery when unset." }, "contextTier": { "$ref": "#/definitions/OptionsUpdateContextTier", "description": "Context tier for models with tiered pricing. The session uses this to derive effective `modelCapabilitiesOverrides` so compaction, truncation, token display, and request limits honor the selected tier." } }, "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", "description": "Lists extensions discovered for the session and their current status.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/ExtensionList", "description": "Extensions discovered for the session, with their current status." }, "stability": "experimental" }, "enable": { "rpcMethod": "session.extensions.enable", "description": "Enables an extension for the session.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "id": { "type": "string", "description": "Source-qualified extension ID to enable" } }, "required": [ "sessionId", "id" ], "additionalProperties": false, "description": "Source-qualified extension identifier to enable for the session.", "title": "ExtensionsEnableRequest" }, "result": { "type": "null" }, "stability": "experimental" }, "disable": { "rpcMethod": "session.extensions.disable", "description": "Disables an extension for the session.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "id": { "type": "string", "description": "Source-qualified extension ID to disable" } }, "required": [ "sessionId", "id" ], "additionalProperties": false, "description": "Source-qualified extension identifier to disable for the session.", "title": "ExtensionsDisableRequest" }, "result": { "type": "null" }, "stability": "experimental" }, "reload": { "rpcMethod": "session.extensions.reload", "description": "Reloads extension definitions and processes for the session.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "type": "null" }, "stability": "experimental" }, "sendAttachmentsToMessage": { "rpcMethod": "session.extensions.sendAttachmentsToMessage", "description": "Push attachments into the next user-message turn from an extension. The host should surface them as composer pills and forward them via the next session.send call. Callable only by extension-owned connections.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "instanceId": { "type": "string", "description": "Optional canvas instance binding the push for provenance. When supplied, the runtime resolves the canvas, verifies it is owned by the calling extension, and stamps canvasId/instanceId onto each extension_context entry. When omitted, no resolution runs and those fields stay unset on the attachment." }, "attachments": { "type": "array", "items": { "$ref": "#/definitions/PushAttachment" }, "description": "Attachments to push into the next user-message turn. extension_context entries take the slim shape; standard variants take their full AttachmentSchema shape." } }, "required": [ "sessionId", "attachments" ], "additionalProperties": false, "description": "Parameters for session.extensions.sendAttachmentsToMessage.", "title": "SendAttachmentsToMessageParams" }, "result": { "type": "null" }, "stability": "experimental" } }, "tools": { "handlePendingToolCall": { "rpcMethod": "session.tools.handlePendingToolCall", "description": "Provides the result for a pending external tool call.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "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": [ "sessionId", "requestId" ], "additionalProperties": false, "description": "Pending external tool call request ID, with the tool result or an error describing why it failed.", "title": "HandlePendingToolCallRequest" }, "result": { "$ref": "#/definitions/HandlePendingToolCallResult", "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" }, "getCurrentMetadata": { "rpcMethod": "session.tools.getCurrentMetadata", "description": "Returns lightweight metadata for the session's currently initialized tools.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/ToolsGetCurrentMetadataResult", "description": "Current lightweight tool metadata snapshot for the session." }, "stability": "experimental" }, "updateSubagentSettings": { "rpcMethod": "session.tools.updateSubagentSettings", "description": "Updates the current session's live subagent settings after user settings change. The persisted user settings remain the source of truth for future sessions.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "subagents": { "$ref": "#/definitions/SubagentSettings", "description": "Subagent settings to apply, or null to clear the live session override" } }, "required": [ "sessionId", "subagents" ], "additionalProperties": false, "description": "Subagent settings to apply to the current session", "title": "UpdateSubagentSettingsRequest" }, "result": { "$ref": "#/definitions/ToolsUpdateSubagentSettingsResult", "description": "Empty result after applying subagent settings" }, "stability": "experimental" } }, "commands": { "list": { "rpcMethod": "session.commands.list", "description": "Lists slash commands available in the session.", "params": { "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", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ] }, "result": { "$ref": "#/definitions/CommandList", "description": "Slash commands available in the session, after applying any include/exclude filters." }, "stability": "experimental" }, "invoke": { "rpcMethod": "session.commands.invoke", "description": "Invokes a slash command in the session.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "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": [ "sessionId", "name" ], "additionalProperties": false, "description": "Slash command name and optional raw input string to invoke.", "title": "CommandsInvokeRequest" }, "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", "description": "Reports completion of a pending client-handled slash command.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "requestId": { "type": "string", "description": "Request ID from the command invocation event" }, "error": { "type": "string", "description": "Error message if the command handler failed" } }, "required": [ "sessionId", "requestId" ], "additionalProperties": false, "description": "Pending command request ID and an optional error if the client handler failed.", "title": "CommandsHandlePendingCommandRequest" }, "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": "Reports whether the host actually executed a queued command and whether to continue processing.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "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": [ "sessionId", "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" }, "result": { "$ref": "#/definitions/CommandsRespondToQueuedCommandResult", "description": "Indicates whether the queued-command response was matched to a pending request." }, "stability": "experimental" } }, "telemetry": { "getEngagementId": { "rpcMethod": "session.telemetry.getEngagementId", "description": "Gets the telemetry engagement ID currently associated with the session, when available.", "params": { "type": "object", "description": "Identifies the target session.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/SessionTelemetryEngagement", "description": "Telemetry engagement ID for the session, when available." }, "stability": "experimental" }, "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": { "ephemeralQuery": { "rpcMethod": "session.ui.ephemeralQuery", "description": "Runs a transient no-tools model query against the current conversation context.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "question": { "type": "string", "description": "Question to answer from the current conversation context." }, "onChunk": { "description": "In-process streaming callback `(text) => void` invoked with each token as the model emits it. Marked internal: excluded from the public SDK surface. In a process-separated SDK this is replaced by a streaming RPC that yields chunks and a final answer.", "visibility": "internal", "x-opaque-json": true }, "abortSignal": { "description": "In-process `AbortSignal` forwarded to the model client to cancel an in-flight request. Marked internal: excluded from the public SDK surface. Replaced by an explicit cancellation token + cancel RPC in the SDK migration.", "visibility": "internal", "x-opaque-json": true } }, "required": [ "sessionId", "question" ], "additionalProperties": false, "description": "Transient question to answer without adding it to conversation history.", "title": "UIEphemeralQueryRequest" }, "result": { "$ref": "#/definitions/UIEphemeralQueryResult", "description": "Transient answer generated from current conversation context." }, "stability": "experimental" }, "elicitation": { "rpcMethod": "session.ui.elicitation", "description": "Requests structured input from a UI-capable client.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "message": { "type": "string", "description": "Message describing what information is needed from the user" }, "requestedSchema": { "$ref": "#/definitions/UIElicitationSchema", "description": "JSON Schema describing the form fields to present to the user" } }, "required": [ "sessionId", "message", "requestedSchema" ], "additionalProperties": false, "description": "Prompt message and JSON schema describing the form fields to elicit from the user.", "title": "UIElicitationRequest" }, "result": { "$ref": "#/definitions/UIElicitationResponse", "description": "The elicitation response (accept with form values, decline, or cancel)" }, "stability": "experimental" }, "handlePendingElicitation": { "rpcMethod": "session.ui.handlePendingElicitation", "description": "Provides the user response for a pending elicitation request.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "requestId": { "type": "string", "description": "The unique request ID from the elicitation.requested event" }, "result": { "$ref": "#/definitions/UIElicitationResponse", "description": "The elicitation response (accept with form values, decline, or cancel)" } }, "required": [ "sessionId", "requestId", "result" ], "additionalProperties": false, "description": "Pending elicitation request ID and the user's response (accept/decline/cancel + form values).", "title": "UIHandlePendingElicitationRequest" }, "result": { "$ref": "#/definitions/UIElicitationResult", "description": "Indicates whether the elicitation response was accepted; false if it was already resolved by another client." }, "stability": "experimental" }, "handlePendingUserInput": { "rpcMethod": "session.ui.handlePendingUserInput", "description": "Resolves a pending `user_input.requested` event with the user's response.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "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": [ "sessionId", "requestId", "response" ], "additionalProperties": false, "description": "Request ID of a pending `user_input.requested` event and the user's response.", "title": "UIHandlePendingUserInputRequest" }, "result": { "$ref": "#/definitions/UIHandlePendingResult", "description": "Indicates whether the pending UI request was resolved by this call." }, "stability": "experimental" }, "handlePendingSampling": { "rpcMethod": "session.ui.handlePendingSampling", "description": "Resolves a pending `sampling.requested` event with a sampling result, or rejects it.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "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", "requestId" ], "additionalProperties": false, "description": "Request ID of a pending `sampling.requested` event and an optional sampling result payload (omit to reject).", "title": "UIHandlePendingSamplingRequest" }, "result": { "$ref": "#/definitions/UIHandlePendingResult", "description": "Indicates whether the pending UI request was resolved by this call." }, "stability": "experimental" }, "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": { "sessionId": { "type": "string", "description": "Target session identifier" }, "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": [ "sessionId", "requestId", "response" ], "additionalProperties": false, "description": "Request ID of a pending `auto_mode_switch.requested` event and the user's response.", "title": "UIHandlePendingAutoModeSwitchRequest" }, "result": { "$ref": "#/definitions/UIHandlePendingResult", "description": "Indicates whether the pending UI request was resolved by this call." }, "stability": "experimental" }, "handlePendingExitPlanMode": { "rpcMethod": "session.ui.handlePendingExitPlanMode", "description": "Resolves a pending `exit_plan_mode.requested` event with the user's response.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "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": [ "sessionId", "requestId", "response" ], "additionalProperties": false, "description": "Request ID of a pending `exit_plan_mode.requested` event and the user's response.", "title": "UIHandlePendingExitPlanModeRequest" }, "result": { "$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.", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$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" }, "unregisterDirectAutoModeSwitchHandler": { "rpcMethod": "session.ui.unregisterDirectAutoModeSwitchHandler", "description": "Unregisters a previously-registered in-process auto-mode-switch handler by its opaque handle.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "handle": { "type": "string", "description": "Handle previously returned by `registerDirectAutoModeSwitchHandler`" } }, "required": [ "sessionId", "handle" ], "additionalProperties": false, "description": "Opaque handle previously returned by `registerDirectAutoModeSwitchHandler` to release.", "title": "UIUnregisterDirectAutoModeSwitchHandlerRequest" }, "result": { "$ref": "#/definitions/UIUnregisterDirectAutoModeSwitchHandlerResult", "description": "Indicates whether the handle was active and the registration count was decremented." }, "stability": "experimental" } }, "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", "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" ] }, "result": { "$ref": "#/definitions/PermissionsConfigureResult", "description": "Indicates whether the operation succeeded." }, "stability": "experimental" }, "handlePendingPermissionRequest": { "rpcMethod": "session.permissions.handlePendingPermissionRequest", "description": "Provides a decision for a pending tool permission request.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "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" } }, "required": [ "sessionId", "requestId", "result" ], "additionalProperties": false, "description": "Pending permission request ID and the decision to apply (approve/reject and scope).", "title": "PermissionDecisionRequest" }, "result": { "$ref": "#/definitions/PermissionRequestResult", "description": "Indicates whether the permission decision was applied; false when the request was already resolved." }, "stability": "experimental" }, "pendingRequests": { "rpcMethod": "session.permissions.pendingRequests", "description": "Reconstructs the set of pending tool permission requests from the session's event history.", "params": { "type": "object", "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" ] }, "result": { "$ref": "#/definitions/PendingPermissionRequestList", "description": "List of pending permission requests reconstructed from event history." }, "stability": "experimental" }, "setApproveAll": { "rpcMethod": "session.permissions.setApproveAll", "description": "Enables or disables automatic approval of tool permission requests for the session.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "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", "enabled" ], "additionalProperties": false, "description": "Allow-all toggle for tool permission requests, with an optional telemetry source.", "title": "PermissionsSetApproveAllRequest" }, "result": { "$ref": "#/definitions/PermissionsSetApproveAllResult", "description": "Indicates whether the operation succeeded." }, "stability": "experimental" }, "setAllowAll": { "rpcMethod": "session.permissions.setAllowAll", "description": "Enables or disables full allow-all permissions (tools, paths, and URLs) for the session. Used by attach-mode clients (e.g. LocalRpcSession's `/allow-all` forwarder) to flip the target session's permission state. Unlike `setApproveAll`, this swaps in the unrestricted path and URL managers and emits `session.permissions_changed` on transition. The result returns the authoritative post-mutation state so callers can update their local mirrors without racing the `session.permissions_changed` notification on the same wire.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "enabled": { "type": "boolean", "description": "Whether to enable full allow-all permissions" }, "source": { "$ref": "#/definitions/PermissionsSetAllowAllSource", "description": "Optional source for allow-all telemetry. Defaults to `rpc` when omitted for SDK callers." } }, "required": [ "sessionId", "enabled" ], "additionalProperties": false, "description": "Whether to enable full allow-all permissions for the session.", "title": "PermissionsSetAllowAllRequest" }, "result": { "$ref": "#/definitions/AllowAllPermissionSetResult", "description": "Indicates whether the operation succeeded and reports the post-mutation state." }, "stability": "experimental" }, "getAllowAll": { "rpcMethod": "session.permissions.getAllowAll", "description": "Returns whether full allow-all permissions are currently active for the session.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "additionalProperties": false, "description": "No parameters.", "title": "PermissionsGetAllowAllRequest", "required": [ "sessionId" ] }, "result": { "$ref": "#/definitions/AllowAllPermissionState", "description": "Current full allow-all permission state." }, "stability": "experimental" }, "modifyRules": { "rpcMethod": "session.permissions.modifyRules", "description": "Adds or removes session-scoped or location-scoped permission rules.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "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." }, "add": { "type": "array", "items": { "$ref": "#/definitions/PermissionRule" }, "description": "Rules to add to the scope. Applied before `remove`/`removeAll`." }, "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", "scope" ], "additionalProperties": false, "description": "Scope and add/remove instructions for modifying session- or location-scoped permission rules.", "title": "PermissionsModifyRulesParams" }, "result": { "$ref": "#/definitions/PermissionsModifyRulesResult", "description": "Indicates whether the operation succeeded." }, "stability": "experimental" }, "setRequired": { "rpcMethod": "session.permissions.setRequired", "description": "Sets whether the client wants permission prompts bridged into session events.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "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", "required" ], "additionalProperties": false, "description": "Toggles whether permission prompts should be bridged into session events for this client.", "title": "PermissionsSetRequiredRequest" }, "result": { "$ref": "#/definitions/PermissionsSetRequiredResult", "description": "Indicates whether the operation succeeded." }, "stability": "experimental" }, "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" ] }, "result": { "$ref": "#/definitions/PermissionsResetSessionApprovalsResult", "description": "Indicates whether the operation succeeded." }, "stability": "experimental" }, "notifyPromptShown": { "rpcMethod": "session.permissions.notifyPromptShown", "description": "Notifies the runtime that a permission prompt UI has been shown to the user.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "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": [ "sessionId", "message" ], "additionalProperties": false, "description": "Notification payload describing the permission prompt that the client just rendered.", "title": "PermissionPromptShownNotification" }, "result": { "$ref": "#/definitions/PermissionsNotifyPromptShownResult", "description": "Indicates whether the operation succeeded." }, "stability": "experimental" }, "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" } }, "additionalProperties": false, "description": "No parameters; returns the session's allow-listed directories.", "title": "PermissionsPathsListRequest", "required": [ "sessionId" ] }, "result": { "$ref": "#/definitions/PermissionPathsList", "description": "Snapshot of the session's allow-listed directories and primary working directory." }, "stability": "experimental" }, "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." } }, "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" } }, "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" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/SessionMetadataSnapshot", "description": "Point-in-time snapshot of slow-changing session identifier and state fields" }, "stability": "experimental" }, "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" } }, "required": [ "sessionId" ], "additionalProperties": false }, "result": { "$ref": "#/definitions/MetadataIsProcessingResult", "description": "Indicates whether the local session is currently processing a turn or background continuation." }, "stability": "experimental" }, "activity": { "rpcMethod": "session.metadata.activity", "description": "Returns a snapshot of activity flags 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/SessionActivity", "description": "Current activity flags for the session." }, "stability": "experimental" }, "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": { "sessionId": { "type": "string", "description": "Target session identifier" }, "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": [ "sessionId", "promptTokenLimit", "outputTokenLimit" ], "additionalProperties": false, "description": "Model identifier and token limits used to compute the context-info breakdown.", "title": "MetadataContextInfoRequest" }, "result": { "$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" }, "context": { "$ref": "#/definitions/SessionWorkingDirectoryContext", "description": "Updated working directory and git context. Emitted as the new payload of `session.context_changed`." } }, "required": [ "sessionId", "context" ], "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" }, "setWorkingDirectory": { "rpcMethod": "session.metadata.setWorkingDirectory", "description": "Updates the session's recorded working directory.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "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": [ "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" }, "modelId": { "type": "string", "description": "Model identifier used for tokenization. The runtime token-counts both chat-context and system-context messages against this model." } }, "required": [ "sessionId", "modelId" ], "additionalProperties": false, "description": "Model identifier to use when re-tokenizing the session's existing messages.", "title": "MetadataRecomputeContextTokensRequest" }, "result": { "$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" }, "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" ], "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" }, "kill": { "rpcMethod": "session.shell.kill", "description": "Sends a signal to a shell process previously started via \"shell.exec\".", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "processId": { "type": "string", "description": "Process identifier returned by shell.exec" }, "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" }, "executeUserRequested": { "rpcMethod": "session.shell.executeUserRequested", "description": "Executes a user-requested shell command through the session runtime.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "requestId": { "type": "string", "description": "Caller-provided cancellation handle for this execution" }, "command": { "type": "string", "description": "Shell command to execute" } }, "required": [ "sessionId", "requestId", "command" ], "additionalProperties": false, "description": "User-requested shell command and cancellation handle.", "title": "ShellExecuteUserRequestedRequest" }, "result": { "$ref": "#/definitions/UserRequestedShellCommandResult", "description": "Result of a user-requested shell command." }, "stability": "experimental" }, "cancelUserRequested": { "rpcMethod": "session.shell.cancelUserRequested", "description": "Cancels a user-requested shell command by request ID.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "requestId": { "type": "string", "description": "Request ID previously passed to executeUserRequested" } }, "required": [ "sessionId", "requestId" ], "additionalProperties": false, "description": "User-requested shell execution cancellation handle.", "title": "ShellCancelUserRequestedRequest" }, "result": { "$ref": "#/definitions/CancelUserRequestedShellCommandResult", "description": "Cancellation result for a user-requested shell command." }, "stability": "experimental" } }, "history": { "compact": { "rpcMethod": "session.history.compact", "description": "Compacts the session history to reduce context usage.", "params": { "anyOf": [ { "not": {} }, { "type": "object", "properties": { "customInstructions": { "type": "string", "maxLength": 4000, "description": "Optional user-provided instructions to focus the compaction summary" } }, "additionalProperties": false } ], "description": "Optional compaction parameters.", "title": "HistoryCompactRequest", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" } }, "required": [ "sessionId" ] }, "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" }, "eventId": { "type": "string", "description": "Event ID to truncate to. This event and all events after it are removed from the session." } }, "required": [ "sessionId", "eventId" ], "additionalProperties": false, "description": "Identifier of the event to truncate to; this event and all later events are removed.", "title": "HistoryTruncateRequest" }, "result": { "$ref": "#/definitions/HistoryTruncateResult", "description": "Number of events that were removed by the truncation." }, "stability": "experimental" }, "cancelBackgroundCompaction": { "rpcMethod": "session.history.cancelBackgroundCompaction", "description": "Cancels any in-progress background 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/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": 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": 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." }, "stability": "experimental" }, "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." }, "stability": "experimental" }, "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." }, "stability": "experimental" }, "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." }, "stability": "experimental" }, "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." }, "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" }, "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." }, "stability": "experimental" }, "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." }, "stability": "experimental" }, "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." }, "stability": "experimental" }, "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." }, "stability": "experimental" }, "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." }, "stability": "experimental" }, "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" ], "x-opaque-json": true }, "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." }, "stability": "experimental" }, "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." }, "stability": "experimental" } }, "canvas": { "open": { "rpcMethod": "canvas.open", "description": "Opens a canvas instance on the provider.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "extensionId": { "type": "string", "description": "Owning provider identifier" }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier" }, "instanceId": { "type": "string", "description": "Stable caller-supplied canvas instance identifier" }, "input": { "description": "Canvas open input", "x-opaque-json": true }, "host": { "$ref": "#/definitions/CanvasHostContext", "description": "Host context supplied by the runtime." }, "session": { "$ref": "#/definitions/CanvasSessionContext", "description": "Session context supplied by the runtime." } }, "required": [ "sessionId", "extensionId", "canvasId", "instanceId" ], "additionalProperties": false, "description": "Canvas open parameters sent to the provider.", "title": "CanvasProviderOpenRequest" }, "result": { "$ref": "#/definitions/CanvasProviderOpenResult", "description": "Canvas open result returned by the provider." }, "stability": "experimental" }, "close": { "rpcMethod": "canvas.close", "description": "Closes a canvas instance on the provider.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "extensionId": { "type": "string", "description": "Owning provider identifier" }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier" }, "instanceId": { "type": "string", "description": "Canvas instance identifier" }, "host": { "$ref": "#/definitions/CanvasHostContext", "description": "Host context supplied by the runtime." }, "session": { "$ref": "#/definitions/CanvasSessionContext", "description": "Session context supplied by the runtime." } }, "required": [ "sessionId", "extensionId", "canvasId", "instanceId" ], "additionalProperties": false, "description": "Canvas close parameters sent to the provider.", "title": "CanvasProviderCloseRequest" }, "result": { "type": "null" }, "stability": "experimental" }, "action": { "invoke": { "rpcMethod": "canvas.action.invoke", "description": "Invokes an action on an open canvas instance via the provider.", "params": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Target session identifier" }, "extensionId": { "type": "string", "description": "Owning provider identifier" }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier" }, "instanceId": { "type": "string", "description": "Canvas instance identifier" }, "actionName": { "type": "string", "description": "Action name to invoke" }, "input": { "description": "Action input", "x-opaque-json": true }, "host": { "$ref": "#/definitions/CanvasHostContext", "description": "Host context supplied by the runtime." }, "session": { "$ref": "#/definitions/CanvasSessionContext", "description": "Session context supplied by the runtime." } }, "required": [ "sessionId", "extensionId", "canvasId", "instanceId", "actionName" ], "additionalProperties": false, "description": "Canvas action invocation parameters sent to the provider.", "title": "CanvasProviderInvokeActionRequest" }, "result": { "description": "Provider-supplied action result.", "x-opaque-json": true }, "stability": "experimental" } } } }, "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 additional usage requests made this period" }, "overageAllowedWithExhaustedQuota": { "type": "boolean", "description": "Whether additional usage 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": { "x-opaque-json": true }, "description": "MCP server configurations attached to this agent, keyed by server name. Server config shape mirrors the MCP `mcpServers` schema.", "stability": "experimental" }, "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" }, "AgentRegistryLiveTargetEntry": { "type": "object", "properties": { "schemaVersion": { "type": "integer", "description": "Registry entry schema version (1 = ui-server, 2 = managed-server)" }, "kind": { "$ref": "#/definitions/AgentRegistryLiveTargetEntryKind", "description": "Process kind tag for the registry entry" }, "pid": { "type": "integer", "description": "Operating-system pid of the process owning this entry" }, "host": { "type": "string", "description": "Bind host for the entry's JSON-RPC server" }, "port": { "type": "integer", "description": "TCP port the entry's JSON-RPC server is listening on" }, "token": { "type": [ "string", "null" ], "description": "Connection token (null when the target is unauthenticated)", "visibility": "internal" }, "sessionId": { "type": "string", "description": "Session ID of the foreground session for this entry" }, "sessionName": { "type": "string", "description": "Friendly session name (when set)" }, "cwd": { "type": "string", "description": "Working directory of the session (when known)" }, "branch": { "type": "string", "description": "Git branch of the session (when known)" }, "model": { "type": "string", "description": "Model identifier currently selected for the session" }, "status": { "$ref": "#/definitions/AgentRegistryLiveTargetEntryStatus", "description": "Coarse lifecycle status of the foreground session" }, "attentionKind": { "$ref": "#/definitions/AgentRegistryLiveTargetEntryAttentionKind", "description": "Kind of attention required when status === \"attention\". Meaningful only when status === \"attention\"." }, "statusRevision": { "type": "integer", "minimum": 0, "description": "Monotonic per-publisher revision counter incremented on every status update. Lets watchers detect transient flips." }, "lastTerminalEvent": { "$ref": "#/definitions/AgentRegistryLiveTargetEntryLastTerminalEvent", "description": "How the most recent turn ended (clean vs aborted). Lets the renderer distinguish done from done_cancelled." }, "startedAt": { "type": "string", "description": "ISO 8601 timestamp captured at registration" }, "copilotVersion": { "type": "string", "description": "Copilot CLI version that wrote the entry" }, "lastSeenMs": { "type": "integer", "description": "Wall-clock milliseconds since the watcher last observed this entry (heartbeat freshness)" } }, "required": [ "schemaVersion", "kind", "pid", "host", "port", "startedAt", "copilotVersion", "lastSeenMs" ], "additionalProperties": false, "description": "Full registry entry for the spawned child. Lets the controller call `handleLiveTargetSelected(entry)` directly without re-reading the registry (avoids a TOCTOU window).", "title": "AgentRegistryLiveTargetEntry" }, "AgentRegistryLiveTargetEntryAttentionKind": { "type": "string", "enum": [ "error", "permission", "exit_plan", "elicitation", "user_input" ], "description": "Kind of attention required when status === \"attention\". Meaningful only when status === \"attention\".", "title": "AgentRegistryLiveTargetEntryAttentionKind", "x-enumDescriptions": { "error": "Session is blocked on an unrecoverable error", "permission": "Session is waiting for a tool-permission decision", "exit_plan": "Session is waiting for the user to approve or reject a plan", "elicitation": "Session is waiting on an elicitation prompt", "user_input": "Session is waiting for free-form user input" } }, "AgentRegistryLiveTargetEntryKind": { "type": "string", "enum": [ "ui-server", "managed-server" ], "description": "Process kind tag for the registry entry", "title": "AgentRegistryLiveTargetEntryKind", "x-enumDescriptions": { "ui-server": "Interactive Copilot CLI exposing a UI server (legacy/normal CLI process)", "managed-server": "Headless `--server --managed-server` child spawned by a controller" } }, "AgentRegistryLiveTargetEntryLastTerminalEvent": { "type": "string", "enum": [ "turn_end", "abort" ], "description": "How the most recent turn ended (clean vs aborted). Lets the renderer distinguish done from done_cancelled.", "title": "AgentRegistryLiveTargetEntryLastTerminalEvent", "x-enumDescriptions": { "turn_end": "Last turn ended cleanly (model returned a final assistant message)", "abort": "Last turn was aborted (e.g. user interrupted)" } }, "AgentRegistryLiveTargetEntryStatus": { "type": "string", "enum": [ "working", "waiting", "done", "attention" ], "description": "Coarse lifecycle status of the foreground session", "title": "AgentRegistryLiveTargetEntryStatus", "x-enumDescriptions": { "working": "Session is actively processing a turn", "waiting": "Session is idle, waiting for input", "done": "Last turn completed successfully", "attention": "Session needs user attention (see attentionKind for the specific reason)" } }, "AgentRegistryLogCapture": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether per-spawn log capture is on (false when env-disabled or open failed)" }, "path": { "type": "string", "description": "Absolute path to the per-spawn log file (only set when enabled)" }, "openError": { "type": "string", "description": "Human-readable open failure message (only set when enabled === false AND the env-disable opt-out was NOT used)" }, "openErrorReason": { "$ref": "#/definitions/AgentRegistryLogCaptureOpenErrorReason", "description": "Categorized reason for log-open failure" } }, "required": [ "enabled" ], "additionalProperties": false, "description": "Per-spawn log-capture outcome; populated from spawnLiveTarget.", "title": "AgentRegistryLogCapture" }, "AgentRegistryLogCaptureOpenErrorReason": { "type": "string", "enum": [ "permission", "disk_full", "other" ], "description": "Categorized reason for log-open failure", "title": "AgentRegistryLogCaptureOpenErrorReason", "x-enumDescriptions": { "permission": "Filesystem permission denied opening the log file", "disk_full": "No space left on device", "other": "Other / uncategorized open failure" } }, "AgentRegistrySpawnError": { "type": "object", "properties": { "kind": { "type": "string", "const": "spawn-error", "description": "Discriminator: child_process.spawn itself failed" }, "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Underlying errno code (e.g. ENOENT, EACCES) when available" } }, "required": [ "kind", "message" ], "additionalProperties": false, "description": "`child_process.spawn` itself failed before the child entered the registry.", "title": "AgentRegistrySpawnError" }, "AgentRegistrySpawnPermissionMode": { "type": "string", "enum": [ "default", "yolo" ], "description": "Permission posture for the new session. 'yolo' requires the controller-local session to currently be in allow-all mode.", "title": "AgentRegistrySpawnPermissionMode", "x-enumDescriptions": { "default": "Standard permission posture (prompts for each request)", "yolo": "Full allow-all (requires the controller-local session to currently be in allow-all mode)" } }, "AgentRegistrySpawnRegistryTimeout": { "type": "object", "properties": { "kind": { "type": "string", "const": "registry-timeout", "description": "Discriminator: spawn succeeded but child never registered" }, "childPid": { "type": "integer", "description": "Process ID of the orphaned child (so the caller can offer 'kill the pid' guidance)" }, "logCapture": { "$ref": "#/definitions/AgentRegistryLogCapture", "description": "Per-spawn log-capture outcome; populated from spawnLiveTarget." } }, "required": [ "kind", "childPid" ], "additionalProperties": false, "description": "Spawn succeeded but the child did not publish a matching managed-server entry within the timeout.", "title": "AgentRegistrySpawnRegistryTimeout" }, "AgentRegistrySpawnRequest": { "type": "object", "properties": { "cwd": { "type": "string", "description": "Working directory for the spawned child (must be an existing directory)" }, "agentName": { "type": "string", "description": "Custom or built-in agent name (e.g. 'explore'). When omitted, the child uses its own default." }, "model": { "type": "string", "description": "Model identifier to apply to the new session" }, "name": { "type": "string", "description": "Friendly session name. Must satisfy validateSessionName: non-empty, no leading/trailing whitespace, <=100 chars, no control chars, no double quotes." }, "permissionMode": { "$ref": "#/definitions/AgentRegistrySpawnPermissionMode", "description": "Permission posture for the new session. 'yolo' requires the controller-local session to currently be in allow-all mode." }, "initialPrompt": { "type": "string", "description": "Optional first user message. Forwarded to the caller (the CLI's spawn wrapper sends it post-attach via the standard LocalRpcSession.send path)." } }, "required": [ "cwd" ], "additionalProperties": false, "description": "Inputs to spawn a managed-server child via the controller's spawn delegate.", "title": "AgentRegistrySpawnRequest" }, "AgentRegistrySpawnResult": { "anyOf": [ { "$ref": "#/definitions/AgentRegistrySpawnSpawned", "description": "Managed-server child was spawned and registered successfully." }, { "$ref": "#/definitions/AgentRegistrySpawnError", "description": "`child_process.spawn` itself failed before the child entered the registry." }, { "$ref": "#/definitions/AgentRegistrySpawnRegistryTimeout", "description": "Spawn succeeded but the child did not publish a matching managed-server entry within the timeout." }, { "$ref": "#/definitions/AgentRegistrySpawnValidationError", "description": "Synchronous pre-validation rejected the spawn request." } ], "description": "Outcome of an agentRegistry.spawn call.", "title": "AgentRegistrySpawnResult" }, "AgentRegistrySpawnSpawned": { "type": "object", "properties": { "kind": { "type": "string", "const": "spawned", "description": "Discriminator: managed-server child spawned successfully" }, "entry": { "$ref": "#/definitions/AgentRegistryLiveTargetEntry", "description": "Full registry entry for the spawned child. Lets the controller call `handleLiveTargetSelected(entry)` directly without re-reading the registry (avoids a TOCTOU window)." }, "initialPromptSent": { "type": "boolean", "description": "Whether the delegate already sent the initial prompt. Always omitted in the current wiring: the controller sends the prompt post-attach via the standard LocalRpcSession.send path." }, "initialPromptError": { "type": "string", "description": "If the delegate attempted to send the initial prompt and failed, the categorized error message." }, "logCapture": { "$ref": "#/definitions/AgentRegistryLogCapture", "description": "Per-spawn log-capture outcome; populated from spawnLiveTarget." } }, "required": [ "kind", "entry" ], "additionalProperties": false, "description": "Managed-server child was spawned and registered successfully.", "title": "AgentRegistrySpawnSpawned" }, "AgentRegistrySpawnValidationError": { "type": "object", "properties": { "kind": { "type": "string", "const": "validation-error", "description": "Discriminator: synchronous pre-validation rejected the request" }, "reason": { "$ref": "#/definitions/AgentRegistrySpawnValidationErrorReason", "description": "Categorized reason for the rejection. Low-cardinality enum so telemetry can aggregate by reason without leaking raw paths or agent/model names." }, "field": { "$ref": "#/definitions/AgentRegistrySpawnValidationErrorField", "description": "Which parameter field was invalid. Omitted when the rejection is not field-specific." }, "message": { "type": "string", "description": "Human-readable explanation; safe to surface in the UI banner. Never logged to unrestricted telemetry." } }, "required": [ "kind", "reason", "message" ], "additionalProperties": false, "description": "Synchronous pre-validation rejected the spawn request.", "title": "AgentRegistrySpawnValidationError" }, "AgentRegistrySpawnValidationErrorField": { "type": "string", "enum": [ "cwd", "name", "agentName", "model", "permissionMode" ], "description": "Which parameter field was invalid. Omitted when the rejection is not field-specific.", "title": "AgentRegistrySpawnValidationErrorField", "x-enumDescriptions": { "cwd": "The cwd parameter", "name": "The session name parameter", "agentName": "The agentName parameter", "model": "The model parameter", "permissionMode": "The permissionMode parameter" } }, "AgentRegistrySpawnValidationErrorReason": { "type": "string", "enum": [ "cwd-not-found", "cwd-not-directory", "invalid-name", "unknown-agent", "unknown-model", "yolo-not-allowed" ], "description": "Categorized reason for the rejection. Low-cardinality enum so telemetry can aggregate by reason without leaking raw paths or agent/model names.", "title": "AgentRegistrySpawnValidationErrorReason", "x-enumDescriptions": { "cwd-not-found": "Provided cwd does not exist on disk", "cwd-not-directory": "Provided cwd exists but is not a directory", "invalid-name": "Session name failed validateSessionName", "unknown-agent": "Requested agent name was not found in builtin or custom agents", "unknown-model": "Requested model is not available to this session", "yolo-not-allowed": "Caller asked for permissionMode='yolo' but the controller is not currently in allow-all mode" } }, "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" }, "AgentsDiscoverRequest": { "type": "object", "properties": { "projectPaths": { "type": "array", "items": { "type": "string" }, "description": "Optional list of project directory paths to scan for project-scoped agents. When omitted or empty, only user/plugin/remote-independent agents are returned (no project scan)." }, "excludeHostAgents": { "type": "boolean", "description": "When true, omit the host's agents (the `/agents` directory and all plugin agents), leaving only project and remote agents. For multitenant deployments." } }, "additionalProperties": false, "description": "Optional project paths to include in agent discovery.", "title": "AgentsDiscoverRequest" }, "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" }, "AllowAllPermissionSetResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" }, "enabled": { "type": "boolean", "description": "Authoritative allow-all state after the mutation" } }, "required": [ "success", "enabled" ], "additionalProperties": false, "description": "Indicates whether the operation succeeded and reports the post-mutation state.", "title": "AllowAllPermissionSetResult" }, "AllowAllPermissionState": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether full allow-all permissions are currently active" } }, "required": [ "enabled" ], "additionalProperties": false, "description": "Current full allow-all permission state.", "title": "AllowAllPermissionState" }, "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." }, "Attachment": { "anyOf": [ { "$ref": "#/definitions/AttachmentFile", "description": "File attachment" }, { "$ref": "#/definitions/AttachmentDirectory", "description": "Directory attachment" }, { "$ref": "#/definitions/AttachmentSelection", "description": "Code selection attachment from an editor" }, { "$ref": "#/definitions/AttachmentGitHubReference", "description": "GitHub issue, pull request, or discussion reference" }, { "$ref": "#/definitions/AttachmentBlob", "description": "Blob attachment with inline base64-encoded data" }, { "$ref": "#/definitions/AttachmentExtensionContext", "description": "Structured context contributed by an extension. Composer pills displayed in the host are forwarded back through session.send.attachments, then rendered into the model prompt as an XML block." } ], "description": "A user message attachment — a file, directory, code selection, blob, GitHub reference, or extension-supplied context payload", "title": "Attachment" }, "AttachmentBlob": { "type": "object", "properties": { "type": { "type": "string", "const": "blob", "description": "Attachment type discriminator" }, "data": { "type": "string", "description": "Base64-encoded content", "contentEncoding": "base64" }, "mimeType": { "type": "string", "description": "MIME type of the inline data" }, "displayName": { "type": "string", "description": "User-facing display name for the attachment" } }, "required": [ "type", "data", "mimeType" ], "additionalProperties": false, "description": "Blob attachment with inline base64-encoded data", "title": "AttachmentBlob" }, "AttachmentDirectory": { "type": "object", "properties": { "type": { "type": "string", "const": "directory", "description": "Attachment type discriminator" }, "path": { "type": "string", "description": "Absolute directory path" }, "displayName": { "type": "string", "description": "User-facing display name for the attachment" } }, "required": [ "type", "path", "displayName" ], "additionalProperties": false, "description": "Directory attachment", "title": "AttachmentDirectory" }, "AttachmentExtensionContext": { "type": "object", "properties": { "type": { "type": "string", "const": "extension_context", "description": "Attachment type discriminator" }, "extensionId": { "type": "string", "description": "Owning extension identifier. Runtime-derived from the caller's connection when produced via session.extensions.sendAttachmentsToMessage; preserved verbatim on subsequent transports." }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier when the push was bound to a canvas instance" }, "instanceId": { "type": "string", "description": "Open canvas instance identifier when the push was bound to a canvas instance" }, "title": { "type": "string", "minLength": 1, "description": "Human-readable composer pill label" }, "payload": { "description": "Caller-supplied JSON payload", "x-opaque-json": true }, "capturedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp captured by the runtime when the push was accepted" } }, "required": [ "type", "extensionId", "title", "capturedAt" ], "additionalProperties": false, "description": "Structured context contributed by an extension. Composer pills displayed in the host are forwarded back through session.send.attachments, then rendered into the model prompt as an XML block.", "title": "AttachmentExtensionContext" }, "AttachmentFile": { "type": "object", "properties": { "type": { "type": "string", "const": "file", "description": "Attachment type discriminator" }, "path": { "type": "string", "description": "Absolute file path" }, "displayName": { "type": "string", "description": "User-facing display name for the attachment" }, "lineRange": { "$ref": "#/definitions/AttachmentFileLineRange", "description": "Optional line range to scope the attachment to a specific section of the file" } }, "required": [ "type", "path", "displayName" ], "additionalProperties": false, "description": "File attachment", "title": "AttachmentFile" }, "AttachmentFileLineRange": { "type": "object", "properties": { "start": { "type": "integer", "exclusiveMinimum": 0, "description": "Start line number (1-based)" }, "end": { "type": "integer", "exclusiveMinimum": 0, "description": "End line number (1-based, inclusive)" } }, "required": [ "start", "end" ], "additionalProperties": false, "description": "Optional line range to scope the attachment to a specific section of the file", "title": "AttachmentFileLineRange" }, "AttachmentGitHubReference": { "type": "object", "properties": { "type": { "type": "string", "const": "github_reference", "description": "Attachment type discriminator" }, "number": { "type": "integer", "exclusiveMinimum": 0, "description": "Issue, pull request, or discussion number" }, "title": { "type": "string", "description": "Title of the referenced item" }, "referenceType": { "$ref": "#/definitions/AttachmentGitHubReferenceType", "description": "Type of GitHub reference" }, "state": { "type": "string", "description": "Current state of the referenced item (e.g., open, closed, merged)" }, "url": { "type": "string", "description": "URL to the referenced item on GitHub" } }, "required": [ "type", "number", "title", "referenceType", "state", "url" ], "additionalProperties": false, "description": "GitHub issue, pull request, or discussion reference", "title": "AttachmentGitHubReference" }, "AttachmentGitHubReferenceType": { "type": "string", "enum": [ "issue", "pr", "discussion" ], "description": "Type of GitHub reference", "title": "AttachmentGitHubReferenceType", "x-enumDescriptions": { "issue": "GitHub issue reference.", "pr": "GitHub pull request reference.", "discussion": "GitHub discussion reference." } }, "AttachmentSelection": { "type": "object", "properties": { "type": { "type": "string", "const": "selection", "description": "Attachment type discriminator" }, "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/AttachmentSelectionDetails", "description": "Position range of the selection within the file" } }, "required": [ "type", "filePath", "displayName", "text", "selection" ], "additionalProperties": false, "description": "Code selection attachment from an editor", "title": "AttachmentSelection" }, "AttachmentSelectionDetails": { "type": "object", "properties": { "start": { "$ref": "#/definitions/AttachmentSelectionDetailsStart", "description": "Start position of the selection" }, "end": { "$ref": "#/definitions/AttachmentSelectionDetailsEnd", "description": "End position of the selection" } }, "required": [ "start", "end" ], "additionalProperties": false, "description": "Position range of the selection within the file", "title": "AttachmentSelectionDetails" }, "AttachmentSelectionDetailsEnd": { "type": "object", "properties": { "line": { "type": "integer", "minimum": 0, "description": "End line number (0-based)" }, "character": { "type": "integer", "minimum": 0, "description": "End character offset within the line (0-based)" } }, "required": [ "line", "character" ], "additionalProperties": false, "description": "End position of the selection", "title": "AttachmentSelectionDetailsEnd" }, "AttachmentSelectionDetailsStart": { "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" ], "additionalProperties": false, "description": "Start position of the selection", "title": "AttachmentSelectionDetailsStart" }, "AuthInfo": { "anyOf": [ { "$ref": "#/definitions/HMACAuthInfo" }, { "$ref": "#/definitions/EnvAuthInfo" }, { "$ref": "#/definitions/TokenAuthInfo" }, { "$ref": "#/definitions/CopilotApiTokenAuthInfo" }, { "$ref": "#/definitions/UserAuthInfo" }, { "$ref": "#/definitions/GhCliAuthInfo" }, { "$ref": "#/definitions/ApiKeyAuthInfo" } ], "description": "Initial authentication info for the session.", "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." } }, "CancelUserRequestedShellCommandResult": { "type": "object", "properties": { "cancelled": { "type": "boolean", "description": "Whether an in-flight execution was found and signalled to cancel" } }, "required": [ "cancelled" ], "additionalProperties": false, "description": "Cancellation result for a user-requested shell command.", "title": "CancelUserRequestedShellCommandResult" }, "CanvasAction": { "type": "object", "properties": { "name": { "type": "string", "description": "Action name exposed by the canvas provider" }, "description": { "type": "string", "description": "Description of the action" }, "inputSchema": { "$ref": "#/definitions/CanvasJsonSchema", "description": "JSON Schema for the action input" } }, "required": [ "name" ], "additionalProperties": false, "description": "Canvas action that the agent or host can invoke. To discover the input schema for a particular action, call the list_canvas_capabilities tool.", "title": "CanvasAction" }, "CanvasActionInvokeRequest": { "type": "object", "properties": { "instanceId": { "type": "string", "description": "Open canvas instance identifier" }, "actionName": { "type": "string", "description": "Action name to invoke" }, "input": { "description": "Action input", "x-opaque-json": true } }, "required": [ "instanceId", "actionName" ], "additionalProperties": false, "description": "Canvas action invocation parameters.", "title": "CanvasActionInvokeRequest" }, "CanvasActionInvokeResult": { "type": "object", "properties": { "result": { "description": "Provider-supplied action result", "x-opaque-json": true } }, "additionalProperties": false, "description": "Canvas action invocation result.", "title": "CanvasActionInvokeResult" }, "CanvasCloseRequest": { "type": "object", "properties": { "instanceId": { "type": "string", "description": "Open canvas instance identifier" } }, "required": [ "instanceId" ], "additionalProperties": false, "description": "Canvas close parameters.", "title": "CanvasCloseRequest" }, "CanvasHostContext": { "type": "object", "properties": { "capabilities": { "$ref": "#/definitions/CanvasHostContextCapabilities", "description": "Host capabilities" } }, "additionalProperties": false, "description": "Host context supplied by the runtime.", "title": "CanvasHostContext" }, "CanvasHostContextCapabilities": { "type": "object", "properties": { "canvases": { "type": "boolean", "description": "Whether canvas rendering is supported" } }, "additionalProperties": false, "description": "Host capabilities", "title": "CanvasHostContextCapabilities" }, "CanvasInstanceAvailability": { "type": "string", "enum": [ "ready", "stale" ], "description": "Runtime-controlled routing state for an open canvas instance.", "title": "CanvasInstanceAvailability", "x-enumDescriptions": { "ready": "The owning provider is currently connected and routing calls will be dispatched normally.", "stale": "The owning provider is not currently connected. Routing calls fail with canvas_provider_unavailable until the agent re-issues open_canvas (which rehydrates via a fresh canvas.open) or the provider reconnects." } }, "CanvasJsonSchema": { "description": "JSON Schema for canvas open input", "title": "CanvasJsonSchema", "x-opaque-json": true }, "CanvasList": { "type": "object", "properties": { "canvases": { "type": "array", "items": { "$ref": "#/definitions/DiscoveredCanvas", "description": "Canvas available in the current session." }, "description": "Declared canvases available in this session" } }, "required": [ "canvases" ], "additionalProperties": false, "description": "Declared canvases available in this session.", "title": "CanvasList" }, "CanvasListOpenResult": { "type": "object", "properties": { "openCanvases": { "type": "array", "items": { "$ref": "#/definitions/OpenCanvasInstance", "description": "Open canvas instance snapshot." }, "description": "Currently open canvas instances" } }, "required": [ "openCanvases" ], "additionalProperties": false, "description": "Live open-canvas snapshot.", "title": "CanvasListOpenResult" }, "CanvasOpenRequest": { "type": "object", "properties": { "extensionId": { "type": "string", "description": "Owning provider identifier. Optional when the canvasId is unique across providers; required to disambiguate when multiple providers register the same canvasId." }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier" }, "instanceId": { "type": "string", "description": "Caller-supplied stable instance identifier" }, "input": { "description": "Canvas open input", "x-opaque-json": true } }, "required": [ "canvasId", "instanceId" ], "additionalProperties": false, "description": "Canvas open parameters.", "title": "CanvasOpenRequest" }, "CanvasProviderCloseRequest": { "type": "object", "properties": { "extensionId": { "type": "string", "description": "Owning provider identifier" }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier" }, "instanceId": { "type": "string", "description": "Canvas instance identifier" }, "host": { "$ref": "#/definitions/CanvasHostContext", "description": "Host context supplied by the runtime." }, "session": { "$ref": "#/definitions/CanvasSessionContext", "description": "Session context supplied by the runtime." } }, "required": [ "extensionId", "canvasId", "instanceId" ], "additionalProperties": false, "description": "Canvas close parameters sent to the provider.", "title": "CanvasProviderCloseRequest" }, "CanvasProviderInvokeActionRequest": { "type": "object", "properties": { "extensionId": { "type": "string", "description": "Owning provider identifier" }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier" }, "instanceId": { "type": "string", "description": "Canvas instance identifier" }, "actionName": { "type": "string", "description": "Action name to invoke" }, "input": { "description": "Action input", "x-opaque-json": true }, "host": { "$ref": "#/definitions/CanvasHostContext", "description": "Host context supplied by the runtime." }, "session": { "$ref": "#/definitions/CanvasSessionContext", "description": "Session context supplied by the runtime." } }, "required": [ "extensionId", "canvasId", "instanceId", "actionName" ], "additionalProperties": false, "description": "Canvas action invocation parameters sent to the provider.", "title": "CanvasProviderInvokeActionRequest" }, "CanvasProviderOpenRequest": { "type": "object", "properties": { "extensionId": { "type": "string", "description": "Owning provider identifier" }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier" }, "instanceId": { "type": "string", "description": "Stable caller-supplied canvas instance identifier" }, "input": { "description": "Canvas open input", "x-opaque-json": true }, "host": { "$ref": "#/definitions/CanvasHostContext", "description": "Host context supplied by the runtime." }, "session": { "$ref": "#/definitions/CanvasSessionContext", "description": "Session context supplied by the runtime." } }, "required": [ "extensionId", "canvasId", "instanceId" ], "additionalProperties": false, "description": "Canvas open parameters sent to the provider.", "title": "CanvasProviderOpenRequest" }, "CanvasProviderOpenResult": { "type": "object", "properties": { "url": { "type": "string", "description": "URL for web-rendered canvases" }, "title": { "type": "string", "description": "Provider-supplied title" }, "status": { "type": "string", "description": "Provider-supplied status text" } }, "additionalProperties": false, "description": "Canvas open result returned by the provider.", "title": "CanvasProviderOpenResult" }, "CanvasSessionContext": { "type": "object", "properties": { "workingDirectory": { "type": "string", "description": "Active session working directory, when known." } }, "additionalProperties": false, "description": "Session context supplied by the runtime.", "title": "CanvasSessionContext" }, "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" }, "ConfigureSessionExtensionsParams": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Session to attach the extension controller delegate to." }, "controller": { "description": "In-process ExtensionController delegate (CLI-only optimization). Marked internal: this field is excluded from the public SDK surface. The post-SDK extension surface exposes list/enable/disable/reload via dedicated RPCs served by the runtime.", "visibility": "internal", "x-opaque-json": true } }, "required": [ "sessionId" ], "additionalProperties": false, "description": "Params to attach or detach an in-process ExtensionController delegate.", "title": "ConfigureSessionExtensionsParams", "visibility": "internal" }, "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": 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": 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." } }, "ContextTier": { "type": "string", "enum": [ "default", "long_context" ], "description": "Context tier for models that support multiple context-window sizes.", "title": "ContextTier", "x-enumDescriptions": { "default": "Use the model's default context window.", "long_context": "Pin the session to the long-context tier when supported." } }, "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", "x-opaque-json": true, "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." }, "contextTier": { "$ref": "#/definitions/ContextTier", "description": "Context tier for models that support multiple context-window sizes." } }, "additionalProperties": false, "description": "The currently selected model, reasoning effort, and context tier for the session. The context tier reflects `Session.getContextTier()`, restored from the session journal on resume.", "title": "CurrentModel" }, "CurrentToolMetadata": { "type": "object", "properties": { "name": { "type": "string", "description": "Model-facing tool name" }, "namespacedName": { "type": "string", "description": "Optional MCP/config namespaced tool name" }, "mcpServerName": { "type": "string", "description": "MCP server name for MCP-backed tools" }, "mcpToolName": { "type": "string", "description": "Raw MCP tool name for MCP-backed tools" }, "description": { "type": "string", "description": "Tool description" }, "input_schema": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "JSON Schema for tool input" }, "deferLoading": { "type": "boolean", "description": "Whether the tool is loaded on demand via tool search" } }, "required": [ "name", "description" ], "additionalProperties": false, "description": "Lightweight metadata for a currently initialized session tool", "title": "CurrentToolMetadata" }, "DiscoveredCanvas": { "type": "object", "properties": { "displayName": { "type": "string", "description": "Human-readable canvas name" }, "description": { "type": "string", "minLength": 1, "description": "Short, single-sentence description shown to the agent in canvas catalogs." }, "inputSchema": { "$ref": "#/definitions/CanvasJsonSchema", "description": "JSON Schema for canvas open input" }, "actions": { "type": "array", "items": { "$ref": "#/definitions/CanvasAction", "description": "Canvas action that the agent or host can invoke. To discover the input schema for a particular action, call the list_canvas_capabilities tool." }, "description": "Actions the agent or host may invoke on an open instance" }, "extensionId": { "type": "string", "description": "Owning provider identifier" }, "extensionName": { "type": "string", "description": "Owning extension display name, when available" }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier" } }, "required": [ "displayName", "description", "extensionId", "canvasId" ], "additionalProperties": false, "description": "Canvas available in the current session.", "title": "DiscoveredCanvas" }, "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 (deprecated), 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 (deprecated), 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 (deprecated).", "memory": "Server is backed by an in-memory runtime implementation." } }, "EmbeddedBlobResourceContents": { "type": "object", "properties": { "uri": { "type": "string", "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", "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": 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", "x-opaque-json": true }, "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', 'plugin:my-plugin:my-ext')" }, "name": { "type": "string", "description": "Extension name (directory name)" }, "source": { "$ref": "#/definitions/ExtensionSource", "description": "Discovery source: project (.github/extensions/), user (~/.copilot/extensions/), plugin (installed plugin), or session (session-state//extensions/)" }, "status": { "$ref": "#/definitions/ExtensionStatus", "description": "Current status: running, disabled, failed, or starting" }, "pid": { "type": "integer", "exclusiveMinimum": 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." }, "ExtensionContextPushInput": { "type": "object", "properties": { "type": { "type": "string", "const": "extension_context", "description": "Attachment type discriminator" }, "title": { "type": "string", "minLength": 1, "description": "Human-readable composer pill label" }, "payload": { "description": "Caller-supplied JSON payload (required, may be null but not undefined)", "x-opaque-json": true } }, "required": [ "type", "title", "payload" ], "additionalProperties": false, "description": "Slim input shape for extension_context attachments; identity fields are runtime-derived.", "title": "ExtensionContextPushInput" }, "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", "plugin", "session" ], "description": "Discovery source: project (.github/extensions/), user (~/.copilot/extensions/), plugin (installed plugin), or session (session-state//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.", "plugin": "Extension contributed by an installed plugin.", "session": "Extension discovered from the current session's state directory (loaded only for this session)." } }, "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", "x-opaque-json": true }, "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": { "x-opaque-json": true }, "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" }, "metadata": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "Optional metadata from the producing tool." } }, "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", "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", "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", "x-opaque-json": true }, "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" }, "HistoryCompactRequest": { "anyOf": [ { "not": {} }, { "type": "object", "properties": { "customInstructions": { "type": "string", "maxLength": 4000, "description": "Optional user-provided instructions to focus the compaction summary" } }, "additionalProperties": false } ], "description": "Optional compaction parameters.", "title": "HistoryCompactRequest" }, "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." }, "InstalledPluginInfo": { "type": "object", "properties": { "name": { "type": "string", "description": "Plugin name" }, "marketplace": { "type": "string", "description": "Marketplace the plugin came from. Empty string (\"\") for direct repo / URL / local installs." }, "version": { "type": "string", "description": "Installed version (when reported by the plugin manifest)" }, "enabled": { "type": "boolean", "description": "Whether the plugin is currently enabled for new sessions" } }, "required": [ "name", "marketplace", "enabled" ], "additionalProperties": false, "description": "Information about an installed plugin tracked in global state.", "title": "InstalledPluginInfo" }, "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", "x-opaque-json": true, "stability": "experimental" }, "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." }, "InstructionsDiscoverRequest": { "type": "object", "properties": { "projectPaths": { "type": "array", "items": { "type": "string" }, "description": "Optional list of project directory paths to scan for repository/working-directory instruction sources. When omitted or empty, only user-level and plugin instruction sources are returned (no project scan)." }, "excludeHostInstructions": { "type": "boolean", "description": "When true, omit the host's instruction sources (user/home-level files and plugin rules), leaving only repository and working-directory sources. For multitenant deployments." } }, "additionalProperties": false, "description": "Optional project paths to include in instruction discovery.", "title": "InstructionsDiscoverRequest" }, "InstructionsGetSourcesResult": { "type": "object", "properties": { "sources": { "type": "array", "items": { "$ref": "#/definitions/InstructionSource" }, "description": "Instruction sources for the session" } }, "required": [ "sources" ], "additionalProperties": false, "description": "Instruction sources loaded for the session, in merge order.", "title": "InstructionsGetSourcesResult" }, "InstructionSource": { "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/InstructionSourceType", "description": "Category of instruction source — used for merge logic" }, "location": { "$ref": "#/definitions/InstructionSourceLocation", "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" }, "projectPath": { "type": "string", "description": "The project path this source was discovered from. Only set by sessionless discovery for repository/working-directory sources, where it disambiguates same-named files (e.g. .github/copilot-instructions.md) across multiple workspace roots. The session-scoped getSources leaves it unset." } }, "required": [ "id", "label", "sourcePath", "content", "type", "location" ], "additionalProperties": false, "title": "InstructionSource", "description": "Schema for the `InstructionSource` type." }, "InstructionSourceLocation": { "type": "string", "enum": [ "user", "repository", "working-directory", "plugin" ], "description": "Where this source lives — used for UI grouping", "title": "InstructionSourceLocation", "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." } }, "InstructionSourceType": { "type": "string", "enum": [ "home", "repo", "model", "vscode", "nested-agents", "child-instructions", "plugin" ], "description": "Category of instruction source — used for merge logic", "title": "InstructionSourceType", "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." } }, "LocalSessionMetadataValue": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Stable session identifier" }, "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" }, "clientName": { "type": "string", "description": "Runtime client name that created/last resumed this session" }, "isRemote": { "type": "boolean", "const": false, "description": "Always false for local sessions." }, "isDetached": { "type": "boolean", "description": "True for detached maintenance sessions that should be hidden from normal resume lists." }, "context": { "$ref": "#/definitions/SessionContext", "description": "Pre-resolved working-directory context for session startup." }, "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": [ "sessionId", "startTime", "modifiedTime", "isRemote" ], "additionalProperties": false, "title": "LocalSessionMetadataValue", "description": "Schema for the `LocalSessionMetadataValue` type." }, "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" }, "MarketplaceAddResult": { "type": "object", "properties": { "name": { "type": "string", "description": "Final name of the marketplace as resolved from its manifest" } }, "required": [ "name" ], "additionalProperties": false, "description": "Result of registering a new marketplace.", "title": "MarketplaceAddResult" }, "MarketplaceBrowseResult": { "type": "object", "properties": { "plugins": { "type": "array", "items": { "$ref": "#/definitions/MarketplacePluginInfo", "description": "Plugin entry advertised by a marketplace." }, "description": "Plugins advertised by the marketplace" } }, "required": [ "plugins" ], "additionalProperties": false, "description": "Plugins advertised by the marketplace.", "title": "MarketplaceBrowseResult" }, "MarketplaceInfo": { "type": "object", "properties": { "name": { "type": "string", "description": "Marketplace name (matches the @marketplace suffix in plugin specs)" }, "source": { "type": "string", "description": "Human-readable description of where the marketplace data is fetched from (e.g. \"GitHub: owner/repo\")." }, "isDefault": { "type": "boolean", "description": "True when this is a default marketplace shipped with the runtime. Defaults are not removable." } }, "required": [ "name", "source" ], "additionalProperties": false, "description": "Registered marketplace summary.", "title": "MarketplaceInfo" }, "MarketplaceListResult": { "type": "object", "properties": { "marketplaces": { "type": "array", "items": { "$ref": "#/definitions/MarketplaceInfo", "description": "Registered marketplace summary." }, "description": "Registered marketplaces" } }, "required": [ "marketplaces" ], "additionalProperties": false, "description": "All registered marketplaces, including built-in defaults.", "title": "MarketplaceListResult" }, "MarketplacePluginInfo": { "type": "object", "properties": { "name": { "type": "string", "description": "Plugin name as listed in the marketplace catalog" }, "description": { "type": "string", "description": "Short description from the marketplace catalog, when present" } }, "required": [ "name" ], "additionalProperties": false, "description": "Plugin entry advertised by a marketplace.", "title": "MarketplacePluginInfo" }, "MarketplaceRefreshEntry": { "type": "object", "properties": { "name": { "type": "string", "description": "Marketplace name that was refreshed" }, "success": { "type": "boolean", "description": "Whether the refresh succeeded" }, "error": { "type": "string", "description": "Error message (failure only)" } }, "required": [ "name", "success" ], "additionalProperties": false, "title": "MarketplaceRefreshEntry", "description": "Schema for the `MarketplaceRefreshEntry` type." }, "MarketplaceRefreshResult": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/definitions/MarketplaceRefreshEntry" }, "description": "Per-marketplace refresh results in deterministic order." } }, "required": [ "results" ], "additionalProperties": false, "description": "Result of refreshing one or more marketplace catalogs.", "title": "MarketplaceRefreshResult" }, "MarketplaceRemoveResult": { "type": "object", "properties": { "removed": { "type": "boolean", "description": "True when the marketplace was actually removed. False when removal was skipped because the marketplace has dependent plugins and `force` was not set." }, "dependentPlugins": { "type": "array", "items": { "type": "string" }, "description": "Names of installed plugins that prevented removal. Populated only when `removed=false`." } }, "required": [ "removed" ], "additionalProperties": false, "description": "Outcome of the remove attempt, including dependent-plugin info when applicable.", "title": "MarketplaceRemoveResult" }, "McpAllowedServer": { "type": "object", "properties": { "name": { "type": "string", "description": "Allowed server name" }, "redactedNote": { "type": "string", "description": "PII-free note explaining why the server was allowed" } }, "required": [ "name" ], "additionalProperties": false, "title": "McpAllowedServer", "description": "Schema for the `McpAllowedServer` type." }, "McpAppsCallToolRequest": { "type": "object", "properties": { "serverName": { "type": "string", "minLength": 1, "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", "description": "MCP server hosting the tool" }, "toolName": { "type": "string", "description": "MCP tool name" }, "arguments": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "Tool arguments" }, "originServerName": { "type": "string", "minLength": 1, "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", "description": "**Required.** Server whose ui:// view issued the request. Per SEP-1865 ('callable by the app from this server only'), the call is rejected when this differs from `serverName`, and rejected outright when missing." } }, "required": [ "serverName", "toolName", "originServerName" ], "additionalProperties": false, "description": "MCP server, tool name, and arguments to invoke from an MCP App view.", "title": "McpAppsCallToolRequest" }, "McpAppsDiagnoseCapability": { "type": "object", "properties": { "sessionHasMcpApps": { "type": "boolean", "description": "Whether the session has the `mcp-apps` capability" }, "featureFlagEnabled": { "type": "boolean", "description": "Whether the MCP_APPS feature flag (or COPILOT_MCP_APPS env override) is on" }, "advertised": { "type": "boolean", "description": "Whether the runtime advertises `extensions.io.modelcontextprotocol/ui` to MCP servers" } }, "required": [ "sessionHasMcpApps", "featureFlagEnabled", "advertised" ], "additionalProperties": false, "description": "Capability negotiation snapshot", "title": "McpAppsDiagnoseCapability" }, "McpAppsDiagnoseRequest": { "type": "object", "properties": { "serverName": { "type": "string", "minLength": 1, "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", "description": "MCP server to probe" } }, "required": [ "serverName" ], "additionalProperties": false, "description": "MCP server to diagnose MCP Apps wiring for.", "title": "McpAppsDiagnoseRequest" }, "McpAppsDiagnoseResult": { "type": "object", "properties": { "capability": { "$ref": "#/definitions/McpAppsDiagnoseCapability", "description": "Capability negotiation snapshot" }, "server": { "$ref": "#/definitions/McpAppsDiagnoseServer", "description": "What the server returned for this session" } }, "required": [ "capability", "server" ], "additionalProperties": false, "description": "Diagnostic snapshot of MCP Apps wiring for the named server.", "title": "McpAppsDiagnoseResult" }, "McpAppsDiagnoseServer": { "type": "object", "properties": { "connected": { "type": "boolean", "description": "Whether the named server is currently connected" }, "toolCount": { "type": "number", "description": "Total tools returned by the server's tools/list" }, "toolsWithUiMeta": { "type": "number", "description": "Tools whose `_meta.ui` is populated (resourceUri and/or visibility set)" }, "sampleToolNames": { "type": "array", "items": { "type": "string" }, "description": "Up to 5 tool names with `_meta.ui` for quick inspection" } }, "required": [ "connected", "toolCount", "toolsWithUiMeta", "sampleToolNames" ], "additionalProperties": false, "description": "What the server returned for this session", "title": "McpAppsDiagnoseServer" }, "McpAppsHostContext": { "type": "object", "properties": { "context": { "$ref": "#/definitions/McpAppsHostContextDetails", "description": "Current host context" } }, "required": [ "context" ], "additionalProperties": false, "description": "Current host context advertised to MCP App guests.", "title": "McpAppsHostContext" }, "McpAppsHostContextDetails": { "type": "object", "properties": { "theme": { "$ref": "#/definitions/McpAppsHostContextDetailsTheme", "description": "UI theme preference per SEP-1865" }, "locale": { "type": "string", "description": "BCP-47 locale, e.g. 'en-US'" }, "timeZone": { "type": "string", "description": "IANA timezone, e.g. 'America/New_York'" }, "displayMode": { "$ref": "#/definitions/McpAppsHostContextDetailsDisplayMode", "description": "Current display mode (SEP-1865)" }, "availableDisplayModes": { "type": "array", "items": { "$ref": "#/definitions/McpAppsHostContextDetailsAvailableDisplayMode" }, "description": "Display modes the host supports" }, "platform": { "$ref": "#/definitions/McpAppsHostContextDetailsPlatform", "description": "Platform type for responsive design" }, "userAgent": { "type": "string", "description": "Host application identifier" } }, "additionalProperties": {}, "description": "Current host context", "title": "McpAppsHostContextDetails" }, "McpAppsHostContextDetailsAvailableDisplayMode": { "type": "string", "enum": [ "inline", "fullscreen", "pip" ], "title": "McpAppsHostContextDetailsAvailableDisplayMode", "x-enumDescriptions": { "inline": "Rendered inline within the host conversation surface", "fullscreen": "Rendered as a fullscreen overlay", "pip": "Rendered as a picture-in-picture floating panel" }, "description": "Allowed values for the `McpAppsHostContextDetailsAvailableDisplayMode` enumeration." }, "McpAppsHostContextDetailsDisplayMode": { "type": "string", "enum": [ "inline", "fullscreen", "pip" ], "description": "Current display mode (SEP-1865)", "title": "McpAppsHostContextDetailsDisplayMode", "x-enumDescriptions": { "inline": "Rendered inline within the host conversation surface", "fullscreen": "Rendered as a fullscreen overlay", "pip": "Rendered as a picture-in-picture floating panel" } }, "McpAppsHostContextDetailsPlatform": { "type": "string", "enum": [ "web", "desktop", "mobile" ], "description": "Platform type for responsive design", "title": "McpAppsHostContextDetailsPlatform", "x-enumDescriptions": { "web": "Host runs in a web browser", "desktop": "Host runs as a desktop application", "mobile": "Host runs on a mobile device" } }, "McpAppsHostContextDetailsTheme": { "type": "string", "enum": [ "light", "dark" ], "description": "UI theme preference per SEP-1865", "title": "McpAppsHostContextDetailsTheme", "x-enumDescriptions": { "light": "Light UI theme", "dark": "Dark UI theme" } }, "McpAppsListToolsRequest": { "type": "object", "properties": { "serverName": { "type": "string", "minLength": 1, "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", "description": "MCP server hosting the app" }, "originServerName": { "type": "string", "minLength": 1, "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", "description": "**Required.** Server whose ui:// view issued the request. Per SEP-1865 ('callable by the app from this server only'), the call is rejected when this differs from `serverName`, and rejected outright when missing." } }, "required": [ "serverName", "originServerName" ], "additionalProperties": false, "description": "MCP server to list app-callable tools for.", "title": "McpAppsListToolsRequest" }, "McpAppsListToolsResult": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "x-opaque-json": true } }, "description": "App-callable tools from the server" } }, "required": [ "tools" ], "additionalProperties": false, "description": "App-callable tools from the named MCP server.", "title": "McpAppsListToolsResult" }, "McpAppsReadResourceRequest": { "type": "object", "properties": { "serverName": { "type": "string", "minLength": 1, "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", "description": "Name of the MCP server hosting the resource" }, "uri": { "type": "string", "description": "Resource URI (typically ui://...)" } }, "required": [ "serverName", "uri" ], "additionalProperties": false, "description": "MCP server and resource URI to fetch.", "title": "McpAppsReadResourceRequest" }, "McpAppsReadResourceResult": { "type": "object", "properties": { "contents": { "type": "array", "items": { "$ref": "#/definitions/McpAppsResourceContent" }, "description": "Resource contents returned by the server" } }, "required": [ "contents" ], "additionalProperties": false, "description": "Resource contents returned by the MCP server.", "title": "McpAppsReadResourceResult" }, "McpAppsResourceContent": { "type": "object", "properties": { "uri": { "type": "string", "description": "The resource URI (typically ui://...)" }, "mimeType": { "type": "string", "description": "MIME type of the content" }, "text": { "type": "string", "description": "Text content (e.g. HTML)" }, "blob": { "type": "string", "description": "Base64-encoded binary content" }, "_meta": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "Resource-level metadata (CSP, permissions, etc.)" } }, "required": [ "uri" ], "additionalProperties": false, "title": "McpAppsResourceContent", "description": "Schema for the `McpAppsResourceContent` type." }, "McpAppsSetHostContextDetails": { "type": "object", "properties": { "theme": { "$ref": "#/definitions/McpAppsSetHostContextDetailsTheme", "description": "UI theme preference per SEP-1865" }, "locale": { "type": "string", "description": "BCP-47 locale, e.g. 'en-US'" }, "timeZone": { "type": "string", "description": "IANA timezone, e.g. 'America/New_York'" }, "displayMode": { "$ref": "#/definitions/McpAppsSetHostContextDetailsDisplayMode", "description": "Current display mode (SEP-1865)" }, "availableDisplayModes": { "type": "array", "items": { "$ref": "#/definitions/McpAppsSetHostContextDetailsAvailableDisplayMode" }, "description": "Display modes the host supports" }, "platform": { "$ref": "#/definitions/McpAppsSetHostContextDetailsPlatform", "description": "Platform type for responsive design" }, "userAgent": { "type": "string", "description": "Host application identifier" } }, "additionalProperties": {}, "description": "Host context advertised to MCP App guests", "title": "McpAppsSetHostContextDetails" }, "McpAppsSetHostContextDetailsAvailableDisplayMode": { "type": "string", "enum": [ "inline", "fullscreen", "pip" ], "title": "McpAppsSetHostContextDetailsAvailableDisplayMode", "x-enumDescriptions": { "inline": "Rendered inline within the host conversation surface", "fullscreen": "Rendered as a fullscreen overlay", "pip": "Rendered as a picture-in-picture floating panel" }, "description": "Allowed values for the `McpAppsSetHostContextDetailsAvailableDisplayMode` enumeration." }, "McpAppsSetHostContextDetailsDisplayMode": { "type": "string", "enum": [ "inline", "fullscreen", "pip" ], "description": "Current display mode (SEP-1865)", "title": "McpAppsSetHostContextDetailsDisplayMode", "x-enumDescriptions": { "inline": "Rendered inline within the host conversation surface", "fullscreen": "Rendered as a fullscreen overlay", "pip": "Rendered as a picture-in-picture floating panel" } }, "McpAppsSetHostContextDetailsPlatform": { "type": "string", "enum": [ "web", "desktop", "mobile" ], "description": "Platform type for responsive design", "title": "McpAppsSetHostContextDetailsPlatform", "x-enumDescriptions": { "web": "Host runs in a web browser", "desktop": "Host runs as a desktop application", "mobile": "Host runs on a mobile device" } }, "McpAppsSetHostContextDetailsTheme": { "type": "string", "enum": [ "light", "dark" ], "description": "UI theme preference per SEP-1865", "title": "McpAppsSetHostContextDetailsTheme", "x-enumDescriptions": { "light": "Light UI theme", "dark": "Dark UI theme" } }, "McpAppsSetHostContextRequest": { "type": "object", "properties": { "context": { "$ref": "#/definitions/McpAppsSetHostContextDetails", "description": "Host context advertised to MCP App guests" } }, "required": [ "context" ], "additionalProperties": false, "description": "Host context to advertise to MCP App guests.", "title": "McpAppsSetHostContextRequest" }, "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" }, "McpConfigureGitHubRequest": { "type": "object", "properties": { "authInfo": { "description": "Opaque runtime auth info for GitHub MCP configuration. Marked internal: an in-process runtime shape (configureGitHubMcp is a no-op over the wire).", "visibility": "internal", "x-opaque-json": true } }, "required": [ "authInfo" ], "additionalProperties": false, "description": "Opaque auth info used to configure GitHub MCP.", "title": "McpConfigureGitHubRequest", "visibility": "internal" }, "McpConfigureGitHubResult": { "type": "object", "properties": { "changed": { "type": "boolean", "description": "Whether GitHub MCP configuration changed." } }, "required": [ "changed" ], "additionalProperties": false, "description": "Result of configuring GitHub MCP.", "title": "McpConfigureGitHubResult" }, "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).", "x-opaque-json": true }, "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", "x-opaque-json": true }, "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", "x-opaque-json": true, "stability": "experimental" }, "McpFilteredServer": { "type": "object", "properties": { "name": { "type": "string", "description": "Filtered server name" }, "reason": { "type": "string", "description": "Human-readable filter reason" }, "redactedReason": { "type": "string", "description": "PII-free filter reason" }, "enterpriseName": { "type": "string", "description": "Enterprise login associated with an allowlist policy" } }, "required": [ "name", "reason" ], "additionalProperties": false, "title": "McpFilteredServer", "description": "Schema for the `McpFilteredServer` type." }, "McpHostState": { "type": "object", "properties": { "mcp3pEnabled": { "type": "boolean", "description": "Whether third-party MCP servers are policy-enabled for this session." }, "disabledServers": { "type": "array", "items": { "type": "string" }, "description": "Configured servers that are explicitly disabled." }, "filteredServers": { "type": "array", "items": { "type": "string" }, "description": "Configured servers filtered out by enterprise allowlist policy." }, "clients": { "type": "array", "items": { "type": "string" }, "description": "Names of currently-connected MCP clients." }, "pendingConnections": { "type": "array", "items": { "type": "string" }, "description": "Names of servers with in-flight connection attempts." }, "failedServers": { "type": "object", "additionalProperties": { "$ref": "#/definitions/McpServerFailureInfo", "description": "Recorded MCP server connection failure." }, "description": "Map of server name to recorded connection failure." }, "needsAuthServers": { "type": "object", "additionalProperties": { "$ref": "#/definitions/McpServerNeedsAuthInfo", "description": "Recorded MCP server pending-auth state." }, "description": "Map of server name to recorded pending-auth state." } }, "required": [ "mcp3pEnabled", "disabledServers", "filteredServers", "clients", "pendingConnections", "failedServers", "needsAuthServers" ], "additionalProperties": false, "description": "Host-level state, omitted when no MCP host is initialized.", "title": "McpHostState" }, "McpIsServerRunningRequest": { "type": "object", "properties": { "serverName": { "type": "string", "description": "Name of the MCP server to check" } }, "required": [ "serverName" ], "additionalProperties": false, "description": "Server name to check running status for.", "title": "McpIsServerRunningRequest" }, "McpIsServerRunningResult": { "type": "object", "properties": { "running": { "type": "boolean", "description": "True if the server has an active client and transport." } }, "required": [ "running" ], "additionalProperties": false, "description": "Whether the named MCP server is running.", "title": "McpIsServerRunningResult" }, "McpListToolsRequest": { "type": "object", "properties": { "serverName": { "type": "string", "minLength": 1, "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$", "description": "Name of the connected MCP server whose tools to list." } }, "required": [ "serverName" ], "additionalProperties": false, "description": "Server name whose tool list should be returned.", "title": "McpListToolsRequest" }, "McpListToolsResult": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/definitions/McpTools" }, "description": "Tools exposed by the server." } }, "required": [ "tools" ], "additionalProperties": false, "description": "Tools exposed by the connected MCP server. Throws when the server is not connected.", "title": "McpListToolsResult" }, "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" }, "McpOauthRespondRequest": { "type": "object", "properties": { "requestId": { "type": "string", "description": "OAuth request identifier from mcp.oauth_required" }, "provider": { "description": "In-process OAuthClientProvider instance, or omitted to deny. Marked internal: cannot be serialized across the JSON-RPC boundary.", "visibility": "internal", "x-opaque-json": true } }, "required": [ "requestId" ], "additionalProperties": false, "description": "MCP OAuth request id and optional provider response.", "title": "McpOauthRespondRequest", "visibility": "internal" }, "McpOauthRespondResult": { "type": "object", "properties": {}, "additionalProperties": false, "description": "Empty result after recording the MCP OAuth response.", "title": "McpOauthRespondResult" }, "McpRegisterExternalClientRequest": { "type": "object", "properties": { "serverName": { "type": "string", "description": "Logical server name for the external client" }, "client": { "description": "In-process MCP Client instance. Marked internal: cannot be serialized across the JSON-RPC boundary.", "visibility": "internal", "x-opaque-json": true }, "transport": { "description": "In-process MCP Transport instance. Marked internal: cannot be serialized across the JSON-RPC boundary.", "visibility": "internal", "x-opaque-json": true }, "config": { "description": "In-process server config (MCPServerConfig) paired with the in-process client/transport. Marked internal alongside its companions.", "visibility": "internal", "x-opaque-json": true } }, "required": [ "serverName", "client", "transport", "config" ], "additionalProperties": false, "description": "Registration parameters for an external MCP client.", "title": "McpRegisterExternalClientRequest", "visibility": "internal" }, "McpReloadWithConfigRequest": { "type": "object", "properties": { "config": { "description": "Opaque runtime MCP reload configuration. Marked internal: an in-process runtime shape (reloadMcpServers throws over the wire).", "visibility": "internal", "x-opaque-json": true } }, "required": [ "config" ], "additionalProperties": false, "description": "Opaque MCP reload configuration.", "title": "McpReloadWithConfigRequest", "visibility": "internal" }, "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" }, "McpRestartServerRequest": { "type": "object", "properties": { "serverName": { "type": "string", "description": "Name of the MCP server to restart" }, "config": { "description": "Opaque server configuration (MCPServerConfig). Marked internal: an in-process runtime shape supplied only by in-process CLI callers.", "visibility": "internal", "x-opaque-json": true } }, "required": [ "serverName", "config" ], "additionalProperties": false, "description": "Server name and opaque configuration for an individual MCP server restart.", "title": "McpRestartServerRequest", "visibility": "internal" }, "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." }, "McpServerAuthConfig": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/definitions/McpServerAuthConfigRedirectPort", "description": "Authentication settings with optional redirect port configuration." } ], "description": "Set to `true` to use defaults, or provide an object with additional auth or OIDC settings.", "title": "McpServerAuthConfig", "x-opaque-json": true }, "McpServerAuthConfigRedirectPort": { "type": "object", "properties": { "redirectPort": { "type": "integer", "minimum": 1, "maximum": 65535, "description": "Fixed port for the OAuth redirect callback server." } }, "additionalProperties": true, "description": "Authentication settings with optional redirect port configuration.", "title": "McpServerAuthConfigRedirectPort" }, "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", "x-opaque-json": true }, "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": 0, "description": "Timeout in milliseconds for tool calls to this server.", "format": "duration" }, "oidc": { "$ref": "#/definitions/McpServerAuthConfig", "description": "Set to `true` to use defaults, or provide an object with additional auth or OIDC settings." }, "auth": { "$ref": "#/definitions/McpServerAuthConfig", "description": "Set to `true` to use defaults, or provide an object with additional auth or OIDC settings." }, "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." } }, "required": [ "url" ], "additionalProperties": false, "description": "Remote MCP server configuration accessed over HTTP or SSE.", "title": "McpServerConfigHttp" }, "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": 0, "description": "Timeout in milliseconds for tool calls to this server.", "format": "duration" }, "oidc": { "$ref": "#/definitions/McpServerAuthConfig", "description": "Set to `true` to use defaults, or provide an object with additional auth or OIDC settings." }, "auth": { "$ref": "#/definitions/McpServerAuthConfig", "description": "Set to `true` to use defaults, or provide an object with additional auth or OIDC settings." }, "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" }, "McpServerFailureInfo": { "type": "object", "properties": { "message": { "type": "string", "description": "Failure message produced when the MCP server connection failed." }, "timestamp": { "type": "integer", "minimum": 0, "description": "epoch-ms timestamp at which the failure was recorded." } }, "required": [ "message", "timestamp" ], "additionalProperties": false, "description": "Recorded MCP server connection failure.", "title": "McpServerFailureInfo" }, "McpServerList": { "type": "object", "properties": { "servers": { "type": "array", "items": { "$ref": "#/definitions/McpServer" }, "description": "Configured MCP servers" }, "host": { "$ref": "#/definitions/McpHostState", "description": "Host-level state, omitted when no MCP host is initialized." } }, "required": [ "servers" ], "additionalProperties": false, "description": "MCP servers configured for the session, with their connection status and host-level state.", "title": "McpServerList" }, "McpServerNeedsAuthInfo": { "type": "object", "properties": { "timestamp": { "type": "integer", "minimum": 0, "description": "epoch-ms timestamp at which the server signalled it needs authentication." } }, "required": [ "timestamp" ], "additionalProperties": false, "description": "Recorded MCP server pending-auth state.", "title": "McpServerNeedsAuthInfo" }, "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" }, "McpStartServerRequest": { "type": "object", "properties": { "serverName": { "type": "string", "description": "Name of the MCP server to start" }, "config": { "description": "Opaque server configuration (MCPServerConfig). Marked internal: an in-process runtime shape supplied only by in-process CLI callers.", "visibility": "internal", "x-opaque-json": true } }, "required": [ "serverName", "config" ], "additionalProperties": false, "description": "Server name and opaque configuration for an individual MCP server start.", "title": "McpStartServerRequest", "visibility": "internal" }, "McpStartServersResult": { "type": "object", "properties": { "filteredServers": { "type": "array", "items": { "$ref": "#/definitions/McpFilteredServer" }, "description": "Servers filtered out before startup" }, "allowedServers": { "type": "array", "items": { "$ref": "#/definitions/McpAllowedServer" }, "description": "Non-default servers allowed by policy" } }, "required": [ "filteredServers" ], "additionalProperties": false, "description": "MCP server startup filtering result.", "title": "McpStartServersResult" }, "McpStopServerRequest": { "type": "object", "properties": { "serverName": { "type": "string", "description": "Name of the MCP server to stop" } }, "required": [ "serverName" ], "additionalProperties": false, "description": "Server name for an individual MCP server stop.", "title": "McpStopServerRequest" }, "McpTools": { "type": "object", "properties": { "name": { "type": "string", "description": "Tool name." }, "description": { "type": "string", "description": "Tool description, when provided." } }, "required": [ "name" ], "additionalProperties": false, "title": "McpTools", "description": "Schema for the `McpTools` type." }, "McpUnregisterExternalClientRequest": { "type": "object", "properties": { "serverName": { "type": "string", "description": "Server name of the external client to unregister" } }, "required": [ "serverName" ], "additionalProperties": false, "description": "Server name identifying the external client to remove.", "title": "McpUnregisterExternalClientRequest", "visibility": "internal" }, "MemoryConfiguration": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether memory is enabled for the session." } }, "required": [ "enabled" ], "additionalProperties": false, "description": "Memory configuration for this session.", "title": "MemoryConfiguration" }, "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": 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": "number", "minimum": 0, "description": "AI Credits cost per billing batch of input tokens" }, "outputPrice": { "type": "number", "minimum": 0, "description": "AI Credits cost per billing batch of output tokens" }, "cachePrice": { "type": "number", "minimum": 0, "description": "AI Credits cost per billing batch of cached tokens" }, "batchSize": { "type": "integer", "exclusiveMinimum": 0, "description": "Number of tokens per standard billing batch" }, "contextMax": { "type": "integer", "description": "Prompt token budget (max_prompt_tokens) for the default tier. The total context window is this value plus the model's max_output_tokens." }, "longContext": { "$ref": "#/definitions/ModelBillingTokenPricesLongContext", "description": "Long context tier pricing (available for models with extended context windows)" } }, "additionalProperties": false, "description": "Token-level pricing information for this model", "title": "ModelBillingTokenPrices" }, "ModelBillingTokenPricesLongContext": { "type": "object", "properties": { "inputPrice": { "type": "number", "minimum": 0, "description": "AI Credits cost per billing batch of input tokens" }, "outputPrice": { "type": "number", "minimum": 0, "description": "AI Credits cost per billing batch of output tokens" }, "cachePrice": { "type": "number", "minimum": 0, "description": "AI Credits cost per billing batch of cached tokens" }, "contextMax": { "type": "integer", "description": "Prompt token budget (max_prompt_tokens) for the long context tier. The total context window is this value plus the model's max_output_tokens." } }, "additionalProperties": false, "description": "Long context tier pricing (available for models with extended context windows)", "title": "ModelBillingTokenPricesLongContext" }, "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": "Initial model capability overrides.", "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" }, "ModelListRequest": { "anyOf": [ { "not": {} }, { "type": "object", "properties": { "skipCache": { "type": "boolean", "description": "If true, bypasses the per-session model list cache and re-fetches from CAPI." } }, "additionalProperties": false } ], "description": "Optional listing options.", "title": "ModelListRequest" }, "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" }, "contextTier": { "$ref": "#/definitions/ContextTier", "description": "Explicit context tier for the selected model. `\"default\"` / `\"long_context\"` apply the requested tier; omit this field to use normal model behavior with no explicit tier." } }, "required": [ "modelId" ], "additionalProperties": false, "description": "Target model identifier and optional reasoning effort, summary, capability overrides, and context tier.", "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" }, "OpenCanvasInstance": { "type": "object", "properties": { "instanceId": { "type": "string", "description": "Stable caller-supplied canvas instance identifier" }, "extensionId": { "type": "string", "description": "Owning provider identifier" }, "extensionName": { "type": "string", "description": "Owning extension display name, when available" }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier" }, "title": { "type": "string", "description": "Rendered title" }, "status": { "type": "string", "description": "Provider-supplied status text" }, "url": { "type": "string", "description": "URL for web-rendered canvases" }, "input": { "description": "Input supplied when the instance was opened", "x-opaque-json": true }, "reopen": { "type": "boolean", "description": "Whether this snapshot came from an idempotent reopen" }, "availability": { "$ref": "#/definitions/CanvasInstanceAvailability", "description": "Runtime-controlled routing state for an open canvas instance." } }, "required": [ "instanceId", "extensionId", "canvasId", "reopen", "availability" ], "additionalProperties": false, "description": "Open canvas instance snapshot.", "title": "OpenCanvasInstance" }, "OptionsUpdateAdditionalContentExclusionPolicy": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/definitions/OptionsUpdateAdditionalContentExclusionPolicyRule" } }, "last_updated_at": { "type": [ "string", "number" ], "x-opaque-json": true }, "scope": { "$ref": "#/definitions/OptionsUpdateAdditionalContentExclusionPolicyScope", "description": "Allowed values for the `OptionsUpdateAdditionalContentExclusionPolicyScope` enumeration." } }, "required": [ "rules", "last_updated_at", "scope" ], "additionalProperties": true, "title": "OptionsUpdateAdditionalContentExclusionPolicy", "description": "Schema for the `OptionsUpdateAdditionalContentExclusionPolicy` type." }, "OptionsUpdateAdditionalContentExclusionPolicyRule": { "type": "object", "properties": { "paths": { "type": "array", "items": { "type": "string" } }, "ifAnyMatch": { "type": "array", "items": { "type": "string" } }, "ifNoneMatch": { "type": "array", "items": { "type": "string" } }, "source": { "$ref": "#/definitions/OptionsUpdateAdditionalContentExclusionPolicyRuleSource", "description": "Schema for the `OptionsUpdateAdditionalContentExclusionPolicyRuleSource` type." } }, "required": [ "paths", "source" ], "additionalProperties": true, "title": "OptionsUpdateAdditionalContentExclusionPolicyRule", "description": "Schema for the `OptionsUpdateAdditionalContentExclusionPolicyRule` type." }, "OptionsUpdateAdditionalContentExclusionPolicyRuleSource": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type" ], "additionalProperties": false, "title": "OptionsUpdateAdditionalContentExclusionPolicyRuleSource", "description": "Schema for the `OptionsUpdateAdditionalContentExclusionPolicyRuleSource` type." }, "OptionsUpdateAdditionalContentExclusionPolicyScope": { "type": "string", "enum": [ "repo", "all" ], "title": "OptionsUpdateAdditionalContentExclusionPolicyScope", "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 `OptionsUpdateAdditionalContentExclusionPolicyScope` enumeration." }, "OptionsUpdateContextTier": { "type": "string", "enum": [ "default", "long_context" ], "description": "Context tier for models with tiered pricing. The session uses this to derive effective `modelCapabilitiesOverrides` so compaction, truncation, token display, and request limits honor the selected tier.", "title": "OptionsUpdateContextTier", "x-enumDescriptions": { "default": "Use the model's default context tier and its standard token limits / pricing.", "long_context": "Use the model's long-context tier (when available) so larger inputs are accepted and tier-specific pricing applies." } }, "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." } }, "OptionsUpdateReasoningSummary": { "type": "string", "enum": [ "none", "concise", "detailed" ], "description": "Reasoning summary mode for supported model clients.", "title": "OptionsUpdateReasoningSummary", "x-enumDescriptions": { "none": "Do not request reasoning summaries from the model.", "concise": "Request a concise summary of model reasoning.", "detailed": "Request a detailed summary of model reasoning." } }, "OptionsUpdateToolFilterPrecedence": { "type": "string", "enum": [ "available", "excluded" ], "description": "Controls how availableTools (allowlist) and excludedTools (denylist) combine when both are set.", "title": "OptionsUpdateToolFilterPrecedence", "x-enumDescriptions": { "available": "If availableTools is set, it is the only constraint that applies (excludedTools is ignored). Preserves CLI / pre-existing client behavior. Default.", "excluded": "A tool is enabled if and only if it matches the allowlist (or the allowlist is unset) AND it does not match the denylist. Makes 'all except X' expressible by combining the two lists." } }, "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." }, "commandIdentifiers": { "type": "array", "items": { "type": "string" }, "description": "Command identifiers covered by this approval." } }, "required": [ "kind", "commandIdentifiers" ], "additionalProperties": false, "title": "PermissionDecisionApproveForSessionApprovalCommands", "description": "Schema for the `PermissionDecisionApproveForSessionApprovalCommands` type." }, "PermissionDecisionApproveForSessionApprovalCustomTool": { "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": "PermissionDecisionApproveForSessionApprovalCustomTool", "description": "Schema for the `PermissionDecisionApproveForSessionApprovalCustomTool` type." }, "PermissionDecisionApproveForSessionApprovalExtensionManagement": { "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": "PermissionDecisionApproveForSessionApprovalExtensionManagement", "description": "Schema for the `PermissionDecisionApproveForSessionApprovalExtensionManagement` type." }, "PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess": { "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": "PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess", "description": "Schema for the `PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess` type." }, "PermissionDecisionApproveForSessionApprovalMcp": { "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": "PermissionDecisionApproveForSessionApprovalMcp", "description": "Schema for the `PermissionDecisionApproveForSessionApprovalMcp` type." }, "PermissionDecisionApproveForSessionApprovalMcpSampling": { "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": "PermissionDecisionApproveForSessionApprovalMcpSampling", "description": "Schema for the `PermissionDecisionApproveForSessionApprovalMcpSampling` type." }, "PermissionDecisionApproveForSessionApprovalMemory": { "type": "object", "properties": { "kind": { "type": "string", "const": "memory", "description": "Approval covering writes to long-term memory." } }, "required": [ "kind" ], "additionalProperties": false, "title": "PermissionDecisionApproveForSessionApprovalMemory", "description": "Schema for the `PermissionDecisionApproveForSessionApprovalMemory` type." }, "PermissionDecisionApproveForSessionApprovalRead": { "type": "object", "properties": { "kind": { "type": "string", "const": "read", "description": "Approval covering read-only filesystem operations." } }, "required": [ "kind" ], "additionalProperties": false, "title": "PermissionDecisionApproveForSessionApprovalRead", "description": "Schema for the `PermissionDecisionApproveForSessionApprovalRead` type." }, "PermissionDecisionApproveForSessionApprovalWrite": { "type": "object", "properties": { "kind": { "type": "string", "const": "write", "description": "Approval covering filesystem write operations." } }, "required": [ "kind" ], "additionalProperties": false, "title": "PermissionDecisionApproveForSessionApprovalWrite", "description": "Schema for the `PermissionDecisionApproveForSessionApprovalWrite` type." }, "PermissionDecisionApproveOnce": { "type": "object", "properties": { "kind": { "type": "string", "const": "approve-once", "description": "Approve this single request only" } }, "required": [ "kind" ], "additionalProperties": false, "title": "PermissionDecisionApproveOnce", "description": "Schema for the `PermissionDecisionApproveOnce` type." }, "PermissionDecisionApprovePermanently": { "type": "object", "properties": { "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": [ "kind", "domain" ], "additionalProperties": false, "title": "PermissionDecisionApprovePermanently", "description": "Schema for the `PermissionDecisionApprovePermanently` type." }, "PermissionDecisionCancelled": { "type": "object", "properties": { "kind": { "type": "string", "const": "cancelled", "description": "The permission request was cancelled before a response was used" }, "reason": { "type": "string", "description": "Optional explanation of why the request was cancelled" } }, "required": [ "kind" ], "additionalProperties": false, "title": "PermissionDecisionCancelled", "description": "Schema for the `PermissionDecisionCancelled` type." }, "PermissionDecisionDeniedByContentExclusionPolicy": { "type": "object", "properties": { "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": [ "kind", "path", "message" ], "additionalProperties": false, "title": "PermissionDecisionDeniedByContentExclusionPolicy", "description": "Schema for the `PermissionDecisionDeniedByContentExclusionPolicy` type." }, "PermissionDecisionDeniedByPermissionRequestHook": { "type": "object", "properties": { "kind": { "type": "string", "const": "denied-by-permission-request-hook", "description": "Denied by a permission request hook registered by an extension or plugin" }, "message": { "type": "string", "description": "Optional message from the hook explaining the denial" }, "interrupt": { "type": "boolean", "description": "Whether to interrupt the current agent turn" } }, "required": [ "kind" ], "additionalProperties": false, "title": "PermissionDecisionDeniedByPermissionRequestHook", "description": "Schema for the `PermissionDecisionDeniedByPermissionRequestHook` type." }, "PermissionDecisionDeniedByRules": { "type": "object", "properties": { "kind": { "type": "string", "const": "denied-by-rules", "description": "Denied because approval rules explicitly blocked it" }, "rules": { "type": "array", "items": { "$ref": "#/definitions/PermissionRule" }, "description": "Rules that denied the request" } }, "required": [ "kind", "rules" ], "additionalProperties": false, "title": "PermissionDecisionDeniedByRules", "description": "Schema for the `PermissionDecisionDeniedByRules` type." }, "PermissionDecisionDeniedInteractivelyByUser": { "type": "object", "properties": { "kind": { "type": "string", "const": "denied-interactively-by-user", "description": "Denied by the user during an interactive prompt" }, "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": [ "kind" ], "additionalProperties": false, "title": "PermissionDecisionDeniedInteractivelyByUser", "description": "Schema for the `PermissionDecisionDeniedInteractivelyByUser` type." }, "PermissionDecisionDeniedNoApprovalRuleAndCouldNotRequestFromUser": { "type": "object", "properties": { "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": [ "kind" ], "additionalProperties": false, "title": "PermissionDecisionDeniedNoApprovalRuleAndCouldNotRequestFromUser", "description": "Schema for the `PermissionDecisionDeniedNoApprovalRuleAndCouldNotRequestFromUser` type." }, "PermissionDecisionReject": { "type": "object", "properties": { "kind": { "type": "string", "const": "reject", "description": "Reject the request" }, "feedback": { "type": "string", "description": "Optional feedback explaining the rejection" } }, "required": [ "kind" ], "additionalProperties": false, "title": "PermissionDecisionReject", "description": "Schema for the `PermissionDecisionReject` type." }, "PermissionDecisionRequest": { "type": "object", "properties": { "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" } }, "required": [ "requestId", "result" ], "additionalProperties": false, "description": "Pending permission request ID and the decision to apply (approve/reject and scope).", "title": "PermissionDecisionRequest" }, "PermissionDecisionUserNotAvailable": { "type": "object", "properties": { "kind": { "type": "string", "const": "user-not-available", "description": "No user is available to confirm the request" } }, "required": [ "kind" ], "additionalProperties": false, "title": "PermissionDecisionUserNotAvailable", "description": "Schema for the `PermissionDecisionUserNotAvailable` type." }, "PermissionLocationAddToolApprovalParams": { "type": "object", "properties": { "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": [ "locationKey", "approval" ], "additionalProperties": false, "description": "Location-scoped tool approval to persist.", "title": "PermissionLocationAddToolApprovalParams" }, "PermissionLocationApplyParams": { "type": "object", "properties": { "workingDirectory": { "type": "string", "description": "Working directory whose persisted location permissions should be applied" } }, "required": [ "workingDirectory" ], "additionalProperties": false, "description": "Working directory to load persisted location permissions for.", "title": "PermissionLocationApplyParams" }, "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" ], "additionalProperties": false, "description": "Summary of persisted location permissions applied to the session.", "title": "PermissionLocationApplyResult" }, "PermissionLocationResolveParams": { "type": "object", "properties": { "workingDirectory": { "type": "string", "description": "Working directory whose permission location should be resolved" } }, "required": [ "workingDirectory" ], "additionalProperties": false, "description": "Working directory to resolve into a location-permissions key.", "title": "PermissionLocationResolveParams" }, "PermissionLocationResolveResult": { "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" } }, "required": [ "locationKey", "locationType" ], "additionalProperties": false, "description": "Resolved location-permissions key and type.", "title": "PermissionLocationResolveResult" }, "PermissionLocationType": { "type": "string", "enum": [ "repo", "dir" ], "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." } }, "PermissionPathsAddParams": { "type": "object", "properties": { "path": { "type": "string", "description": "Directory to add to the allow-list. The runtime resolves and validates the path before adding." } }, "required": [ "path" ], "additionalProperties": false, "description": "Directory path to add to the session's allowed directories.", "title": "PermissionPathsAddParams" }, "PermissionPathsAllowedCheckParams": { "type": "object", "properties": { "path": { "type": "string", "description": "Path to check against the session's allowed directories" } }, "required": [ "path" ], "additionalProperties": false, "description": "Path to evaluate against the session's allowed directories.", "title": "PermissionPathsAllowedCheckParams" }, "PermissionPathsAllowedCheckResult": { "type": "object", "properties": { "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." }, "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)." }, "includeTempDirectory": { "type": "boolean", "description": "Whether to include the system temp directory in the allowed list (defaults to true). Ignored when `unrestricted` is true." }, "workspacePath": { "type": "string", "description": "Workspace root path (special-cased to be allowed even before the directory exists). Ignored when `unrestricted` is true." } }, "additionalProperties": false, "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" }, "PermissionPathsList": { "type": "object", "properties": { "directories": { "type": "array", "items": { "type": "string" }, "description": "All directories currently allowed for tool access on this session." }, "primary": { "type": "string", "description": "The primary working directory for this session." } }, "required": [ "directories", "primary" ], "additionalProperties": false, "description": "Snapshot of the session's allow-listed directories and primary working directory.", "title": "PermissionPathsList" }, "PermissionPathsUpdatePrimaryParams": { "type": "object", "properties": { "path": { "type": "string", "description": "Directory to set as the new primary working directory for the session's permission policy." } }, "required": [ "path" ], "additionalProperties": false, "description": "Directory path to set as the session's new primary working directory.", "title": "PermissionPathsUpdatePrimaryParams" }, "PermissionPathsWorkspaceCheckParams": { "type": "object", "properties": { "path": { "type": "string", "description": "Path to check against the session workspace directory" } }, "required": [ "path" ], "additionalProperties": false, "description": "Path to evaluate against the session's workspace (primary) directory.", "title": "PermissionPathsWorkspaceCheckParams" }, "PermissionPathsWorkspaceCheckResult": { "type": "object", "properties": { "allowed": { "type": "boolean", "description": "Whether the path is within the session workspace directory" } }, "required": [ "allowed" ], "additionalProperties": false, "description": "Indicates whether the supplied path is within the session's workspace directory.", "title": "PermissionPathsWorkspaceCheckResult" }, "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" ], "additionalProperties": false, "description": "Notification payload describing the permission prompt that the client just rendered.", "title": "PermissionPromptShownNotification" }, "PermissionRequestResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the permission request was handled successfully" } }, "required": [ "success" ], "additionalProperties": false, "description": "Indicates whether the permission decision was applied; false when the request was already resolved.", "title": "PermissionRequestResult" }, "PermissionRule": { "type": "object", "properties": { "kind": { "type": "string", "description": "The rule kind, such as Shell or GitHubMCP" }, "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" }, "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" } }, "last_updated_at": { "type": [ "string", "number" ], "x-opaque-json": true }, "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" } }, "ifAnyMatch": { "type": "array", "items": { "type": "string" } }, "ifNoneMatch": { "type": "array", "items": { "type": "string" } }, "source": { "$ref": "#/definitions/PermissionsConfigureAdditionalContentExclusionPolicyRuleSource", "description": "Schema for the `PermissionsConfigureAdditionalContentExclusionPolicyRuleSource` type." } }, "required": [ "paths", "source" ], "additionalProperties": true, "title": "PermissionsConfigureAdditionalContentExclusionPolicyRule", "description": "Schema for the `PermissionsConfigureAdditionalContentExclusionPolicyRule` type." }, "PermissionsConfigureAdditionalContentExclusionPolicyRuleSource": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "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." }, "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" }, "PermissionsConfigureResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" } }, "required": [ "success" ], "additionalProperties": false, "description": "Indicates whether the operation succeeded.", "title": "PermissionsConfigureResult" }, "PermissionsFolderTrustAddTrustedResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" } }, "required": [ "success" ], "additionalProperties": false, "description": "Indicates whether the operation succeeded.", "title": "PermissionsFolderTrustAddTrustedResult" }, "PermissionsGetAllowAllRequest": { "type": "object", "properties": {}, "additionalProperties": false, "description": "No parameters.", "title": "PermissionsGetAllowAllRequest" }, "PermissionsLocationsAddToolApprovalDetails": { "anyOf": [ { "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsCommands" }, { "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsRead" }, { "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsWrite" }, { "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsMcp" }, { "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsMcpSampling" }, { "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsMemory" }, { "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsCustomTool" }, { "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsExtensionManagement" }, { "$ref": "#/definitions/PermissionsLocationsAddToolApprovalDetailsExtensionPermissionAccess" } ], "description": "Tool approval to persist and apply", "title": "PermissionsLocationsAddToolApprovalDetails" }, "PermissionsLocationsAddToolApprovalDetailsCommands": { "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": "PermissionsLocationsAddToolApprovalDetailsCommands", "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsCommands` type." }, "PermissionsLocationsAddToolApprovalDetailsCustomTool": { "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": "PermissionsLocationsAddToolApprovalDetailsCustomTool", "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsCustomTool` type." }, "PermissionsLocationsAddToolApprovalDetailsExtensionManagement": { "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": "PermissionsLocationsAddToolApprovalDetailsExtensionManagement", "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsExtensionManagement` type." }, "PermissionsLocationsAddToolApprovalDetailsExtensionPermissionAccess": { "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": "PermissionsLocationsAddToolApprovalDetailsExtensionPermissionAccess", "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsExtensionPermissionAccess` type." }, "PermissionsLocationsAddToolApprovalDetailsMcp": { "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": "PermissionsLocationsAddToolApprovalDetailsMcp", "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsMcp` type." }, "PermissionsLocationsAddToolApprovalDetailsMcpSampling": { "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": "PermissionsLocationsAddToolApprovalDetailsMcpSampling", "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsMcpSampling` type." }, "PermissionsLocationsAddToolApprovalDetailsMemory": { "type": "object", "properties": { "kind": { "type": "string", "const": "memory", "description": "Approval covering writes to long-term memory." } }, "required": [ "kind" ], "additionalProperties": false, "title": "PermissionsLocationsAddToolApprovalDetailsMemory", "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsMemory` type." }, "PermissionsLocationsAddToolApprovalDetailsRead": { "type": "object", "properties": { "kind": { "type": "string", "const": "read", "description": "Approval covering read-only filesystem operations." } }, "required": [ "kind" ], "additionalProperties": false, "title": "PermissionsLocationsAddToolApprovalDetailsRead", "description": "Schema for the `PermissionsLocationsAddToolApprovalDetailsRead` type." }, "PermissionsLocationsAddToolApprovalDetailsWrite": { "type": "object", "properties": { "kind": { "type": "string", "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." }, "add": { "type": "array", "items": { "$ref": "#/definitions/PermissionRule" }, "description": "Rules to add to the scope. Applied before `remove`/`removeAll`." }, "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": [ "scope" ], "additionalProperties": false, "description": "Scope and add/remove instructions for modifying session- or location-scoped permission rules.", "title": "PermissionsModifyRulesParams" }, "PermissionsModifyRulesResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" } }, "required": [ "success" ], "additionalProperties": false, "description": "Indicates whether the operation succeeded.", "title": "PermissionsModifyRulesResult" }, "PermissionsModifyRulesScope": { "type": "string", "enum": [ "session", "location" ], "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." } }, "PermissionsNotifyPromptShownResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" } }, "required": [ "success" ], "additionalProperties": false, "description": "Indicates whether the operation succeeded.", "title": "PermissionsNotifyPromptShownResult" }, "PermissionsPathsAddResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" } }, "required": [ "success" ], "additionalProperties": false, "description": "Indicates whether the operation succeeded.", "title": "PermissionsPathsAddResult" }, "PermissionsPathsListRequest": { "type": "object", "properties": {}, "additionalProperties": false, "description": "No parameters; returns the session's allow-listed directories.", "title": "PermissionsPathsListRequest" }, "PermissionsPathsUpdatePrimaryResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" } }, "required": [ "success" ], "additionalProperties": false, "description": "Indicates whether the operation succeeded.", "title": "PermissionsPathsUpdatePrimaryResult" }, "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 operation succeeded" } }, "required": [ "success" ], "additionalProperties": false, "description": "Indicates whether the operation succeeded.", "title": "PermissionsResetSessionApprovalsResult" }, "PermissionsSetAllowAllRequest": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether to enable full allow-all permissions" }, "source": { "$ref": "#/definitions/PermissionsSetAllowAllSource", "description": "Optional source for allow-all telemetry. Defaults to `rpc` when omitted for SDK callers." } }, "required": [ "enabled" ], "additionalProperties": false, "description": "Whether to enable full allow-all permissions for the session.", "title": "PermissionsSetAllowAllRequest" }, "PermissionsSetAllowAllSource": { "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": "PermissionsSetAllowAllSource", "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." } }, "PermissionsSetApproveAllRequest": { "type": "object", "properties": { "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": [ "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": [ "success" ], "additionalProperties": false, "description": "Indicates whether the operation succeeded.", "title": "PermissionsSetApproveAllResult" }, "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": { "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": [ "required" ], "additionalProperties": false, "description": "Toggles whether permission prompts should be bridged into session events for this client.", "title": "PermissionsSetRequiredRequest" }, "PermissionsSetRequiredResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" } }, "required": [ "success" ], "additionalProperties": false, "description": "Indicates whether the operation succeeded.", "title": "PermissionsSetRequiredResult" }, "PermissionsUrlsSetUnrestrictedModeResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" } }, "required": [ "success" ], "additionalProperties": false, "description": "Indicates whether the operation succeeded.", "title": "PermissionsUrlsSetUnrestrictedModeResult" }, "PermissionUrlsConfig": { "type": "object", "properties": { "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": { "type": "string" }, "description": "Initial list of allowed URL/domain patterns. Patterns may include path components. Ignored when `unrestricted` is true." } }, "additionalProperties": false, "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" }, "PermissionUrlsSetUnrestrictedModeParams": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether to allow access to all URLs without prompting. Toggles the runtime's URL-permission policy in place." } }, "required": [ "enabled" ], "additionalProperties": false, "description": "Whether the URL-permission policy should run in unrestricted mode.", "title": "PermissionUrlsSetUnrestrictedModeParams" }, "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" }, "PingResult": { "type": "object", "properties": { "message": { "type": "string", "description": "Echoed message (or default greeting)" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the server handled the ping" }, "protocolVersion": { "type": "integer", "exclusiveMinimum": 0, "description": "Server protocol version number" } }, "required": [ "message", "timestamp", "protocolVersion" ], "additionalProperties": false, "description": "Server liveness response, including the echoed message, current server timestamp, and protocol version.", "title": "PingResult" }, "PlanReadResult": { "type": "object", "properties": { "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": [ "exists", "content", "path" ], "additionalProperties": false, "description": "Existence, contents, and resolved path of the session plan file.", "title": "PlanReadResult" }, "PlanReadSqlTodosResult": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/definitions/PlanSqlTodosRow", "description": "A single todo row read from the session SQL `todos` table. All fields are optional because the SQL schema is best-effort and the agent may not have populated every column." }, "description": "Rows from the session SQL todos table, ordered by creation time and id." } }, "required": [ "rows" ], "additionalProperties": false, "description": "Todo rows read from the session SQL database. Empty when no session database is available.", "title": "PlanReadSqlTodosResult" }, "PlanReadSqlTodosWithDependenciesResult": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/definitions/PlanSqlTodosRow", "description": "A single todo row read from the session SQL `todos` table. All fields are optional because the SQL schema is best-effort and the agent may not have populated every column." }, "description": "Rows from the session SQL todos table, ordered by creation time and id. Empty when no database, no todos table, or the SELECT failed." }, "dependencies": { "type": "array", "items": { "$ref": "#/definitions/PlanSqlTodoDependency", "description": "A single dependency edge read from the session SQL `todo_deps` table, indicating that one todo must complete before another." }, "description": "Edges from the session SQL todo_deps table. Empty when no database, no todo_deps table, or the SELECT failed. Read independently from `rows`, so a broken todo_deps table does not affect the rows result and vice versa." } }, "required": [ "rows", "dependencies" ], "additionalProperties": false, "description": "Todo rows + dependency edges read from the session SQL database.", "title": "PlanReadSqlTodosWithDependenciesResult" }, "PlanSqlTodoDependency": { "type": "object", "properties": { "todoId": { "type": "string", "description": "ID of the todo that has the dependency." }, "dependsOn": { "type": "string", "description": "ID of the todo it depends on." } }, "required": [ "todoId", "dependsOn" ], "additionalProperties": false, "description": "A single dependency edge read from the session SQL `todo_deps` table, indicating that one todo must complete before another.", "title": "PlanSqlTodoDependency" }, "PlanSqlTodosRow": { "type": "object", "properties": { "id": { "type": "string", "description": "Todo identifier." }, "title": { "type": "string", "description": "Todo title." }, "description": { "type": "string", "description": "Todo description." }, "status": { "type": "string", "description": "Todo status." } }, "additionalProperties": false, "description": "A single todo row read from the session SQL `todos` table. All fields are optional because the SQL schema is best-effort and the agent may not have populated every column.", "title": "PlanSqlTodosRow" }, "PlanUpdateRequest": { "type": "object", "properties": { "content": { "type": "string", "description": "The new content for the plan file" } }, "required": [ "content" ], "additionalProperties": false, "description": "Replacement contents to write to the session plan file.", "title": "PlanUpdateRequest" }, "Plugin": { "type": "object", "properties": { "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": [ "name", "marketplace", "enabled" ], "additionalProperties": false, "title": "Plugin", "description": "Schema for the `Plugin` type." }, "PluginInstallResult": { "type": "object", "properties": { "plugin": { "$ref": "#/definitions/InstalledPluginInfo", "description": "The newly installed plugin's metadata" }, "skillsInstalled": { "type": "integer", "description": "Number of skills discovered and installed from the plugin" }, "postInstallMessage": { "type": "string", "description": "Optional post-install message provided by the plugin (e.g. setup instructions)" }, "deprecationWarning": { "type": "string", "description": "Set when the install path is deprecated (e.g. direct repo / URL / local installs). Callers should surface this to end users." } }, "required": [ "plugin", "skillsInstalled" ], "additionalProperties": false, "description": "Result of installing a plugin.", "title": "PluginInstallResult" }, "PluginList": { "type": "object", "properties": { "plugins": { "type": "array", "items": { "$ref": "#/definitions/Plugin" }, "description": "Installed plugins" } }, "required": [ "plugins" ], "additionalProperties": false, "description": "Plugins installed for the session, with their enabled state and version metadata.", "title": "PluginList" }, "PluginListResult": { "type": "object", "properties": { "plugins": { "type": "array", "items": { "$ref": "#/definitions/InstalledPluginInfo", "description": "Information about an installed plugin tracked in global state." }, "description": "Installed plugins" } }, "required": [ "plugins" ], "additionalProperties": false, "description": "Plugins installed in user/global state.", "title": "PluginListResult" }, "PluginsDisableRequest": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string" }, "description": "Plugin names or \"plugin@marketplace\" specs to disable. Unknown names are ignored. Non-marketplace direct installs cannot be disabled via this API; uninstall them instead. Plugin-owned MCP servers are stopped in active sessions immediately; other plugin contributions remain available until each session reloads plugins." } }, "required": [ "names" ], "additionalProperties": false, "description": "Plugin names (or specs) to disable.", "title": "PluginsDisableRequest" }, "PluginsEnableRequest": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string" }, "description": "Plugin names or \"plugin@marketplace\" specs to enable. Unknown names are ignored. Non-marketplace direct installs are always enabled and cannot be toggled via this API." } }, "required": [ "names" ], "additionalProperties": false, "description": "Plugin names (or specs) to enable.", "title": "PluginsEnableRequest" }, "PluginsInstallRequest": { "type": "object", "properties": { "source": { "type": "string", "description": "Plugin install spec. Accepts the same forms as the CLI: \"plugin@marketplace\" (marketplace install), \"owner/repo\" or \"owner/repo:subpath\" (GitHub direct), an http/https/ssh URL, or a local path. Direct (non-marketplace) installs are deprecated and will produce a deprecationWarning in the result." }, "workingDirectory": { "type": "string", "description": "Working directory used to resolve relative local paths in `source`. Defaults to the server's current working directory." } }, "required": [ "source" ], "additionalProperties": false, "description": "Plugin source and optional working directory for relative-path resolution.", "title": "PluginsInstallRequest" }, "PluginsMarketplacesAddRequest": { "type": "object", "properties": { "source": { "type": "string", "description": "Marketplace source. Accepts the same forms as the CLI: \"owner/repo\" or \"owner/repo#ref\" (GitHub), an http/https/ssh URL (optionally with #ref), a git scp-style URL (user@host:path), or a local path. The marketplace's own name (from its manifest) is used as the registration key." } }, "required": [ "source" ], "additionalProperties": false, "description": "Marketplace source to register.", "title": "PluginsMarketplacesAddRequest" }, "PluginsMarketplacesBrowseRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Marketplace name to browse" } }, "required": [ "name" ], "additionalProperties": false, "description": "Name of the marketplace whose plugin catalog to fetch.", "title": "PluginsMarketplacesBrowseRequest" }, "PluginsMarketplacesRefreshRequest": { "anyOf": [ { "not": {} }, { "type": "object", "properties": { "name": { "type": "string", "description": "Marketplace name to refresh. When omitted, every registered marketplace is refreshed." } }, "additionalProperties": false } ], "description": "Optional marketplace name; omit to refresh all.", "title": "PluginsMarketplacesRefreshRequest" }, "PluginsMarketplacesRemoveRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Marketplace name to remove" }, "force": { "type": "boolean", "description": "When true, also uninstall every plugin sourced from this marketplace. When false (default), removal is a no-op if any plugin from this marketplace is installed and the dependent plugin names are returned in the result." } }, "required": [ "name" ], "additionalProperties": false, "description": "Name of the marketplace to remove and an optional force flag.", "title": "PluginsMarketplacesRemoveRequest" }, "PluginsReloadRequest": { "anyOf": [ { "not": {} }, { "type": "object", "properties": { "reloadMcp": { "type": "boolean", "description": "Reload MCP server connections after refreshing plugins. Defaults to true." }, "reloadCustomAgents": { "type": "boolean", "description": "Re-run custom-agent discovery after refreshing plugins. Defaults to true." }, "reloadHooks": { "type": "boolean", "description": "Re-load user, plugin, and (subject to `deferRepoHooks`) repo hooks. Defaults to true. Has no effect when the host has not registered a hook reloader (e.g. remote sessions)." }, "deferRepoHooks": { "type": "boolean", "description": "When true, skip repo-level hooks during the hook reload. Use before folder trust is confirmed; load them post-trust via `sessions.loadDeferredRepoHooks`." } }, "additionalProperties": false } ], "description": "Optional flags controlling which side effects the reload performs.", "title": "PluginsReloadRequest" }, "PluginsUninstallRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Plugin name or \"plugin@marketplace\" spec to uninstall. When ambiguous, prefer the fully-qualified spec." } }, "required": [ "name" ], "additionalProperties": false, "description": "Name (or spec) of the plugin to uninstall.", "title": "PluginsUninstallRequest" }, "PluginsUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Plugin name or \"plugin@marketplace\" spec to update." } }, "required": [ "name" ], "additionalProperties": false, "description": "Name (or spec) of the plugin to update.", "title": "PluginsUpdateRequest" }, "PluginUpdateAllEntry": { "type": "object", "properties": { "name": { "type": "string", "description": "Plugin name that was updated" }, "marketplace": { "type": "string", "description": "Marketplace the plugin came from. Empty string (\"\") for direct installs." }, "success": { "type": "boolean", "description": "Whether the update succeeded for this plugin" }, "previousVersion": { "type": "string", "description": "Previously installed version, when available" }, "newVersion": { "type": "string", "description": "Version after the update, when available" }, "skillsInstalled": { "type": "integer", "description": "Number of skills installed after the update (success only)" }, "error": { "type": "string", "description": "Error message (failure only)" } }, "required": [ "name", "marketplace", "success" ], "additionalProperties": false, "title": "PluginUpdateAllEntry", "description": "Schema for the `PluginUpdateAllEntry` type." }, "PluginUpdateAllResult": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/definitions/PluginUpdateAllEntry" }, "description": "Per-plugin update results in deterministic order." } }, "required": [ "results" ], "additionalProperties": false, "description": "Result of updating all installed plugins.", "title": "PluginUpdateAllResult" }, "PluginUpdateResult": { "type": "object", "properties": { "previousVersion": { "type": "string", "description": "Version that was previously installed, when available" }, "newVersion": { "type": "string", "description": "Version after the update, when reported by the plugin manifest" }, "skillsInstalled": { "type": "integer", "description": "Number of skills discovered and installed after the update" } }, "required": [ "skillsInstalled" ], "additionalProperties": false, "description": "Result of updating a single plugin.", "title": "PluginUpdateResult" }, "PollSpawnedSessionsResult": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/definitions/SessionsPollSpawnedSessionsEvent" }, "description": "Spawn events emitted since the supplied cursor." }, "cursor": { "type": "string", "description": "Opaque cursor to pass back to receive only events after this batch." } }, "required": [ "events", "cursor" ], "additionalProperties": false, "description": "Batch of spawn events plus a cursor for follow-up polls.", "title": "PollSpawnedSessionsResult" }, "ProviderConfig": { "type": "object", "properties": { "type": { "$ref": "#/definitions/ProviderConfigType", "description": "Provider type. Defaults to \"openai\" for generic OpenAI-compatible APIs." }, "wireApi": { "$ref": "#/definitions/ProviderConfigWireApi", "description": "Wire API format (openai/azure only). Defaults to \"completions\"." }, "baseUrl": { "type": "string", "description": "API endpoint URL." }, "apiKey": { "type": "string", "description": "API key. Optional for local providers like Ollama." }, "bearerToken": { "type": "string", "description": "Bearer token for authentication. Sets the Authorization header directly. Takes precedence over apiKey when both are set." }, "azure": { "$ref": "#/definitions/ProviderConfigAzure", "description": "Azure-specific provider options." }, "modelId": { "type": "string", "description": "Well-known model ID used for capability lookup. When set, agent behavior config and token limits are inferred from this model." }, "wireModel": { "type": "string", "description": "The model identifier sent to the provider API for inference (the \"wire\" model), as opposed to modelId which is the well-known base." }, "maxPromptTokens": { "type": "number", "description": "Maximum prompt/input tokens for the model." }, "maxContextWindowTokens": { "type": "number", "description": "Maximum context window tokens for the model." }, "maxOutputTokens": { "type": "number", "description": "Maximum output tokens for the model." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom HTTP headers to include in all outbound requests to the provider." } }, "required": [ "baseUrl" ], "additionalProperties": false, "description": "Custom model-provider configuration (BYOK).", "title": "ProviderConfig", "stability": "experimental" }, "ProviderConfigAzure": { "type": "object", "properties": { "apiVersion": { "type": "string", "description": "API version. When set, uses the versioned deployment route. When omitted, uses the GA versionless v1 route." } }, "additionalProperties": false, "description": "Azure-specific provider options.", "title": "ProviderConfigAzure" }, "ProviderConfigType": { "type": "string", "enum": [ "openai", "azure", "anthropic" ], "description": "Provider type. Defaults to \"openai\" for generic OpenAI-compatible APIs.", "title": "ProviderConfigType", "x-enumDescriptions": { "openai": "Generic OpenAI-compatible API.", "azure": "Azure OpenAI Service endpoint.", "anthropic": "Anthropic API endpoint." } }, "ProviderConfigWireApi": { "type": "string", "enum": [ "completions", "responses" ], "description": "Wire API format (openai/azure only). Defaults to \"completions\".", "title": "ProviderConfigWireApi", "x-enumDescriptions": { "completions": "OpenAI Chat Completions wire format.", "responses": "OpenAI Responses API wire format." } }, "ProviderEndpoint": { "type": "object", "properties": { "type": { "$ref": "#/definitions/ProviderEndpointType", "description": "Provider family. Matches the `type` field of a BYOK provider config." }, "wireApi": { "$ref": "#/definitions/ProviderEndpointWireApi", "description": "Wire API to be used, when required for the provider type." }, "baseUrl": { "type": "string", "format": "uri", "description": "Base URL to pass to the LLM client library." }, "apiKey": { "type": "string", "description": "A credential the caller should use with this endpoint. Omitted only when the endpoint accepts unauthenticated requests." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "HTTP headers the caller must include on every outbound request." }, "sessionToken": { "$ref": "#/definitions/ProviderSessionToken", "description": "Short-lived, rotating credential the caller must send on every request, in addition to `apiKey` if one is present. Omitted when the endpoint does not require one." } }, "required": [ "type", "baseUrl", "headers" ], "additionalProperties": false, "description": "A snapshot of the provider endpoint the session is currently configured to talk to.", "title": "ProviderEndpoint" }, "ProviderEndpointType": { "type": "string", "enum": [ "openai", "azure", "anthropic" ], "description": "Provider family. Matches the `type` field of a BYOK provider config.", "title": "ProviderEndpointType", "x-enumDescriptions": { "openai": "OpenAI-compatible endpoint (use the OpenAI client library).", "azure": "Azure OpenAI endpoint (use the OpenAI client library with the Azure base URL).", "anthropic": "Anthropic endpoint (use the Anthropic client library)." } }, "ProviderEndpointWireApi": { "type": "string", "enum": [ "completions", "responses" ], "description": "Wire API to be used, when required for the provider type.", "title": "ProviderEndpointWireApi", "x-enumDescriptions": { "completions": "Classic chat-completions request shape.", "responses": "Newer responses request shape." } }, "ProviderGetEndpointRequest": { "anyOf": [ { "not": {} }, { "type": "object", "properties": { "modelId": { "type": "string", "description": "Model identifier the caller intends to use against the returned endpoint. Used to pick the correct wire shape. Omit to use whichever model the session is currently using." } }, "additionalProperties": false } ], "description": "Optional model identifier to scope the endpoint snapshot to.", "title": "ProviderGetEndpointRequest" }, "ProviderSessionToken": { "type": "object", "properties": { "token": { "type": "string", "description": "The short-lived token value." }, "header": { "type": "string", "description": "HTTP header name the token must be sent under." }, "model": { "type": "string", "description": "The model the token is bound to, when applicable. When set, the token is only valid for requests against this model." }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the token expires, if known. Callers should refresh by calling `getEndpoint` again before this time, or reactively on any 401/403 response from `baseUrl`." } }, "required": [ "token", "header" ], "additionalProperties": false, "description": "Short-lived, rotating credential the caller must send on every request, in addition to `apiKey` if one is present. Omitted when the endpoint does not require one.", "title": "ProviderSessionToken" }, "PushAttachment": { "anyOf": [ { "$ref": "#/definitions/PushAttachmentFile", "description": "File attachment" }, { "$ref": "#/definitions/PushAttachmentDirectory", "description": "Directory attachment" }, { "$ref": "#/definitions/PushAttachmentSelection", "description": "Code selection attachment from an editor" }, { "$ref": "#/definitions/PushAttachmentGitHubReference", "description": "GitHub issue, pull request, or discussion reference" }, { "$ref": "#/definitions/PushAttachmentBlob", "description": "Blob attachment with inline base64-encoded data" }, { "$ref": "#/definitions/ExtensionContextPushInput", "description": "Slim input shape for extension_context attachments; identity fields are runtime-derived." } ], "title": "PushAttachment", "description": "Schema for the `PushAttachment` type." }, "PushAttachmentBlob": { "type": "object", "properties": { "type": { "type": "string", "const": "blob", "description": "Attachment type discriminator" }, "data": { "type": "string", "description": "Base64-encoded content", "contentEncoding": "base64" }, "mimeType": { "type": "string", "description": "MIME type of the inline data" }, "displayName": { "type": "string", "description": "User-facing display name for the attachment" } }, "required": [ "type", "data", "mimeType" ], "additionalProperties": false, "description": "Blob attachment with inline base64-encoded data", "title": "PushAttachmentBlob" }, "PushAttachmentDirectory": { "type": "object", "properties": { "type": { "type": "string", "const": "directory", "description": "Attachment type discriminator" }, "path": { "type": "string", "description": "Absolute directory path" }, "displayName": { "type": "string", "description": "User-facing display name for the attachment" } }, "required": [ "type", "path", "displayName" ], "additionalProperties": false, "description": "Directory attachment", "title": "PushAttachmentDirectory" }, "PushAttachmentFile": { "type": "object", "properties": { "type": { "type": "string", "const": "file", "description": "Attachment type discriminator" }, "path": { "type": "string", "description": "Absolute file path" }, "displayName": { "type": "string", "description": "User-facing display name for the attachment" }, "lineRange": { "$ref": "#/definitions/PushAttachmentFileLineRange", "description": "Optional line range to scope the attachment to a specific section of the file" } }, "required": [ "type", "path", "displayName" ], "additionalProperties": false, "description": "File attachment", "title": "PushAttachmentFile" }, "PushAttachmentFileLineRange": { "type": "object", "properties": { "start": { "type": "integer", "exclusiveMinimum": 0, "description": "Start line number (1-based)" }, "end": { "type": "integer", "exclusiveMinimum": 0, "description": "End line number (1-based, inclusive)" } }, "required": [ "start", "end" ], "additionalProperties": false, "description": "Optional line range to scope the attachment to a specific section of the file", "title": "PushAttachmentFileLineRange" }, "PushAttachmentGitHubReference": { "type": "object", "properties": { "type": { "type": "string", "const": "github_reference", "description": "Attachment type discriminator" }, "number": { "type": "integer", "exclusiveMinimum": 0, "description": "Issue, pull request, or discussion number" }, "title": { "type": "string", "description": "Title of the referenced item" }, "referenceType": { "$ref": "#/definitions/PushAttachmentGitHubReferenceType", "description": "Type of GitHub reference" }, "state": { "type": "string", "description": "Current state of the referenced item (e.g., open, closed, merged)" }, "url": { "type": "string", "description": "URL to the referenced item on GitHub" } }, "required": [ "type", "number", "title", "referenceType", "state", "url" ], "additionalProperties": false, "description": "GitHub issue, pull request, or discussion reference", "title": "PushAttachmentGitHubReference" }, "PushAttachmentGitHubReferenceType": { "type": "string", "enum": [ "issue", "pr", "discussion" ], "description": "Type of GitHub reference", "title": "PushAttachmentGitHubReferenceType", "x-enumDescriptions": { "issue": "GitHub issue reference.", "pr": "GitHub pull request reference.", "discussion": "GitHub discussion reference." } }, "PushAttachmentSelection": { "type": "object", "properties": { "type": { "type": "string", "const": "selection", "description": "Attachment type discriminator" }, "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/PushAttachmentSelectionDetails", "description": "Position range of the selection within the file" } }, "required": [ "type", "filePath", "displayName", "text", "selection" ], "additionalProperties": false, "description": "Code selection attachment from an editor", "title": "PushAttachmentSelection" }, "PushAttachmentSelectionDetails": { "type": "object", "properties": { "start": { "$ref": "#/definitions/PushAttachmentSelectionDetailsStart", "description": "Start position of the selection" }, "end": { "$ref": "#/definitions/PushAttachmentSelectionDetailsEnd", "description": "End position of the selection" } }, "required": [ "start", "end" ], "additionalProperties": false, "description": "Position range of the selection within the file", "title": "PushAttachmentSelectionDetails" }, "PushAttachmentSelectionDetailsEnd": { "type": "object", "properties": { "line": { "type": "integer", "minimum": 0, "description": "End line number (0-based)" }, "character": { "type": "integer", "minimum": 0, "description": "End character offset within the line (0-based)" } }, "required": [ "line", "character" ], "additionalProperties": false, "description": "End position of the selection", "title": "PushAttachmentSelectionDetailsEnd" }, "PushAttachmentSelectionDetailsStart": { "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" ], "additionalProperties": false, "description": "Start position of the selection", "title": "PushAttachmentSelectionDetailsStart" }, "QueuedCommandHandled": { "type": "object", "properties": { "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": [ "handled" ], "additionalProperties": false, "title": "QueuedCommandHandled", "description": "Schema for the `QueuedCommandHandled` type." }, "QueuedCommandNotHandled": { "type": "object", "properties": { "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": [ "handled" ], "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" }, "QueuePendingItems": { "type": "object", "properties": { "kind": { "$ref": "#/definitions/QueuePendingItemsKind", "description": "Whether this item is a queued user message or a queued slash command / model change" }, "displayText": { "type": "string", "description": "Human-readable text to display for this queue entry in the UI" } }, "required": [ "kind", "displayText" ], "additionalProperties": false, "title": "QueuePendingItems", "description": "Schema for the `QueuePendingItems` type." }, "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." } }, "QueuePendingItemsResult": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/QueuePendingItems" }, "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": [ "items", "steeringMessages" ], "additionalProperties": false, "description": "Snapshot of the session's pending queued items and immediate-steering messages.", "title": "QueuePendingItemsResult" }, "QueueRemoveMostRecentResult": { "type": "object", "properties": { "removed": { "type": "boolean", "description": "True if a user-facing pending item was removed (LIFO across both queues); false when no removable items remained." } }, "required": [ "removed" ], "additionalProperties": false, "description": "Indicates whether a user-facing pending item was removed.", "title": "QueueRemoveMostRecentResult" }, "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": { "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": [ "eventType" ], "additionalProperties": false, "description": "Event type to register consumer interest for, used by runtime gating logic.", "title": "RegisterEventInterestParams" }, "RegisterEventInterestResult": { "type": "object", "properties": { "handle": { "type": "string", "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": "Opaque handle representing an event-type interest registration.", "title": "RegisterEventInterestResult" }, "RegisterExtensionToolsParams": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Session to register extension tools on." }, "loader": { "description": "In-process ExtensionLoader handle (CLI-only optimization). Marked internal: this field is excluded from the public SDK surface. When the CLI migrates to a process-separated SDK, extension discovery/launch moves entirely into the runtime — the CLI passes pure config (search paths, disabled ids) via SessionOptions instead.", "visibility": "internal", "x-opaque-json": true }, "options": { "$ref": "#/definitions/SessionsRegisterExtensionToolsOnSessionOptions", "description": "Optional registration options." } }, "required": [ "sessionId", "loader" ], "additionalProperties": false, "description": "Params to attach an extension loader's tools to a session.", "title": "RegisterExtensionToolsParams", "visibility": "internal" }, "RegisterExtensionToolsResult": { "type": "object", "properties": { "unsubscribe": { "description": "In-process unsubscribe function (CLI-only optimization). Marked internal: replaced by an explicit `extensions.unregister` RPC in the SDK migration.", "visibility": "internal", "x-opaque-json": true } }, "required": [ "unsubscribe" ], "additionalProperties": false, "description": "Handle for releasing the extension tool registration.", "title": "RegisterExtensionToolsResult", "visibility": "internal" }, "ReleaseEventInterestParams": { "type": "object", "properties": { "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": [ "handle" ], "additionalProperties": false, "description": "Opaque handle previously returned by `registerInterest` to release.", "title": "ReleaseEventInterestParams" }, "RemoteControlConfig": { "type": "object", "properties": { "remote": { "type": "boolean", "description": "Whether remote export should be enabled." }, "steerable": { "type": "boolean", "description": "Whether the MC session may steer the local session (write mode)." }, "explicit": { "type": "boolean", "description": "Whether the user explicitly requested remote (vs. implicit session-sync). Controls warning surfacing for missing-repo cases." }, "silent": { "type": "boolean", "description": "When true, suppresses timeline messages on successful setup." }, "taskId": { "type": "string", "description": "Existing Mission Control task ID to attach the exported session to." }, "existingMcSession": { "$ref": "#/definitions/RemoteControlConfigExistingMcSession", "description": "Reattach to an existing MC session without creating a new one." } }, "required": [ "remote", "steerable", "explicit", "silent" ], "additionalProperties": false, "description": "Configuration for the runtime-managed remote-control singleton.", "title": "RemoteControlConfig" }, "RemoteControlConfigExistingMcSession": { "type": "object", "properties": { "mcSessionId": { "type": "string", "description": "Existing MC session ID to reattach to." }, "mcTaskId": { "type": "string", "description": "Existing MC task ID for the reattached session." } }, "required": [ "mcSessionId", "mcTaskId" ], "additionalProperties": false, "description": "Reattach to an existing MC session without creating a new one.", "title": "RemoteControlConfigExistingMcSession" }, "RemoteControlStatus": { "anyOf": [ { "$ref": "#/definitions/RemoteControlStatusOff", "description": "Remote control is not connected." }, { "$ref": "#/definitions/RemoteControlStatusConnecting", "description": "Remote control is in the middle of initial setup." }, { "$ref": "#/definitions/RemoteControlStatusActive", "description": "Remote control is connected to a local session." }, { "$ref": "#/definitions/RemoteControlStatusError", "description": "The last setup attempt failed. The singleton is otherwise off." } ], "description": "State of the runtime-managed remote-control singleton.", "title": "RemoteControlStatus" }, "RemoteControlStatusActive": { "type": "object", "properties": { "state": { "type": "string", "const": "active", "description": "Remote control state tag: active." }, "attachedSessionId": { "type": "string", "description": "Session id remote control is pointed at." }, "frontendUrl": { "type": "string", "description": "MC frontend URL for this session, when known." }, "isSteerable": { "type": "boolean", "description": "Whether the MC session may steer this session." }, "promptManager": { "description": "In-process prompt-manager handle (CLI-only optimization). Marked internal: this field is excluded from the public SDK surface. When the CLI migrates to a process-separated SDK, the same bidirectional prompt-routing handshake is expressed via dedicated remote-control RPCs (register/resolve) rather than a shared in-process object.", "visibility": "internal", "x-opaque-json": true } }, "required": [ "state", "attachedSessionId", "isSteerable" ], "additionalProperties": false, "description": "Remote control is connected to a local session.", "title": "RemoteControlStatusActive" }, "RemoteControlStatusConnecting": { "type": "object", "properties": { "state": { "type": "string", "const": "connecting", "description": "Remote control state tag: connecting." }, "attachedSessionId": { "type": "string", "description": "Session id the connection is attaching to." } }, "required": [ "state", "attachedSessionId" ], "additionalProperties": false, "description": "Remote control is in the middle of initial setup.", "title": "RemoteControlStatusConnecting" }, "RemoteControlStatusError": { "type": "object", "properties": { "state": { "type": "string", "const": "error", "description": "Remote control state tag: setup failed." }, "error": { "type": "string", "description": "Human-readable error message from the last setup attempt." }, "attachedSessionId": { "type": "string", "description": "Session id the failing setup attempt targeted, when known." } }, "required": [ "state", "error" ], "additionalProperties": false, "description": "The last setup attempt failed. The singleton is otherwise off.", "title": "RemoteControlStatusError" }, "RemoteControlStatusOff": { "type": "object", "properties": { "state": { "type": "string", "const": "off", "description": "Remote control state tag: not connected." } }, "required": [ "state" ], "additionalProperties": false, "description": "Remote control is not connected.", "title": "RemoteControlStatusOff" }, "RemoteControlStatusResult": { "type": "object", "properties": { "status": { "$ref": "#/definitions/RemoteControlStatus", "description": "State of the runtime-managed remote-control singleton." } }, "required": [ "status" ], "additionalProperties": false, "description": "Wrapper for the singleton's current status.", "title": "RemoteControlStatusResult" }, "RemoteControlStopResult": { "type": "object", "properties": { "status": { "$ref": "#/definitions/RemoteControlStatus", "description": "State of the runtime-managed remote-control singleton." }, "stopped": { "type": "boolean", "description": "Whether the singleton was actually torn down by this call." } }, "required": [ "status", "stopped" ], "additionalProperties": false, "description": "Outcome of a stopRemoteControl call.", "title": "RemoteControlStopResult" }, "RemoteControlTransferResult": { "type": "object", "properties": { "status": { "$ref": "#/definitions/RemoteControlStatus", "description": "State of the runtime-managed remote-control singleton." }, "transferred": { "type": "boolean", "description": "Whether the rebinding actually happened." } }, "required": [ "status", "transferred" ], "additionalProperties": false, "description": "Outcome of a transferRemoteControl call.", "title": "RemoteControlTransferResult" }, "RemoteEnableRequest": { "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." } }, "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", "format": "uri", "description": "GitHub frontend URL for this session" }, "remoteSteerable": { "type": "boolean", "description": "Whether remote steering is enabled" } }, "required": [ "remoteSteerable" ], "additionalProperties": false, "description": "GitHub URL for the session and a flag indicating whether remote steering is enabled.", "title": "RemoteEnableResult" }, "RemoteNotifySteerableChangedRequest": { "type": "object", "properties": { "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": "New remote-steerability state to persist as a `session.remote_steerable_changed` event.", "title": "RemoteNotifySteerableChangedRequest" }, "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" ], "additionalProperties": false, "description": "Remote session connection result.", "title": "RemoteSessionConnectionResult" }, "RemoteSessionMetadataRepository": { "type": "object", "properties": { "owner": { "type": "string", "description": "Repository owner." }, "name": { "type": "string", "description": "Repository name." }, "branch": { "type": "string", "description": "Branch associated with the remote session." } }, "required": [ "owner", "name", "branch" ], "additionalProperties": false, "description": "GitHub repository the remote session belongs to.", "title": "RemoteSessionMetadataRepository" }, "RemoteSessionMetadataTaskType": { "type": "string", "enum": [ "cca", "cli" ], "description": "Whether the remote task originated from CCA or CLI `--remote`.", "title": "RemoteSessionMetadataTaskType", "x-enumDescriptions": { "cca": "GitHub Copilot coding agent task.", "cli": "CLI remote task." } }, "RemoteSessionMetadataValue": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Stable session identifier." }, "startTime": { "type": "string", "description": "Session creation time as an ISO 8601 timestamp." }, "modifiedTime": { "type": "string", "description": "Last-modified time as an ISO 8601 timestamp." }, "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", "const": true, "description": "Always true for remote sessions." }, "context": { "$ref": "#/definitions/SessionContext", "description": "Most recent working directory context." }, "repository": { "$ref": "#/definitions/RemoteSessionMetadataRepository", "description": "GitHub repository the remote session belongs to." }, "remoteSessionIds": { "type": "array", "items": { "type": "string" }, "description": "Backing remote session IDs (most recent first)." }, "pullRequestNumber": { "type": "integer", "exclusiveMinimum": 0, "description": "Pull request number associated with the session." }, "resourceId": { "type": "string", "description": "Original remote resource identifier (task ID or PR node ID)." }, "taskType": { "$ref": "#/definitions/RemoteSessionMetadataTaskType", "description": "Whether the remote task originated from CCA or CLI `--remote`." }, "staleAt": { "type": "string", "description": "Deadline (ISO 8601) at which a CLI remote session becomes stale without further heartbeats." }, "state": { "type": "string", "description": "Server-side task state returned by GitHub." } }, "required": [ "sessionId", "startTime", "modifiedTime", "isRemote", "repository", "remoteSessionIds" ], "additionalProperties": false, "description": "Remote session metadata for the session to hand off (typically obtained from `sessions.list` with `source: \"remote\"`).", "title": "RemoteSessionMetadataValue" }, "RemoteSessionMode": { "type": "string", "enum": [ "off", "export", "on" ], "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." } }, "RemoteSessionRepository": { "type": "object", "properties": { "owner": { "type": "string", "description": "Repository owner or organization login." }, "name": { "type": "string", "description": "Repository name." }, "branch": { "type": "string", "description": "Optional branch associated with the remote session." } }, "required": [ "owner", "name" ], "additionalProperties": false, "description": "Repository context for the remote session.", "title": "RemoteSessionRepository" }, "SandboxConfig": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether sandboxing is enabled for the session." }, "userPolicy": { "$ref": "#/definitions/SandboxConfigUserPolicy", "description": "User-managed sandbox policy fragment merged into the auto-discovered base policy." }, "config": { "type": "object", "additionalProperties": {}, "description": "Raw `ContainerConfig` (per `@microsoft/mxc-sdk`) passed directly to `spawnSandboxFromConfig`, bypassing policy merging.", "x-opaque-json": true }, "addCurrentWorkingDirectory": { "type": "boolean", "description": "Whether to auto-add the current working directory to readwritePaths. Default: true." } }, "required": [ "enabled" ], "additionalProperties": false, "description": "Resolved sandbox configuration.", "title": "SandboxConfig", "stability": "experimental" }, "SandboxConfigUserPolicy": { "type": "object", "properties": { "filesystem": { "$ref": "#/definitions/SandboxConfigUserPolicyFilesystem", "description": "Filesystem rules to merge into the base policy." }, "network": { "$ref": "#/definitions/SandboxConfigUserPolicyNetwork", "description": "Network rules to merge into the base policy." }, "experimental": { "$ref": "#/definitions/SandboxConfigUserPolicyExperimental", "description": "Platform-specific experimental policy fields." } }, "additionalProperties": false, "description": "User-managed sandbox policy fragment merged into the auto-discovered base policy.", "title": "SandboxConfigUserPolicy" }, "SandboxConfigUserPolicyExperimental": { "type": "object", "properties": { "seatbelt": { "$ref": "#/definitions/SandboxConfigUserPolicyExperimentalSeatbelt", "description": "macOS seatbelt experimental options." } }, "additionalProperties": false, "description": "Platform-specific experimental policy fields.", "title": "SandboxConfigUserPolicyExperimental" }, "SandboxConfigUserPolicyExperimentalSeatbelt": { "type": "object", "properties": { "keychainAccess": { "type": "boolean", "description": "Whether the macOS seatbelt profile may access the keychain." } }, "additionalProperties": false, "description": "macOS seatbelt experimental options.", "title": "SandboxConfigUserPolicyExperimentalSeatbelt" }, "SandboxConfigUserPolicyFilesystem": { "type": "object", "properties": { "readwritePaths": { "type": "array", "items": { "type": "string" }, "description": "Paths granted read/write access." }, "readonlyPaths": { "type": "array", "items": { "type": "string" }, "description": "Paths granted read-only access." }, "deniedPaths": { "type": "array", "items": { "type": "string" }, "description": "Paths explicitly denied." }, "clearPolicyOnExit": { "type": "boolean", "description": "Whether to clear the policy when the session exits." } }, "additionalProperties": false, "description": "Filesystem rules to merge into the base policy.", "title": "SandboxConfigUserPolicyFilesystem" }, "SandboxConfigUserPolicyNetwork": { "type": "object", "properties": { "allowOutbound": { "type": "boolean", "description": "Whether outbound network traffic is allowed at all." }, "allowLocalNetwork": { "type": "boolean", "description": "Whether traffic to local/loopback addresses is allowed." }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts allowed in addition to the base policy." }, "blockedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts explicitly blocked." } }, "additionalProperties": false, "description": "Network rules to merge into the base policy.", "title": "SandboxConfigUserPolicyNetwork" }, "ScheduleEntry": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "description": "Sequential id assigned by the runtime within the session. Stable across resumes (rebuilt from the event log)." }, "intervalMs": { "type": "integer", "exclusiveMinimum": 0, "description": "Interval between scheduled ticks, in milliseconds (relative-interval schedules).", "format": "duration" }, "cron": { "type": "string", "description": "5-field cron expression for a recurring calendar schedule, evaluated in `tz`." }, "tz": { "type": "string", "description": "IANA timezone the `cron` expression is evaluated in." }, "at": { "type": "integer", "exclusiveMinimum": 0, "description": "Absolute fire time (epoch milliseconds) for a one-shot calendar schedule." }, "prompt": { "type": "string", "description": "Prompt text that gets enqueued on every tick." }, "recurring": { "type": "boolean", "description": "Whether the schedule re-arms after each tick (`/every`) or fires once (`/after`)." }, "displayPrompt": { "type": "string", "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`." }, "nextRunAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the next tick is scheduled to fire." } }, "required": [ "id", "prompt", "recurring", "nextRunAt" ], "additionalProperties": false, "title": "ScheduleEntry", "description": "Schema for the `ScheduleEntry` type." }, "ScheduleList": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/ScheduleEntry" }, "description": "Active scheduled prompts, ordered by id." } }, "required": [ "entries" ], "additionalProperties": false, "description": "Snapshot of the currently active recurring prompts for this session.", "title": "ScheduleList" }, "ScheduleStopRequest": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "description": "Id of the scheduled prompt to remove." } }, "required": [ "id" ], "additionalProperties": false, "description": "Identifier of the scheduled prompt to remove.", "title": "ScheduleStopRequest" }, "ScheduleStopResult": { "type": "object", "properties": { "entry": { "$ref": "#/definitions/ScheduleEntry", "description": "The removed entry, or omitted if no entry matched." } }, "additionalProperties": false, "description": "Remove a scheduled prompt by id. The result entry is omitted if the id was unknown.", "title": "ScheduleStopResult" }, "SecretsAddFilterValuesRequest": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string" }, "description": "Raw secret values to register for redaction" } }, "required": [ "values" ], "additionalProperties": false, "description": "Secret values to add to the redaction filter.", "title": "SecretsAddFilterValuesRequest" }, "SecretsAddFilterValuesResult": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true, "description": "Whether the values were successfully registered" } }, "required": [ "ok" ], "additionalProperties": false, "description": "Confirmation that the secret values were registered.", "title": "SecretsAddFilterValuesResult" }, "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." } }, "SendAttachmentsToMessageParams": { "type": "object", "properties": { "instanceId": { "type": "string", "description": "Optional canvas instance binding the push for provenance. When supplied, the runtime resolves the canvas, verifies it is owned by the calling extension, and stamps canvasId/instanceId onto each extension_context entry. When omitted, no resolution runs and those fields stay unset on the attachment." }, "attachments": { "type": "array", "items": { "$ref": "#/definitions/PushAttachment" }, "description": "Attachments to push into the next user-message turn. extension_context entries take the slim shape; standard variants take their full AttachmentSchema shape." } }, "required": [ "attachments" ], "additionalProperties": false, "description": "Parameters for session.extensions.sendAttachmentsToMessage.", "title": "SendAttachmentsToMessageParams" }, "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": { "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/Attachment", "description": "A user message attachment — a file, directory, code selection, blob, GitHub reference, or extension-supplied context payload" }, "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": { "type": "string", "pattern": "^(system|command-.*|schedule-\\d+)$", "description": "Optional provenance tag copied to the resulting user.message event. Must match one of three forms: the literal `system`, `command-` for messages originating from a command (e.g. slash command, Mission Control command), or `schedule-` for messages originating from a scheduled job.", "visibility": "internal" }, "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": [ "prompt" ], "additionalProperties": false, "description": "Parameters for sending a user message to the session", "title": "SendRequest" }, "SendResult": { "type": "object", "properties": { "messageId": { "type": "string", "description": "Unique identifier assigned to the message" } }, "required": [ "messageId" ], "additionalProperties": false, "description": "Result of sending a user message", "title": "SendResult" }, "ServerAgentList": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/definitions/AgentInfo" }, "description": "All discovered agents across all sources" } }, "required": [ "agents" ], "additionalProperties": false, "description": "Agents discovered across user, project, plugin, and remote sources.", "title": "ServerAgentList" }, "ServerInstructionSourceList": { "type": "object", "properties": { "sources": { "type": "array", "items": { "$ref": "#/definitions/InstructionSource" }, "description": "All discovered instruction sources" } }, "required": [ "sources" ], "additionalProperties": false, "description": "Instruction sources discovered across user, repository, and plugin sources.", "title": "ServerInstructionSourceList" }, "ServerSkill": { "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": { "type": "string", "description": "The project path this skill belongs to (only for project/inherited skills)" } }, "required": [ "name", "description", "source", "userInvocable", "enabled" ], "additionalProperties": false, "title": "ServerSkill", "description": "Schema for the `ServerSkill` type." }, "ServerSkillList": { "type": "object", "properties": { "skills": { "type": "array", "items": { "$ref": "#/definitions/ServerSkill" }, "description": "All discovered skills across all sources" } }, "required": [ "skills" ], "additionalProperties": false, "description": "Skills discovered across global and project sources.", "title": "ServerSkillList" }, "SessionActivity": { "type": "object", "properties": { "abortable": { "type": "boolean", "description": "Whether an in-flight operation can currently be aborted." }, "hasActiveWork": { "type": "boolean", "description": "Whether the session currently has active work, including running turns or tasks." } }, "required": [ "abortable", "hasActiveWork" ], "additionalProperties": false, "description": "Current activity flags for the session.", "title": "SessionActivity" }, "SessionAuthStatus": { "type": "object", "properties": { "isAuthenticated": { "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)" } }, "required": [ "isAuthenticated" ], "additionalProperties": false, "description": "Authentication status and account metadata for the session.", "title": "SessionAuthStatus" }, "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" ], "additionalProperties": false, "description": "Map of sessionId -> bytes freed by removing the session's workspace directory.", "title": "SessionBulkDeleteResult" }, "SessionCapability": { "type": "string", "enum": [ "tui-hints", "plan-mode", "memory", "cli-documentation", "ask-user", "interactive-mode", "system-notifications", "elicitation", "session-store", "mcp-apps", "canvas-renderer" ], "description": "Session capability enabled for this session", "title": "SessionCapability", "x-enumDescriptions": { "tui-hints": "TUI-specific prompt hints such as keyboard shortcuts.", "plan-mode": "Plan-mode handling and instructions.", "memory": "Memory tool and memories prompt section.", "cli-documentation": "Copilot CLI documentation tool and prompt section.", "ask-user": "Interactive ask_user tool support.", "interactive-mode": "Interactive CLI identity and behavior.", "system-notifications": "Automatic hidden system notifications.", "elicitation": "SDK elicitation support.", "session-store": "Cross-session history tools and session-store SQL prompt/tool metadata.", "mcp-apps": "MCP Apps UI passthrough.", "canvas-renderer": "Host-provided canvas rendering support." } }, "SessionContext": { "type": "object", "properties": { "cwd": { "type": "string", "description": "Most recent working directory for this session" }, "gitRoot": { "type": "string", "description": "Git repository root, if the cwd was inside a git repo" }, "repository": { "type": "string", "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": [ "cwd" ], "additionalProperties": false, "description": "Pre-resolved working-directory context for session startup.", "title": "SessionContext" }, "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": [ { "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)" }, "mcpToolsTokens": { "type": "integer", "minimum": 0, "description": "Tokens consumed by MCP tool definitions (subset of toolDefinitionsTokens, 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": "Prompt token limit plus the model's full output token limit." }, "bufferTokens": { "type": "integer", "minimum": 0, "description": "Output reserve plus tokens after the buffer-exhaustion blocking threshold (default 95%)" } }, "required": [ "modelName", "systemTokens", "conversationTokens", "toolDefinitionsTokens", "mcpToolsTokens", "totalTokens", "promptTokenLimit", "compactionThreshold", "limit", "bufferTokens" ], "additionalProperties": false, "description": "Token-usage breakdown for the session's current context window" }, { "type": "null" } ], "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" }, "SessionEnrichMetadataResult": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/definitions/LocalSessionMetadataValue" }, "description": "Enriched records, with summary and context backfilled. Sessions confirmed empty and unnamed may be omitted." } }, "required": [ "sessions" ], "additionalProperties": false, "description": "The enriched metadata records, with summary and context fields backfilled where available. Sessions confirmed empty and unnamed are omitted.", "title": "SessionEnrichMetadataResult" }, "SessionFsAppendFileRequest": { "type": "object", "properties": { "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": [ "path", "content" ], "additionalProperties": false, "description": "File path, content to append, and optional mode for the client-provided session filesystem.", "title": "SessionFsAppendFileRequest" }, "SessionFsError": { "type": "object", "properties": { "code": { "$ref": "#/definitions/SessionFsErrorCode", "description": "Error classification" }, "message": { "type": "string", "description": "Free-form detail about the error, for logging/diagnostics" } }, "required": [ "code" ], "additionalProperties": false, "description": "Describes a filesystem error.", "title": "SessionFsError" }, "SessionFsErrorCode": { "type": "string", "enum": [ "ENOENT", "UNKNOWN" ], "description": "Error classification", "title": "SessionFsErrorCode", "x-enumDescriptions": { "ENOENT": "The requested path does not exist.", "UNKNOWN": "The filesystem operation failed for an unspecified reason." } }, "SessionFsExistsRequest": { "type": "object", "properties": { "path": { "type": "string", "description": "Path using SessionFs conventions" } }, "required": [ "path" ], "additionalProperties": false, "description": "Path to test for existence in the client-provided session filesystem.", "title": "SessionFsExistsRequest" }, "SessionFsExistsResult": { "type": "object", "properties": { "exists": { "type": "boolean", "description": "Whether the path exists" } }, "required": [ "exists" ], "additionalProperties": false, "description": "Indicates whether the requested path exists in the client-provided session filesystem.", "title": "SessionFsExistsResult" }, "SessionFsMkdirRequest": { "type": "object", "properties": { "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": [ "path" ], "additionalProperties": false, "description": "Directory path to create in the client-provided session filesystem, with options for recursive creation and POSIX mode.", "title": "SessionFsMkdirRequest" }, "SessionFsReaddirRequest": { "type": "object", "properties": { "path": { "type": "string", "description": "Path using SessionFs conventions" } }, "required": [ "path" ], "additionalProperties": false, "description": "Directory path whose entries should be listed from the client-provided session filesystem.", "title": "SessionFsReaddirRequest" }, "SessionFsReaddirResult": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "string" }, "description": "Entry names in the directory" }, "error": { "$ref": "#/definitions/SessionFsError", "description": "Describes a filesystem error." } }, "required": [ "entries" ], "additionalProperties": false, "description": "Names of entries in the requested directory, or a filesystem error if the read failed.", "title": "SessionFsReaddirResult" }, "SessionFsReaddirWithTypesEntry": { "type": "object", "properties": { "name": { "type": "string", "description": "Entry name" }, "type": { "$ref": "#/definitions/SessionFsReaddirWithTypesEntryType", "description": "Entry type" } }, "required": [ "name", "type" ], "additionalProperties": false, "title": "SessionFsReaddirWithTypesEntry", "description": "Schema for the `SessionFsReaddirWithTypesEntry` type." }, "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": { "path": { "type": "string", "description": "Path using SessionFs conventions" } }, "required": [ "path" ], "additionalProperties": false, "description": "Directory path whose entries (with type information) should be listed from the client-provided session filesystem.", "title": "SessionFsReaddirWithTypesRequest" }, "SessionFsReaddirWithTypesResult": { "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." } }, "required": [ "entries" ], "additionalProperties": false, "description": "Entries in the requested directory paired with file/directory type information, or a filesystem error if the read failed.", "title": "SessionFsReaddirWithTypesResult" }, "SessionFsReadFileRequest": { "type": "object", "properties": { "path": { "type": "string", "description": "Path using SessionFs conventions" } }, "required": [ "path" ], "additionalProperties": false, "description": "Path of the file to read from the client-provided session filesystem.", "title": "SessionFsReadFileRequest" }, "SessionFsReadFileResult": { "type": "object", "properties": { "content": { "type": "string", "description": "File content as UTF-8 string" }, "error": { "$ref": "#/definitions/SessionFsError", "description": "Describes a filesystem error." } }, "required": [ "content" ], "additionalProperties": false, "description": "File content as a UTF-8 string, or a filesystem error if the read failed.", "title": "SessionFsReadFileResult" }, "SessionFsRenameRequest": { "type": "object", "properties": { "src": { "type": "string", "description": "Source path using SessionFs conventions" }, "dest": { "type": "string", "description": "Destination path using SessionFs conventions" } }, "required": [ "src", "dest" ], "additionalProperties": false, "description": "Source and destination paths for renaming or moving an entry in the client-provided session filesystem.", "title": "SessionFsRenameRequest" }, "SessionFsRmRequest": { "type": "object", "properties": { "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": [ "path" ], "additionalProperties": false, "description": "Path to remove from the client-provided session filesystem, with options for recursive removal and force.", "title": "SessionFsRmRequest" }, "SessionFsSetProviderCapabilities": { "type": "object", "properties": { "sqlite": { "type": "boolean", "description": "Whether the provider supports SQLite query/exists operations" } }, "additionalProperties": false, "description": "Optional capabilities declared by the provider", "title": "SessionFsSetProviderCapabilities" }, "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": { "initialCwd": { "type": "string", "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": [ "initialCwd", "sessionStatePath", "conventions" ], "additionalProperties": false, "description": "Initial working directory, session-state path layout, and path conventions used to register the calling SDK client as the session filesystem provider.", "title": "SessionFsSetProviderRequest" }, "SessionFsSetProviderResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the provider was set successfully" } }, "required": [ "success" ], "additionalProperties": false, "description": "Indicates whether the calling client was registered as the session filesystem provider.", "title": "SessionFsSetProviderResult" }, "SessionFsSqliteExistsResult": { "type": "object", "properties": { "exists": { "type": "boolean", "description": "Whether the session database already exists" } }, "required": [ "exists" ], "additionalProperties": false, "description": "Indicates whether the per-session SQLite database already exists.", "title": "SessionFsSqliteExistsResult" }, "SessionFsSqliteQueryRequest": { "type": "object", "properties": { "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" ], "x-opaque-json": true }, "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": { "type": "array", "items": { "type": "object", "additionalProperties": { "x-opaque-json": true } }, "description": "For SELECT: array of row objects. For others: empty array." }, "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": [ "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", "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": { "path": { "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": { "type": "boolean", "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": [ "isFile", "isDirectory", "size", "mtime", "birthtime" ], "additionalProperties": false, "description": "Filesystem metadata for the requested path, or a filesystem error if the stat failed.", "title": "SessionFsStatResult" }, "SessionFsWriteFileRequest": { "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" } }, "required": [ "path", "content" ], "additionalProperties": false, "description": "File path, content to write, and optional mode for the client-provided session filesystem.", "title": "SessionFsWriteFileRequest" }, "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 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, "title": "SessionInstalledPlugin", "description": "Schema for the `SessionInstalledPlugin` type." }, "SessionInstalledPluginSource": { "anyOf": [ { "type": "string", "pattern": "^[^/]+\\/[^/]+$" }, { "$ref": "#/definitions/SessionInstalledPluginSourceGitHub" }, { "$ref": "#/definitions/SessionInstalledPluginSourceUrl" }, { "$ref": "#/definitions/SessionInstalledPluginSourceLocal" } ], "description": "Source descriptor for direct repo installs (when marketplace is empty)", "title": "SessionInstalledPluginSource", "x-opaque-json": true, "stability": "experimental" }, "SessionInstalledPluginSourceGitHub": { "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": "SessionInstalledPluginSourceGitHub", "description": "Schema for the `SessionInstalledPluginSourceGitHub` type." }, "SessionInstalledPluginSourceLocal": { "type": "object", "properties": { "source": { "type": "string", "const": "local", "description": "Constant value. Always \"local\"." }, "path": { "type": "string" } }, "required": [ "source", "path" ], "additionalProperties": false, "title": "SessionInstalledPluginSourceLocal", "description": "Schema for the `SessionInstalledPluginSourceLocal` type." }, "SessionInstalledPluginSourceUrl": { "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": "SessionInstalledPluginSourceUrl", "description": "Schema for the `SessionInstalledPluginSourceUrl` type." }, "SessionList": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/definitions/SessionListEntry", "description": "Local or remote session metadata entry. Narrow on `isRemote` to access source-specific fields." }, "description": "Sessions ordered most-recently-modified first. Discriminated by `isRemote`." } }, "required": [ "sessions" ], "additionalProperties": false, "description": "Sessions matching the filter, ordered most-recently-modified first.", "title": "SessionList" }, "SessionListEntry": { "anyOf": [ { "$ref": "#/definitions/LocalSessionMetadataValue" }, { "$ref": "#/definitions/RemoteSessionMetadataValue", "description": "Full remote-session metadata in wire-portable form." } ], "description": "Local or remote session metadata entry. Narrow on `isRemote` to access source-specific fields.", "title": "SessionListEntry" }, "SessionListFilter": { "type": "object", "properties": { "cwd": { "type": "string", "description": "Match sessions whose context.cwd equals this value" }, "gitRoot": { "type": "string", "description": "Match sessions whose context.gitRoot equals this value" }, "repository": { "type": "string", "description": "Match sessions whose context.repository equals this value" }, "branch": { "type": "string", "description": "Match sessions whose context.branch equals this value" } }, "additionalProperties": false, "description": "Optional filter applied to the returned sessions", "title": "SessionListFilter" }, "SessionLoadDeferredRepoHooksResult": { "type": "object", "properties": { "startupPrompts": { "type": "array", "items": { "type": "string" }, "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": [ "startupPrompts", "hookCount" ], "additionalProperties": false, "description": "Queued repo-level startup prompts and the total hook command count after loading.", "title": "SessionLoadDeferredRepoHooksResult" }, "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." } }, "SessionMetadataSnapshot": { "type": "object", "properties": { "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", "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." }, "clientName": { "type": "string", "description": "Runtime client name associated with the session (telemetry identifier)." }, "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": [ "sessionId", "startTime", "modifiedTime", "isRemote", "alreadyInUse", "workspacePath", "workingDirectory", "currentMode", "workspace" ], "additionalProperties": false, "description": "Point-in-time snapshot of slow-changing session identifier and state fields", "title": "SessionMetadataSnapshot" }, "SessionMode": { "type": "string", "enum": [ "interactive", "plan", "autopilot" ], "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." } }, "SessionModelList": { "type": "object", "properties": { "list": { "type": "array", "items": { "x-opaque-json": true }, "description": "Available models, ordered with the most preferred default first." }, "quotaSnapshots": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "Per-quota snapshots returned alongside the model list, keyed by quota type." } }, "required": [ "list" ], "additionalProperties": false, "description": "The list of models available to this session.", "title": "SessionModelList" }, "SessionOpenOptions": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Optional stable session identifier to use for a new session." }, "name": { "type": "string", "description": "Optional human-friendly session name." }, "model": { "type": "string", "description": "Initial model identifier." }, "reasoningEffort": { "type": "string", "description": "Initial reasoning effort level." }, "reasoningSummary": { "$ref": "#/definitions/SessionOpenOptionsReasoningSummary", "description": "Initial reasoning summary mode for supported model clients." }, "clientName": { "type": "string", "description": "Identifier of the client driving the session." }, "clientKind": { "type": "string", "description": "Structured client kind used for runtime behavior gates." }, "lspClientName": { "type": "string", "description": "Identifier sent to LSP-style integrations." }, "integrationId": { "type": "string", "description": "Stable integration identifier for analytics." }, "expAssignments": { "description": "ExP assignment ('flight') data injected by an SDK integrator, in the same JSON shape the Copilot CLI fetches from the experimentation service (CopilotExpAssignmentResponse). When supplied this is fed into the FeatureFlagService exactly like CLI-fetched assignments and ExP-backed flags wait for it. When absent the session does not block on ExP.", "visibility": "internal", "x-opaque-json": true }, "featureFlags": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Feature-flag values resolved by the host." }, "isExperimentalMode": { "type": "boolean", "description": "Whether experimental behavior is enabled." }, "authInfo": { "$ref": "#/definitions/AuthInfo", "description": "Initial authentication info for the session." }, "provider": { "$ref": "#/definitions/ProviderConfig", "description": "Custom model-provider configuration (BYOK)." }, "workingDirectory": { "type": "string", "description": "Working directory to anchor the session." }, "workingDirectoryContext": { "$ref": "#/definitions/SessionContext", "description": "Pre-resolved working-directory context for session startup." }, "remoteSteerable": { "type": "boolean", "description": "Whether this session supports remote steering." }, "remoteExporting": { "type": "boolean", "description": "Telemetry-only remote exporting flag." }, "remoteDefaultedOn": { "type": "boolean", "description": "Telemetry-only remote-defaulted flag." }, "detachedFromSpawningParentSessionId": { "type": "string", "description": "Parent session ID for detached child telemetry rollup." }, "detachedFromSpawningParentEngagementId": { "type": "string", "description": "Parent engagement ID for detached child telemetry rollup." }, "availableTools": { "type": "array", "items": { "type": "string" }, "description": "Allowlist of available tool names." }, "excludedTools": { "type": "array", "items": { "type": "string" }, "description": "Denylist of tool names." }, "enableScriptSafety": { "type": "boolean", "description": "Whether shell-script safety heuristics are enabled." }, "shellInitProfile": { "type": "string", "description": "Shell init profile." }, "shellProcessFlags": { "type": "array", "items": { "type": "string" }, "description": "Per-shell process flags." }, "sandboxConfig": { "$ref": "#/definitions/SandboxConfig", "description": "Resolved sandbox configuration." }, "logInteractiveShells": { "type": "boolean", "description": "Whether interactive shell sessions are logged." }, "envValueMode": { "$ref": "#/definitions/SessionOpenOptionsEnvValueMode", "description": "How MCP server environment values are interpreted." }, "skillDirectories": { "type": "array", "items": { "type": "string" }, "description": "Additional directories to search for skills." }, "disabledSkills": { "type": "array", "items": { "type": "string" }, "description": "Skill IDs disabled for this session." }, "installedPlugins": { "type": "array", "items": { "$ref": "#/definitions/InstalledPlugin" }, "description": "Installed plugins visible to the session." }, "customAgentsLocalOnly": { "type": "boolean", "description": "Whether custom agents default to local-only execution." }, "skipCustomInstructions": { "type": "boolean", "description": "Whether to skip custom instruction sources." }, "disabledInstructionSources": { "type": "array", "items": { "type": "string" }, "description": "Instruction source IDs disabled for this session." }, "coauthorEnabled": { "type": "boolean", "description": "Whether commit-message coauthor trailers are enabled." }, "trajectoryFile": { "type": "string", "description": "Optional trajectory output file path." }, "enableStreaming": { "type": "boolean", "description": "Whether model responses stream as delta events." }, "copilotUrl": { "type": "string", "description": "Override URL for the Copilot API endpoint." }, "askUserDisabled": { "type": "boolean", "description": "Whether ask_user is explicitly disabled." }, "continueOnAutoMode": { "type": "boolean", "description": "Whether auto-mode continuation is enabled." }, "runningInInteractiveMode": { "type": "boolean", "description": "Whether the host is an interactive UI." }, "enableOnDemandInstructionDiscovery": { "type": "boolean", "description": "Whether on-demand custom instruction discovery is enabled." }, "modelCapabilitiesOverrides": { "$ref": "#/definitions/ModelCapabilitiesOverride", "description": "Initial model capability overrides." }, "agentContext": { "type": "string", "description": "Runtime context discriminator for agent filtering." }, "eventsLogDirectory": { "type": "string", "description": "Override directory for session event logs." }, "configDir": { "type": "string", "description": "Override Copilot configuration directory." }, "additionalContentExclusionPolicies": { "type": "array", "items": { "$ref": "#/definitions/SessionOpenOptionsAdditionalContentExclusionPolicy" }, "description": "Additional content-exclusion policies to merge into the session policy set.", "stability": "experimental" }, "memory": { "$ref": "#/definitions/MemoryConfiguration", "description": "Memory configuration for this session." }, "sessionCapabilities": { "type": "array", "items": { "$ref": "#/definitions/SessionCapability", "description": "Session capability enabled for this session" }, "description": "Capabilities enabled for this session." } }, "additionalProperties": false, "description": "Session construction options.", "title": "SessionOpenOptions" }, "SessionOpenOptionsAdditionalContentExclusionPolicy": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/definitions/SessionOpenOptionsAdditionalContentExclusionPolicyRule" } }, "last_updated_at": { "type": [ "string", "number" ], "x-opaque-json": true }, "scope": { "$ref": "#/definitions/SessionOpenOptionsAdditionalContentExclusionPolicyScope", "description": "Allowed values for the `SessionOpenOptionsAdditionalContentExclusionPolicyScope` enumeration." } }, "required": [ "rules", "last_updated_at", "scope" ], "additionalProperties": true, "title": "SessionOpenOptionsAdditionalContentExclusionPolicy", "description": "Schema for the `SessionOpenOptionsAdditionalContentExclusionPolicy` type." }, "SessionOpenOptionsAdditionalContentExclusionPolicyRule": { "type": "object", "properties": { "paths": { "type": "array", "items": { "type": "string" } }, "ifAnyMatch": { "type": "array", "items": { "type": "string" } }, "ifNoneMatch": { "type": "array", "items": { "type": "string" } }, "source": { "$ref": "#/definitions/SessionOpenOptionsAdditionalContentExclusionPolicyRuleSource", "description": "Schema for the `SessionOpenOptionsAdditionalContentExclusionPolicyRuleSource` type." } }, "required": [ "paths", "source" ], "additionalProperties": true, "title": "SessionOpenOptionsAdditionalContentExclusionPolicyRule", "description": "Schema for the `SessionOpenOptionsAdditionalContentExclusionPolicyRule` type." }, "SessionOpenOptionsAdditionalContentExclusionPolicyRuleSource": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type" ], "additionalProperties": false, "title": "SessionOpenOptionsAdditionalContentExclusionPolicyRuleSource", "description": "Schema for the `SessionOpenOptionsAdditionalContentExclusionPolicyRuleSource` type." }, "SessionOpenOptionsAdditionalContentExclusionPolicyScope": { "type": "string", "enum": [ "repo", "all" ], "title": "SessionOpenOptionsAdditionalContentExclusionPolicyScope", "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 `SessionOpenOptionsAdditionalContentExclusionPolicyScope` enumeration." }, "SessionOpenOptionsEnvValueMode": { "type": "string", "enum": [ "direct", "indirect" ], "description": "How MCP server environment values are interpreted.", "title": "SessionOpenOptionsEnvValueMode", "x-enumDescriptions": { "direct": "Pass MCP server environment values as literal strings.", "indirect": "Resolve MCP server environment values from host-side references." } }, "SessionOpenOptionsReasoningSummary": { "type": "string", "enum": [ "none", "concise", "detailed" ], "description": "Initial reasoning summary mode for supported model clients.", "title": "SessionOpenOptionsReasoningSummary", "x-enumDescriptions": { "none": "Do not request reasoning summaries from the model.", "concise": "Request a concise summary of model reasoning.", "detailed": "Request a detailed summary of model reasoning." } }, "SessionOpenParams": { "anyOf": [ { "$ref": "#/definitions/SessionsOpenCreate", "description": "Parameters for creating a new local session." }, { "$ref": "#/definitions/SessionsOpenResume", "description": "Parameters for resuming a specific local session." }, { "$ref": "#/definitions/SessionsOpenResumeLast", "description": "Parameters for resuming the most relevant local session." }, { "$ref": "#/definitions/SessionsOpenAttach", "description": "Parameters for attaching to an already-active session by ID." }, { "$ref": "#/definitions/SessionsOpenRemote", "description": "Parameters for connecting to a live remote session." }, { "$ref": "#/definitions/SessionsOpenCloud", "description": "Parameters for creating a new cloud session." }, { "$ref": "#/definitions/SessionsOpenHandoff", "description": "Parameters for fetching a remote session and handing it off to a new local session." } ], "description": "Open a session by creating, resuming, attaching, connecting to a remote, or handing off.", "title": "SessionOpenParams" }, "SessionOpenResult": { "type": "object", "properties": { "status": { "$ref": "#/definitions/SessionsOpenStatus", "description": "Outcome of the open request." }, "sessionId": { "type": "string", "description": "Opened session ID. Omitted when status is `not_found`." }, "sessionApi": { "description": "In-process SessionClientApi handle for the opened session, returned to CLI callers as a transitional shortcut. Marked internal so the public SDK surface does not expose it; SDK consumers should construct per-session clients from `sessionId` instead.", "visibility": "internal", "x-opaque-json": true }, "startupPrompts": { "type": "array", "items": { "type": "string" }, "description": "Startup prompts queued by user-level hook configs at session creation. Only populated when status is `created`; resumed sessions return an empty array." }, "remoteSessionId": { "type": "string", "description": "Remote session ID, present when status is `connected`." }, "metadata": { "$ref": "#/definitions/RemoteSessionMetadataValue", "description": "Remote session metadata, present when status is `connected`." }, "progress": { "type": "array", "items": { "$ref": "#/definitions/SessionsOpenProgress" }, "description": "Handoff progress steps, present when status is `handed_off`." } }, "required": [ "status" ], "additionalProperties": false, "description": "Result of opening a session.", "title": "SessionOpenResult" }, "SessionPruneResult": { "type": "object", "properties": { "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": "Outcome of the prune operation: deleted IDs, dry-run candidates, skipped IDs, total bytes freed, and the dry-run flag.", "title": "SessionPruneResult" }, "SessionsBulkDeleteRequest": { "type": "object", "properties": { "sessionIds": { "type": "array", "items": { "type": "string" }, "description": "Session IDs to close, deactivate, and delete from disk" } }, "required": [ "sessionIds" ], "additionalProperties": false, "description": "Session IDs to close, deactivate, and delete from disk.", "title": "SessionsBulkDeleteRequest" }, "SessionsCheckInUseRequest": { "type": "object", "properties": { "sessionIds": { "type": "array", "items": { "type": "string" }, "description": "Session IDs to test for live in-use locks" } }, "required": [ "sessionIds" ], "additionalProperties": false, "description": "Session IDs to test for live in-use locks.", "title": "SessionsCheckInUseRequest" }, "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" ], "additionalProperties": false, "description": "Session IDs from the input set that are currently in use by another process.", "title": "SessionsCheckInUseResult" }, "SessionsCloseRequest": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Session ID to close" } }, "required": [ "sessionId" ], "additionalProperties": false, "description": "Session ID to close.", "title": "SessionsCloseRequest" }, "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": { "sessions": { "type": "array", "items": { "$ref": "#/definitions/LocalSessionMetadataValue" }, "description": "Session metadata records to enrich. Records that already have summary and context are returned unchanged." } }, "required": [ "sessions" ], "additionalProperties": false, "description": "Session metadata records to enrich with summary and context information.", "title": "SessionsEnrichMetadataRequest" }, "SessionSetCredentialsParams": { "type": "object", "properties": { "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 operation succeeded" } }, "required": [ "success" ], "additionalProperties": false, "description": "Indicates whether the credential update succeeded.", "title": "SessionSetCredentialsResult" }, "SessionsFindByPrefixRequest": { "type": "object", "properties": { "prefix": { "type": "string", "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": [ "prefix" ], "additionalProperties": false, "description": "UUID prefix to resolve to a unique session ID.", "title": "SessionsFindByPrefixRequest" }, "SessionsFindByPrefixResult": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Omitted when no unique session matches the prefix (no match or ambiguous)" } }, "additionalProperties": false, "description": "Session ID matching the prefix, omitted when no unique match exists.", "title": "SessionsFindByPrefixResult" }, "SessionsFindByTaskIDRequest": { "type": "object", "properties": { "taskId": { "type": "string", "description": "GitHub task ID to look up" } }, "required": [ "taskId" ], "additionalProperties": false, "description": "GitHub task ID to look up.", "title": "SessionsFindByTaskIDRequest" }, "SessionsFindByTaskIDResult": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Omitted when no local session is bound to that GitHub task" } }, "additionalProperties": false, "description": "ID of the local session bound to the given GitHub task, or omitted when none.", "title": "SessionsFindByTaskIDResult" }, "SessionsForkRequest": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Source session ID to fork from" }, "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." }, "name": { "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": { "type": "string", "description": "The new forked session's ID" }, "name": { "type": "string", "description": "Friendly name assigned to the forked session, if any." } }, "required": [ "sessionId" ], "additionalProperties": false, "description": "Identifier and optional friendly name assigned to the newly forked session.", "title": "SessionsForkResult" }, "SessionsGetBoardEntryCountRequest": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Session ID whose board entry count should be returned." } }, "required": [ "sessionId" ], "additionalProperties": false, "description": "Session ID whose board entry count should be returned.", "title": "SessionsGetBoardEntryCountRequest" }, "SessionsGetBoardEntryCountResult": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "description": "Board entry count, when available." } }, "additionalProperties": false, "description": "Dynamic-context board entry count, when available.", "title": "SessionsGetBoardEntryCountResult" }, "SessionsGetEventFilePathRequest": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Session ID whose event-log file path to compute" } }, "required": [ "sessionId" ], "additionalProperties": false, "description": "Session ID whose event-log file path to compute.", "title": "SessionsGetEventFilePathRequest" }, "SessionsGetEventFilePathResult": { "type": "object", "properties": { "filePath": { "type": "string", "description": "Absolute path to the session's events.jsonl file" } }, "required": [ "filePath" ], "additionalProperties": false, "description": "Absolute path to the session's events.jsonl file on disk.", "title": "SessionsGetEventFilePathResult" }, "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" }, "SessionsGetLastForContextResult": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Most-relevant session ID for the supplied context, or omitted when no sessions exist" } }, "additionalProperties": false, "description": "Most-relevant session ID for the supplied context, or omitted when no sessions exist.", "title": "SessionsGetLastForContextResult" }, "SessionsGetPersistedRemoteSteerableRequest": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Session ID to look up the persisted remote-steerable flag for" } }, "required": [ "sessionId" ], "additionalProperties": false, "description": "Session ID to look up the persisted remote-steerable flag for.", "title": "SessionsGetPersistedRemoteSteerableRequest" }, "SessionsGetPersistedRemoteSteerableResult": { "type": "object", "properties": { "remoteSteerable": { "type": "boolean", "description": "The session's persisted remote-steerable flag if recorded; omitted when no value has been persisted" } }, "additionalProperties": false, "description": "The session's persisted remote-steerable flag, or omitted when no value has been persisted.", "title": "SessionsGetPersistedRemoteSteerableResult" }, "SessionSizes": { "type": "object", "properties": { "sizes": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 }, "description": "Map of sessionId -> on-disk size in bytes for the session's workspace directory" } }, "required": [ "sizes" ], "additionalProperties": false, "description": "Map of sessionId -> on-disk size in bytes for each session's workspace directory.", "title": "SessionSizes" }, "SessionsListRequest": { "anyOf": [ { "not": {} }, { "type": "object", "properties": { "source": { "$ref": "#/definitions/SessionSource", "description": "Which session sources to include. Defaults to `local` for backward compatibility." }, "metadataLimit": { "type": "integer", "minimum": 0, "description": "When provided, only the first N local 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 local session. Has no effect on remote entries (which always carry their full shape)." }, "filter": { "$ref": "#/definitions/SessionListFilter", "description": "Optional filter applied to the returned sessions" }, "includeDetached": { "type": "boolean", "description": "When true, include detached maintenance sessions. Defaults to false for user-facing session lists." }, "throwOnError": { "type": "boolean", "description": "Only meaningful when `source` includes remote. When true, propagates errors from the remote service instead of silently returning an empty remote list. Defaults to false." } }, "additionalProperties": false, "description": "Optional source filter, metadata-load limit, and context filter applied to the returned sessions." } ], "description": "Optional source filter, metadata-load limit, and context filter applied to the returned sessions.", "title": "SessionsListRequest" }, "SessionsLoadDeferredRepoHooksRequest": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Active session ID whose deferred repo-level hooks should be loaded" } }, "required": [ "sessionId" ], "additionalProperties": false, "description": "Active session ID whose deferred repo-level hooks should be loaded.", "title": "SessionsLoadDeferredRepoHooksRequest" }, "SessionsOpenAttach": { "type": "object", "properties": { "kind": { "type": "string", "const": "attach", "description": "Attach to an already-active in-process session by ID. Unlike `resume`, this does NOT re-load from disk; the session must already be loaded by an earlier `create`/`resume` call. Returns `status: 'not_found'` when no active session matches the id. Useful for in-process consumers that need a fresh API handle to a session opened elsewhere (e.g., a peer foreground-session switch)." }, "sessionId": { "type": "string", "description": "Session ID to attach to." } }, "required": [ "kind", "sessionId" ], "additionalProperties": false, "description": "Parameters for attaching to an already-active session by ID.", "title": "SessionsOpenAttach" }, "SessionsOpenCloud": { "type": "object", "properties": { "kind": { "type": "string", "const": "cloud", "description": "Create a new cloud (coding-agent) session." }, "repository": { "$ref": "#/definitions/RemoteSessionRepository", "description": "Repository for the cloud session." }, "owner": { "type": "string", "description": "Optional owner (user or organization login) to associate with the cloud session when no repository is provided. Ignored when `repository` is set (the repo's owner takes precedence)." }, "options": { "$ref": "#/definitions/SessionOpenOptions", "description": "Session options for cloud session creation." }, "onTaskCreated": { "description": "In-process callback invoked when the cloud task is created (before connection). Marked internal because a function reference cannot cross the JSON-RPC boundary. Disappears in the SDK migration: the field is purely cosmetic (it flips a single CLI phase label from 'creating' to 'connecting') and the wire-clean version just drops the intermediate phase.", "visibility": "internal", "x-opaque-json": true } }, "required": [ "kind" ], "additionalProperties": false, "description": "Parameters for creating a new cloud session.", "title": "SessionsOpenCloud" }, "SessionsOpenCreate": { "type": "object", "properties": { "kind": { "type": "string", "const": "create", "description": "Create a new local session." }, "options": { "$ref": "#/definitions/SessionOpenOptions", "description": "Session construction options." }, "emitStart": { "type": "boolean", "description": "Whether to emit session.start during creation. Defaults to true." } }, "required": [ "kind" ], "additionalProperties": false, "description": "Parameters for creating a new local session.", "title": "SessionsOpenCreate" }, "SessionsOpenHandoff": { "type": "object", "properties": { "kind": { "type": "string", "const": "handoff", "description": "Fetch a remote session and hand it off to a new local session." }, "metadata": { "$ref": "#/definitions/RemoteSessionMetadataValue", "description": "Remote session metadata for the session to hand off (typically obtained from `sessions.list` with `source: \"remote\"`)." }, "options": { "$ref": "#/definitions/SessionOpenOptions", "description": "Session construction options for the new local session." }, "taskType": { "$ref": "#/definitions/SessionsOpenHandoffTaskType", "description": "Task type determines the handoff strategy (CCA fetches events; CLI prepares a transient session)." }, "onProgress": { "description": "In-process progress callback `(update) => void` invoked for each handoff step. Marked internal because a function reference cannot cross the JSON-RPC boundary. The host-side `handoffSession` is already declared as `AsyncGenerator`; the schema layer flattens it because it does not yet support streaming methods. The wire-clean replacement is to expose the AsyncGenerator directly (or use vscode-jsonrpc `$/progress` notifications) once the schema/transport layer supports it.", "visibility": "internal", "x-opaque-json": true } }, "required": [ "kind", "metadata" ], "additionalProperties": false, "description": "Parameters for fetching a remote session and handing it off to a new local session.", "title": "SessionsOpenHandoff" }, "SessionsOpenHandoffTaskType": { "type": "string", "enum": [ "cca", "cli" ], "description": "Task type determines the handoff strategy (CCA fetches events; CLI prepares a transient session).", "title": "SessionsOpenHandoffTaskType", "x-enumDescriptions": { "cca": "GitHub Copilot coding agent task.", "cli": "CLI remote task." } }, "SessionsOpenProgress": { "type": "object", "properties": { "step": { "$ref": "#/definitions/SessionsOpenProgressStep", "description": "Handoff step." }, "status": { "$ref": "#/definitions/SessionsOpenProgressStatus", "description": "Step status." }, "message": { "type": "string", "description": "Optional step message." } }, "required": [ "step", "status" ], "additionalProperties": false, "title": "SessionsOpenProgress", "description": "Schema for the `SessionsOpenProgress` type." }, "SessionsOpenProgressStatus": { "type": "string", "enum": [ "in-progress", "complete" ], "description": "Step status.", "title": "SessionsOpenProgressStatus", "x-enumDescriptions": { "in-progress": "The step has started and has not yet finished.", "complete": "The step has completed successfully." } }, "SessionsOpenProgressStep": { "type": "string", "enum": [ "load-session", "validate-repo", "check-changes", "checkout-branch", "create-session", "save-session" ], "description": "Handoff step.", "title": "SessionsOpenProgressStep", "x-enumDescriptions": { "load-session": "Loading the source session's events from the remote service.", "validate-repo": "Validating that the local repository matches the remote session's repository.", "check-changes": "Checking the local working tree for uncommitted changes that would block the handoff.", "checkout-branch": "Checking out the branch associated with the remote session in the local working tree.", "create-session": "Creating the new local session and seeding it with the source session's events.", "save-session": "Persisting the newly-created local session to disk." } }, "SessionsOpenRemote": { "type": "object", "properties": { "kind": { "type": "string", "const": "remote", "description": "Connect to a live remote session." }, "remoteSessionId": { "type": "string", "description": "Remote session identifier to connect to." }, "repository": { "$ref": "#/definitions/RemoteSessionRepository", "description": "Repository context for the remote session." }, "options": { "$ref": "#/definitions/SessionOpenOptions", "description": "Session options for the connection." } }, "required": [ "kind", "remoteSessionId" ], "additionalProperties": false, "description": "Parameters for connecting to a live remote session.", "title": "SessionsOpenRemote" }, "SessionsOpenResume": { "type": "object", "properties": { "kind": { "type": "string", "const": "resume", "description": "Resume a specific local session by ID or prefix." }, "sessionId": { "type": "string", "description": "Session ID or unique prefix to resume." }, "options": { "$ref": "#/definitions/SessionOpenOptions", "description": "Session resume options." }, "resume": { "type": "boolean", "description": "Whether to emit session.resume after loading. Defaults to true." }, "suppressResumeWorkspaceMetadataWriteback": { "type": "boolean", "description": "Suppress workspace.yaml metadata writeback when resuming from an incidental cwd." } }, "required": [ "kind", "sessionId" ], "additionalProperties": false, "description": "Parameters for resuming a specific local session.", "title": "SessionsOpenResume" }, "SessionsOpenResumeLast": { "type": "object", "properties": { "kind": { "type": "string", "const": "resumeLast", "description": "Resume the most relevant existing local session." }, "context": { "$ref": "#/definitions/SessionContext", "description": "Working-directory context used to choose the most relevant session." }, "options": { "$ref": "#/definitions/SessionOpenOptions", "description": "Session resume options." }, "suppressResumeWorkspaceMetadataWriteback": { "type": "boolean", "description": "Suppress workspace.yaml metadata writeback when resuming from an incidental cwd." } }, "required": [ "kind" ], "additionalProperties": false, "description": "Parameters for resuming the most relevant local session.", "title": "SessionsOpenResumeLast" }, "SessionsOpenStatus": { "type": "string", "enum": [ "created", "resumed", "not_found", "connected", "handed_off" ], "description": "Outcome of the open request.", "title": "SessionsOpenStatus", "x-enumDescriptions": { "created": "A new session was created.", "resumed": "An existing session was loaded or reattached.", "not_found": "No matching persisted session was found.", "connected": "Connected to an existing remote session.", "handed_off": "Remote session was handed off to a new local session." } }, "SessionSource": { "type": "string", "enum": [ "local", "remote", "all" ], "description": "Which session sources to include. Defaults to `local` for backward compatibility.", "title": "SessionSource", "x-enumDescriptions": { "local": "Return only local sessions.", "remote": "Return only remote sessions.", "all": "Return both local and remote sessions." } }, "SessionsPollSpawnedSessionsEvent": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Session id of the newly-spawned session." } }, "required": [ "sessionId" ], "additionalProperties": false, "title": "SessionsPollSpawnedSessionsEvent", "description": "Schema for the `SessionsPollSpawnedSessionsEvent` type." }, "SessionsPollSpawnedSessionsRequest": { "anyOf": [ { "not": {} }, { "type": "object", "properties": { "cursor": { "type": "string", "description": "Opaque cursor returned by a previous poll. Omit on the first call to receive any spawn events buffered since the runtime started." }, "waitMs": { "type": "integer", "minimum": 0, "maximum": 60000, "description": "Milliseconds to wait for new spawn events when the cursor is at the tail. 0 (default) returns immediately even if no events are buffered. Capped at 60000ms.", "format": "duration" } }, "additionalProperties": false } ], "description": "Cursor and optional long-poll wait for polling runtime-spawned sessions.", "title": "SessionsPollSpawnedSessionsRequest" }, "SessionsPruneOldRequest": { "type": "object", "properties": { "olderThanDays": { "type": "integer", "minimum": 0, "description": "Delete sessions whose modifiedTime is at least this many days old" }, "dryRun": { "type": "boolean", "description": "When true, only report what would be deleted without performing any deletion" }, "includeNamed": { "type": "boolean", "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": [ "olderThanDays" ], "additionalProperties": false, "description": "Age threshold and optional flags controlling which old sessions are pruned (or simulated when dryRun is true).", "title": "SessionsPruneOldRequest" }, "SessionsRegisterExtensionToolsOnSessionOptions": { "type": "object", "properties": { "enabled": { "description": "In-process `() => boolean` gating callback (CLI-only optimization). Marked internal: replaced by runtime-side enable/disable RPCs in the SDK migration.", "visibility": "internal", "x-opaque-json": true } }, "additionalProperties": false, "description": "Optional registration options.", "title": "SessionsRegisterExtensionToolsOnSessionOptions" }, "SessionsReleaseLockRequest": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Session ID whose in-use lock should be released" } }, "required": [ "sessionId" ], "additionalProperties": false, "description": "Session ID whose in-use lock should be released.", "title": "SessionsReleaseLockRequest" }, "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" }, "SessionsReloadPluginHooksRequest": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Active session ID to reload hooks for" }, "deferRepoHooks": { "type": "boolean", "description": "When true, skip repo-level hooks. Use before folder trust is confirmed; loadDeferredRepoHooks loads them post-trust." } }, "required": [ "sessionId" ], "additionalProperties": false, "description": "Active session ID and an optional flag for deferring repo-level hooks until folder trust.", "title": "SessionsReloadPluginHooksRequest" }, "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": { "sessionId": { "type": "string", "description": "Session ID whose pending events should be flushed to disk" } }, "required": [ "sessionId" ], "additionalProperties": false, "description": "Session ID whose pending events should be flushed to disk.", "title": "SessionsSaveRequest" }, "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": { "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": [ "plugins" ], "additionalProperties": false, "description": "Manager-wide additional plugins to register; replaces any previously-configured set.", "title": "SessionsSetAdditionalPluginsRequest" }, "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" }, "SessionsSetRemoteControlSteeringRequest": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Target steering state. Today only `true` is actionable on the underlying exporter; `false` is reserved for future use." } }, "required": [ "enabled" ], "additionalProperties": false, "description": "Patch for the singleton's steering state.", "title": "SessionsSetRemoteControlSteeringRequest" }, "SessionsStartRemoteControlRequest": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Local session id to attach remote control to." }, "config": { "$ref": "#/definitions/RemoteControlConfig", "description": "Configuration for the runtime-managed remote-control singleton." } }, "required": [ "sessionId", "config" ], "additionalProperties": false, "description": "Parameters for attaching the remote-control singleton to a session.", "title": "SessionsStartRemoteControlRequest" }, "SessionsStopRemoteControlRequest": { "anyOf": [ { "not": {} }, { "type": "object", "properties": { "expectedSessionId": { "type": "string", "description": "When provided, the stop is rejected unless the singleton currently points at this session id (compare-and-swap semantics)." }, "force": { "type": "boolean", "description": "When true, the singleton is unconditionally torn down regardless of `expectedSessionId`. Use during shutdown or explicit `/remote off`." } }, "additionalProperties": false } ], "description": "Parameters for stopping the remote-control singleton.", "title": "SessionsStopRemoteControlRequest" }, "SessionsTransferRemoteControlRequest": { "type": "object", "properties": { "toSessionId": { "type": "string", "description": "Local session id to point remote control at." }, "expectedFromSessionId": { "type": "string", "description": "When provided, the transfer is rejected unless the singleton currently points at this session id (compare-and-swap semantics to avoid clobbering newer state)." } }, "required": [ "toSessionId" ], "additionalProperties": false, "description": "Parameters for atomically rebinding the remote-control singleton.", "title": "SessionsTransferRemoteControlRequest" }, "SessionTelemetryEngagement": { "type": "object", "properties": { "engagementId": { "type": "string", "description": "Current telemetry engagement ID, when available." } }, "additionalProperties": false, "description": "Telemetry engagement ID for the session, when available.", "title": "SessionTelemetryEngagement" }, "SessionUpdateOptionsParams": { "type": "object", "properties": { "model": { "type": "string", "description": "The model ID to use for assistant turns." }, "modelCapabilitiesOverrides": { "$ref": "#/definitions/ModelCapabilitiesOverride", "description": "Per-property model capability overrides for the selected model." }, "reasoningEffort": { "type": "string", "description": "Reasoning effort for the selected model (model-defined enum)." }, "reasoningSummary": { "$ref": "#/definitions/OptionsUpdateReasoningSummary", "description": "Reasoning summary mode for supported model clients." }, "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": { "$ref": "#/definitions/ProviderConfig", "description": "Custom model-provider configuration (BYOK)." }, "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." }, "toolFilterPrecedence": { "$ref": "#/definitions/OptionsUpdateToolFilterPrecedence", "description": "Controls how availableTools (allowlist) and excludedTools (denylist) combine when both are set." }, "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": { "$ref": "#/definitions/SandboxConfig", "description": "Resolved sandbox configuration." }, "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." }, "suppressCustomAgentPrompt": { "type": "boolean", "description": "When true, the selected custom agent's prompt is not injected into the user message (skill context is still injected). Used by automation triggers where the agent prompt is already in the problem statement." }, "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": { "$ref": "#/definitions/OptionsUpdateAdditionalContentExclusionPolicy" }, "description": "Additional content-exclusion policies to merge into the session's policy set.", "stability": "experimental" }, "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)." }, "sessionCapabilities": { "type": "array", "items": { "$ref": "#/definitions/SessionCapability", "description": "Session capability id" }, "description": "Replaces the session's capability set with the given list. Use to enable or disable capabilities mid-session (e.g., remove `memory` for reproducible scripted runs). Omit the field to leave the existing capability set unchanged." }, "skipEmbeddingRetrieval": { "type": "boolean", "description": "Whether to skip embedding retrieval pipeline initialization and execution." }, "organizationCustomInstructions": { "type": "string", "description": "Organization-level custom instructions to inject into the system prompt." }, "enableFileHooks": { "type": "boolean", "description": "Whether to enable loading of `.github/hooks/` filesystem hooks. Separate from the SDK callback hook mechanism." }, "enableHostGitOperations": { "type": "boolean", "description": "Whether to enable host git operations (context resolution, child repo scanning, git info in system prompt)." }, "enableSessionStore": { "type": "boolean", "description": "Whether to enable cross-session store writes and reads." }, "enableSkills": { "type": "boolean", "description": "Whether to enable skill directory scanning and loading. Falls back to enableConfigDiscovery when unset." }, "contextTier": { "$ref": "#/definitions/OptionsUpdateContextTier", "description": "Context tier for models with tiered pricing. The session uses this to derive effective `modelCapabilitiesOverrides` so compaction, truncation, token display, and request limits honor the selected tier." } }, "additionalProperties": false, "description": "Patch of mutable session options to apply to the running session.", "title": "SessionUpdateOptionsParams" }, "SessionUpdateOptionsResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" } }, "required": [ "success" ], "additionalProperties": false, "description": "Indicates whether the session options patch was applied successfully.", "title": "SessionUpdateOptionsResult" }, "SessionWorkingDirectoryContext": { "type": "object", "properties": { "cwd": { "type": "string", "description": "Current working directory path" }, "gitRoot": { "type": "string", "description": "Root directory of the git repository, resolved via git rev-parse" }, "repository": { "type": "string", "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": "Raw host string from the git remote URL (e.g. \"github.com\", \"dev.azure.com\")" }, "branch": { "type": "string", "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": [ "cwd" ], "additionalProperties": false, "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." } }, "ShellCancelUserRequestedRequest": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Request ID previously passed to executeUserRequested" } }, "required": [ "requestId" ], "additionalProperties": false, "description": "User-requested shell execution cancellation handle.", "title": "ShellCancelUserRequestedRequest" }, "ShellExecRequest": { "type": "object", "properties": { "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": [ "command" ], "additionalProperties": false, "description": "Shell command to run, with optional working directory and timeout in milliseconds.", "title": "ShellExecRequest" }, "ShellExecResult": { "type": "object", "properties": { "processId": { "type": "string", "description": "Unique identifier for tracking streamed output" } }, "required": [ "processId" ], "additionalProperties": false, "description": "Identifier of the spawned process, used to correlate streamed output and exit notifications.", "title": "ShellExecResult" }, "ShellExecuteUserRequestedRequest": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Caller-provided cancellation handle for this execution" }, "command": { "type": "string", "description": "Shell command to execute" } }, "required": [ "requestId", "command" ], "additionalProperties": false, "description": "User-requested shell command and cancellation handle.", "title": "ShellExecuteUserRequestedRequest" }, "ShellKillRequest": { "type": "object", "properties": { "processId": { "type": "string", "description": "Process identifier returned by shell.exec" }, "signal": { "$ref": "#/definitions/ShellKillSignal", "description": "Signal to send (default: SIGTERM)" } }, "required": [ "processId" ], "additionalProperties": false, "description": "Identifier of a process previously returned by \"shell.exec\" and the signal to send.", "title": "ShellKillRequest" }, "ShellKillResult": { "type": "object", "properties": { "killed": { "type": "boolean", "description": "Whether the signal was sent successfully" } }, "required": [ "killed" ], "additionalProperties": false, "description": "Indicates whether the signal was delivered; false if the process was unknown or already exited.", "title": "ShellKillResult" }, "ShellKillSignal": { "type": "string", "enum": [ "SIGTERM", "SIGKILL", "SIGINT" ], "description": "Signal to send (default: SIGTERM)", "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", "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" }, "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": [ "name", "description", "source", "userInvocable", "enabled" ], "additionalProperties": false, "title": "Skill", "description": "Schema for the `Skill` type." }, "SkillList": { "type": "object", "properties": { "skills": { "type": "array", "items": { "$ref": "#/definitions/Skill" }, "description": "Available skills" } }, "required": [ "skills" ], "additionalProperties": false, "description": "Skills available to the session, with their enabled state.", "title": "SkillList" }, "SkillsConfigSetDisabledSkillsRequest": { "type": "object", "properties": { "disabledSkills": { "type": "array", "items": { "type": "string" }, "description": "List of skill names to disable" } }, "required": [ "disabledSkills" ], "additionalProperties": false, "description": "Skill names to mark as disabled in global configuration, replacing any previous list.", "title": "SkillsConfigSetDisabledSkillsRequest" }, "SkillsDisableRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the skill to disable" } }, "required": [ "name" ], "additionalProperties": false, "description": "Name of the skill to disable for the session.", "title": "SkillsDisableRequest" }, "SkillsDiscoverRequest": { "type": "object", "properties": { "projectPaths": { "type": "array", "items": { "type": "string" }, "description": "Optional list of project directory paths to scan for project-scoped skills" }, "skillDirectories": { "type": "array", "items": { "type": "string" }, "description": "Optional list of additional skill directory paths to include" } }, "additionalProperties": false, "description": "Optional project paths and additional skill directories to include in discovery.", "title": "SkillsDiscoverRequest" }, "SkillsEnableRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the skill to enable" } }, "required": [ "name" ], "additionalProperties": false, "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": { "warnings": { "type": "array", "items": { "type": "string" }, "description": "Warnings emitted while loading skills (e.g. skills that loaded but had issues)" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Errors emitted while loading skills (e.g. skills that failed to load entirely)" } }, "required": [ "warnings", "errors" ], "additionalProperties": false, "description": "Diagnostics from reloading skill definitions, with warnings and errors as separate lists.", "title": "SkillsLoadDiagnostics" }, "SkillSource": { "type": "string", "enum": [ "project", "inherited", "personal-copilot", "personal-agents", "plugin", "custom", "builtin" ], "description": "Source location type (e.g., project, personal-copilot, plugin, builtin)", "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", "properties": { "kind": { "type": "string", "const": "agent-prompt", "description": "Agent prompt result discriminator" }, "prompt": { "type": "string", "description": "Prompt to submit to the agent" }, "displayPrompt": { "type": "string", "description": "Prompt text to display to the user" }, "mode": { "$ref": "#/definitions/SessionMode", "description": "Optional target session mode for the agent prompt" }, "runtimeSettingsChanged": { "type": "boolean", "description": "True when the invocation mutated user runtime settings; consumers caching settings should refresh" } }, "required": [ "kind", "prompt", "displayPrompt" ], "additionalProperties": false, "title": "SlashCommandAgentPromptResult", "description": "Schema for the `SlashCommandAgentPromptResult` type." }, "SlashCommandCompletedResult": { "type": "object", "properties": { "kind": { "type": "string", "const": "completed", "description": "Completed result discriminator" }, "message": { "type": "string", "description": "Optional user-facing message describing the completed command" }, "runtimeSettingsChanged": { "type": "boolean", "description": "True when the invocation mutated user runtime settings; consumers caching settings should refresh" } }, "required": [ "kind" ], "additionalProperties": false, "title": "SlashCommandCompletedResult", "description": "Schema for the `SlashCommandCompletedResult` type." }, "SlashCommandInfo": { "type": "object", "properties": { "name": { "type": "string", "description": "Canonical command name without a leading slash" }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Canonical aliases without leading slashes" }, "description": { "type": "string", "description": "Human-readable command description" }, "kind": { "$ref": "#/definitions/SlashCommandKind", "description": "Coarse command category for grouping and behavior: runtime built-in, skill-backed command, or SDK/client-owned command" }, "input": { "$ref": "#/definitions/SlashCommandInput", "description": "Optional unstructured input hint" }, "allowDuringAgentExecution": { "type": "boolean", "description": "Whether the command may run while an agent turn is active" }, "experimental": { "type": "boolean", "description": "Whether the command is experimental" }, "schedulable": { "type": "boolean", "description": "Whether the command may be the target of `/every` / `/after` schedules. Resolution happens at every tick, so only set this when the command is safe to re-invoke and produces an agent prompt." } }, "required": [ "name", "description", "kind", "allowDuringAgentExecution" ], "additionalProperties": false, "title": "SlashCommandInfo", "description": "Schema for the `SlashCommandInfo` type." }, "SlashCommandInput": { "type": "object", "properties": { "hint": { "type": "string", "description": "Hint to display when command input has not been provided" }, "required": { "type": "boolean", "description": "When true, the command requires non-empty input; clients should render the input hint as required" }, "completion": { "$ref": "#/definitions/SlashCommandInputCompletion", "description": "Optional completion hint for the input (e.g. 'directory' for filesystem path completion)" }, "preserveMultilineInput": { "type": "boolean", "description": "When true, clients should pass the full text after the command name as a single argument rather than splitting on whitespace" } }, "required": [ "hint" ], "additionalProperties": false, "description": "Optional unstructured input hint", "title": "SlashCommandInput" }, "SlashCommandInputCompletion": { "type": "string", "enum": [ "directory" ], "description": "Optional completion hint for the input (e.g. 'directory' for filesystem path completion)", "title": "SlashCommandInputCompletion", "x-enumDescriptions": { "directory": "Input should complete filesystem directories." } }, "SlashCommandInvocationResult": { "anyOf": [ { "$ref": "#/definitions/SlashCommandTextResult" }, { "$ref": "#/definitions/SlashCommandAgentPromptResult" }, { "$ref": "#/definitions/SlashCommandCompletedResult" }, { "$ref": "#/definitions/SlashCommandSelectSubcommandResult" } ], "description": "Result of invoking the slash command (text output, prompt to send to the agent, or completion).", "title": "SlashCommandInvocationResult" }, "SlashCommandKind": { "type": "string", "enum": [ "builtin", "skill", "client" ], "description": "Coarse command category for grouping and behavior: runtime built-in, skill-backed command, or SDK/client-owned command", "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", "properties": { "kind": { "type": "string", "const": "text", "description": "Text result discriminator" }, "text": { "type": "string", "description": "Text output for the client to render" }, "markdown": { "type": "boolean", "description": "Whether text contains Markdown" }, "preserveAnsi": { "type": "boolean", "description": "Whether ANSI sequences should be preserved" }, "runtimeSettingsChanged": { "type": "boolean", "description": "True when the invocation mutated user runtime settings; consumers caching settings should refresh" } }, "required": [ "kind", "text" ], "additionalProperties": false, "title": "SlashCommandTextResult", "description": "Schema for the `SlashCommandTextResult` type." }, "SubagentSettings": { "anyOf": [ { "type": "object", "properties": { "agents": { "type": "object", "additionalProperties": { "$ref": "#/definitions/SubagentSettingsEntry", "description": "Subagent model, reasoning effort, and context tier settings" }, "description": "Per-agent settings keyed by subagent agent_type" }, "disabledSubagents": { "type": "array", "items": { "type": "string" }, "description": "Names of subagents the user has turned off; they cannot be dispatched" } }, "additionalProperties": false, "description": "Configured per-agent subagent overrides" }, { "type": "null" } ], "description": "Subagent settings to apply, or null to clear the live session override", "title": "SubagentSettings" }, "SubagentSettingsEntry": { "type": "object", "properties": { "model": { "type": "string", "description": "Model override for matching subagents" }, "effortLevel": { "type": "string", "description": "Reasoning effort override for matching subagents" }, "contextTier": { "$ref": "#/definitions/SubagentSettingsEntryContextTier", "description": "Context tier override for matching subagents" } }, "additionalProperties": false, "description": "Subagent model, reasoning effort, and context tier settings", "title": "SubagentSettingsEntry" }, "SubagentSettingsEntryContextTier": { "type": "string", "enum": [ "inherit", "default", "long_context" ], "description": "Context tier override for matching subagents", "title": "SubagentSettingsEntryContextTier", "x-enumDescriptions": { "inherit": "Inherit the parent session's effective context tier at dispatch time.", "default": "Use the model's default context window.", "long_context": "Pin the subagent to the long-context tier when supported." } }, "TaskAgentInfo": { "type": "object", "properties": { "type": { "type": "string", "const": "agent", "description": "Task kind" }, "id": { "type": "string", "description": "Unique task identifier" }, "toolCallId": { "type": "string", "description": "Tool call ID associated with this agent task" }, "description": { "type": "string", "description": "Short description of the task" }, "status": { "$ref": "#/definitions/TaskStatus", "description": "Current lifecycle status of the task" }, "startedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the task was started" }, "completedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the task finished" }, "activeTimeMs": { "type": "integer", "minimum": 0, "description": "Accumulated active execution time in milliseconds", "format": "duration" }, "activeStartedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the current active period began" }, "error": { "type": "string", "description": "Error message when the task failed" }, "agentType": { "type": "string", "description": "Type of agent running this task" }, "prompt": { "type": "string", "description": "Most recent prompt delivered to the agent. Updated whenever the agent receives a follow-up message." }, "result": { "type": "string", "description": "Result text from the task when available" }, "model": { "type": "string", "description": "Requested model override for the task when specified" }, "resolvedModel": { "type": "string", "description": "Runtime model resolved for the task when available" }, "executionMode": { "$ref": "#/definitions/TaskExecutionMode", "description": "Whether task execution is synchronously awaited or managed in the background" }, "canPromoteToBackground": { "type": "boolean", "description": "Whether the task is currently in the original sync wait and can be moved to background mode. False once it is already backgrounded, idle, finished, or no longer has a promotable sync waiter." }, "latestResponse": { "type": "string", "description": "Most recent response text from the agent" }, "idleSince": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the agent entered idle state" } }, "required": [ "type", "id", "toolCallId", "description", "status", "startedAt", "agentType", "prompt" ], "additionalProperties": false, "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": [ "sync", "background" ], "description": "Whether task execution is synchronously awaited or managed in the background", "title": "TaskExecutionMode", "x-enumDescriptions": { "sync": "The task was started with synchronous waiting.", "background": "The task is managed in the background." } }, "TaskInfo": { "anyOf": [ { "$ref": "#/definitions/TaskAgentInfo" }, { "$ref": "#/definitions/TaskShellInfo" } ], "title": "TaskInfo", "description": "Schema for the `TaskInfo` type." }, "TaskList": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/definitions/TaskInfo" }, "description": "Currently tracked tasks" } }, "required": [ "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, "title": "TaskProgressLine", "description": "Schema for the `TaskProgressLine` type." }, "TasksCancelRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "Task identifier" } }, "required": [ "id" ], "additionalProperties": false, "description": "Identifier of the background task to cancel.", "title": "TasksCancelRequest" }, "TasksCancelResult": { "type": "object", "properties": { "cancelled": { "type": "boolean", "description": "Whether the task was successfully cancelled" } }, "required": [ "cancelled" ], "additionalProperties": false, "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": { "type": { "type": "string", "const": "shell", "description": "Task kind" }, "id": { "type": "string", "description": "Unique task identifier" }, "description": { "type": "string", "description": "Short description of the task" }, "status": { "$ref": "#/definitions/TaskStatus", "description": "Current lifecycle status of the task" }, "startedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the task was started" }, "completedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the task finished" }, "command": { "type": "string", "description": "Command being executed" }, "attachmentMode": { "$ref": "#/definitions/TaskShellInfoAttachmentMode", "description": "Whether the shell runs inside a managed PTY session or as an independent background process" }, "executionMode": { "$ref": "#/definitions/TaskExecutionMode", "description": "Whether task execution is synchronously awaited or managed in the background" }, "canPromoteToBackground": { "type": "boolean", "description": "Whether this shell task can be promoted to background mode" }, "logPath": { "type": "string", "description": "Path to the detached shell log, when available" }, "pid": { "type": "integer", "exclusiveMinimum": 0, "maximum": 4294967295, "description": "Process ID when available" } }, "required": [ "type", "id", "description", "status", "startedAt", "command", "attachmentMode" ], "additionalProperties": false, "title": "TaskShellInfo", "description": "Schema for the `TaskShellInfo` type." }, "TaskShellInfoAttachmentMode": { "type": "string", "enum": [ "attached", "detached" ], "description": "Whether the shell runs inside a managed PTY session or as an independent background process", "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": 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", "properties": { "id": { "type": "string", "description": "Task identifier" } }, "required": [ "id" ], "additionalProperties": false, "description": "Identifier of the task to promote to background mode.", "title": "TasksPromoteToBackgroundRequest" }, "TasksPromoteToBackgroundResult": { "type": "object", "properties": { "promoted": { "type": "boolean", "description": "Whether the task was successfully promoted to background mode" } }, "required": [ "promoted" ], "additionalProperties": false, "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": { "id": { "type": "string", "description": "Task identifier" } }, "required": [ "id" ], "additionalProperties": false, "description": "Identifier of the completed or cancelled task to remove from tracking.", "title": "TasksRemoveRequest" }, "TasksRemoveResult": { "type": "object", "properties": { "removed": { "type": "boolean", "description": "Whether the task was removed. Returns false if the task does not exist or is still running/idle (cancel it first)." } }, "required": [ "removed" ], "additionalProperties": false, "description": "Indicates whether the task was removed. False when the task does not exist or is still running/idle.", "title": "TasksRemoveResult" }, "TasksSendMessageRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "Agent task identifier" }, "message": { "type": "string", "description": "Message content to send to the agent" }, "fromAgentId": { "type": "string", "description": "Agent ID of the sender, if sent on behalf of another agent" } }, "required": [ "id", "message" ], "additionalProperties": false, "description": "Identifier of the target agent task, message content, and optional sender agent ID.", "title": "TasksSendMessageRequest" }, "TasksSendMessageResult": { "type": "object", "properties": { "sent": { "type": "boolean", "description": "Whether the message was successfully delivered or steered" }, "error": { "type": "string", "description": "Error message if delivery failed" } }, "required": [ "sent" ], "additionalProperties": false, "description": "Indicates whether the message was delivered, with an error message when delivery failed.", "title": "TasksSendMessageResult" }, "TasksStartAgentRequest": { "type": "object", "properties": { "agentType": { "type": "string", "description": "Type of agent to start (e.g., 'explore', 'task', 'general-purpose')" }, "prompt": { "type": "string", "description": "Task prompt for the agent" }, "name": { "type": "string", "description": "Short name for the agent, used to generate a human-readable ID" }, "description": { "type": "string", "description": "Short description of the task" }, "model": { "type": "string", "description": "Optional model override" } }, "required": [ "agentType", "prompt", "name" ], "additionalProperties": false, "description": "Agent type, prompt, name, and optional description and model override for the new task.", "title": "TasksStartAgentRequest" }, "TasksStartAgentResult": { "type": "object", "properties": { "agentId": { "type": "string", "description": "Generated agent ID for the background task" } }, "required": [ "agentId" ], "additionalProperties": false, "description": "Identifier assigned to the newly started background agent task.", "title": "TasksStartAgentResult" }, "TaskStatus": { "type": "string", "enum": [ "running", "idle", "completed", "failed", "cancelled" ], "description": "Current lifecycle status of the task", "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", "properties": { "name": { "type": "string", "description": "Tool identifier (e.g., \"bash\", \"grep\", \"str_replace_editor\")" }, "namespacedName": { "type": "string", "description": "Optional namespaced name for declarative filtering (e.g., \"playwright/navigate\" for MCP tools)" }, "description": { "type": "string", "description": "Description of what the tool does" }, "parameters": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "JSON Schema for the tool's input parameters" }, "instructions": { "type": "string", "description": "Optional instructions for how to use this tool effectively" } }, "required": [ "name", "description" ], "additionalProperties": false, "title": "Tool", "description": "Schema for the `Tool` type." }, "ToolList": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/definitions/Tool" }, "description": "List of available built-in tools with metadata" } }, "required": [ "tools" ], "additionalProperties": false, "description": "Built-in tools available for the requested model, with their parameters and instructions.", "title": "ToolList" }, "ToolsGetCurrentMetadataResult": { "type": "object", "properties": { "tools": { "anyOf": [ { "type": "array", "items": { "$ref": "#/definitions/CurrentToolMetadata", "description": "Lightweight metadata for a currently initialized session tool" } }, { "type": "null" } ], "description": "Current tool metadata, or null when tools have not been initialized yet" } }, "required": [ "tools" ], "additionalProperties": false, "description": "Current lightweight tool metadata snapshot for the session.", "title": "ToolsGetCurrentMetadataResult" }, "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": { "model": { "type": "string", "description": "Optional model ID — when provided, the returned tool list reflects model-specific overrides" } }, "additionalProperties": false, "description": "Optional model identifier whose tool overrides should be applied to the listing.", "title": "ToolsListRequest" }, "ToolsUpdateSubagentSettingsResult": { "type": "object", "properties": {}, "additionalProperties": false, "description": "Empty result after applying subagent settings", "title": "ToolsUpdateSubagentSettingsResult" }, "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": { "type": { "type": "string", "const": "array", "description": "Type discriminator. Always \"array\"." }, "title": { "type": "string", "description": "Human-readable label for the field." }, "description": { "type": "string", "description": "Help text describing the field." }, "minItems": { "type": "integer", "minimum": 0, "description": "Minimum number of items the user must select." }, "maxItems": { "type": "integer", "minimum": 0, "description": "Maximum number of items the user may select." }, "items": { "$ref": "#/definitions/UIElicitationArrayAnyOfFieldItems", "description": "Schema applied to each item in the array." }, "default": { "type": "array", "items": { "type": "string" }, "description": "Default values selected when the form is first shown." } }, "required": [ "type", "items" ], "additionalProperties": false, "description": "Multi-select string field where each option pairs a value with a display label.", "title": "UIElicitationArrayAnyOfField" }, "UIElicitationArrayAnyOfFieldItems": { "type": "object", "properties": { "anyOf": { "type": "array", "items": { "$ref": "#/definitions/UIElicitationArrayAnyOfFieldItemsAnyOf" }, "description": "Selectable options, each with a value and a display label." } }, "required": [ "anyOf" ], "additionalProperties": false, "description": "Schema applied to each item in the array.", "title": "UIElicitationArrayAnyOfFieldItems" }, "UIElicitationArrayAnyOfFieldItemsAnyOf": { "type": "object", "properties": { "const": { "type": "string", "description": "Value submitted when this option is selected." }, "title": { "type": "string", "description": "Display label for this option." } }, "required": [ "const", "title" ], "additionalProperties": false, "title": "UIElicitationArrayAnyOfFieldItemsAnyOf", "description": "Schema for the `UIElicitationArrayAnyOfFieldItemsAnyOf` type." }, "UIElicitationArrayEnumField": { "type": "object", "properties": { "type": { "type": "string", "const": "array", "description": "Type discriminator. Always \"array\"." }, "title": { "type": "string", "description": "Human-readable label for the field." }, "description": { "type": "string", "description": "Help text describing the field." }, "minItems": { "type": "integer", "minimum": 0, "description": "Minimum number of items the user must select." }, "maxItems": { "type": "integer", "minimum": 0, "description": "Maximum number of items the user may select." }, "items": { "$ref": "#/definitions/UIElicitationArrayEnumFieldItems", "description": "Schema applied to each item in the array." }, "default": { "type": "array", "items": { "type": "string" }, "description": "Default values selected when the form is first shown." } }, "required": [ "type", "items" ], "additionalProperties": false, "description": "Multi-select string field whose allowed values are defined inline.", "title": "UIElicitationArrayEnumField" }, "UIElicitationArrayEnumFieldItems": { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "Type discriminator. Always \"string\"." }, "enum": { "type": "array", "items": { "type": "string" }, "description": "Allowed string values for each selected item." } }, "required": [ "type", "enum" ], "additionalProperties": false, "description": "Schema applied to each item in the array.", "title": "UIElicitationArrayEnumFieldItems" }, "UIElicitationFieldValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ], "title": "UIElicitationFieldValue", "x-opaque-json": true, "description": "Schema for the `UIElicitationFieldValue` type." }, "UIElicitationRequest": { "type": "object", "properties": { "message": { "type": "string", "description": "Message describing what information is needed from the user" }, "requestedSchema": { "$ref": "#/definitions/UIElicitationSchema", "description": "JSON Schema describing the form fields to present to the user" } }, "required": [ "message", "requestedSchema" ], "additionalProperties": false, "description": "Prompt message and JSON schema describing the form fields to elicit from the user.", "title": "UIElicitationRequest" }, "UIElicitationResponse": { "type": "object", "properties": { "action": { "$ref": "#/definitions/UIElicitationResponseAction", "description": "The user's response: accept (submitted), decline (rejected), or cancel (dismissed)" }, "content": { "$ref": "#/definitions/UIElicitationResponseContent", "description": "The form values submitted by the user (present when action is 'accept')" } }, "required": [ "action" ], "additionalProperties": false, "description": "The elicitation response (accept with form values, decline, or cancel)", "title": "UIElicitationResponse" }, "UIElicitationResponseAction": { "type": "string", "enum": [ "accept", "decline", "cancel" ], "description": "The user's response: accept (submitted), decline (rejected), or cancel (dismissed)", "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", "additionalProperties": { "$ref": "#/definitions/UIElicitationFieldValue" }, "description": "The form values submitted by the user (present when action is 'accept')", "title": "UIElicitationResponseContent" }, "UIElicitationResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the response was accepted. False if the request was already resolved by another client." } }, "required": [ "success" ], "additionalProperties": false, "description": "Indicates whether the elicitation response was accepted; false if it was already resolved by another client.", "title": "UIElicitationResult" }, "UIElicitationSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "object", "description": "Schema type indicator (always 'object')" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/definitions/UIElicitationSchemaProperty", "description": "Definition for a single elicitation form field." }, "description": "Form field definitions, keyed by field name" }, "required": { "type": "array", "items": { "type": "string" }, "description": "List of required field names" } }, "required": [ "type", "properties" ], "additionalProperties": false, "description": "JSON Schema describing the form fields to present to the user", "title": "UIElicitationSchema" }, "UIElicitationSchemaProperty": { "anyOf": [ { "$ref": "#/definitions/UIElicitationStringEnumField", "description": "Single-select string field whose allowed values are defined inline." }, { "$ref": "#/definitions/UIElicitationStringOneOfField", "description": "Single-select string field where each option pairs a value with a display label." }, { "$ref": "#/definitions/UIElicitationArrayEnumField", "description": "Multi-select string field whose allowed values are defined inline." }, { "$ref": "#/definitions/UIElicitationArrayAnyOfField", "description": "Multi-select string field where each option pairs a value with a display label." }, { "$ref": "#/definitions/UIElicitationSchemaPropertyBoolean", "description": "Boolean field rendered as a yes/no toggle." }, { "$ref": "#/definitions/UIElicitationSchemaPropertyString", "description": "Free-text string field with optional length and format constraints." }, { "$ref": "#/definitions/UIElicitationSchemaPropertyNumber", "description": "Numeric field accepting either a number or an integer." } ], "description": "Definition for a single elicitation form field.", "title": "UIElicitationSchemaProperty", "x-opaque-json": true }, "UIElicitationSchemaPropertyBoolean": { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "Type discriminator. Always \"boolean\"." }, "title": { "type": "string", "description": "Human-readable label for the field." }, "description": { "type": "string", "description": "Help text describing the field." }, "default": { "type": "boolean", "description": "Default value selected when the form is first shown." } }, "required": [ "type" ], "additionalProperties": false, "description": "Boolean field rendered as a yes/no toggle.", "title": "UIElicitationSchemaPropertyBoolean" }, "UIElicitationSchemaPropertyNumber": { "type": "object", "properties": { "type": { "$ref": "#/definitions/UIElicitationSchemaPropertyNumberType", "description": "Numeric type accepted by the field." }, "title": { "type": "string", "description": "Human-readable label for the field." }, "description": { "type": "string", "description": "Help text describing the field." }, "minimum": { "type": "number", "description": "Minimum allowed value (inclusive)." }, "maximum": { "type": "number", "description": "Maximum allowed value (inclusive)." }, "default": { "type": "number", "description": "Default value populated in the input when the form is first shown." } }, "required": [ "type" ], "additionalProperties": false, "description": "Numeric field accepting either a number or an integer.", "title": "UIElicitationSchemaPropertyNumber" }, "UIElicitationSchemaPropertyNumberType": { "type": "string", "enum": [ "number", "integer" ], "description": "Numeric type accepted by the field.", "title": "UIElicitationSchemaPropertyNumberType", "x-enumDescriptions": { "number": "Any JSON number.", "integer": "Integer JSON number." } }, "UIElicitationSchemaPropertyString": { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "Type discriminator. Always \"string\"." }, "title": { "type": "string", "description": "Human-readable label for the field." }, "description": { "type": "string", "description": "Help text describing the field." }, "minLength": { "type": "integer", "minimum": 0, "description": "Minimum number of characters required." }, "maxLength": { "type": "integer", "minimum": 0, "description": "Maximum number of characters allowed." }, "format": { "$ref": "#/definitions/UIElicitationSchemaPropertyStringFormat", "description": "Optional format hint that constrains the accepted input." }, "default": { "type": "string", "description": "Default value populated in the input when the form is first shown." } }, "required": [ "type" ], "additionalProperties": false, "description": "Free-text string field with optional length and format constraints.", "title": "UIElicitationSchemaPropertyString" }, "UIElicitationSchemaPropertyStringFormat": { "type": "string", "enum": [ "email", "uri", "date", "date-time" ], "description": "Optional format hint that constrains the accepted input.", "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", "properties": { "type": { "type": "string", "const": "string", "description": "Type discriminator. Always \"string\"." }, "title": { "type": "string", "description": "Human-readable label for the field." }, "description": { "type": "string", "description": "Help text describing the field." }, "enum": { "type": "array", "items": { "type": "string" }, "description": "Allowed string values." }, "enumNames": { "type": "array", "items": { "type": "string" }, "description": "Optional display labels for each enum value, in the same order as `enum`." }, "default": { "type": "string", "description": "Default value selected when the form is first shown." } }, "required": [ "type", "enum" ], "additionalProperties": false, "description": "Single-select string field whose allowed values are defined inline.", "title": "UIElicitationStringEnumField" }, "UIElicitationStringOneOfField": { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "Type discriminator. Always \"string\"." }, "title": { "type": "string", "description": "Human-readable label for the field." }, "description": { "type": "string", "description": "Help text describing the field." }, "oneOf": { "type": "array", "items": { "$ref": "#/definitions/UIElicitationStringOneOfFieldOneOf" }, "description": "Selectable options, each with a value and a display label." }, "default": { "type": "string", "description": "Default value selected when the form is first shown." } }, "required": [ "type", "oneOf" ], "additionalProperties": false, "description": "Single-select string field where each option pairs a value with a display label.", "title": "UIElicitationStringOneOfField" }, "UIElicitationStringOneOfFieldOneOf": { "type": "object", "properties": { "const": { "type": "string", "description": "Value submitted when this option is selected." }, "title": { "type": "string", "description": "Display label for this option." } }, "required": [ "const", "title" ], "additionalProperties": false, "title": "UIElicitationStringOneOfFieldOneOf", "description": "Schema for the `UIElicitationStringOneOfFieldOneOf` type." }, "UIEphemeralQueryRequest": { "type": "object", "properties": { "question": { "type": "string", "description": "Question to answer from the current conversation context." }, "onChunk": { "description": "In-process streaming callback `(text) => void` invoked with each token as the model emits it. Marked internal: excluded from the public SDK surface. In a process-separated SDK this is replaced by a streaming RPC that yields chunks and a final answer.", "visibility": "internal", "x-opaque-json": true }, "abortSignal": { "description": "In-process `AbortSignal` forwarded to the model client to cancel an in-flight request. Marked internal: excluded from the public SDK surface. Replaced by an explicit cancellation token + cancel RPC in the SDK migration.", "visibility": "internal", "x-opaque-json": true } }, "required": [ "question" ], "additionalProperties": false, "description": "Transient question to answer without adding it to conversation history.", "title": "UIEphemeralQueryRequest" }, "UIEphemeralQueryResult": { "type": "object", "properties": { "answer": { "type": "string", "description": "Full assistant response text." } }, "required": [ "answer" ], "additionalProperties": false, "description": "Transient answer generated from current conversation context.", "title": "UIEphemeralQueryResult" }, "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": { "requestId": { "type": "string", "description": "The unique request ID from the elicitation.requested event" }, "result": { "$ref": "#/definitions/UIElicitationResponse", "description": "The elicitation response (accept with form values, decline, or cancel)" } }, "required": [ "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", "x-opaque-json": true }, "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, "title": "UIUserInputResponse", "description": "Schema for the `UIUserInputResponse` type." }, "UpdateSubagentSettingsRequest": { "type": "object", "properties": { "subagents": { "$ref": "#/definitions/SubagentSettings", "description": "Subagent settings to apply, or null to clear the live session override" } }, "required": [ "subagents" ], "additionalProperties": false, "description": "Subagent settings to apply to the current session", "title": "UpdateSubagentSettingsRequest" }, "UsageGetMetricsResult": { "type": "object", "properties": { "totalPremiumRequestCost": { "type": "number", "description": "Total user-initiated premium request cost across all models (may be fractional due to multipliers)" }, "totalUserRequests": { "type": "integer", "minimum": 0, "description": "Raw count of user-initiated API requests" }, "totalNanoAiu": { "type": "number", "minimum": 0, "description": "Session-wide accumulated nano-AI units cost" }, "tokenDetails": { "type": "object", "additionalProperties": { "$ref": "#/definitions/UsageMetricsTokenDetail" }, "description": "Session-wide per-token-type accumulated token counts" }, "totalApiDurationMs": { "type": "integer", "minimum": 0, "description": "Total time spent in model API calls (milliseconds)", "format": "duration" }, "sessionStartTime": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the session started" }, "codeChanges": { "$ref": "#/definitions/UsageMetricsCodeChanges", "description": "Aggregated code change metrics" }, "modelMetrics": { "type": "object", "additionalProperties": { "$ref": "#/definitions/UsageMetricsModelMetric" }, "description": "Per-model token and request metrics, keyed by model identifier" }, "currentModel": { "type": "string", "description": "Currently active model identifier" }, "lastCallInputTokens": { "type": "integer", "minimum": 0, "description": "Input tokens from the most recent main-agent API call" }, "lastCallOutputTokens": { "type": "integer", "minimum": 0, "description": "Output tokens from the most recent main-agent API call" } }, "required": [ "totalPremiumRequestCost", "totalUserRequests", "totalApiDurationMs", "sessionStartTime", "codeChanges", "modelMetrics", "lastCallInputTokens", "lastCallOutputTokens" ], "additionalProperties": false, "description": "Accumulated session usage metrics, including premium request cost, token counts, model breakdown, and code-change totals.", "title": "UsageGetMetricsResult" }, "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." }, "UserRequestedShellCommandResult": { "type": "object", "properties": { "toolCallId": { "type": "string", "description": "Tool call id emitted for the shell execution" }, "success": { "type": "boolean", "description": "Whether the command completed successfully" }, "output": { "type": "string", "description": "Captured command output" }, "exitCode": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Process exit code, when available" }, "error": { "type": "string", "description": "Error output when the execution failed" } }, "required": [ "toolCallId", "success", "output" ], "additionalProperties": false, "description": "Result of a user-requested shell command.", "title": "UserRequestedShellCommandResult" }, "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": { "kind": { "type": "string", "const": "extension-permission-access", "description": "Extension permission access approval kind" }, "extensionName": { "type": "string", "description": "Extension name" } }, "required": [ "kind", "extensionName" ], "additionalProperties": false, "title": "UserToolSessionApprovalExtensionPermissionAccess", "description": "Schema for the `UserToolSessionApprovalExtensionPermissionAccess` type." }, "UserToolSessionApprovalMcp": { "type": "object", "properties": { "kind": { "type": "string", "const": "mcp", "description": "MCP tool approval kind" }, "serverName": { "type": "string", "description": "MCP server name" }, "toolName": { "type": [ "string", "null" ], "description": "Optional MCP tool name, or null for all tools on the server" } }, "required": [ "kind", "serverName", "toolName" ], "additionalProperties": false, "title": "UserToolSessionApprovalMcp", "description": "Schema for the `UserToolSessionApprovalMcp` type." }, "UserToolSessionApprovalMemory": { "type": "object", "properties": { "kind": { "type": "string", "const": "memory", "description": "Memory approval kind" } }, "required": [ "kind" ], "additionalProperties": false, "title": "UserToolSessionApprovalMemory", "description": "Schema for the `UserToolSessionApprovalMemory` type." }, "UserToolSessionApprovalRead": { "type": "object", "properties": { "kind": { "type": "string", "const": "read", "description": "Read approval kind" } }, "required": [ "kind" ], "additionalProperties": false, "title": "UserToolSessionApprovalRead", "description": "Schema for the `UserToolSessionApprovalRead` type." }, "UserToolSessionApprovalWrite": { "type": "object", "properties": { "kind": { "type": "string", "const": "write", "description": "Write approval kind" } }, "required": [ "kind" ], "additionalProperties": false, "title": "UserToolSessionApprovalWrite", "description": "Schema for the `UserToolSessionApprovalWrite` type." }, "WorkspaceDiffFileChange": { "type": "object", "properties": { "path": { "type": "string", "description": "Path to the changed file, relative to the workspace root." }, "diff": { "type": "string", "description": "Unified diff content for the file. Empty when the diff was truncated." }, "changeType": { "$ref": "#/definitions/WorkspaceDiffFileChangeType", "description": "Type of change represented by this file diff." }, "oldPath": { "type": "string", "description": "Original file path for renamed files." }, "isTruncated": { "type": "boolean", "description": "Whether the diff content was omitted because it exceeded the per-file size limit." } }, "required": [ "path", "diff", "changeType" ], "additionalProperties": false, "description": "A single changed file and its unified diff.", "title": "WorkspaceDiffFileChange" }, "WorkspaceDiffFileChangeType": { "type": "string", "enum": [ "added", "modified", "deleted", "renamed" ], "description": "Type of change represented by this file diff.", "title": "WorkspaceDiffFileChangeType", "x-enumDescriptions": { "added": "The file was added.", "modified": "The file was modified.", "deleted": "The file was deleted.", "renamed": "The file was renamed." } }, "WorkspaceDiffMode": { "type": "string", "enum": [ "unstaged", "branch" ], "description": "Diff mode requested by the client.", "title": "WorkspaceDiffMode", "x-enumDescriptions": { "unstaged": "Return staged, unstaged, and untracked working tree changes.", "branch": "Return changes compared with the default branch." } }, "WorkspaceDiffResult": { "type": "object", "properties": { "requestedMode": { "$ref": "#/definitions/WorkspaceDiffMode", "description": "Diff mode requested by the client." }, "mode": { "$ref": "#/definitions/WorkspaceDiffMode", "description": "Effective mode used for the returned changes." }, "changes": { "type": "array", "items": { "$ref": "#/definitions/WorkspaceDiffFileChange", "description": "A single changed file and its unified diff." }, "description": "Changed files and their unified diffs." }, "baseBranch": { "type": "string", "description": "Default branch used for a branch diff, when branch mode was requested." }, "isFallback": { "type": "boolean", "description": "Whether a requested branch diff fell back to unstaged changes because branch diff failed." } }, "required": [ "requestedMode", "mode", "changes", "isFallback" ], "additionalProperties": false, "description": "Workspace diff result for the requested mode.", "title": "WorkspaceDiffResult" }, "WorkspacesCheckpoints": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 0, "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": [ "number", "title", "filename" ], "additionalProperties": false, "title": "WorkspacesCheckpoints", "description": "Schema for the `WorkspacesCheckpoints` type." }, "WorkspacesCreateFileRequest": { "type": "object", "properties": { "path": { "type": "string", "description": "Relative path within the workspace files directory" }, "content": { "type": "string", "description": "File content to write as a UTF-8 string" } }, "required": [ "path", "content" ], "additionalProperties": false, "description": "Relative path and UTF-8 content for the workspace file to create or overwrite.", "title": "WorkspacesCreateFileRequest" }, "WorkspacesDiffRequest": { "type": "object", "properties": { "mode": { "$ref": "#/definitions/WorkspaceDiffMode", "description": "Diff mode requested by the client." } }, "required": [ "mode" ], "additionalProperties": false, "description": "Parameters for computing a workspace diff.", "title": "WorkspacesDiffRequest" }, "WorkspacesGetWorkspaceResult": { "type": "object", "properties": { "workspace": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "cwd": { "type": "string" }, "git_root": { "type": "string" }, "repository": { "type": "string" }, "host_type": { "$ref": "#/definitions/WorkspacesWorkspaceDetailsHostType", "description": "Allowed values for the `WorkspacesWorkspaceDetailsHostType` enumeration." }, "branch": { "type": "string" }, "name": { "type": "string" }, "client_name": { "type": "string" }, "user_named": { "type": "boolean" }, "summary_count": { "type": "integer", "minimum": 0, "default": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "remote_steerable": { "type": "boolean" }, "mc_task_id": { "type": "string" }, "mc_session_id": { "type": "string" }, "mc_last_event_id": { "type": "string" }, "chronicle_sync_dismissed": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, { "type": "null" } ], "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, 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": { "files": { "type": "array", "items": { "type": "string" }, "description": "Relative file paths in the workspace files directory" } }, "required": [ "files" ], "additionalProperties": false, "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": { "path": { "type": "string", "description": "Relative path within the workspace files directory" } }, "required": [ "path" ], "additionalProperties": false, "description": "Relative path of the workspace file to read.", "title": "WorkspacesReadFileRequest" }, "WorkspacesReadFileResult": { "type": "object", "properties": { "content": { "type": "string", "description": "File content as a UTF-8 string" } }, "required": [ "content" ], "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" }, "user_named": { "type": "boolean", "description": "Whether the display name was explicitly set by the user" }, "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." } } }