{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$comment": "Generated from types/commands.ts — do not edit", "$id": "https://microsoft.github.io/agent-host-protocol/schema/commands.schema.json", "title": "AHP Command Types", "description": "All command parameter and result types in the Agent Host Protocol.", "$defs": { "InitializeParams": { "type": "object", "description": "Establishes a new connection and negotiates the protocol version.\nThis MUST be the first message sent by the client.", "properties": { "protocolVersions": { "type": "array", "items": { "type": "string" }, "description": "Protocol versions the client is willing to speak, ordered from most\npreferred to least preferred. Each entry is a [SemVer](https://semver.org)\n`MAJOR.MINOR.PATCH` string (e.g. `\"0.1.0\"`).\n\nThe server selects one entry and returns it as `InitializeResult.protocolVersion`.\nIf the server cannot speak any of the offered versions, it MUST return\nerror code `-32005` (`UnsupportedProtocolVersion`)." }, "clientId": { "type": "string", "description": "Unique client identifier" }, "initialSubscriptions": { "type": "array", "items": { "$ref": "#/$defs/URI" }, "description": "URIs to subscribe to during handshake" }, "locale": { "type": "string", "description": "IETF BCP 47 language tag indicating the client's preferred locale\n(e.g. `\"en-US\"`, `\"ja\"`). The server SHOULD use this to localise\nuser-facing strings such as confirmation option labels." } }, "required": [ "protocolVersions", "clientId" ] }, "InitializeResult": { "type": "object", "description": "Result of the `initialize` command.\n\n`protocolVersion` is the version the server has selected from the client's\n`protocolVersions` list. The client and server MUST use this version for\nthe rest of the connection. If the server cannot speak any of the offered\nversions it MUST return error code `-32005` (`UnsupportedProtocolVersion`)\ninstead of a result.", "properties": { "protocolVersion": { "type": "string", "description": "Protocol version selected by the server. MUST be one of the entries in\n`InitializeParams.protocolVersions`. Formatted as a [SemVer](https://semver.org)\n`MAJOR.MINOR.PATCH` string (e.g. `\"0.1.0\"`)." }, "serverSeq": { "type": "number", "description": "Current server sequence number" }, "snapshots": { "type": "array", "items": { "$ref": "#/$defs/Snapshot" }, "description": "Snapshots for each `initialSubscriptions` URI" }, "defaultDirectory": { "$ref": "#/$defs/URI", "description": "Suggested default directory for remote filesystem browsing" }, "completionTriggerCharacters": { "type": "array", "items": { "type": "string" }, "description": "Characters that, when typed in a {@link UserMessage} input, SHOULD cause\nthe client to issue a `completions` request with\n{@link CompletionItemKind.UserMessage}. Typically includes characters like\n`'@'` or `'/'`." } }, "required": [ "protocolVersion", "serverSeq", "snapshots" ] }, "PingParams": { "type": "object", "description": "Verifies that the AHP connection is still alive and keeps it from being\nclosed by idle-timeout intermediaries (proxies, load balancers, etc.).\n\nThe server MUST respond regardless of whether the client has completed\n`initialize` or holds any subscriptions. Ping carries no payload in either\ndirection; the response itself is the signal.", "properties": {} }, "ReconnectParams": { "type": "object", "description": "Re-establishes a dropped connection. The server replays missed actions or\nprovides fresh snapshots.", "properties": { "clientId": { "type": "string", "description": "Client identifier from the original connection" }, "lastSeenServerSeq": { "type": "number", "description": "Last `serverSeq` the client received" }, "subscriptions": { "type": "array", "items": { "$ref": "#/$defs/URI" }, "description": "URIs the client was subscribed to" } }, "required": [ "clientId", "lastSeenServerSeq", "subscriptions" ] }, "ReconnectReplayResult": { "type": "object", "description": "Reconnect result when the server can replay from the requested sequence.\n\nThe server MUST include all replayed data in the response.", "properties": { "type": { "$ref": "#/$defs/ReconnectResultType.Replay", "description": "Discriminant" }, "actions": { "type": "array", "items": { "$ref": "#/$defs/ActionEnvelope" }, "description": "Missed action envelopes since `lastSeenServerSeq`" }, "missing": { "type": "array", "items": { "$ref": "#/$defs/URI" }, "description": "URIs from `ReconnectParams.subscriptions` that the server cannot resume.\nThis includes resources that no longer exist (e.g. disposed sessions or\nterminals) as well as resources the client is no longer permitted to\nobserve. Clients SHOULD drop these from their local subscription set." } }, "required": [ "type", "actions", "missing" ] }, "ReconnectSnapshotResult": { "type": "object", "description": "Reconnect result when the gap exceeds the replay buffer.", "properties": { "type": { "$ref": "#/$defs/ReconnectResultType.Snapshot", "description": "Discriminant" }, "snapshots": { "type": "array", "items": { "$ref": "#/$defs/Snapshot" }, "description": "Fresh snapshots for each subscription" } }, "required": [ "type", "snapshots" ] }, "SubscribeParams": { "type": "object", "description": "Subscribe to a URI-identified state resource.", "properties": { "resource": { "$ref": "#/$defs/URI", "description": "URI to subscribe to" } }, "required": [ "resource" ] }, "SubscribeResult": { "type": "object", "description": "Result of the `subscribe` command.", "properties": { "snapshot": { "$ref": "#/$defs/Snapshot", "description": "Snapshot of the subscribed resource" } }, "required": [ "snapshot" ] }, "SessionForkSource": { "type": "object", "description": "Creates a new session with the specified agent provider.\n\nIf the session URI already exists, the server MUST return an error with code\n`-32003` (`SessionAlreadyExists`).\n\nAfter creation, the client should subscribe to the session URI to receive state\nupdates. The server also broadcasts a `notify/sessionAdded` notification to all\nclients.", "properties": { "session": { "$ref": "#/$defs/URI", "description": "URI of the existing session to fork from" }, "turnId": { "type": "string", "description": "Turn ID in the source session; content up to and including this turn's response is copied" } }, "required": [ "session", "turnId" ] }, "CreateSessionParams": { "type": "object", "properties": { "session": { "$ref": "#/$defs/URI", "description": "Session URI (client-chosen, e.g. `copilot:/`)" }, "provider": { "type": "string", "description": "Agent provider ID" }, "model": { "$ref": "#/$defs/ModelSelection", "description": "Model selection (ID and optional model-specific configuration)" }, "workingDirectory": { "$ref": "#/$defs/URI", "description": "Working directory for the session" }, "fork": { "$ref": "#/$defs/SessionForkSource", "description": "Fork from an existing session. The new session is populated with content\nfrom the source session up to and including the specified turn's response." }, "config": { "type": "object", "additionalProperties": {}, "description": "Agent-specific configuration values collected via `resolveSessionConfig`.\nKeys and values correspond to the schema returned by the server." }, "activeClient": { "$ref": "#/$defs/SessionActiveClient", "description": "Eagerly claim the active client role for the new session.\n\nWhen provided, the server initializes the session with this client as the\nactive client, equivalent to dispatching a `session/activeClientChanged`\naction immediately after creation. The `clientId` MUST match the\n`clientId` the creating client supplied in `initialize`." } }, "required": [ "session" ] }, "DisposeSessionParams": { "type": "object", "description": "Disposes a session and cleans up server-side resources.\n\nThe server broadcasts a `notify/sessionRemoved` notification to all clients.", "properties": { "session": { "$ref": "#/$defs/URI", "description": "Session URI to dispose" } }, "required": [ "session" ] }, "CreateTerminalParams": { "type": "object", "description": "Creates a new terminal on the server.\n\nAfter creation, the client should subscribe to the terminal URI to receive\nstate updates. The server dispatches `root/terminalsChanged` to update the\nroot terminal list.", "properties": { "terminal": { "$ref": "#/$defs/URI", "description": "Terminal URI (client-chosen)" }, "claim": { "$ref": "#/$defs/TerminalClaim", "description": "Initial owner of the terminal" }, "name": { "type": "string", "description": "Human-readable terminal name" }, "cwd": { "$ref": "#/$defs/URI", "description": "Initial working directory URI" }, "cols": { "type": "number", "description": "Initial terminal width in columns" }, "rows": { "type": "number", "description": "Initial terminal height in rows" } }, "required": [ "terminal", "claim" ] }, "DisposeTerminalParams": { "type": "object", "description": "Disposes a terminal and kills its process if still running.\n\nThe server dispatches `root/terminalsChanged` to remove the terminal from\nthe root terminal list.", "properties": { "terminal": { "$ref": "#/$defs/URI", "description": "Terminal URI to dispose" } }, "required": [ "terminal" ] }, "ListSessionsParams": { "type": "object", "description": "Returns a list of session summaries. Used to populate session lists and sidebars.\n\nThe session list is **not** part of the state tree because it can be arbitrarily\nlarge. Clients fetch it imperatively and maintain a local cache updated by\n`notify/sessionAdded` and `notify/sessionRemoved` notifications.", "properties": { "filter": { "type": "object", "description": "Optional filter criteria" } } }, "ListSessionsResult": { "type": "object", "description": "Result of the `listSessions` command.", "properties": { "items": { "type": "array", "items": { "$ref": "#/$defs/SessionSummary" }, "description": "The list of session summaries." } }, "required": [ "items" ] }, "ResourceReadParams": { "type": "object", "description": "Reads the content of a resource by URI.\n\nContent references keep the state tree small by storing large data (images,\nlong tool outputs) by reference rather than inline.\n\nBinary content (images, etc.) MUST use `base64` encoding. Text content MAY\nuse `utf-8` encoding.", "properties": { "uri": { "type": "string", "description": "Content URI from a `ContentRef`" }, "encoding": { "$ref": "#/$defs/ContentEncoding", "description": "Preferred encoding for the returned data (default: server-chosen)" } }, "required": [ "uri" ] }, "ResourceReadResult": { "type": "object", "description": "Result of the `resourceRead` command.\n\nThe server SHOULD honor the `encoding` requested in the params. If the\nserver cannot provide the requested encoding, it MUST fall back to either\n`base64` or `utf-8`.", "properties": { "data": { "type": "string", "description": "Content encoded as a string" }, "encoding": { "$ref": "#/$defs/ContentEncoding", "description": "How `data` is encoded" }, "contentType": { "type": "string", "description": "Content type (e.g. `\"image/png\"`, `\"text/plain\"`)" } }, "required": [ "data", "encoding" ] }, "ResourceWriteParams": { "type": "object", "description": "Writes content to a file on the server's filesystem.\n\nBinary content (images, etc.) MUST use `base64` encoding. Text content MAY\nuse `utf-8` encoding.\n\nIf the file does not exist, it is created. If the file already exists, it is\noverwritten unless `createOnly` is set.", "properties": { "uri": { "$ref": "#/$defs/URI", "description": "Target file URI on the server filesystem" }, "data": { "type": "string", "description": "Content encoded as a string" }, "encoding": { "$ref": "#/$defs/ContentEncoding", "description": "How `data` is encoded" }, "contentType": { "type": "string", "description": "Content type (e.g. `\"text/plain\"`, `\"image/png\"`)" }, "createOnly": { "type": "boolean", "description": "If `true`, the server MUST fail if the file already exists instead of\noverwriting it. Useful for safe creation of new files." } }, "required": [ "uri", "data", "encoding" ] }, "ResourceWriteResult": { "type": "object", "description": "Result of the `resourceWrite` command.\n\nAn empty object on success.", "properties": {} }, "ResourceListParams": { "type": "object", "description": "Lists directory entries at a file URI on the server's filesystem.\n\nThis is intended for remote folder pickers and similar UI that needs to let\nusers navigate the server's local filesystem.\n\nThe server MUST return success only if the target exists and is a directory.\nIf the target does not exist, is not a directory, or cannot be accessed, the\nserver MUST return a JSON-RPC error.", "properties": { "uri": { "$ref": "#/$defs/URI", "description": "Directory URI on the server filesystem" } }, "required": [ "uri" ] }, "DirectoryEntry": { "type": "object", "description": "Directory entry returned by `resourceList`.", "properties": { "name": { "type": "string", "description": "Base name of the entry" }, "type": { "type": "string", "enum": [ "file", "directory" ], "description": "Whether the entry is a file or directory" } }, "required": [ "name", "type" ] }, "ResourceListResult": { "type": "object", "description": "Result of the `resourceList` command.", "properties": { "entries": { "type": "array", "items": { "$ref": "#/$defs/DirectoryEntry" }, "description": "Entries directly contained in the requested directory" } }, "required": [ "entries" ] }, "FetchTurnsParams": { "type": "object", "description": "Fetches historical turns for a session. Used for lazy loading of conversation\nhistory.", "properties": { "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "before": { "type": "string", "description": "Turn ID to fetch before (exclusive). Omit to fetch from the most recent turn." }, "limit": { "type": "number", "description": "Maximum number of turns to return. Server MAY impose its own upper bound." } }, "required": [ "session" ] }, "FetchTurnsResult": { "type": "object", "description": "Result of the `fetchTurns` command.", "properties": { "turns": { "type": "array", "items": { "$ref": "#/$defs/Turn" }, "description": "The requested turns, ordered oldest-first" }, "hasMore": { "type": "boolean", "description": "Whether more turns exist before the returned range" } }, "required": [ "turns", "hasMore" ] }, "UnsubscribeParams": { "type": "object", "description": "Stop receiving updates for a URI.", "properties": { "resource": { "$ref": "#/$defs/URI", "description": "URI to unsubscribe from" } }, "required": [ "resource" ] }, "DispatchActionParams": { "type": "object", "description": "Fire-and-forget action dispatch (write-ahead). The client applies actions\noptimistically to local state.", "properties": { "clientSeq": { "type": "number", "description": "Client sequence number" }, "action": { "$ref": "#/$defs/StateAction", "description": "The action to dispatch" } }, "required": [ "clientSeq", "action" ] }, "ResourceCopyParams": { "type": "object", "description": "Copies a resource from one URI to another on the server's filesystem.\n\nIf the destination already exists, it is overwritten unless `failIfExists`\nis set.", "properties": { "source": { "$ref": "#/$defs/URI", "description": "Source URI to copy from" }, "destination": { "$ref": "#/$defs/URI", "description": "Destination URI to copy to" }, "failIfExists": { "type": "boolean", "description": "If `true`, the server MUST fail if the destination already exists instead\nof overwriting it." } }, "required": [ "source", "destination" ] }, "ResourceCopyResult": { "type": "object", "description": "Result of the `resourceCopy` command.\n\nAn empty object on success.", "properties": {} }, "ResourceDeleteParams": { "type": "object", "description": "Deletes a resource at a URI on the server's filesystem.", "properties": { "uri": { "$ref": "#/$defs/URI", "description": "URI of the resource to delete" }, "recursive": { "type": "boolean", "description": "If `true` and the target is a directory, delete it and all its contents\nrecursively. If `false` (default), deleting a non-empty directory MUST fail." } }, "required": [ "uri" ] }, "ResourceDeleteResult": { "type": "object", "description": "Result of the `resourceDelete` command.\n\nAn empty object on success.", "properties": {} }, "ResourceRequestParams": { "type": "object", "description": "Requests permission to access a resource on the receiver's filesystem.\n\n`resourceRequest` is symmetrical and MAY be sent in either direction: a\nclient asks the server to grant access to a server-side resource, or a\nserver asks the client to grant access to a client-side resource. The\nreceiver decides whether to allow, deny, or prompt the user for the\nrequested access.\n\nIf the receiver denies access, it MUST respond with `PermissionDenied`\n(-32009). The error data MAY include a `ResourceRequestParams` value\ndescribing the access the caller would need to be granted for the\noperation to succeed; see `PermissionDeniedErrorData` in\n`types/errors.ts`.\n\nAfter a successful `resourceRequest`, the caller MAY use the corresponding\n`resource*` commands (e.g. `resourceRead`, `resourceWrite`) to perform the\noperation. Receivers MAY rescind access at any time by returning\n`PermissionDenied` on subsequent operations.\n\nEither `read`, `write`, or both SHOULD be set to `true`. A request with\nneither flag set is treated as `read: true` by receivers.", "properties": { "uri": { "$ref": "#/$defs/URI", "description": "Resource URI being requested. Typically a `file:` URI on the receiver's\nfilesystem, but any URI scheme that the receiver mediates access to is\nallowed." }, "read": { "type": "boolean", "description": "Whether the caller needs read access to the resource." }, "write": { "type": "boolean", "description": "Whether the caller needs write access to the resource." } }, "required": [ "uri" ] }, "ResourceRequestResult": { "type": "object", "description": "Result of the `resourceRequest` command.\n\nAn empty object on success.", "properties": {} }, "ResourceMoveParams": { "type": "object", "description": "Moves (renames) a resource from one URI to another on the server's filesystem.\n\nIf the destination already exists, it is overwritten unless `failIfExists`\nis set.", "properties": { "source": { "$ref": "#/$defs/URI", "description": "Source URI to move from" }, "destination": { "$ref": "#/$defs/URI", "description": "Destination URI to move to" }, "failIfExists": { "type": "boolean", "description": "If `true`, the server MUST fail if the destination already exists instead\nof overwriting it." } }, "required": [ "source", "destination" ] }, "ResourceMoveResult": { "type": "object", "description": "Result of the `resourceMove` command.\n\nAn empty object on success.", "properties": {} }, "AuthenticateParams": { "type": "object", "description": "Pushes a Bearer token for a protected resource. The `resource` field MUST\nmatch a `ProtectedResourceMetadata.resource` value declared by an agent\nin `AgentInfo.protectedResources`.\n\nTokens are delivered using [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)\n(Bearer Token Usage) semantics. The client obtains the token from the\nauthorization server(s) listed in the resource's metadata and pushes it\nto the server via this command.", "properties": { "resource": { "type": "string", "description": "The protected resource identifier. MUST match a `resource` value from\n`ProtectedResourceMetadata` declared in `AgentInfo.protectedResources`." }, "token": { "type": "string", "description": "Bearer token obtained from the resource's authorization server" } }, "required": [ "resource", "token" ] }, "AuthenticateResult": { "type": "object", "description": "Result of the `authenticate` command.\n\nAn empty object on success. If the token is invalid or the resource is\nunrecognized, the server MUST return a JSON-RPC error (e.g. `AuthRequired`\n`-32007` or `InvalidParams` `-32602`).", "properties": {} }, "ResolveSessionConfigParams": { "type": "object", "description": "Iteratively resolves the session configuration schema. The client sends the\ncurrent partial session config and any user-filled metadata values. The server\nreturns a property schema describing what additional metadata is needed,\ncontextual to the current selections.\n\nThe client calls this command whenever the user changes a significant input\n(e.g. picks a working directory, toggles a property). Each response returns\nthe full current property set (not a delta). The returned `values` contain\nserver-resolved defaults to pass to `createSession`.", "properties": { "provider": { "type": "string", "description": "Agent provider ID" }, "workingDirectory": { "$ref": "#/$defs/URI", "description": "Working directory for the session" }, "config": { "type": "object", "additionalProperties": {}, "description": "Current user-filled configuration values" } } }, "ResolveSessionConfigResult": { "type": "object", "description": "Result of the `resolveSessionConfig` command.", "properties": { "schema": { "$ref": "#/$defs/SessionConfigSchema", "description": "JSON Schema describing available configuration properties given the current context" }, "values": { "type": "object", "additionalProperties": {}, "description": "Current configuration values (echoed back with server-resolved defaults applied)" } }, "required": [ "schema", "values" ] }, "SessionConfigValueItem": { "type": "object", "description": "A single value item returned by `sessionConfigCompletions`.", "properties": { "value": { "type": "string", "description": "The value to store in config" }, "label": { "type": "string", "description": "Human-readable display label" }, "description": { "type": "string", "description": "Optional secondary description" } }, "required": [ "value", "label" ] }, "SessionConfigCompletionsParams": { "type": "object", "description": "Queries the server for allowed values of a dynamic session config property.\n\nUsed when a property in the schema returned by `resolveSessionConfig` has\n`enumDynamic: true`. The client sends a search query and receives matching\nvalues with display metadata.", "properties": { "provider": { "type": "string", "description": "Agent provider ID" }, "workingDirectory": { "$ref": "#/$defs/URI", "description": "Working directory for the session" }, "config": { "type": "object", "additionalProperties": {}, "description": "Current user-filled configuration values (provides context for the query)" }, "property": { "type": "string", "description": "Property id from the schema to query values for" }, "query": { "type": "string", "description": "Search filter text (empty or omitted returns default/recent values)" } }, "required": [ "property" ] }, "SessionConfigCompletionsResult": { "type": "object", "description": "Result of the `sessionConfigCompletions` command.", "properties": { "items": { "type": "array", "items": { "$ref": "#/$defs/SessionConfigValueItem" }, "description": "Matching value items" } }, "required": [ "items" ] }, "CompletionsParams": { "type": "object", "description": "Requests completion items for a partially-typed input (e.g. a user message\nthe user is currently composing). Used to power `@`-mention pickers,\nfile/symbol references, and similar inline-completion experiences.\n\nServers SHOULD treat this command as best-effort and return promptly. The\nclient SHOULD debounce calls to avoid flooding the server with requests on\nevery keystroke.", "properties": { "kind": { "$ref": "#/$defs/CompletionItemKind", "description": "What kind of completion is being requested." }, "session": { "$ref": "#/$defs/URI", "description": "The session URI the completion is being requested for." }, "text": { "type": "string", "description": "The complete text of the input being completed (e.g. the full user\nmessage text typed so far)." }, "offset": { "type": "number", "description": "The character offset within `text` at which the completion is requested,\nmeasured in UTF-16 code units. MUST satisfy `0 <= offset <= text.length`." } }, "required": [ "kind", "session", "text", "offset" ] }, "CompletionItem": { "type": "object", "description": "A single completion item returned by the `completions` command.\n\nWhen the user accepts an item, the client SHOULD:\n1. Replace the range `[rangeStart, rangeEnd)` in the input with `insertText`\n (or insert `insertText` at the cursor when the range is omitted).\n2. Associate the item's `attachment` with the resulting {@link UserMessage}.", "properties": { "insertText": { "type": "string", "description": "The text inserted into the input when this item is accepted." }, "rangeStart": { "type": "number", "description": "If defined, the start of the range in the input's `text` that is replaced\nby `insertText`. The range is the half-open interval\n`[rangeStart, rangeEnd)` of character offsets, measured in UTF-16 code\nunits.\n\nWhen omitted, the client SHOULD insert `insertText` at the cursor.\n\nNote: this range refers to positions in the *current* input. The\nattachment's own `rangeStart`/`rangeEnd` (when present) refer to\npositions in the final {@link UserMessage.text} after the item is\naccepted." }, "rangeEnd": { "type": "number", "description": "The end of the range in the input's `text` that is replaced by\n`insertText`. See {@link rangeStart}." }, "attachment": { "$ref": "#/$defs/MessageAttachment", "description": "The attachment associated with this completion item." } }, "required": [ "insertText", "attachment" ] }, "CompletionsResult": { "type": "object", "description": "Result of the `completions` command.", "properties": { "items": { "type": "array", "items": { "$ref": "#/$defs/CompletionItem" }, "description": "The completion items, in the order the server suggests displaying them." } }, "required": [ "items" ] }, "Icon": { "type": "object", "description": "An optionally-sized icon that can be displayed in a user interface.", "properties": { "src": { "$ref": "#/$defs/URI", "description": "A standard URI pointing to an icon resource. May be an HTTP/HTTPS URL or a\n`data:` URI with Base64-encoded image data.\n\nConsumers SHOULD take steps to ensure URLs serving icons are from the\nsame domain as the client/server or a trusted domain.\n\nConsumers SHOULD take appropriate precautions when consuming SVGs as they can contain\nexecutable JavaScript." }, "contentType": { "type": "string", "description": "Optional MIME type override if the source MIME type is missing or generic.\nFor example: `\"image/png\"`, `\"image/jpeg\"`, or `\"image/svg+xml\"`." }, "sizes": { "type": "array", "items": { "type": "string" }, "description": "Optional array of strings that specify sizes at which the icon can be used.\nEach string should be in WxH format (e.g., `\"48x48\"`, `\"96x96\"`) or `\"any\"` for scalable formats like SVG.\n\nIf not provided, the client should assume that the icon can be used at any size." }, "theme": { "type": "string", "enum": [ "light", "dark" ], "description": "Optional specifier for the theme this icon is designed for. `\"light\"` indicates\nthe icon is designed to be used with a light background, and `\"dark\"` indicates\nthe icon is designed to be used with a dark background.\n\nIf not provided, the client should assume the icon can be used with any theme." } }, "required": [ "src" ] }, "ProtectedResourceMetadata": { "type": "object", "description": "Describes a protected resource's authentication requirements using\n[RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) (OAuth 2.0\nProtected Resource Metadata) semantics.\n\nField names use snake_case to match the RFC 9728 JSON format.", "properties": { "resource": { "type": "string", "description": "REQUIRED. The protected resource's resource identifier, a URL using the\n`https` scheme with no fragment component (e.g. `\"https://api.github.com\"`)." }, "resource_name": { "type": "string", "description": "OPTIONAL. Human-readable name of the protected resource." }, "authorization_servers": { "type": "array", "items": { "type": "string" }, "description": "OPTIONAL. JSON array of OAuth authorization server identifier URLs." }, "jwks_uri": { "type": "string", "description": "OPTIONAL. URL of the protected resource's JWK Set document." }, "scopes_supported": { "type": "array", "items": { "type": "string" }, "description": "RECOMMENDED. JSON array of OAuth 2.0 scope values used in authorization requests." }, "bearer_methods_supported": { "type": "array", "items": { "type": "string" }, "description": "OPTIONAL. JSON array of Bearer Token presentation methods supported." }, "resource_signing_alg_values_supported": { "type": "array", "items": { "type": "string" }, "description": "OPTIONAL. JSON array of JWS signing algorithms supported." }, "resource_encryption_alg_values_supported": { "type": "array", "items": { "type": "string" }, "description": "OPTIONAL. JSON array of JWE encryption algorithms (alg) supported." }, "resource_encryption_enc_values_supported": { "type": "array", "items": { "type": "string" }, "description": "OPTIONAL. JSON array of JWE encryption algorithms (enc) supported." }, "resource_documentation": { "type": "string", "description": "OPTIONAL. URL of human-readable documentation for the resource." }, "resource_policy_uri": { "type": "string", "description": "OPTIONAL. URL of the resource's data-usage policy." }, "resource_tos_uri": { "type": "string", "description": "OPTIONAL. URL of the resource's terms of service." }, "required": { "type": "boolean", "description": "AHP extension. Whether authentication is required for this resource.\n\n- `true` (default) — the agent cannot be used without a valid token.\n The server SHOULD return `AuthRequired` (`-32007`) if the client\n attempts to use the agent without authenticating.\n- `false` — the agent works without authentication but MAY offer\n enhanced capabilities when a token is provided.\n\nClients SHOULD treat an absent field the same as `true`." } }, "required": [ "resource" ] }, "RootState": { "type": "object", "description": "Global state shared with every client subscribed to `agenthost:/root`.", "properties": { "agents": { "type": "array", "items": { "$ref": "#/$defs/AgentInfo" }, "description": "Available agent backends and their models" }, "activeSessions": { "type": "number", "description": "Number of active (non-disposed) sessions on the server" }, "terminals": { "type": "array", "items": { "$ref": "#/$defs/TerminalInfo" }, "description": "Known terminals on the server. Subscribe to individual terminal URIs for full state." }, "config": { "$ref": "#/$defs/RootConfigState", "description": "Agent host configuration schema and current values" } }, "required": [ "agents" ] }, "AgentInfo": { "type": "object", "properties": { "provider": { "type": "string", "description": "Agent provider ID (e.g. `'copilot'`)" }, "displayName": { "type": "string", "description": "Human-readable name" }, "description": { "type": "string", "description": "Description string" }, "models": { "type": "array", "items": { "$ref": "#/$defs/SessionModelInfo" }, "description": "Available models for this agent" }, "protectedResources": { "type": "array", "items": { "$ref": "#/$defs/ProtectedResourceMetadata" }, "description": "Protected resources this agent requires authentication for.\n\nEach entry describes an OAuth 2.0 protected resource using\n[RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) semantics.\nClients should obtain tokens from the declared `authorization_servers`\nand push them via the `authenticate` command before creating sessions\nwith this agent." }, "customizations": { "type": "array", "items": { "$ref": "#/$defs/CustomizationRef" }, "description": "Customizations (Open Plugins) associated with this agent.\n\nEach entry is a reference to an [Open Plugins](https://open-plugins.com/)\nplugin that the agent host can activate for sessions using this agent." } }, "required": [ "provider", "displayName", "description", "models" ] }, "SessionModelInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "Model identifier" }, "provider": { "type": "string", "description": "Provider this model belongs to" }, "name": { "type": "string", "description": "Human-readable model name" }, "maxContextWindow": { "type": "number", "description": "Maximum context window size" }, "supportsVision": { "type": "boolean", "description": "Whether the model supports vision" }, "policyState": { "$ref": "#/$defs/PolicyState", "description": "Policy configuration state" }, "configSchema": { "$ref": "#/$defs/ConfigSchema", "description": "Configuration schema describing model-specific options (e.g. thinking\nlevel). Clients present this as a form and pass the resolved values in\n{@link ModelSelection.config} when creating or changing sessions." }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this model.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `pricing` key may carry model pricing metadata." } }, "required": [ "id", "provider", "name" ] }, "ModelSelection": { "type": "object", "description": "A model selection: the chosen model ID together with any model-specific\nconfiguration values whose keys correspond to the model's\n{@link SessionModelInfo.configSchema}.", "properties": { "id": { "type": "string", "description": "Model identifier" }, "config": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Model-specific configuration values" } }, "required": [ "id" ] }, "PendingMessage": { "type": "object", "description": "A message queued for future delivery to the agent.\n\nSteering messages are injected into the current turn mid-flight.\nQueued messages are automatically started as new turns after the\ncurrent turn naturally finishes.", "properties": { "id": { "type": "string", "description": "Unique identifier for this pending message" }, "userMessage": { "$ref": "#/$defs/UserMessage", "description": "The message content" } }, "required": [ "id", "userMessage" ] }, "SessionState": { "type": "object", "description": "Full state for a single session, loaded when a client subscribes to the session's URI.", "properties": { "summary": { "$ref": "#/$defs/SessionSummary", "description": "Lightweight session metadata" }, "lifecycle": { "$ref": "#/$defs/SessionLifecycle", "description": "Session initialization state" }, "creationError": { "$ref": "#/$defs/ErrorInfo", "description": "Error details if creation failed" }, "serverTools": { "type": "array", "items": { "$ref": "#/$defs/ToolDefinition" }, "description": "Tools provided by the server (agent host) for this session" }, "activeClient": { "$ref": "#/$defs/SessionActiveClient", "description": "The client currently providing tools and interactive capabilities to this session" }, "turns": { "type": "array", "items": { "$ref": "#/$defs/Turn" }, "description": "Completed turns" }, "activeTurn": { "$ref": "#/$defs/ActiveTurn", "description": "Currently in-progress turn" }, "steeringMessage": { "$ref": "#/$defs/PendingMessage", "description": "Message to inject into the current turn at a convenient point" }, "queuedMessages": { "type": "array", "items": { "$ref": "#/$defs/PendingMessage" }, "description": "Messages to send automatically as new turns after the current turn finishes" }, "inputRequests": { "type": "array", "items": { "$ref": "#/$defs/SessionInputRequest" }, "description": "Requests for user input that are currently blocking or informing session progress" }, "config": { "$ref": "#/$defs/SessionConfigState", "description": "Session configuration schema and current values" }, "customizations": { "type": "array", "items": { "$ref": "#/$defs/SessionCustomization" }, "description": "Server-provided customizations active in this session.\n\nClient-provided customizations are available on\n{@link SessionActiveClient.customizations | activeClient.customizations}." }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this session.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `git` key may provide extra git metadata about the session's\nworkingDirectory." } }, "required": [ "summary", "lifecycle", "turns" ] }, "SessionActiveClient": { "type": "object", "description": "The client currently providing tools and interactive capabilities to a session.\n\nOnly one client may be active per session at a time. The server SHOULD\nautomatically unset the active client if that client disconnects.", "properties": { "clientId": { "type": "string", "description": "Client identifier (matches `clientId` from `initialize`)" }, "displayName": { "type": "string", "description": "Human-readable client name (e.g. `\"VS Code\"`)" }, "tools": { "type": "array", "items": { "$ref": "#/$defs/ToolDefinition" }, "description": "Tools this client provides to the session" }, "customizations": { "type": "array", "items": { "$ref": "#/$defs/CustomizationRef" }, "description": "Customizations this client contributes to the session" } }, "required": [ "clientId", "tools" ] }, "ProjectInfo": { "type": "object", "description": "Server-owned project metadata for a session.", "properties": { "uri": { "$ref": "#/$defs/URI", "description": "Project URI" }, "displayName": { "type": "string", "description": "Human-readable project name" } }, "required": [ "uri", "displayName" ] }, "SessionSummary": { "type": "object", "properties": { "resource": { "$ref": "#/$defs/URI", "description": "Session URI" }, "provider": { "type": "string", "description": "Agent provider ID" }, "title": { "type": "string", "description": "Session title" }, "status": { "$ref": "#/$defs/SessionStatus", "description": "Current session status" }, "activity": { "type": "string", "description": "Human-readable description of what the session is currently doing" }, "createdAt": { "type": "number", "description": "Creation timestamp" }, "modifiedAt": { "type": "number", "description": "Last modification timestamp" }, "project": { "$ref": "#/$defs/ProjectInfo", "description": "Server-owned project for this session" }, "model": { "$ref": "#/$defs/ModelSelection", "description": "Currently selected model" }, "workingDirectory": { "$ref": "#/$defs/URI", "description": "The working directory URI for this session" }, "diffs": { "type": "array", "items": { "$ref": "#/$defs/FileEdit" }, "description": "Files changed during this session with diff statistics" } }, "required": [ "resource", "provider", "title", "status", "createdAt", "modifiedAt" ] }, "ConfigPropertySchema": { "type": "object", "description": "A JSON Schema-compatible property descriptor with display extensions.\n\nStandard JSON Schema fields (`type`, `title`, `description`, `default`,\n`enum`) allow validators to process the schema. Display extensions\n(`enumLabels`, `enumDescriptions`) are parallel arrays that provide UI\nmetadata for each `enum` value.\n\nThis is the generic base type. See {@link SessionConfigPropertySchema} for\nsession-specific extensions.", "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean", "array", "object" ], "description": "JSON Schema: property type" }, "title": { "type": "string", "description": "JSON Schema: human-readable label for the property" }, "description": { "type": "string", "description": "JSON Schema: description / tooltip" }, "default": { "description": "JSON Schema: default value" }, "enum": { "type": "array", "items": { "type": "string" }, "description": "JSON Schema: allowed values (typically used with `string` type)" }, "enumLabels": { "type": "array", "items": { "type": "string" }, "description": "Display extension: human-readable label per enum value (parallel array)" }, "enumDescriptions": { "type": "array", "items": { "type": "string" }, "description": "Display extension: description per enum value (parallel array)" }, "readOnly": { "type": "boolean", "description": "JSON Schema: when `true`, the property is displayed but cannot be modified by the user" }, "items": { "$ref": "#/$defs/ConfigPropertySchema", "description": "JSON Schema: schema for array items (used when `type` is `'array'`)" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/$defs/ConfigPropertySchema" }, "description": "JSON Schema: property descriptors for object properties (used when `type` is `'object'`)" }, "required": { "type": "array", "items": { "type": "string" }, "description": "JSON Schema: list of required property ids (used when `type` is `'object'`)" } }, "required": [ "type", "title" ] }, "ConfigSchema": { "type": "object", "description": "A JSON Schema object describing available configuration properties.\n\nThis is the generic base type. See {@link SessionConfigSchema} for\nsession-specific usage.", "properties": { "type": { "type": "string", "enum": [ "object" ], "description": "JSON Schema: always `'object'`" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/$defs/ConfigPropertySchema" }, "description": "JSON Schema: property descriptors keyed by property id" }, "required": { "type": "array", "items": { "type": "string" }, "description": "JSON Schema: list of required property ids" } }, "required": [ "type", "properties" ] }, "RootConfigState": { "type": "object", "description": "Live agent-host configuration metadata.\n\nThe schema describes the available configuration properties and the values\ncontain the current value for each resolved property.", "properties": { "schema": { "$ref": "#/$defs/ConfigSchema", "description": "JSON Schema describing available configuration properties" }, "values": { "type": "object", "additionalProperties": {}, "description": "Current configuration values" } }, "required": [ "schema", "values" ] }, "SessionConfigPropertySchema": { "type": "object", "description": "A session configuration property descriptor.\n\nExtends the generic {@link ConfigPropertySchema} with session-specific\ndisplay extensions.", "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean", "array", "object" ], "description": "JSON Schema: property type" }, "title": { "type": "string", "description": "JSON Schema: human-readable label for the property" }, "description": { "type": "string", "description": "JSON Schema: description / tooltip" }, "default": { "description": "JSON Schema: default value" }, "enum": { "type": "array", "items": { "type": "string" }, "description": "JSON Schema: allowed values (typically used with `string` type)" }, "enumLabels": { "type": "array", "items": { "type": "string" }, "description": "Display extension: human-readable label per enum value (parallel array)" }, "enumDescriptions": { "type": "array", "items": { "type": "string" }, "description": "Display extension: description per enum value (parallel array)" }, "readOnly": { "type": "boolean", "description": "JSON Schema: when `true`, the property is displayed but cannot be modified by the user" }, "items": { "$ref": "#/$defs/ConfigPropertySchema", "description": "JSON Schema: schema for array items (used when `type` is `'array'`)" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/$defs/ConfigPropertySchema" }, "description": "JSON Schema: property descriptors for object properties (used when `type` is `'object'`)" }, "required": { "type": "array", "items": { "type": "string" }, "description": "JSON Schema: list of required property ids (used when `type` is `'object'`)" }, "enumDynamic": { "type": "boolean", "description": "Display extension: when `true`, the full set of allowed values is too large\nto enumerate statically. The client SHOULD use `sessionConfigCompletions`\nto fetch matching values based on user input. Any values in `enum` are\nseed/recent values for initial display." }, "sessionMutable": { "type": "boolean", "description": "When `true`, the user may change this property after session creation" } }, "required": [ "type", "title" ] }, "SessionConfigSchema": { "type": "object", "description": "A JSON Schema object describing available session configuration metadata.", "properties": { "type": { "type": "string", "enum": [ "object" ], "description": "JSON Schema: always `'object'`" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/$defs/SessionConfigPropertySchema" }, "description": "JSON Schema: property descriptors keyed by property id" }, "required": { "type": "array", "items": { "type": "string" }, "description": "JSON Schema: list of required property ids" } }, "required": [ "type", "properties" ] }, "SessionConfigState": { "type": "object", "description": "Live session configuration metadata.\n\nThe schema describes the available configuration properties and the values\ncontain the current value for each resolved property.", "properties": { "schema": { "$ref": "#/$defs/SessionConfigSchema", "description": "JSON Schema describing available configuration properties" }, "values": { "type": "object", "additionalProperties": {}, "description": "Current configuration values" } }, "required": [ "schema", "values" ] }, "SessionInputOption": { "type": "object", "description": "A choice in a select-style question.", "properties": { "id": { "type": "string", "description": "Stable option identifier; for MCP enum values this is the enum string" }, "label": { "type": "string", "description": "Display label" }, "description": { "type": "string", "description": "Optional secondary text" }, "recommended": { "type": "boolean", "description": "Whether this option is the recommended/default choice" } }, "required": [ "id", "label" ] }, "SessionInputQuestionBase": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable question identifier used as the key in `answers`" }, "title": { "type": "string", "description": "Short display title" }, "message": { "type": "string", "description": "Prompt shown to the user" }, "required": { "type": "boolean", "description": "Whether the user must answer this question to accept the request" } }, "required": [ "id", "message" ] }, "SessionInputTextQuestion": { "type": "object", "description": "Text question within a session input request.", "properties": { "id": { "type": "string", "description": "Stable question identifier used as the key in `answers`" }, "title": { "type": "string", "description": "Short display title" }, "message": { "type": "string", "description": "Prompt shown to the user" }, "required": { "type": "boolean", "description": "Whether the user must answer this question to accept the request" }, "kind": { "$ref": "#/$defs/SessionInputQuestionKind.Text" }, "format": { "type": "string", "description": "Format hint for text questions, such as `email`, `uri`, `date`, or `date-time`" }, "min": { "type": "number", "description": "Minimum string length" }, "max": { "type": "number", "description": "Maximum string length" }, "defaultValue": { "type": "string", "description": "Default text" } }, "required": [ "id", "message", "kind" ] }, "SessionInputNumberQuestion": { "type": "object", "description": "Numeric question within a session input request.", "properties": { "id": { "type": "string", "description": "Stable question identifier used as the key in `answers`" }, "title": { "type": "string", "description": "Short display title" }, "message": { "type": "string", "description": "Prompt shown to the user" }, "required": { "type": "boolean", "description": "Whether the user must answer this question to accept the request" }, "kind": { "oneOf": [ { "$ref": "#/$defs/SessionInputQuestionKind.Number" }, { "$ref": "#/$defs/SessionInputQuestionKind.Integer" } ] }, "min": { "type": "number", "description": "Minimum value" }, "max": { "type": "number", "description": "Maximum value" }, "defaultValue": { "type": "number", "description": "Default numeric value" } }, "required": [ "id", "message", "kind" ] }, "SessionInputBooleanQuestion": { "type": "object", "description": "Boolean question within a session input request.", "properties": { "id": { "type": "string", "description": "Stable question identifier used as the key in `answers`" }, "title": { "type": "string", "description": "Short display title" }, "message": { "type": "string", "description": "Prompt shown to the user" }, "required": { "type": "boolean", "description": "Whether the user must answer this question to accept the request" }, "kind": { "$ref": "#/$defs/SessionInputQuestionKind.Boolean" }, "defaultValue": { "type": "boolean", "description": "Default boolean value" } }, "required": [ "id", "message", "kind" ] }, "SessionInputSingleSelectQuestion": { "type": "object", "description": "Single-select question within a session input request.", "properties": { "id": { "type": "string", "description": "Stable question identifier used as the key in `answers`" }, "title": { "type": "string", "description": "Short display title" }, "message": { "type": "string", "description": "Prompt shown to the user" }, "required": { "type": "boolean", "description": "Whether the user must answer this question to accept the request" }, "kind": { "$ref": "#/$defs/SessionInputQuestionKind.SingleSelect" }, "options": { "type": "array", "items": { "$ref": "#/$defs/SessionInputOption" }, "description": "Options the user may select from" }, "allowFreeformInput": { "type": "boolean", "description": "Whether the user may enter text instead of selecting an option" } }, "required": [ "id", "message", "kind", "options" ] }, "SessionInputMultiSelectQuestion": { "type": "object", "description": "Multi-select question within a session input request.", "properties": { "id": { "type": "string", "description": "Stable question identifier used as the key in `answers`" }, "title": { "type": "string", "description": "Short display title" }, "message": { "type": "string", "description": "Prompt shown to the user" }, "required": { "type": "boolean", "description": "Whether the user must answer this question to accept the request" }, "kind": { "$ref": "#/$defs/SessionInputQuestionKind.MultiSelect" }, "options": { "type": "array", "items": { "$ref": "#/$defs/SessionInputOption" }, "description": "Options the user may select from" }, "allowFreeformInput": { "type": "boolean", "description": "Whether the user may enter text in addition to selecting options" }, "min": { "type": "number", "description": "Minimum selected item count" }, "max": { "type": "number", "description": "Maximum selected item count" } }, "required": [ "id", "message", "kind", "options" ] }, "SessionInputRequest": { "type": "object", "description": "A live request for user input.\n\nThe server creates or replaces requests with `session/inputRequested`.\nClients sync drafts with `session/inputAnswerChanged` and complete requests\nwith `session/inputCompleted`.", "properties": { "id": { "type": "string", "description": "Stable request identifier" }, "message": { "type": "string", "description": "Display message for the request as a whole" }, "url": { "$ref": "#/$defs/URI", "description": "URL the user should review or open, for URL-style elicitations" }, "questions": { "type": "array", "items": { "$ref": "#/$defs/SessionInputQuestion" }, "description": "Ordered questions to ask the user" }, "answers": { "type": "object", "additionalProperties": { "$ref": "#/$defs/SessionInputAnswer" }, "description": "Current draft or submitted answers, keyed by question ID" } }, "required": [ "id" ] }, "SessionInputTextAnswerValue": { "type": "object", "description": "Value captured for one answer.", "properties": { "kind": { "$ref": "#/$defs/SessionInputAnswerValueKind.Text" }, "value": { "type": "string" } }, "required": [ "kind", "value" ] }, "SessionInputNumberAnswerValue": { "type": "object", "properties": { "kind": { "$ref": "#/$defs/SessionInputAnswerValueKind.Number" }, "value": { "type": "number" } }, "required": [ "kind", "value" ] }, "SessionInputBooleanAnswerValue": { "type": "object", "properties": { "kind": { "$ref": "#/$defs/SessionInputAnswerValueKind.Boolean" }, "value": { "type": "boolean" } }, "required": [ "kind", "value" ] }, "SessionInputSelectedAnswerValue": { "type": "object", "properties": { "kind": { "$ref": "#/$defs/SessionInputAnswerValueKind.Selected" }, "value": { "type": "string" }, "freeformValues": { "type": "array", "items": { "type": "string" }, "description": "Free-form text entered instead of selecting an option" } }, "required": [ "kind", "value" ] }, "SessionInputSelectedManyAnswerValue": { "type": "object", "properties": { "kind": { "$ref": "#/$defs/SessionInputAnswerValueKind.SelectedMany" }, "value": { "type": "array", "items": { "type": "string" } }, "freeformValues": { "type": "array", "items": { "type": "string" }, "description": "Free-form text entered in addition to selected options" } }, "required": [ "kind", "value" ] }, "SessionInputAnswered": { "type": "object", "properties": { "state": { "oneOf": [ { "$ref": "#/$defs/SessionInputAnswerState.Draft" }, { "$ref": "#/$defs/SessionInputAnswerState.Submitted" } ], "description": "Answer state" }, "value": { "$ref": "#/$defs/SessionInputAnswerValue", "description": "Answer value" } }, "required": [ "state", "value" ] }, "SessionInputSkipped": { "type": "object", "properties": { "state": { "$ref": "#/$defs/SessionInputAnswerState.Skipped", "description": "Answer state" }, "freeformValues": { "type": "array", "items": { "type": "string" }, "description": "Free-form reason or value captured while skipping, if any" } }, "required": [ "state" ] }, "Turn": { "type": "object", "description": "A completed request/response cycle.", "properties": { "id": { "type": "string", "description": "Turn identifier" }, "userMessage": { "$ref": "#/$defs/UserMessage", "description": "The user's input" }, "responseParts": { "type": "array", "items": { "$ref": "#/$defs/ResponsePart" }, "description": "All response content in stream order: text, tool calls, reasoning, and content refs.\n\nConsumers should derive display text by concatenating markdown parts,\nand find tool calls by filtering for `ToolCall` parts." }, "usage": { "$ref": "#/$defs/UsageInfo", "description": "Token usage info" }, "state": { "$ref": "#/$defs/TurnState", "description": "How the turn ended" }, "error": { "$ref": "#/$defs/ErrorInfo", "description": "Error details if state is `'error'`" } }, "required": [ "id", "userMessage", "responseParts", "usage", "state" ] }, "ActiveTurn": { "type": "object", "description": "An in-progress turn — the assistant is actively streaming.", "properties": { "id": { "type": "string", "description": "Turn identifier" }, "userMessage": { "$ref": "#/$defs/UserMessage", "description": "The user's input" }, "responseParts": { "type": "array", "items": { "$ref": "#/$defs/ResponsePart" }, "description": "All response content in stream order: text, tool calls, reasoning, and content refs.\n\nTool call parts include `pendingPermissions` when permissions are awaiting user approval." }, "usage": { "$ref": "#/$defs/UsageInfo", "description": "Token usage info" } }, "required": [ "id", "userMessage", "responseParts", "usage" ] }, "UserMessage": { "type": "object", "description": "A user message and its associated attachments.\n\nAttachments MAY be referenced inside {@link UserMessage.text} via their\n{@link MessageAttachmentBase.range} field. Attachments without a range are\nstill associated with the message but do not correspond to a specific span\nin the text.", "properties": { "text": { "type": "string", "description": "Message text" }, "attachments": { "type": "array", "items": { "$ref": "#/$defs/MessageAttachment" }, "description": "File/selection attachments" } }, "required": [ "text" ] }, "MessageAttachmentBase": { "type": "object", "description": "Common fields shared by all {@link MessageAttachment} variants.", "properties": { "label": { "type": "string", "description": "A human-readable label for the attachment (e.g. the filename of a file\nattachment). Used for display in UI." }, "range": { "$ref": "#/$defs/TextRange", "description": "If defined, the range in {@link UserMessage.text} that references this\nattachment. This is a text range, not a byte range." }, "displayKind": { "type": "string", "description": "Advisory display hint for clients rendering this attachment. Recognized\nvalues include:\n\n- `'image'`: the attachment is an image\n- `'document'`: the attachment is a textual document\n- `'symbol'`: the attachment is a code symbol (e.g. a function or class)\n- `'directory'`: the attachment is a folder\n- `'selection'`: the attachment is a selection within a document\n\nImplementations MAY provide additional values; clients SHOULD fall back\nto a reasonable default when an unknown value is encountered." }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional implementation-defined metadata for the attachment.\n\nIf the attachment was produced by the `completions` command, the client\nMUST preserve every property of `_meta` originally returned by the agent\nhost when sending the user message containing the accepted completion." } }, "required": [ "label" ] }, "TextPosition": { "type": "object", "description": "A zero-based position within a textual document.", "properties": { "line": { "type": "number", "description": "Zero-based line number." }, "character": { "type": "number", "description": "Zero-based character offset within the line." } }, "required": [ "line", "character" ] }, "TextRange": { "type": "object", "description": "A range within a textual document.", "properties": { "start": { "$ref": "#/$defs/TextPosition", "description": "Start position of the range." }, "end": { "$ref": "#/$defs/TextPosition", "description": "End position of the range." } }, "required": [ "start", "end" ] }, "TextSelection": { "type": "object", "description": "A selection within a textual resource.\n\nThis is only meaningful for textual resources. Binary resources may still\nuse resource or embedded resource attachments, but they should not use this\ntext selection field.", "properties": { "range": { "$ref": "#/$defs/TextRange", "description": "The range covered by the selection." } }, "required": [ "range" ] }, "SimpleMessageAttachment": { "type": "object", "description": "A simple, opaque attachment whose model representation is described by\nthe producer.", "properties": { "label": { "type": "string", "description": "A human-readable label for the attachment (e.g. the filename of a file\nattachment). Used for display in UI." }, "range": { "$ref": "#/$defs/TextRange", "description": "If defined, the range in {@link UserMessage.text} that references this\nattachment. This is a text range, not a byte range." }, "displayKind": { "type": "string", "description": "Advisory display hint for clients rendering this attachment. Recognized\nvalues include:\n\n- `'image'`: the attachment is an image\n- `'document'`: the attachment is a textual document\n- `'symbol'`: the attachment is a code symbol (e.g. a function or class)\n- `'directory'`: the attachment is a folder\n- `'selection'`: the attachment is a selection within a document\n\nImplementations MAY provide additional values; clients SHOULD fall back\nto a reasonable default when an unknown value is encountered." }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional implementation-defined metadata for the attachment.\n\nIf the attachment was produced by the `completions` command, the client\nMUST preserve every property of `_meta` originally returned by the agent\nhost when sending the user message containing the accepted completion." }, "type": { "$ref": "#/$defs/MessageAttachmentKind.Simple", "description": "Discriminant" }, "modelRepresentation": { "type": "string", "description": "Representation of the attachment as it should be shown to the model.\n\nIf the attachment was produced by the client, this property MUST be\ndefined so the agent host can correctly interpret the attachment. This\nproperty MAY be omitted when the attachment originated from a\n`completions` response." } }, "required": [ "label", "type" ] }, "MessageEmbeddedResourceAttachment": { "type": "object", "description": "An attachment whose data is embedded inline as a base64 string.\n\nUse this for small binary payloads (e.g. a pasted image) that should be\ndelivered with the user message itself rather than fetched separately.", "properties": { "label": { "type": "string", "description": "A human-readable label for the attachment (e.g. the filename of a file\nattachment). Used for display in UI." }, "range": { "$ref": "#/$defs/TextRange", "description": "If defined, the range in {@link UserMessage.text} that references this\nattachment. This is a text range, not a byte range." }, "displayKind": { "type": "string", "description": "Advisory display hint for clients rendering this attachment. Recognized\nvalues include:\n\n- `'image'`: the attachment is an image\n- `'document'`: the attachment is a textual document\n- `'symbol'`: the attachment is a code symbol (e.g. a function or class)\n- `'directory'`: the attachment is a folder\n- `'selection'`: the attachment is a selection within a document\n\nImplementations MAY provide additional values; clients SHOULD fall back\nto a reasonable default when an unknown value is encountered." }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional implementation-defined metadata for the attachment.\n\nIf the attachment was produced by the `completions` command, the client\nMUST preserve every property of `_meta` originally returned by the agent\nhost when sending the user message containing the accepted completion." }, "type": { "$ref": "#/$defs/MessageAttachmentKind.EmbeddedResource", "description": "Discriminant" }, "data": { "type": "string", "description": "Base64-encoded binary data" }, "contentType": { "type": "string", "description": "Content MIME type (e.g. `\"image/png\"`, `\"application/pdf\"`)" }, "selection": { "$ref": "#/$defs/TextSelection", "description": "Optional selection within the attached textual resource.\n\nOnly meaningful for textual resources." } }, "required": [ "label", "type", "data", "contentType" ] }, "MessageResourceAttachment": { "type": "object", "description": "An attachment that references a resource by URI. The content is not\ndelivered inline; consumers can fetch it via `resourceRead` when needed.", "properties": { "label": { "type": "string", "description": "A human-readable label for the attachment (e.g. the filename of a file\nattachment). Used for display in UI." }, "range": { "$ref": "#/$defs/TextRange", "description": "If defined, the range in {@link UserMessage.text} that references this\nattachment. This is a text range, not a byte range." }, "displayKind": { "type": "string", "description": "Advisory display hint for clients rendering this attachment. Recognized\nvalues include:\n\n- `'image'`: the attachment is an image\n- `'document'`: the attachment is a textual document\n- `'symbol'`: the attachment is a code symbol (e.g. a function or class)\n- `'directory'`: the attachment is a folder\n- `'selection'`: the attachment is a selection within a document\n\nImplementations MAY provide additional values; clients SHOULD fall back\nto a reasonable default when an unknown value is encountered." }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional implementation-defined metadata for the attachment.\n\nIf the attachment was produced by the `completions` command, the client\nMUST preserve every property of `_meta` originally returned by the agent\nhost when sending the user message containing the accepted completion." }, "uri": { "$ref": "#/$defs/URI", "description": "Content URI" }, "sizeHint": { "type": "number", "description": "Approximate size in bytes" }, "contentType": { "type": "string", "description": "Content MIME type" }, "type": { "$ref": "#/$defs/MessageAttachmentKind.Resource", "description": "Discriminant" }, "selection": { "$ref": "#/$defs/TextSelection", "description": "Optional selection within the referenced textual resource.\n\nOnly meaningful for textual resources." } }, "required": [ "label", "uri", "type" ] }, "MarkdownResponsePart": { "type": "object", "properties": { "kind": { "$ref": "#/$defs/ResponsePartKind.Markdown", "description": "Discriminant" }, "id": { "type": "string", "description": "Part identifier, used by `session/delta` to target this part for content appends" }, "content": { "type": "string", "description": "Markdown content" } }, "required": [ "kind", "id", "content" ] }, "ContentRef": { "type": "object", "description": "A reference to large content stored outside the state tree.", "properties": { "uri": { "$ref": "#/$defs/URI", "description": "Content URI" }, "sizeHint": { "type": "number", "description": "Approximate size in bytes" }, "contentType": { "type": "string", "description": "Content MIME type" } }, "required": [ "uri" ] }, "ResourceReponsePart": { "type": "object", "description": "A content part that's a reference to large content stored outside the state tree.", "properties": { "uri": { "$ref": "#/$defs/URI", "description": "Content URI" }, "sizeHint": { "type": "number", "description": "Approximate size in bytes" }, "contentType": { "type": "string", "description": "Content MIME type" }, "kind": { "$ref": "#/$defs/ResponsePartKind.ContentRef", "description": "Discriminant" } }, "required": [ "uri", "kind" ] }, "ToolCallResponsePart": { "type": "object", "description": "A tool call represented as a response part.\n\nTool calls are part of the response stream, interleaved with text and\nreasoning. The `toolCall.toolCallId` serves as the part identifier for\nactions that target this part.", "properties": { "kind": { "$ref": "#/$defs/ResponsePartKind.ToolCall", "description": "Discriminant" }, "toolCall": { "$ref": "#/$defs/ToolCallState", "description": "Full tool call lifecycle state" } }, "required": [ "kind", "toolCall" ] }, "ReasoningResponsePart": { "type": "object", "description": "Reasoning/thinking content from the model.", "properties": { "kind": { "$ref": "#/$defs/ResponsePartKind.Reasoning", "description": "Discriminant" }, "id": { "type": "string", "description": "Part identifier, used by `session/reasoning` to target this part for content appends" }, "content": { "type": "string", "description": "Accumulated reasoning text" } }, "required": [ "kind", "id", "content" ] }, "SystemNotificationResponsePart": { "type": "object", "description": "A system notification surfaced as part of the response stream.\n\nSystem notifications are messages authored by the agent harness\nthat need to be visible to both the agent (for situational awareness) and\nthe user (for transcript continuity). Examples include \"background subagent\nX completed\" or \"task Y was cancelled\".", "properties": { "kind": { "$ref": "#/$defs/ResponsePartKind.SystemNotification", "description": "Discriminant" }, "content": { "$ref": "#/$defs/StringOrMarkdown", "description": "The text of the system notification" } }, "required": [ "kind", "content" ] }, "ConfirmationOption": { "type": "object", "description": "A confirmation option that the server offers for a tool call awaiting\napproval. Allows richer choices beyond simple approve/deny — for example,\n\"Approve in this Session\" or \"Deny with reason.\"", "properties": { "id": { "type": "string", "description": "Unique identifier for the option, returned in the confirmed action" }, "label": { "type": "string", "description": "Human-readable label displayed to the user" }, "kind": { "$ref": "#/$defs/ConfirmationOptionKind", "description": "Whether this option represents an approval or denial" }, "group": { "type": "number", "description": "Logical group number for visual categorisation.\n\nClients SHOULD display options in the order they are defined and MAY\nuse differing group numbers to insert dividers between logical clusters\nof options." } }, "required": [ "id", "label", "kind" ] }, "ToolCallBase": { "type": "object", "description": "Metadata common to all tool call states.", "properties": { "toolCallId": { "type": "string", "description": "Unique tool call identifier" }, "toolName": { "type": "string", "description": "Internal tool name (for debugging/logging)" }, "displayName": { "type": "string", "description": "Human-readable tool name" }, "toolClientId": { "type": "string", "description": "If this tool is provided by a client, the `clientId` of the owning client.\nAbsent for server-side tools.\n\nWhen set, the identified client is responsible for executing the tool and\ndispatching `session/toolCallComplete` with the result." }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this tool call.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `ptyTerminal` key with `{ input: string; output: string }`\nindicates the tool operated on a terminal (both `input` and `output` may\ncontain escape sequences)." } }, "required": [ "toolCallId", "toolName", "displayName" ] }, "ToolCallParameterFields": { "type": "object", "description": "Properties available once tool call parameters are fully received.", "properties": { "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "Message describing what the tool will do" }, "toolInput": { "type": "string", "description": "Raw tool input" } }, "required": [ "invocationMessage" ] }, "ToolCallResult": { "type": "object", "description": "Tool execution result details, available after execution completes.", "properties": { "success": { "type": "boolean", "description": "Whether the tool succeeded" }, "pastTenseMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "Past-tense description of what the tool did" }, "content": { "type": "array", "items": { "$ref": "#/$defs/ToolResultContent" }, "description": "Unstructured result content blocks.\n\nThis mirrors the `content` field of MCP `CallToolResult`." }, "structuredContent": { "type": "object", "additionalProperties": {}, "description": "Optional structured result object.\n\nThis mirrors the `structuredContent` field of MCP `CallToolResult`." }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "message" ], "description": "Error details if the tool failed" } }, "required": [ "success", "pastTenseMessage" ] }, "ToolCallStreamingState": { "type": "object", "description": "LM is streaming the tool call parameters.", "properties": { "toolCallId": { "type": "string", "description": "Unique tool call identifier" }, "toolName": { "type": "string", "description": "Internal tool name (for debugging/logging)" }, "displayName": { "type": "string", "description": "Human-readable tool name" }, "toolClientId": { "type": "string", "description": "If this tool is provided by a client, the `clientId` of the owning client.\nAbsent for server-side tools.\n\nWhen set, the identified client is responsible for executing the tool and\ndispatching `session/toolCallComplete` with the result." }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this tool call.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `ptyTerminal` key with `{ input: string; output: string }`\nindicates the tool operated on a terminal (both `input` and `output` may\ncontain escape sequences)." }, "status": { "$ref": "#/$defs/ToolCallStatus.Streaming" }, "partialInput": { "type": "string", "description": "Partial parameters accumulated so far" }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "Progress message shown while parameters are streaming" } }, "required": [ "toolCallId", "toolName", "displayName", "status" ] }, "ToolCallPendingConfirmationState": { "type": "object", "description": "Parameters are complete, or a running tool requires re-confirmation\n(e.g. a mid-execution permission check).", "properties": { "toolCallId": { "type": "string", "description": "Unique tool call identifier" }, "toolName": { "type": "string", "description": "Internal tool name (for debugging/logging)" }, "displayName": { "type": "string", "description": "Human-readable tool name" }, "toolClientId": { "type": "string", "description": "If this tool is provided by a client, the `clientId` of the owning client.\nAbsent for server-side tools.\n\nWhen set, the identified client is responsible for executing the tool and\ndispatching `session/toolCallComplete` with the result." }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this tool call.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `ptyTerminal` key with `{ input: string; output: string }`\nindicates the tool operated on a terminal (both `input` and `output` may\ncontain escape sequences)." }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "Message describing what the tool will do" }, "toolInput": { "type": "string", "description": "Raw tool input" }, "status": { "$ref": "#/$defs/ToolCallStatus.PendingConfirmation" }, "confirmationTitle": { "$ref": "#/$defs/StringOrMarkdown", "description": "Short title for the confirmation prompt (e.g. `\"Run in terminal\"`, `\"Write file\"`)" }, "edits": { "type": "object", "properties": { "items": { "type": "string" } }, "required": [ "items" ], "description": "File edits that this tool call will perform, for preview before confirmation" }, "editable": { "type": "boolean", "description": "Whether the agent host allows the client to edit the tool's input parameters before confirming" }, "options": { "type": "array", "items": { "$ref": "#/$defs/ConfirmationOption" }, "description": "Options the server offers for this confirmation. When present, the client\nSHOULD render these instead of a plain approve/deny UI. Each option\nbelongs to a {@link ConfirmationOptionGroup} so the client can still\ncategorise the choices." } }, "required": [ "toolCallId", "toolName", "displayName", "invocationMessage", "status" ] }, "ToolCallRunningState": { "type": "object", "description": "Tool is actively executing.", "properties": { "toolCallId": { "type": "string", "description": "Unique tool call identifier" }, "toolName": { "type": "string", "description": "Internal tool name (for debugging/logging)" }, "displayName": { "type": "string", "description": "Human-readable tool name" }, "toolClientId": { "type": "string", "description": "If this tool is provided by a client, the `clientId` of the owning client.\nAbsent for server-side tools.\n\nWhen set, the identified client is responsible for executing the tool and\ndispatching `session/toolCallComplete` with the result." }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this tool call.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `ptyTerminal` key with `{ input: string; output: string }`\nindicates the tool operated on a terminal (both `input` and `output` may\ncontain escape sequences)." }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "Message describing what the tool will do" }, "toolInput": { "type": "string", "description": "Raw tool input" }, "status": { "$ref": "#/$defs/ToolCallStatus.Running" }, "confirmed": { "$ref": "#/$defs/ToolCallConfirmationReason", "description": "How the tool was confirmed for execution" }, "selectedOption": { "$ref": "#/$defs/ConfirmationOption", "description": "The confirmation option the user selected, if confirmation options were provided" }, "content": { "type": "array", "items": { "$ref": "#/$defs/ToolResultContent" }, "description": "Partial content produced while the tool is still executing.\n\nFor example, a terminal content block lets clients subscribe to live\noutput before the tool completes." } }, "required": [ "toolCallId", "toolName", "displayName", "invocationMessage", "status", "confirmed" ] }, "ToolCallPendingResultConfirmationState": { "type": "object", "description": "Tool finished executing, waiting for client to approve the result.", "properties": { "toolCallId": { "type": "string", "description": "Unique tool call identifier" }, "toolName": { "type": "string", "description": "Internal tool name (for debugging/logging)" }, "displayName": { "type": "string", "description": "Human-readable tool name" }, "toolClientId": { "type": "string", "description": "If this tool is provided by a client, the `clientId` of the owning client.\nAbsent for server-side tools.\n\nWhen set, the identified client is responsible for executing the tool and\ndispatching `session/toolCallComplete` with the result." }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this tool call.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `ptyTerminal` key with `{ input: string; output: string }`\nindicates the tool operated on a terminal (both `input` and `output` may\ncontain escape sequences)." }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "Message describing what the tool will do" }, "toolInput": { "type": "string", "description": "Raw tool input" }, "success": { "type": "boolean", "description": "Whether the tool succeeded" }, "pastTenseMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "Past-tense description of what the tool did" }, "content": { "type": "array", "items": { "$ref": "#/$defs/ToolResultContent" }, "description": "Unstructured result content blocks.\n\nThis mirrors the `content` field of MCP `CallToolResult`." }, "structuredContent": { "type": "object", "additionalProperties": {}, "description": "Optional structured result object.\n\nThis mirrors the `structuredContent` field of MCP `CallToolResult`." }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "message" ], "description": "Error details if the tool failed" }, "status": { "$ref": "#/$defs/ToolCallStatus.PendingResultConfirmation" }, "confirmed": { "$ref": "#/$defs/ToolCallConfirmationReason", "description": "How the tool was confirmed for execution" }, "selectedOption": { "$ref": "#/$defs/ConfirmationOption", "description": "The confirmation option the user selected, if confirmation options were provided" } }, "required": [ "toolCallId", "toolName", "displayName", "invocationMessage", "success", "pastTenseMessage", "status", "confirmed" ] }, "ToolCallCompletedState": { "type": "object", "description": "Tool completed successfully or with an error.", "properties": { "toolCallId": { "type": "string", "description": "Unique tool call identifier" }, "toolName": { "type": "string", "description": "Internal tool name (for debugging/logging)" }, "displayName": { "type": "string", "description": "Human-readable tool name" }, "toolClientId": { "type": "string", "description": "If this tool is provided by a client, the `clientId` of the owning client.\nAbsent for server-side tools.\n\nWhen set, the identified client is responsible for executing the tool and\ndispatching `session/toolCallComplete` with the result." }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this tool call.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `ptyTerminal` key with `{ input: string; output: string }`\nindicates the tool operated on a terminal (both `input` and `output` may\ncontain escape sequences)." }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "Message describing what the tool will do" }, "toolInput": { "type": "string", "description": "Raw tool input" }, "success": { "type": "boolean", "description": "Whether the tool succeeded" }, "pastTenseMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "Past-tense description of what the tool did" }, "content": { "type": "array", "items": { "$ref": "#/$defs/ToolResultContent" }, "description": "Unstructured result content blocks.\n\nThis mirrors the `content` field of MCP `CallToolResult`." }, "structuredContent": { "type": "object", "additionalProperties": {}, "description": "Optional structured result object.\n\nThis mirrors the `structuredContent` field of MCP `CallToolResult`." }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "message" ], "description": "Error details if the tool failed" }, "status": { "$ref": "#/$defs/ToolCallStatus.Completed" }, "confirmed": { "$ref": "#/$defs/ToolCallConfirmationReason", "description": "How the tool was confirmed for execution" }, "selectedOption": { "$ref": "#/$defs/ConfirmationOption", "description": "The confirmation option the user selected, if confirmation options were provided" } }, "required": [ "toolCallId", "toolName", "displayName", "invocationMessage", "success", "pastTenseMessage", "status", "confirmed" ] }, "ToolCallCancelledState": { "type": "object", "description": "Tool call was cancelled before execution.", "properties": { "toolCallId": { "type": "string", "description": "Unique tool call identifier" }, "toolName": { "type": "string", "description": "Internal tool name (for debugging/logging)" }, "displayName": { "type": "string", "description": "Human-readable tool name" }, "toolClientId": { "type": "string", "description": "If this tool is provided by a client, the `clientId` of the owning client.\nAbsent for server-side tools.\n\nWhen set, the identified client is responsible for executing the tool and\ndispatching `session/toolCallComplete` with the result." }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this tool call.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `ptyTerminal` key with `{ input: string; output: string }`\nindicates the tool operated on a terminal (both `input` and `output` may\ncontain escape sequences)." }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "Message describing what the tool will do" }, "toolInput": { "type": "string", "description": "Raw tool input" }, "status": { "$ref": "#/$defs/ToolCallStatus.Cancelled" }, "reason": { "$ref": "#/$defs/ToolCallCancellationReason", "description": "Why the tool was cancelled" }, "reasonMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "Optional message explaining the cancellation" }, "userSuggestion": { "$ref": "#/$defs/UserMessage", "description": "What the user suggested doing instead" }, "selectedOption": { "$ref": "#/$defs/ConfirmationOption", "description": "The confirmation option the user selected, if confirmation options were provided" } }, "required": [ "toolCallId", "toolName", "displayName", "invocationMessage", "status", "reason" ] }, "ToolDefinition": { "type": "object", "description": "Describes a tool available in a session, provided by either the server or the active client.", "properties": { "name": { "type": "string", "description": "Unique tool identifier" }, "title": { "type": "string", "description": "Human-readable display name" }, "description": { "type": "string", "description": "Description of what the tool does" }, "inputSchema": { "type": "object", "properties": { "type": { "type": "string" }, "properties": { "type": "string" }, "required": { "type": "string" } }, "required": [ "type" ], "description": "JSON Schema defining the expected input parameters.\n\nOptional because client-provided tools may not have formal schemas.\nMirrors MCP `Tool.inputSchema`." }, "outputSchema": { "type": "object", "properties": { "type": { "type": "string" }, "properties": { "type": "string" }, "required": { "type": "string" } }, "required": [ "type" ], "description": "JSON Schema defining the structure of the tool's output.\n\nMirrors MCP `Tool.outputSchema`." }, "annotations": { "$ref": "#/$defs/ToolAnnotations", "description": "Behavioral hints about the tool. All properties are advisory." }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata.\n\nMirrors the MCP `_meta` convention." } }, "required": [ "name" ] }, "ToolAnnotations": { "type": "object", "description": "Behavioral hints about a tool. All properties are advisory and not\nguaranteed to faithfully describe tool behavior.\n\nMirrors MCP `ToolAnnotations` from the Model Context Protocol specification.", "properties": { "title": { "type": "string", "description": "Alternate human-readable title" }, "readOnlyHint": { "type": "boolean", "description": "Tool does not modify its environment (default: false)" }, "destructiveHint": { "type": "boolean", "description": "Tool may perform destructive updates (default: true)" }, "idempotentHint": { "type": "boolean", "description": "Repeated calls with the same arguments have no additional effect (default: false)" }, "openWorldHint": { "type": "boolean", "description": "Tool may interact with external entities (default: true)" } } }, "ToolResultTextContent": { "type": "object", "description": "Text content in a tool result.\n\nMirrors MCP `TextContent`.", "properties": { "type": { "$ref": "#/$defs/ToolResultContentType.Text" }, "text": { "type": "string", "description": "The text content" } }, "required": [ "type", "text" ] }, "ToolResultEmbeddedResourceContent": { "type": "object", "description": "Base64-encoded binary content embedded in a tool result.\n\nMirrors MCP `EmbeddedResource` for inline binary data.", "properties": { "type": { "$ref": "#/$defs/ToolResultContentType.EmbeddedResource" }, "data": { "type": "string", "description": "Base64-encoded data" }, "contentType": { "type": "string", "description": "Content type (e.g. `\"image/png\"`, `\"application/pdf\"`)" } }, "required": [ "type", "data", "contentType" ] }, "ToolResultResourceContent": { "type": "object", "description": "A reference to a resource stored outside the tool result.\n\nWraps {@link ContentRef} for lazy-loading large results.", "properties": { "uri": { "$ref": "#/$defs/URI", "description": "Content URI" }, "sizeHint": { "type": "number", "description": "Approximate size in bytes" }, "contentType": { "type": "string", "description": "Content MIME type" }, "type": { "$ref": "#/$defs/ToolResultContentType.Resource" } }, "required": [ "uri", "type" ] }, "FileEdit": { "type": "object", "description": "Describes a file modification with before/after state and diff metadata.\n\nSupports creates (only `after`), deletes (only `before`), renames/moves\n(different `uri` in `before` and `after`), and edits (same `uri`, different content).", "properties": { "before": { "type": "object", "properties": { "uri": { "type": "string" }, "content": { "type": "string" } }, "required": [ "uri", "content" ], "description": "The file state before the edit. Absent for file creations or for in-place file edits." }, "after": { "type": "object", "properties": { "uri": { "type": "string" }, "content": { "type": "string" } }, "required": [ "uri", "content" ], "description": "The file state after the edit. Absent for file deletions." }, "diff": { "type": "object", "properties": { "added": { "type": "number" }, "removed": { "type": "number" } }, "description": "Optional diff display metadata" } } }, "ToolResultFileEditContent": { "type": "object", "description": "Describes a file modification performed by a tool.", "properties": { "before": { "type": "object", "properties": { "uri": { "type": "string" }, "content": { "type": "string" } }, "required": [ "uri", "content" ], "description": "The file state before the edit. Absent for file creations or for in-place file edits." }, "after": { "type": "object", "properties": { "uri": { "type": "string" }, "content": { "type": "string" } }, "required": [ "uri", "content" ], "description": "The file state after the edit. Absent for file deletions." }, "diff": { "type": "object", "properties": { "added": { "type": "number" }, "removed": { "type": "number" } }, "description": "Optional diff display metadata" }, "type": { "$ref": "#/$defs/ToolResultContentType.FileEdit" } }, "required": [ "type" ] }, "ToolResultTerminalContent": { "type": "object", "description": "A reference to a terminal whose output is relevant to this tool result.\n\nClients can subscribe to the terminal's URI to stream its output in real\ntime, providing live feedback while a tool is executing.", "properties": { "type": { "$ref": "#/$defs/ToolResultContentType.Terminal" }, "resource": { "$ref": "#/$defs/URI", "description": "Terminal URI (subscribable for full terminal state)" }, "title": { "type": "string", "description": "Display title for the terminal content" } }, "required": [ "type", "resource", "title" ] }, "ToolResultSubagentContent": { "type": "object", "description": "A reference to a subagent session spawned by a tool.\n\nClients can subscribe to the subagent's session URI to stream its\nprogress in real time, including inner tool calls and responses.", "properties": { "type": { "$ref": "#/$defs/ToolResultContentType.Subagent" }, "resource": { "$ref": "#/$defs/URI", "description": "Subagent session URI (subscribable for full session state)" }, "title": { "type": "string", "description": "Display title for the subagent" }, "agentName": { "type": "string", "description": "Internal agent name" }, "description": { "type": "string", "description": "Human-readable description of the subagent's task" } }, "required": [ "type", "resource", "title" ] }, "CustomizationRef": { "type": "object", "description": "A reference to an [Open Plugins](https://open-plugins.com/) plugin.\n\nThis is intentionally thin — AHP specifies plugin identity and metadata\nbut not implementation details, which are defined by the Open Plugins spec.", "properties": { "uri": { "$ref": "#/$defs/URI", "description": "Plugin URI (e.g. an HTTPS URL or marketplace identifier)" }, "displayName": { "type": "string", "description": "Human-readable name" }, "description": { "type": "string", "description": "Description of what the plugin provides" }, "icons": { "type": "array", "items": { "$ref": "#/$defs/Icon" }, "description": "Icons for the plugin" }, "nonce": { "type": "string", "description": "Opaque version token for this customization.\n\nClients SHOULD include a nonce with every customization they provide.\nConsumers can compare nonces to detect whether a customization has\nchanged since it was last seen, avoiding redundant reloads or copies." } }, "required": [ "uri", "displayName" ] }, "SessionCustomization": { "type": "object", "description": "A customization active in a session.", "properties": { "customization": { "$ref": "#/$defs/CustomizationRef", "description": "The plugin this customization refers to" }, "enabled": { "type": "boolean", "description": "Whether this customization is currently enabled" }, "clientId": { "type": "string", "description": "The `clientId` of the client that contributed this customization.\nAbsent for server-provided customizations." }, "status": { "$ref": "#/$defs/CustomizationStatus", "description": "Server-reported loading status" }, "statusMessage": { "type": "string", "description": "Human-readable status detail (e.g. error message or degradation warning)." } }, "required": [ "customization", "enabled" ] }, "TerminalInfo": { "type": "object", "description": "Lightweight terminal metadata exposed on the root state.", "properties": { "resource": { "$ref": "#/$defs/URI", "description": "Terminal URI (subscribable for full terminal state)" }, "title": { "type": "string", "description": "Human-readable terminal title" }, "claim": { "$ref": "#/$defs/TerminalClaim", "description": "Who currently holds this terminal" }, "exitCode": { "type": "number", "description": "Process exit code, if the terminal process has exited" } }, "required": [ "resource", "title", "claim" ] }, "TerminalClientClaim": { "type": "object", "description": "A terminal claimed by a connected client.", "properties": { "kind": { "$ref": "#/$defs/TerminalClaimKind.Client", "description": "Discriminant" }, "clientId": { "type": "string", "description": "The `clientId` of the claiming client" } }, "required": [ "kind", "clientId" ] }, "TerminalSessionClaim": { "type": "object", "description": "A terminal claimed by a session, optionally scoped to a specific turn or tool call.", "properties": { "kind": { "$ref": "#/$defs/TerminalClaimKind.Session", "description": "Discriminant" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI that claimed the terminal" }, "turnId": { "type": "string", "description": "Optional turn identifier within the session" }, "toolCallId": { "type": "string", "description": "Optional tool call identifier within the turn" } }, "required": [ "kind", "session" ] }, "TerminalState": { "type": "object", "description": "Full state for a single terminal, loaded when a client subscribes to the terminal's URI.", "properties": { "title": { "type": "string", "description": "Human-readable terminal title" }, "cwd": { "$ref": "#/$defs/URI", "description": "Current working directory of the terminal process" }, "cols": { "type": "number", "description": "Terminal width in columns" }, "rows": { "type": "number", "description": "Terminal height in rows" }, "content": { "type": "array", "items": { "$ref": "#/$defs/TerminalContentPart" }, "description": "Typed content parts, replacing the flat `content: string`.\n\nNaive consumers that only need the raw VT stream can reconstruct it with:\n `content.map(p => p.type === 'command' ? p.output : p.value).join('')`\n\nConsumers that need command boundaries can filter by part type." }, "exitCode": { "type": "number", "description": "Process exit code, set when the terminal process exits" }, "claim": { "$ref": "#/$defs/TerminalClaim", "description": "Who currently holds this terminal" }, "supportsCommandDetection": { "type": "boolean", "description": "Whether this terminal emits `terminal/commandExecuted` and\n`terminal/commandFinished` actions and populates `command`-typed parts.\n\nClients MUST check this flag before relying on command detection.\nDo NOT use the presence of a `command` part as a feature flag — parts\nare absent in the normal idle state." } }, "required": [ "title", "content", "claim" ] }, "TerminalUnclassifiedPart": { "type": "object", "description": "Unstructured terminal output — content before, between, or after commands,\nor from terminals that do not support command detection.", "properties": { "type": { "type": "string", "enum": [ "unclassified" ] }, "value": { "type": "string", "description": "Accumulated VT output. Appended to by `terminal/data` when no command is executing." } }, "required": [ "type", "value" ] }, "TerminalCommandPart": { "type": "object", "description": "A single command: its command line and the output it produced.\n\nWhile `isComplete` is false the command is still executing; `output` grows\nas `terminal/data` actions arrive. At `terminal/commandFinished` the part\nis mutated in-place with `isComplete: true` and the completion metadata.", "properties": { "type": { "type": "string", "enum": [ "command" ] }, "commandId": { "type": "string", "description": "Stable id matching the `commandId` on the corresponding\n`terminal/commandExecuted` and `terminal/commandFinished` actions." }, "commandLine": { "type": "string", "description": "The command line submitted to the shell." }, "output": { "type": "string", "description": "Accumulated VT output. Appended to by `terminal/data` while `isComplete`\nis false. Shell integration escape sequences are stripped by the server." }, "timestamp": { "type": "number", "description": "Unix timestamp (ms) when execution started, as reported by the server." }, "isComplete": { "type": "boolean", "description": "Whether the command has finished." }, "exitCode": { "type": "number", "description": "Shell exit code. Set at completion. `undefined` if unknown." }, "durationMs": { "type": "number", "description": "Wall-clock duration in milliseconds. Set at completion." } }, "required": [ "type", "commandId", "commandLine", "output", "timestamp", "isComplete" ] }, "UsageInfo": { "type": "object", "properties": { "inputTokens": { "type": "number", "description": "Input tokens consumed" }, "outputTokens": { "type": "number", "description": "Output tokens generated" }, "model": { "type": "string", "description": "Model used" }, "cacheReadTokens": { "type": "number", "description": "Tokens read from cache" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this usage report.\nClients MAY look for well-known optional keys here to provide enhanced UI." } } }, "ErrorInfo": { "type": "object", "properties": { "errorType": { "type": "string", "description": "Error type identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "stack": { "type": "string", "description": "Stack trace" } }, "required": [ "errorType", "message" ] }, "Snapshot": { "type": "object", "description": "A point-in-time snapshot of a subscribed resource's state, returned by\n`initialize`, `reconnect`, and `subscribe`.", "properties": { "resource": { "$ref": "#/$defs/URI", "description": "The subscribed resource URI (e.g. `agenthost:/root` or `copilot:/`)" }, "state": { "oneOf": [ { "$ref": "#/$defs/RootState" }, { "$ref": "#/$defs/SessionState" }, { "$ref": "#/$defs/TerminalState" } ], "description": "The current state of the resource" }, "fromSeq": { "type": "number", "description": "The `serverSeq` at which this snapshot was taken. Subsequent actions will have `serverSeq > fromSeq`." } }, "required": [ "resource", "state", "fromSeq" ] }, "ActionOrigin": { "type": "object", "description": "Identifies the client that originally dispatched an action.", "properties": { "clientId": { "type": "string" }, "clientSeq": { "type": "number" } }, "required": [ "clientId", "clientSeq" ] }, "ActionEnvelope": { "type": "object", "description": "Every action is wrapped in an `ActionEnvelope`.", "properties": { "action": { "$ref": "#/$defs/StateAction" }, "serverSeq": { "type": "number" }, "origin": { "$ref": "#/$defs/ActionOrigin" }, "rejectionReason": { "type": "string" } }, "required": [ "action", "serverSeq", "origin" ] }, "ToolCallActionBase": { "type": "object", "description": "Base interface for all tool-call-scoped actions, carrying the common\nsession, turn, and tool call identifiers.", "properties": { "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" }, "toolCallId": { "type": "string", "description": "Tool call identifier" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this tool call.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `ptyTerminal` key with `{ input: string; output: string }`\nindicates the tool operated on a terminal (both `input` and `output` may\ncontain escape sequences)." } }, "required": [ "session", "turnId", "toolCallId" ] }, "RootAgentsChangedAction": { "type": "object", "description": "Fired when available agent backends or their models change.", "properties": { "type": { "$ref": "#/$defs/ActionType.RootAgentsChanged" }, "agents": { "type": "array", "items": { "$ref": "#/$defs/AgentInfo" }, "description": "Updated agent list" } }, "required": [ "type", "agents" ] }, "RootActiveSessionsChangedAction": { "type": "object", "description": "Fired when the number of active sessions changes.", "properties": { "type": { "$ref": "#/$defs/ActionType.RootActiveSessionsChanged" }, "activeSessions": { "type": "number", "description": "Current count of active sessions" } }, "required": [ "type", "activeSessions" ] }, "RootTerminalsChangedAction": { "type": "object", "description": "Fired when the list of known terminals changes.\n\nFull-replacement semantics: the `terminals` array replaces the previous\n`terminals` entirely.", "properties": { "type": { "$ref": "#/$defs/ActionType.RootTerminalsChanged" }, "terminals": { "type": "array", "items": { "$ref": "#/$defs/TerminalInfo" }, "description": "Updated terminal list (full replacement)" } }, "required": [ "type", "terminals" ] }, "RootConfigChangedAction": { "type": "object", "description": "Fired when agent-host configuration values change.\n\nBy default, the reducer merges the new values into `state.config.values`.\nSet `replace` to `true` to replace all values instead of merging.", "properties": { "type": { "$ref": "#/$defs/ActionType.RootConfigChanged" }, "config": { "type": "object", "additionalProperties": {}, "description": "Updated config values" }, "replace": { "type": "boolean", "description": "When `true`, replaces all config values instead of merging" } }, "required": [ "type", "config" ] }, "SessionReadyAction": { "type": "object", "description": "Session backend initialized successfully.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionReady" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" } }, "required": [ "type", "session" ] }, "SessionCreationFailedAction": { "type": "object", "description": "Session backend failed to initialize.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionCreationFailed" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "error": { "$ref": "#/$defs/ErrorInfo", "description": "Error details" } }, "required": [ "type", "session", "error" ] }, "SessionTurnStartedAction": { "type": "object", "description": "User sent a message; server starts agent processing.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionTurnStarted" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" }, "userMessage": { "$ref": "#/$defs/UserMessage", "description": "User's message" }, "queuedMessageId": { "type": "string", "description": "If this turn was auto-started from a queued message, the ID of that message" } }, "required": [ "type", "session", "turnId", "userMessage" ] }, "SessionDeltaAction": { "type": "object", "description": "Streaming text chunk from the assistant, appended to a specific response part.\n\nThe server MUST first emit a `session/responsePart` to create the target\npart (markdown or reasoning), then use this action to append text to it.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionDelta" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" }, "partId": { "type": "string", "description": "Identifier of the response part to append to" }, "content": { "type": "string", "description": "Text chunk" } }, "required": [ "type", "session", "turnId", "partId", "content" ] }, "SessionResponsePartAction": { "type": "object", "description": "Structured content appended to the response.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionResponsePart" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" }, "part": { "$ref": "#/$defs/ResponsePart", "description": "Response part (markdown or content ref)" } }, "required": [ "type", "session", "turnId", "part" ] }, "SessionToolCallStartAction": { "type": "object", "description": "A tool call begins — parameters are streaming from the LM.\n\nFor client-provided tools, the server sets `toolClientId` to identify the\nowning client. That client is responsible for executing the tool once it\nreaches the `running` state and dispatching `session/toolCallComplete`.", "properties": { "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" }, "toolCallId": { "type": "string", "description": "Tool call identifier" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this tool call.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `ptyTerminal` key with `{ input: string; output: string }`\nindicates the tool operated on a terminal (both `input` and `output` may\ncontain escape sequences)." }, "type": { "$ref": "#/$defs/ActionType.SessionToolCallStart" }, "toolName": { "type": "string", "description": "Internal tool name (for debugging/logging)" }, "displayName": { "type": "string", "description": "Human-readable tool name" }, "toolClientId": { "type": "string", "description": "If this tool is provided by a client, the `clientId` of the owning client.\nAbsent for server-side tools." } }, "required": [ "session", "turnId", "toolCallId", "type", "toolName", "displayName" ] }, "SessionToolCallDeltaAction": { "type": "object", "description": "Streaming partial parameters for a tool call.", "properties": { "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" }, "toolCallId": { "type": "string", "description": "Tool call identifier" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this tool call.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `ptyTerminal` key with `{ input: string; output: string }`\nindicates the tool operated on a terminal (both `input` and `output` may\ncontain escape sequences)." }, "type": { "$ref": "#/$defs/ActionType.SessionToolCallDelta" }, "content": { "type": "string", "description": "Partial parameter content to append" }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "Updated progress message" } }, "required": [ "session", "turnId", "toolCallId", "type", "content" ] }, "SessionToolCallReadyAction": { "type": "object", "description": "Tool call parameters are complete, or a running tool requires re-confirmation.\n\nWhen dispatched for a `streaming` tool call, transitions to `pending-confirmation`\nor directly to `running` if `confirmed` is set.\n\nWhen dispatched for a `running` tool call (e.g. mid-execution permission needed),\ntransitions back to `pending-confirmation`. The `invocationMessage` and `_meta`\nSHOULD be updated to describe the specific confirmation needed. Clients use the\nstandard `session/toolCallConfirmed` flow to approve or deny.\n\nFor client-provided tools, the server typically sets `confirmed` to\n`'not-needed'` so the tool transitions directly to `running`, where the\nowning client can begin execution immediately.", "properties": { "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" }, "toolCallId": { "type": "string", "description": "Tool call identifier" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this tool call.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `ptyTerminal` key with `{ input: string; output: string }`\nindicates the tool operated on a terminal (both `input` and `output` may\ncontain escape sequences)." }, "type": { "$ref": "#/$defs/ActionType.SessionToolCallReady" }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "Message describing what the tool will do or what confirmation is needed" }, "toolInput": { "type": "string", "description": "Raw tool input" }, "confirmationTitle": { "$ref": "#/$defs/StringOrMarkdown", "description": "Short title for the confirmation prompt (e.g. `\"Run in terminal\"`, `\"Write file\"`)" }, "edits": { "type": "object", "properties": { "items": { "type": "string" } }, "required": [ "items" ], "description": "File edits that this tool call will perform, for preview before confirmation" }, "editable": { "type": "boolean", "description": "Whether the agent host allows the client to edit the tool's input parameters before confirming" }, "confirmed": { "$ref": "#/$defs/ToolCallConfirmationReason", "description": "If set, the tool was auto-confirmed and transitions directly to `running`" }, "options": { "type": "array", "items": { "$ref": "#/$defs/ConfirmationOption" }, "description": "Options the server offers for this confirmation. When present, the client\nSHOULD render these instead of a plain approve/deny UI. Each option\nbelongs to a {@link ConfirmationOptionGroup} so the client can still\ncategorise the choices." } }, "required": [ "session", "turnId", "toolCallId", "type", "invocationMessage" ] }, "SessionToolCallApprovedAction": { "type": "object", "description": "Client approves a pending tool call. The tool transitions to `running`.", "properties": { "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" }, "toolCallId": { "type": "string", "description": "Tool call identifier" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this tool call.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `ptyTerminal` key with `{ input: string; output: string }`\nindicates the tool operated on a terminal (both `input` and `output` may\ncontain escape sequences)." }, "type": { "$ref": "#/$defs/ActionType.SessionToolCallConfirmed" }, "approved": { "description": "The tool call was approved" }, "confirmed": { "$ref": "#/$defs/ToolCallConfirmationReason", "description": "How the tool was confirmed" }, "editedToolInput": { "type": "string", "description": "Edited tool input parameters, if the client modified them before confirming" }, "selectedOptionId": { "type": "string", "description": "ID of the selected confirmation option, if the server provided options" } }, "required": [ "session", "turnId", "toolCallId", "type", "approved", "confirmed" ] }, "SessionToolCallDeniedAction": { "type": "object", "description": "Client denies a pending tool call. The tool transitions to `cancelled`.\n\nFor client-provided tools, the owning client MUST dispatch this if it does\nnot recognize the tool or cannot execute it.", "properties": { "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" }, "toolCallId": { "type": "string", "description": "Tool call identifier" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this tool call.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `ptyTerminal` key with `{ input: string; output: string }`\nindicates the tool operated on a terminal (both `input` and `output` may\ncontain escape sequences)." }, "type": { "$ref": "#/$defs/ActionType.SessionToolCallConfirmed" }, "approved": { "description": "The tool call was denied" }, "reason": { "oneOf": [ { "$ref": "#/$defs/ToolCallCancellationReason.Denied" }, { "$ref": "#/$defs/ToolCallCancellationReason.Skipped" } ], "description": "Why the tool was cancelled" }, "userSuggestion": { "$ref": "#/$defs/UserMessage", "description": "What the user suggested doing instead" }, "reasonMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "Optional explanation for the denial" }, "selectedOptionId": { "type": "string", "description": "ID of the selected confirmation option, if the server provided options" } }, "required": [ "session", "turnId", "toolCallId", "type", "approved", "reason" ] }, "SessionToolCallCompleteAction": { "type": "object", "description": "Tool execution finished. Transitions to `completed` or `pending-result-confirmation`\nif `requiresResultConfirmation` is `true`.\n\nFor client-provided tools (where `toolClientId` is set on the tool call state),\nthe owning client dispatches this action with the execution result. The server\nSHOULD reject this action if the dispatching client does not match `toolClientId`.\n\nServers waiting on a client tool call MAY time out after a reasonable duration\nif the implementing client disconnects or becomes unresponsive, and dispatch\nthis action with `result.success = false` and an appropriate error.", "properties": { "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" }, "toolCallId": { "type": "string", "description": "Tool call identifier" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this tool call.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `ptyTerminal` key with `{ input: string; output: string }`\nindicates the tool operated on a terminal (both `input` and `output` may\ncontain escape sequences)." }, "type": { "$ref": "#/$defs/ActionType.SessionToolCallComplete" }, "result": { "$ref": "#/$defs/ToolCallResult", "description": "Execution result" }, "requiresResultConfirmation": { "type": "boolean", "description": "If true, the result requires client approval before finalizing" } }, "required": [ "session", "turnId", "toolCallId", "type", "result" ] }, "SessionToolCallResultConfirmedAction": { "type": "object", "description": "Client approves or denies a tool's result.\n\nIf `approved` is `false`, the tool transitions to `cancelled` with reason `result-denied`.", "properties": { "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" }, "toolCallId": { "type": "string", "description": "Tool call identifier" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this tool call.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `ptyTerminal` key with `{ input: string; output: string }`\nindicates the tool operated on a terminal (both `input` and `output` may\ncontain escape sequences)." }, "type": { "$ref": "#/$defs/ActionType.SessionToolCallResultConfirmed" }, "approved": { "type": "boolean", "description": "Whether the result was approved" } }, "required": [ "session", "turnId", "toolCallId", "type", "approved" ] }, "SessionToolCallContentChangedAction": { "type": "object", "description": "Partial content produced while a tool is still executing.\n\nReplaces the `content` array on the running tool call state. Clients can\nuse this to display live feedback (e.g. a terminal reference) before the\ntool completes.\n\nFor client-provided tools (where `toolClientId` is set on the tool call state),\nthe owning client dispatches this action to stream intermediate content while\nexecuting. The server SHOULD reject this action if the dispatching client does\nnot match `toolClientId`.", "properties": { "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" }, "toolCallId": { "type": "string", "description": "Tool call identifier" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "Additional provider-specific metadata for this tool call.\n\nClients MAY look for well-known keys here to provide enhanced UI.\nFor example, a `ptyTerminal` key with `{ input: string; output: string }`\nindicates the tool operated on a terminal (both `input` and `output` may\ncontain escape sequences)." }, "type": { "$ref": "#/$defs/ActionType.SessionToolCallContentChanged" }, "content": { "type": "array", "items": { "$ref": "#/$defs/ToolResultContent" }, "description": "The current partial content for the running tool call" } }, "required": [ "session", "turnId", "toolCallId", "type", "content" ] }, "SessionTurnCompleteAction": { "type": "object", "description": "Turn finished — the assistant is idle.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionTurnComplete" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" } }, "required": [ "type", "session", "turnId" ] }, "SessionTurnCancelledAction": { "type": "object", "description": "Turn was aborted; server stops processing.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionTurnCancelled" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" } }, "required": [ "type", "session", "turnId" ] }, "SessionErrorAction": { "type": "object", "description": "Error during turn processing.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionError" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" }, "error": { "$ref": "#/$defs/ErrorInfo", "description": "Error details" } }, "required": [ "type", "session", "turnId", "error" ] }, "SessionTitleChangedAction": { "type": "object", "description": "Session title updated. Fired by the server when the title is auto-generated\nfrom conversation, or dispatched by a client to rename a session.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionTitleChanged" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "title": { "type": "string", "description": "New title" } }, "required": [ "type", "session", "title" ] }, "SessionUsageAction": { "type": "object", "description": "Token usage report for a turn.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionUsage" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" }, "usage": { "$ref": "#/$defs/UsageInfo", "description": "Token usage data" } }, "required": [ "type", "session", "turnId", "usage" ] }, "SessionReasoningAction": { "type": "object", "description": "Reasoning/thinking text from the model, appended to a specific reasoning response part.\n\nThe server MUST first emit a `session/responsePart` to create the target\nreasoning part, then use this action to append text to it.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionReasoning" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Turn identifier" }, "partId": { "type": "string", "description": "Identifier of the reasoning response part to append to" }, "content": { "type": "string", "description": "Reasoning text chunk" } }, "required": [ "type", "session", "turnId", "partId", "content" ] }, "SessionModelChangedAction": { "type": "object", "description": "Model changed for this session.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionModelChanged" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "model": { "$ref": "#/$defs/ModelSelection", "description": "New model selection" } }, "required": [ "type", "session", "model" ] }, "SessionIsReadChangedAction": { "type": "object", "description": "The read state of the session changed.\n\nDispatched by a client to mark a session as read (e.g. after viewing it)\nor unread (e.g. after new activity since the client last looked at it).", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionIsReadChanged" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "isRead": { "type": "boolean", "description": "Whether the session has been read" } }, "required": [ "type", "session", "isRead" ] }, "SessionIsArchivedChangedAction": { "type": "object", "description": "The archived state of the session changed.\n\nDispatched by a client to archive a session (e.g. the task is\ncomplete) or to unarchive it.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionIsArchivedChanged" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "isArchived": { "type": "boolean", "description": "Whether the session is archived" } }, "required": [ "type", "session", "isArchived" ] }, "SessionActivityChangedAction": { "type": "object", "description": "The activity description of the session changed.\n\nDispatched by the server to indicate what the session is currently doing\n(e.g. running a tool, thinking). Clear activity by setting it to `undefined`.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionActivityChanged" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "activity": { "type": "string", "description": "Human-readable description of current activity, or `undefined` to clear" } }, "required": [ "type", "session", "activity" ] }, "SessionDiffsChangedAction": { "type": "object", "description": "The file diffs for the session changed.\n\nFull-replacement semantics: the `diffs` array replaces the previous\n`summary.diffs` entirely.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionDiffsChanged" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "diffs": { "type": "array", "items": { "$ref": "#/$defs/FileEdit" }, "description": "Updated file diffs for the session" } }, "required": [ "type", "session", "diffs" ] }, "SessionServerToolsChangedAction": { "type": "object", "description": "Server tools for this session have changed.\n\nFull-replacement semantics: the `tools` array replaces the previous `serverTools` entirely.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionServerToolsChanged" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "tools": { "type": "array", "items": { "$ref": "#/$defs/ToolDefinition" }, "description": "Updated server tools list (full replacement)" } }, "required": [ "type", "session", "tools" ] }, "SessionActiveClientChangedAction": { "type": "object", "description": "The active client for this session has changed.\n\nA client dispatches this action with its own `SessionActiveClient` to claim\nthe active role, or with `null` to release it. The server SHOULD reject if\nanother client is already active. The server SHOULD automatically dispatch\nthis action with `activeClient: null` when the active client disconnects.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionActiveClientChanged" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "activeClient": { "oneOf": [ { "$ref": "#/$defs/SessionActiveClient" }, {} ], "description": "The new active client, or `null` to unset" } }, "required": [ "type", "session", "activeClient" ] }, "SessionActiveClientToolsChangedAction": { "type": "object", "description": "The active client's tool list has changed.\n\nFull-replacement semantics: the `tools` array replaces the active client's\nprevious tools entirely. The server SHOULD reject if the dispatching client\nis not the current active client.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionActiveClientToolsChanged" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "tools": { "type": "array", "items": { "$ref": "#/$defs/ToolDefinition" }, "description": "Updated client tools list (full replacement)" } }, "required": [ "type", "session", "tools" ] }, "SessionCustomizationsChangedAction": { "type": "object", "description": "The session's customizations have changed.\n\nFull-replacement semantics: the `customizations` array replaces the\nprevious `customizations` entirely.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionCustomizationsChanged" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "customizations": { "type": "array", "items": { "$ref": "#/$defs/SessionCustomization" }, "description": "Updated customization list (full replacement)" } }, "required": [ "type", "session", "customizations" ] }, "SessionCustomizationToggledAction": { "type": "object", "description": "A client toggled a customization on or off.\n\nThe server locates the customization by `uri` in the session's\ncustomization list and sets its `enabled` flag.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionCustomizationToggled" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "uri": { "$ref": "#/$defs/URI", "description": "The URI of the customization to toggle" }, "enabled": { "type": "boolean", "description": "Whether to enable or disable the customization" } }, "required": [ "type", "session", "uri", "enabled" ] }, "SessionCustomizationUpdatedAction": { "type": "object", "description": "Upserts mutable fields on a single customization.\n\nDispatched by the server to update one or more fields on a customization,\nor to add a new customization to the session, without republishing the\nentire `customizations` list. The reducer locates the existing entry by\n`customization.uri`:\n\n- If an entry exists, each provided field is assigned; absent (or\n `undefined`) fields are left unchanged. The stored `customization`\n ref is replaced with the one in the action.\n- If no entry exists, a new {@link SessionCustomization} is appended\n using the provided fields; `enabled` defaults to `false` when absent.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionCustomizationUpdated" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "customization": { "$ref": "#/$defs/CustomizationRef", "description": "The customization to update or insert (matched by `customization.uri`)" }, "enabled": { "type": "boolean", "description": "New enabled state (defaults to `false` on insert)" }, "status": { "$ref": "#/$defs/CustomizationStatus", "description": "New loading status" }, "statusMessage": { "type": "string", "description": "New human-readable status detail" } }, "required": [ "type", "session", "customization" ] }, "SessionConfigChangedAction": { "type": "object", "description": "Client changed a mutable config value mid-session.\n\nOnly properties with `sessionMutable: true` in the config schema may be\nchanged. The server validates and broadcasts the action; the reducer merges\nthe new values into `state.config.values`.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionConfigChanged" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "config": { "type": "object", "additionalProperties": {}, "description": "Updated config values" }, "replace": { "type": "boolean", "description": "When `true`, replaces all config values instead of merging" } }, "required": [ "type", "session", "config" ] }, "SessionMetaChangedAction": { "type": "object", "description": "The session's `_meta` side-channel changed. Replaces `state._meta`\nentirely (full-replacement semantics). Producers SHOULD merge any\nkeys they wish to preserve into the new value before dispatching.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionMetaChanged" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "New `_meta` payload, or `undefined` to clear it" } }, "required": [ "type", "session", "_meta" ] }, "SessionTruncatedAction": { "type": "object", "description": "Truncates a session's history. If `turnId` is provided, all turns after that\nturn are removed and the specified turn is kept. If `turnId` is omitted, all\nturns are removed.\n\nIf there is an active turn it is silently dropped and the session status\nreturns to `idle`.\n\nCommon use-case: truncate old data then dispatch a new\n`session/turnStarted` with an edited message.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionTruncated" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "turnId": { "type": "string", "description": "Keep turns up to and including this turn. Omit to clear all turns." } }, "required": [ "type", "session" ] }, "SessionPendingMessageSetAction": { "type": "object", "description": "A pending message was set (upsert semantics: creates or replaces).\n\nFor steering messages, this always replaces the single steering message.\nFor queued messages, if a message with the given `id` already exists it is\nupdated in place; otherwise it is appended to the queue. If the session is\nidle when a queued message is set, the server SHOULD immediately consume it\nand start a new turn.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionPendingMessageSet" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "kind": { "$ref": "#/$defs/PendingMessageKind", "description": "Whether this is a steering or queued message" }, "id": { "type": "string", "description": "Unique identifier for this pending message" }, "userMessage": { "$ref": "#/$defs/UserMessage", "description": "The message content" } }, "required": [ "type", "session", "kind", "id", "userMessage" ] }, "SessionPendingMessageRemovedAction": { "type": "object", "description": "A pending message was removed (steering or queued).\n\nDispatched by clients to cancel a pending message, or by the server when\nit consumes a message (e.g. starting a turn from a queued message or\ninjecting a steering message into the current turn).", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionPendingMessageRemoved" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "kind": { "$ref": "#/$defs/PendingMessageKind", "description": "Whether this is a steering or queued message" }, "id": { "type": "string", "description": "Identifier of the pending message to remove" } }, "required": [ "type", "session", "kind", "id" ] }, "SessionQueuedMessagesReorderedAction": { "type": "object", "description": "Reorder the queued messages.\n\nThe `order` array contains the IDs of queued messages in their new\ndesired order. IDs not present in the current queue are ignored.\nQueued messages whose IDs are absent from `order` are appended at\nthe end in their original relative order (so a client with a stale\nview of the queue never silently drops messages).", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionQueuedMessagesReordered" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "order": { "type": "array", "items": { "type": "string" }, "description": "Queued message IDs in the desired order" } }, "required": [ "type", "session", "order" ] }, "SessionInputRequestedAction": { "type": "object", "description": "A session requested input from the user.\n\nFull-request upsert semantics: the `request` replaces any existing request\nwith the same `id`, or is appended if it is new. Answer drafts are preserved\nunless `request.answers` is provided.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionInputRequested" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "request": { "$ref": "#/$defs/SessionInputRequest", "description": "Input request to create or replace" } }, "required": [ "type", "session", "request" ] }, "SessionInputAnswerChangedAction": { "type": "object", "description": "A client updated, submitted, skipped, or removed a single in-progress answer.\n\nDispatching with `answer: undefined` removes that question's answer draft.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionInputAnswerChanged" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "requestId": { "type": "string", "description": "Input request identifier" }, "questionId": { "type": "string", "description": "Question identifier within the input request" }, "answer": { "$ref": "#/$defs/SessionInputAnswer", "description": "Updated answer, or `undefined` to clear an answer draft" } }, "required": [ "type", "session", "requestId", "questionId" ] }, "SessionInputCompletedAction": { "type": "object", "description": "A client accepted, declined, or cancelled a session input request.\n\nIf accepted, the server uses `answers` (when provided) plus the request's\nsynced answer state to resume the blocked operation.", "properties": { "type": { "$ref": "#/$defs/ActionType.SessionInputCompleted" }, "session": { "$ref": "#/$defs/URI", "description": "Session URI" }, "requestId": { "type": "string", "description": "Input request identifier" }, "response": { "$ref": "#/$defs/SessionInputResponseKind", "description": "Completion outcome" }, "answers": { "type": "object", "additionalProperties": { "$ref": "#/$defs/SessionInputAnswer" }, "description": "Optional final answer replacement, keyed by question ID" } }, "required": [ "type", "session", "requestId", "response" ] }, "TerminalDataAction": { "type": "object", "description": "Terminal output data (pty → client direction).\n\nAppends `data` to the terminal's `content` in the reducer.\n\n`terminal/data` and `terminal/input` are intentionally separate actions\nbecause standard write-ahead reconciliation is not safe for terminal I/O.\nA pty is a stateful, mutable process — optimistically applying input or\npredicting output would produce incorrect state. Instead, `terminal/input`\nis a side-effect-only action (client → server → pty), and `terminal/data`\nis server-authoritative output (pty → server → client).", "properties": { "type": { "$ref": "#/$defs/ActionType.TerminalData" }, "terminal": { "$ref": "#/$defs/URI", "description": "Terminal URI" }, "data": { "type": "string", "description": "Output data (may contain ANSI escape sequences)" } }, "required": [ "type", "terminal", "data" ] }, "TerminalInputAction": { "type": "object", "description": "Keyboard input sent to the terminal process (client → pty direction).\n\nThis is a side-effect-only action: the server forwards the data to the\nterminal's pty. The reducer treats this as a no-op since `terminal/data`\nactions will reflect any resulting output.\n\nSee `terminal/data` for why these two actions are kept separate.", "properties": { "type": { "$ref": "#/$defs/ActionType.TerminalInput" }, "terminal": { "$ref": "#/$defs/URI", "description": "Terminal URI" }, "data": { "type": "string", "description": "Input data to send to the pty" } }, "required": [ "type", "terminal", "data" ] }, "TerminalResizedAction": { "type": "object", "description": "Terminal dimensions changed.\n\nDispatchable by clients to request a resize, or by the server to inform\nclients of the actual terminal dimensions.", "properties": { "type": { "$ref": "#/$defs/ActionType.TerminalResized" }, "terminal": { "$ref": "#/$defs/URI", "description": "Terminal URI" }, "cols": { "type": "number", "description": "Terminal width in columns" }, "rows": { "type": "number", "description": "Terminal height in rows" } }, "required": [ "type", "terminal", "cols", "rows" ] }, "TerminalClaimedAction": { "type": "object", "description": "Terminal claim changed. A client or session transfers ownership of the terminal.\n\nThe server SHOULD reject if the dispatching client does not currently hold\nthe claim.", "properties": { "type": { "$ref": "#/$defs/ActionType.TerminalClaimed" }, "terminal": { "$ref": "#/$defs/URI", "description": "Terminal URI" }, "claim": { "$ref": "#/$defs/TerminalClaim", "description": "The new claim" } }, "required": [ "type", "terminal", "claim" ] }, "TerminalTitleChangedAction": { "type": "object", "description": "Terminal title changed.\n\nFired by the server when the terminal process updates its title (e.g. via\nescape sequences), or dispatched by a client to rename a terminal.", "properties": { "type": { "$ref": "#/$defs/ActionType.TerminalTitleChanged" }, "terminal": { "$ref": "#/$defs/URI", "description": "Terminal URI" }, "title": { "type": "string", "description": "New terminal title" } }, "required": [ "type", "terminal", "title" ] }, "TerminalCwdChangedAction": { "type": "object", "description": "Terminal working directory changed.", "properties": { "type": { "$ref": "#/$defs/ActionType.TerminalCwdChanged" }, "terminal": { "$ref": "#/$defs/URI", "description": "Terminal URI" }, "cwd": { "$ref": "#/$defs/URI", "description": "New working directory" } }, "required": [ "type", "terminal", "cwd" ] }, "TerminalExitedAction": { "type": "object", "description": "Terminal process exited.", "properties": { "type": { "$ref": "#/$defs/ActionType.TerminalExited" }, "terminal": { "$ref": "#/$defs/URI", "description": "Terminal URI" }, "exitCode": { "type": "number", "description": "Process exit code. `undefined` if the process was killed without an exit code." } }, "required": [ "type", "terminal" ] }, "TerminalClearedAction": { "type": "object", "description": "Terminal scrollback buffer cleared.", "properties": { "type": { "$ref": "#/$defs/ActionType.TerminalCleared" }, "terminal": { "$ref": "#/$defs/URI", "description": "Terminal URI" } }, "required": [ "type", "terminal" ] }, "TerminalCommandDetectionAvailableAction": { "type": "object", "description": "Shell integration has loaded and the terminal now supports command\ndetection. The server dispatches this when shell integration becomes\navailable (which may happen asynchronously after the terminal is created).\n\nClients MUST NOT assume command detection is available until this action\n(or `terminal/commandExecuted`) has been received.", "properties": { "type": { "$ref": "#/$defs/ActionType.TerminalCommandDetectionAvailable" }, "terminal": { "$ref": "#/$defs/URI", "description": "Terminal URI" } }, "required": [ "type", "terminal" ] }, "TerminalCommandExecutedAction": { "type": "object", "description": "A command has been submitted to the shell and is now executing.\nAll subsequent `terminal/data` actions (until the matching\n`terminal/commandFinished`) constitute this command's output.", "properties": { "type": { "$ref": "#/$defs/ActionType.TerminalCommandExecuted" }, "terminal": { "$ref": "#/$defs/URI", "description": "Terminal URI" }, "commandId": { "type": "string", "description": "Stable identifier for this command, scoped to the terminal URI.\nAllows correlating `commandExecuted` → `commandFinished` pairs." }, "commandLine": { "type": "string", "description": "The command line text that was submitted" }, "timestamp": { "type": "number", "description": "Unix timestamp (ms) of when the command started executing, as measured\non the server." } }, "required": [ "type", "terminal", "commandId", "commandLine", "timestamp" ] }, "TerminalCommandFinishedAction": { "type": "object", "description": "A command has finished executing.\n\nThe sequence of `terminal/data` actions between the preceding\n`terminal/commandExecuted` (same `commandId`) and this action constitutes\nthe complete output of the command.", "properties": { "type": { "$ref": "#/$defs/ActionType.TerminalCommandFinished" }, "terminal": { "$ref": "#/$defs/URI", "description": "Terminal URI" }, "commandId": { "type": "string", "description": "Matches the `commandId` from the corresponding `commandExecuted`" }, "exitCode": { "type": "number", "description": "Shell exit code. `undefined` if the shell did not report one." }, "durationMs": { "type": "number", "description": "Wall-clock duration of the command in milliseconds, as measured by the\nshell integration script on the server side." } }, "required": [ "type", "terminal", "commandId" ] } } }