actions.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$comment": "Generated from types/actions.ts — do not edit",
  "$id": "https://microsoft.github.io/agent-host-protocol/schema/actions.schema.json",
  "title": "AHP Action Types",
  "description": "All action types in the Agent Host Protocol.",
  "$defs": {
    "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`.\n\nThe envelope identifies the channel the action belongs to (e.g.\n`ahp-root://` for root actions, the session URI for session actions, the\nterminal URI for terminal actions). Individual action payloads carry only\nfields that are intrinsic to the action; the channel comes from the\nenvelope so that any subscribable resource can route its actions uniformly.",
      "properties": {
        "channel": {
          "$ref": "#/$defs/URI",
          "description": "Channel URI this action belongs to."
        },
        "action": {
          "$ref": "#/$defs/StateAction"
        },
        "serverSeq": {
          "type": "number"
        },
        "origin": {
          "$ref": "#/$defs/ActionOrigin"
        },
        "rejectionReason": {
          "type": "string"
        }
      },
      "required": [
        "channel",
        "action",
        "serverSeq"
      ]
    },
    "RootAgentsChangedAction": {
      "type": "object",
      "description": "Fired when available agent backends or their models change.",
      "properties": {
        "type": {
          "const": "root/agentsChanged"
        },
        "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": {
          "const": "root/activeSessionsChanged"
        },
        "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": {
          "const": "root/terminalsChanged"
        },
        "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": {
          "const": "root/configChanged"
        },
        "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": {
          "const": "session/ready"
        }
      },
      "required": [
        "type"
      ]
    },
    "SessionCreationFailedAction": {
      "type": "object",
      "description": "Session backend failed to initialize.",
      "properties": {
        "type": {
          "const": "session/creationFailed"
        },
        "error": {
          "$ref": "#/$defs/ErrorInfo",
          "description": "Error details"
        }
      },
      "required": [
        "type",
        "error"
      ]
    },
    "SessionChatAddedAction": {
      "type": "object",
      "description": "A chat was added to this session's catalog. Upsert semantics: if a chat\nwith the same `summary.resource` already exists, the existing entry is\nreplaced.\n\nMirrors the root-channel `root/sessionAdded` notification.",
      "properties": {
        "type": {
          "const": "session/chatAdded"
        },
        "summary": {
          "$ref": "#/$defs/ChatSummary",
          "description": "The full summary of the newly added (or upserted) chat."
        }
      },
      "required": [
        "type",
        "summary"
      ]
    },
    "SessionChatRemovedAction": {
      "type": "object",
      "description": "A chat was removed from this session's catalog. No-op when no entry matches.\n\nMirrors the root-channel `root/sessionRemoved` notification.",
      "properties": {
        "type": {
          "const": "session/chatRemoved"
        },
        "chat": {
          "$ref": "#/$defs/URI",
          "description": "The URI of the chat to remove."
        }
      },
      "required": [
        "type",
        "chat"
      ]
    },
    "SessionChatUpdatedAction": {
      "type": "object",
      "description": "One existing chat's summary fields changed.\n\nPartial-update semantics: only fields present in `changes` are written;\nomitted fields are preserved. Identity fields (`resource`) MUST NOT be\ncarried in `changes`. No-op when no entry with `chat` exists — clients\nSHOULD then wait for a {@link SessionChatAddedAction | `session/chatAdded`}.\n\nMirrors the root-channel `root/sessionSummaryChanged` notification.",
      "properties": {
        "type": {
          "const": "session/chatUpdated"
        },
        "chat": {
          "$ref": "#/$defs/URI",
          "description": "The URI of the chat whose summary changed."
        },
        "changes": {
          "type": "object",
          "properties": {
            "resource": {
              "$ref": "#/$defs/URI",
              "description": "Chat URI"
            },
            "title": {
              "type": "string",
              "description": "Chat title"
            },
            "status": {
              "$ref": "#/$defs/SessionStatus",
              "description": "Current chat status (reuses SessionStatus shape)"
            },
            "activity": {
              "type": "string",
              "description": "Human-readable description of what the chat is currently doing"
            },
            "modifiedAt": {
              "type": "string",
              "description": "Last modification timestamp (ISO 8601, e.g. `\"2025-03-10T18:42:03.123Z\"`)"
            },
            "origin": {
              "$ref": "#/$defs/ChatOrigin",
              "description": "How this chat came into existence"
            },
            "interactivity": {
              "$ref": "#/$defs/ChatInteractivity",
              "description": "How the user can interact with this chat. See {@link ChatInteractivity}.\n\nSupports agent-team patterns where worker chats are read-only or hidden.\nAbsence defaults to {@link ChatInteractivity.Full} for backward\ncompatibility."
            },
            "workingDirectories": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/URI"
              },
              "description": "The subset of the session's working directories this chat uses.\nSee {@link ChatState.workingDirectories} for the full semantics."
            }
          },
          "description": "Mutable summary fields that changed; omitted fields are unchanged.\n\nIdentity fields (`resource`) never change and MUST be omitted by\nsenders; receivers SHOULD ignore them if present."
        }
      },
      "required": [
        "type",
        "chat",
        "changes"
      ]
    },
    "SessionDefaultChatChangedAction": {
      "type": "object",
      "description": "The default chat input-routing hint for this session changed.",
      "properties": {
        "type": {
          "const": "session/defaultChatChanged"
        },
        "defaultChat": {
          "$ref": "#/$defs/URI",
          "description": "New default chat URI, or `undefined` to clear the hint."
        }
      },
      "required": [
        "type"
      ]
    },
    "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": {
          "const": "session/titleChanged"
        },
        "title": {
          "type": "string",
          "description": "New title"
        }
      },
      "required": [
        "type",
        "title"
      ]
    },
    "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": {
          "const": "session/isReadChanged"
        },
        "isRead": {
          "type": "boolean",
          "description": "Whether the session has been read"
        }
      },
      "required": [
        "type",
        "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": {
          "const": "session/isArchivedChanged"
        },
        "isArchived": {
          "type": "boolean",
          "description": "Whether the session is archived"
        }
      },
      "required": [
        "type",
        "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": {
          "const": "session/activityChanged"
        },
        "activity": {
          "type": "string",
          "description": "Human-readable description of current activity, or `undefined` to clear"
        }
      },
      "required": [
        "type"
      ]
    },
    "SessionChangesetsChangedAction": {
      "type": "object",
      "description": "The {@link Changeset | catalogue of changesets} the agent host\nadvertises for this session changed. Replaces\n{@link SessionState.changesets | `state.changesets`} entirely\n(full-replacement semantics) — set to `undefined` to clear the\ncatalogue.\n\nProducers dispatch this whenever entries are added or removed. The\nfan-out happens through this action so observers see catalogue\nmutations in the same {@link ChangesetAction | per-changeset} action\nstream they already follow for file-level updates.",
      "properties": {
        "type": {
          "const": "session/changesetsChanged"
        },
        "changesets": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Changeset"
          },
          "description": "New catalogue, or `undefined` to clear it"
        }
      },
      "required": [
        "type"
      ]
    },
    "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": {
          "const": "session/serverToolsChanged"
        },
        "tools": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ToolDefinition"
          },
          "description": "Updated server tools list (full replacement)"
        }
      },
      "required": [
        "type",
        "tools"
      ]
    },
    "SessionActiveClientSetAction": {
      "type": "object",
      "description": "An active client for this session was added or updated.\n\nUpsert semantics keyed by {@link SessionActiveClient.clientId | `clientId`}:\na client dispatches this action with its own `SessionActiveClient` to join\nthe session's active clients or refresh its entry, replacing any existing\nentry that has the same `clientId`. Multiple clients may be active at once.\nThis is also how a client updates its published tools or customizations —\nre-dispatch with the full, updated entry. Use\n{@link SessionActiveClientRemovedAction | `session/activeClientRemoved`} to\nleave. The server SHOULD automatically dispatch that removal when an active\nclient disconnects.",
      "properties": {
        "type": {
          "const": "session/activeClientSet"
        },
        "activeClient": {
          "$ref": "#/$defs/SessionActiveClient",
          "description": "The active client to add or update, matched by `clientId`."
        }
      },
      "required": [
        "type",
        "activeClient"
      ]
    },
    "SessionActiveClientRemovedAction": {
      "type": "object",
      "description": "An active client was removed from this session.\n\nRemoves the entry for the client identified by `clientId` from\n{@link SessionState.activeClients}; a no-op when no entry matches.\n\nThe host SHOULD dispatch this automatically when a client stops participating\nin the session — for example when it unsubscribes from the session channel,\nwhen it disconnects and does not reconnect within a host-defined grace\nperiod, or when a `reconnect` command's `subscriptions` omit a session the\nclient was still active in. When removing a client, the host SHOULD also\ncancel that client's in-flight tool calls — those whose tool call state\ncarries a client `ToolCallContributor` with the matching `clientId` — by\ndispatching `chat/toolCallComplete` with `result.success = false`. (There is\nno per-tool-call server cancel; a failed completion is the cancellation\nmechanism, and the call ends in `completed` status with a failed result.)",
      "properties": {
        "type": {
          "const": "session/activeClientRemoved"
        },
        "clientId": {
          "type": "string",
          "description": "The `clientId` of the active client to remove."
        }
      },
      "required": [
        "type",
        "clientId"
      ]
    },
    "SessionWorkingDirectorySetAction": {
      "type": "object",
      "description": "A working directory was added to the session's\n{@link SessionState.workingDirectories} set.\n\nMembership semantics keyed by the directory URI: the reducer appends\n`directory` when the set does not already contain it (creating the set if\nabsent) and is a no-op when it is already present. Only valid when the agent\nadvertises {@link AgentCapabilities.multipleWorkingDirectories}.",
      "properties": {
        "type": {
          "const": "session/workingDirectorySet"
        },
        "directory": {
          "$ref": "#/$defs/URI",
          "description": "The working directory to grant the session's agent tool access to."
        }
      },
      "required": [
        "type",
        "directory"
      ]
    },
    "SessionWorkingDirectoryRemovedAction": {
      "type": "object",
      "description": "A working directory was removed from the session's\n{@link SessionState.workingDirectories} set.\n\nRemoves `directory` from the set; a no-op when it is not present. There is no\natomic backend \"remove one\" primitive — a host reconfigures its agent to the\nreduced set — so this action is safe to model as idempotent. A host MAY\ndecline to apply the removal (e.g. an immutable primary directory, see\n{@link MultipleWorkingDirectoriesCapability.immutablePrimary}); it then leaves\nthe set unchanged. When the agent advertises\n{@link MultipleWorkingDirectoriesCapability.primaryReplacement}, clients MUST\nNOT use this generic membership action to remove index `0`; the host MUST\nreject such a removal, leaving the protected slot intact.",
      "properties": {
        "type": {
          "const": "session/workingDirectoryRemoved"
        },
        "directory": {
          "$ref": "#/$defs/URI",
          "description": "The working directory to revoke the session's agent tool access to."
        }
      },
      "required": [
        "type",
        "directory"
      ]
    },
    "SessionWorkingDirectoryReplacedAction": {
      "type": "object",
      "description": "Atomically replaces one of the session's working directories.\n\nThis is a targeted compare-and-swap: the reducer is a no-op when\n{@link SessionState.workingDirectories} does not contain `directory`.\nOtherwise it replaces that entry with `replacement` and deduplicates the\nresult, preserving every other directory's relative order. When\n`replacement` occurs after the target, it moves to the target's position;\nfor example, `[A, B, C]` with `B → C` becomes `[A, C]`. When it occurs\nbefore the target, it retains its earlier position and the target is removed;\n`[A, B, C]` with `C → A` becomes `[A, B]`.\n\nOnly valid when the agent advertises\n{@link AgentCapabilities.multipleWorkingDirectories}. Replacing index `0`\nadditionally requires\n{@link MultipleWorkingDirectoriesCapability.primaryReplacement}; clients\nMUST NOT target an immutable primary. The host MUST validate and apply its\nbackend side effect before broadcasting an accepted action, or reject it.",
      "properties": {
        "type": {
          "const": "session/workingDirectoryReplaced"
        },
        "directory": {
          "$ref": "#/$defs/URI",
          "description": "URI of the existing entry to replace."
        },
        "replacement": {
          "$ref": "#/$defs/URI",
          "description": "URI to place in the replaced entry's position."
        }
      },
      "required": [
        "type",
        "directory",
        "replacement"
      ]
    },
    "SessionInputNeededSetAction": {
      "type": "object",
      "description": "A session-level input request was added or updated.\n\nUpsert semantics keyed by {@link SessionInputRequest.id | `request.id`}: the\nhost dispatches this with the full {@link SessionInputRequest} to append a new\nentry to {@link SessionState.inputNeeded} or replace the existing entry with\nthe same `id`.\n\nServer-originated: the host mirrors chat-level requests (elicitations, tool\nconfirmations, client-tool executions) into the session aggregate so clients\nsubscribed only to the session channel can discover them. Clients respond by\ndispatching the ordinary `chat/*` action to the entry's `chat` channel — see\n{@link SessionInputRequest}.",
      "properties": {
        "type": {
          "const": "session/inputNeededSet"
        },
        "request": {
          "$ref": "#/$defs/SessionInputRequest",
          "description": "The input request to add or update, matched by `id`."
        }
      },
      "required": [
        "type",
        "request"
      ]
    },
    "SessionInputNeededRemovedAction": {
      "type": "object",
      "description": "A session-level input request was removed.\n\nRemoves the entry identified by `id` from\n{@link SessionState.inputNeeded}; a no-op when no entry matches.\n\nServer-originated: the host dispatches this once the underlying request\nresolves (the user answers, the tool call is confirmed, or the client\nreports its result).",
      "properties": {
        "type": {
          "const": "session/inputNeededRemoved"
        },
        "id": {
          "type": "string",
          "description": "The `id` of the input request to remove."
        }
      },
      "required": [
        "type",
        "id"
      ]
    },
    "SessionCustomizationsChangedAction": {
      "type": "object",
      "description": "The session's customizations have changed.\n\nFull-replacement semantics: the `customizations` array replaces the\nprevious `customizations` entirely.",
      "properties": {
        "type": {
          "const": "session/customizationsChanged"
        },
        "customizations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Customization"
          },
          "description": "Updated customization list (full replacement)."
        }
      },
      "required": [
        "type",
        "customizations"
      ]
    },
    "SessionCustomizationToggledAction": {
      "type": "object",
      "description": "A client updated a customization's enablement decisions.\n\nMatches `id` against every top-level customization first — a plugin or\ndirectory container, or a bare top-level MCP server — then against the\nchildren inside each container (a skill, agent, or other entry). Plugins\nand MCP servers retain the matched entry's explicit decisions; other\nentries update their `enabled` flag. Disabling a plugin still disables all\nof its children — the effective state of a plugin child is the plugin's\nderived enabled value and `(child.enabled ?? true)` — so toggling a child\nonly matters while its plugin is enabled. Is a no-op when no\ncustomization has the given `id`.\n\nThe `enablement` array completely replaces all explicit decisions. A caller\nchanging one scope must include every decision it intends to preserve.",
      "properties": {
        "type": {
          "const": "session/customizationToggled"
        },
        "id": {
          "type": "string",
          "description": "The id of the container or child to update."
        },
        "enablement": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/CustomizationEnablement"
          },
          "description": "Explicit enablement decisions, replacing the previous list entirely."
        }
      },
      "required": [
        "type",
        "id",
        "enablement"
      ]
    },
    "SessionCustomizationUpdatedAction": {
      "type": "object",
      "description": "Upserts a top-level customization (plugin or directory).\n\nThe reducer locates the existing entry by `customization.id`:\n\n- If found, the entry is replaced entirely with `customization`,\n  including its `children` array. To preserve existing children, the\n  host must include them on the payload.\n- If not found, the entry is appended.",
      "properties": {
        "type": {
          "const": "session/customizationUpdated"
        },
        "customization": {
          "$ref": "#/$defs/Customization",
          "description": "The customization to upsert (matched by `customization.id`)."
        }
      },
      "required": [
        "type",
        "customization"
      ]
    },
    "SessionCustomizationRemovedAction": {
      "type": "object",
      "description": "Removes a customization by id.\n\nSearches every container and its children for the entry. If the entry\nis a container, its children are removed with it. Is a no-op when no\nmatching id is found.",
      "properties": {
        "type": {
          "const": "session/customizationRemoved"
        },
        "id": {
          "type": "string",
          "description": "The id of the customization to remove."
        }
      },
      "required": [
        "type",
        "id"
      ]
    },
    "SessionMcpServerStateChangedAction": {
      "type": "object",
      "description": "Updates the runtime fields of an existing\n{@link McpServerCustomization} — narrow alternative to\n{@link SessionCustomizationUpdatedAction} for the high-frequency\n`starting` ↔ `ready` ↔ `authRequired` transitions.\n\nLocates the target entry by `id`, searching both the top-level\ncustomization list and the `children` array of every container.\nReplaces the entry's {@link McpServerCustomization.state | `state`}\nand {@link McpServerCustomization.channel | `channel`}\n(full-replacement semantics: omit `channel` to clear an existing\nchannel URI). Other fields of the customization are preserved.\n\nIs a no-op when no matching `McpServerCustomization` is found. To\nupdate any other field (name, icons, `mcpApp` capabilities, etc.) use\n{@link SessionCustomizationUpdatedAction} instead.\n\nWhen the transition is to {@link McpServerStatus.AuthRequired}\nbecause of a request issued mid-turn, the host SHOULD also raise\n{@link SessionStatus.InputNeeded} on the session — see\n{@link McpServerAuthRequiredState} for the rationale.",
      "properties": {
        "type": {
          "const": "session/mcpServerStateChanged"
        },
        "id": {
          "type": "string",
          "description": "The id of the {@link McpServerCustomization} to update."
        },
        "state": {
          "$ref": "#/$defs/McpServerState",
          "description": "The new lifecycle state."
        },
        "channel": {
          "$ref": "#/$defs/URI",
          "description": "Updated `mcp://` side-channel URI. Full-replacement: omit to clear\nan existing channel (typical when leaving\n{@link McpServerStatus.Ready | `Ready`})."
        }
      },
      "required": [
        "type",
        "id",
        "state"
      ]
    },
    "SessionMcpServerStartRequestedAction": {
      "type": "object",
      "description": "Requests that the host start or restart an existing\n{@link McpServerCustomization}.\n\nLocates the target entry by `id`, searching both the top-level\ncustomization list and the `children` array of every container. The\nreducer optimistically moves the server to\n{@link McpServerStatus.Starting | `starting`} and clears any previous\n{@link McpServerCustomization.channel | `channel`}; the host remains\nauthoritative and SHOULD follow with\n{@link SessionMcpServerStateChangedAction | `session/mcpServerStateChanged`}\nonce the server becomes ready, needs authentication, fails, or is\nrejected. Is a no-op when no matching `McpServerCustomization` is found.",
      "properties": {
        "type": {
          "const": "session/mcpServerStartRequested"
        },
        "id": {
          "type": "string",
          "description": "The id of the {@link McpServerCustomization} to start."
        }
      },
      "required": [
        "type",
        "id"
      ]
    },
    "SessionMcpServerStopRequestedAction": {
      "type": "object",
      "description": "Requests that the host stop an existing {@link McpServerCustomization}.\n\nLocates the target entry by `id`, searching both the top-level\ncustomization list and the `children` array of every container. The\nreducer optimistically moves the server to\n{@link McpServerStatus.Stopped | `stopped`} and clears any previous\n{@link McpServerCustomization.channel | `channel`}. Replacing an\n{@link McpServerStatus.AuthRequired | `authRequired`} lifecycle state with\n`stopped` unblocks the server from waiting on authentication. If the host\nalso raised session-level input-needed state solely for that MCP server, it\nSHOULD remove that input-needed entry when accepting the stop.\n\nThe host remains authoritative and MAY reject the action or follow with\n{@link SessionMcpServerStateChangedAction | `session/mcpServerStateChanged`}\nif the final lifecycle state differs. Is a no-op when no matching\n`McpServerCustomization` is found.",
      "properties": {
        "type": {
          "const": "session/mcpServerStopRequested"
        },
        "id": {
          "type": "string",
          "description": "The id of the {@link McpServerCustomization} to stop."
        }
      },
      "required": [
        "type",
        "id"
      ]
    },
    "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": {
          "const": "session/configChanged"
        },
        "config": {
          "type": "object",
          "additionalProperties": {},
          "description": "Updated config values"
        },
        "replace": {
          "type": "boolean",
          "description": "When `true`, replaces all config values instead of merging"
        }
      },
      "required": [
        "type",
        "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": {
          "const": "session/metaChanged"
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "New `_meta` payload, or `undefined` to clear it"
        }
      },
      "required": [
        "type"
      ]
    },
    "ToolCallActionBase": {
      "type": "object",
      "description": "Base interface for all tool-call-scoped actions, carrying the common turn\nand tool call identifiers. The owning chat URI is identified by the\nenclosing {@link ActionEnvelope}'s `channel` field.",
      "properties": {
        "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": [
        "turnId",
        "toolCallId"
      ]
    },
    "ChatTurnStartedAction": {
      "type": "object",
      "description": "A new message has been sent to the agent, and a new turn starts.\n\nA client is only allowed to send {@link MessageKind.User} messages.",
      "properties": {
        "type": {
          "const": "chat/turnStarted"
        },
        "turnId": {
          "type": "string",
          "description": "Turn identifier"
        },
        "startedAt": {
          "type": "string",
          "description": "ISO 8601 timestamp when this turn started."
        },
        "message": {
          "$ref": "#/$defs/Message",
          "description": "The new message"
        },
        "queuedMessageId": {
          "type": "string",
          "description": "If this turn was auto-started from a queued message, the ID of that message"
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this action.\n\nClients MAY look for well-known keys here to provide enhanced UI, and\nagent hosts MAY use it to carry per-event context that does not fit any\nother field — for example, attributing the event to a specific agent\n(such as a sub-agent acting within the turn). Mirrors the MCP `_meta`\nconvention."
        }
      },
      "required": [
        "type",
        "turnId",
        "startedAt",
        "message"
      ]
    },
    "ChatDeltaAction": {
      "type": "object",
      "description": "Streaming text chunk from the assistant, appended to a specific response part.\n\nThe server MUST first emit a `chat/responsePart` to create the target\nmarkdown part, then use this action to append text to it.",
      "properties": {
        "type": {
          "const": "chat/delta"
        },
        "turnId": {
          "type": "string",
          "description": "Turn identifier"
        },
        "partId": {
          "type": "string",
          "description": "Identifier of the response part to append to"
        },
        "content": {
          "type": "string",
          "description": "Text chunk"
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this action.\n\nClients MAY look for well-known keys here to provide enhanced UI, and\nagent hosts MAY use it to carry per-event context that does not fit any\nother field — for example, attributing the event to a specific agent\n(such as a sub-agent acting within the turn). Mirrors the MCP `_meta`\nconvention."
        }
      },
      "required": [
        "type",
        "turnId",
        "partId",
        "content"
      ]
    },
    "ChatResponsePartAction": {
      "type": "object",
      "description": "Structured content appended to the response.\n\nAn {@link ErrorResponsePart} MUST be appended with {@link ChatErrorAction}\ninstead so adding the part and ending the turn are one atomic transition.",
      "properties": {
        "type": {
          "const": "chat/responsePart"
        },
        "turnId": {
          "type": "string",
          "description": "Turn identifier"
        },
        "part": {
          "$ref": "#/$defs/ResponsePart",
          "description": "Response part to append; error parts are ignored."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this action.\n\nClients MAY look for well-known keys here to provide enhanced UI, and\nagent hosts MAY use it to carry per-event context that does not fit any\nother field — for example, attributing the event to a specific agent\n(such as a sub-agent acting within the turn). Mirrors the MCP `_meta`\nconvention."
        }
      },
      "required": [
        "type",
        "turnId",
        "part"
      ]
    },
    "ChatToolCallStartAction": {
      "type": "object",
      "description": "A tool call begins — parameters are streaming from the LM.\n\nThe server sets {@link ToolCallContributor | `contributor`} to identify\nthe origin of the tool. For client-provided tools, the named client is\nresponsible for executing the tool once it reaches the `running` state\nand dispatching `chat/toolCallComplete`. For MCP-served tools, the\nserver executes the call against the named `McpServerCustomization`.",
      "properties": {
        "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": {
          "const": "chat/toolCallStart"
        },
        "toolName": {
          "type": "string",
          "description": "Internal tool name (for debugging/logging)"
        },
        "displayName": {
          "type": "string",
          "description": "Human-readable tool name"
        },
        "intention": {
          "type": "string",
          "description": "Human-readable description of what the tool invocation intends to do"
        },
        "contributor": {
          "$ref": "#/$defs/ToolCallContributor",
          "description": "Reference to the contributor of the tool being called. Absent for\nserver-side tools that are not contributed by a client or MCP server."
        }
      },
      "required": [
        "turnId",
        "toolCallId",
        "type",
        "toolName",
        "displayName"
      ]
    },
    "ChatToolCallDeltaAction": {
      "type": "object",
      "description": "Streaming partial parameters for a tool call.",
      "properties": {
        "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": {
          "const": "chat/toolCallDelta"
        },
        "content": {
          "type": "string",
          "description": "Partial parameter content to append, if provided by the host."
        },
        "invocationMessage": {
          "$ref": "#/$defs/StringOrMarkdown",
          "description": "Updated progress message"
        }
      },
      "required": [
        "turnId",
        "toolCallId",
        "type"
      ]
    },
    "ChatToolCallReadyAction": {
      "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 `chat/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": {
        "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": {
          "const": "chat/toolCallReady"
        },
        "contributor": {
          "$ref": "#/$defs/ToolCallContributor",
          "description": "Final contributor metadata. MUST NOT change execution ownership established\nat `chat/toolCallStart`; a client contributor must keep the same `clientId`."
        },
        "intention": {
          "type": "string",
          "description": "Final human-readable description of what the tool invocation intends to do.\nWhen present, replaces the provisional intention from `chat/toolCallStart`."
        },
        "invocationMessage": {
          "$ref": "#/$defs/StringOrMarkdown",
          "description": "Message describing what the tool will do or what confirmation is needed"
        },
        "toolInput": {
          "$ref": "#/$defs/ToolInput",
          "description": "Final tool input"
        },
        "confirmationTitle": {
          "$ref": "#/$defs/StringOrMarkdown",
          "description": "Short title for the confirmation prompt (e.g. `\"Run in terminal\"`, `\"Write file\"`)"
        },
        "riskAssessment": {
          "$ref": "#/$defs/ToolCallRiskAssessment",
          "description": "Risk assessment that informed the confirmation requirement."
        },
        "edits": {
          "type": "object",
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/FileEdit"
              }
            }
          },
          "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": [
        "turnId",
        "toolCallId",
        "type",
        "invocationMessage"
      ]
    },
    "ChatToolCallApprovedAction": {
      "type": "object",
      "description": "Client approves a pending tool call. The tool transitions to `running`.",
      "properties": {
        "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": {
          "const": "chat/toolCallConfirmed"
        },
        "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.\n\nFor inline `toolInput`, the reducer replaces the state value directly.\nFor referenced input, the host MUST replace the resource contents before\nechoing the accepted action."
        },
        "selectedOptionId": {
          "type": "string",
          "description": "ID of the selected confirmation option, if the server provided options"
        }
      },
      "required": [
        "turnId",
        "toolCallId",
        "type",
        "approved",
        "confirmed"
      ]
    },
    "ChatToolCallDeniedAction": {
      "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": {
        "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": {
          "const": "chat/toolCallConfirmed"
        },
        "approved": {
          "description": "The tool call was denied"
        },
        "reason": {
          "oneOf": [
            {
              "const": "denied"
            },
            {
              "const": "skipped"
            }
          ],
          "description": "Why the tool was cancelled"
        },
        "userSuggestion": {
          "$ref": "#/$defs/Message",
          "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": [
        "turnId",
        "toolCallId",
        "type",
        "approved",
        "reason"
      ]
    },
    "ChatToolCallCompleteAction": {
      "type": "object",
      "description": "Tool execution finished. Transitions to `completed` or `pending-result-confirmation`\nif `requiresResultConfirmation` is `true`.\n\nFor client-provided tools (whose tool call state carries a client\n`ToolCallContributor` with a `clientId`), the owning client dispatches this\naction with the execution result. The server SHOULD reject this action if the\ndispatching client does not match the contributor's `clientId`.\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.\n\nA client MAY also dispatch this action with a **failed** result (\n`result.success: false`) for a tool call currently in `auth-required`\nstatus, to cancel that invocation without completing the pending MCP\nauthentication challenge. This always transitions the tool call straight\nto `completed`, preserving the fields it had before pausing for auth;\n`requiresResultConfirmation` is ignored for this transition; the\ncancellation can never enter `pending-result-confirmation`, since there is\nno real result to review.\n\nA **successful** result (`result.success: true`) is invalid for a tool\ncall in `auth-required` status — execution never resumed after the\nchallenge, so there's nothing that could have produced it. The reducer\nMUST reject/ignore it as a no-op, leaving the tool call in\n`auth-required`. The client must resolve the auth challenge\n(`chat/toolCallAuthResolved`) before completing successfully.",
      "properties": {
        "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": {
          "const": "chat/toolCallComplete"
        },
        "result": {
          "$ref": "#/$defs/ToolCallResult",
          "description": "Execution result"
        },
        "requiresResultConfirmation": {
          "type": "boolean",
          "description": "If true, the result requires client approval before finalizing"
        }
      },
      "required": [
        "turnId",
        "toolCallId",
        "type",
        "result"
      ]
    },
    "ChatToolCallResultConfirmedAction": {
      "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": {
        "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": {
          "const": "chat/toolCallResultConfirmed"
        },
        "approved": {
          "type": "boolean",
          "description": "Whether the result was approved"
        }
      },
      "required": [
        "turnId",
        "toolCallId",
        "type",
        "approved"
      ]
    },
    "ChatToolCallContentChangedAction": {
      "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 (whose tool call state carries a client\n`ToolCallContributor` with a `clientId`), the owning client dispatches this\naction to stream intermediate content while executing. The server SHOULD\nreject this action if the dispatching client does not match the contributor's\n`clientId`.",
      "properties": {
        "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": {
          "const": "chat/toolCallContentChanged"
        },
        "content": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ToolResultContent"
          },
          "description": "The current partial content for the running tool call"
        }
      },
      "required": [
        "turnId",
        "toolCallId",
        "type",
        "content"
      ]
    },
    "ChatToolCallAuthRequiredAction": {
      "type": "object",
      "description": "A running tool call is paused pending MCP authentication. Transitions the\ntool call from `running` to `auth-required`.\n\nThe server dispatches this when the MCP server backing the call responds\nwith a 401/403 challenge mid-execution (see\n{@link McpAuthRequirement.reason | `insufficientScope`}). The host SHOULD\npair this with `session/inputNeededSet` (kind `toolAuthentication`) so the\nblock is visible at the session-summary level, mirroring\n{@link McpServerAuthRequiredState}'s own `InputNeeded` guidance.\n\nOnly valid for tool calls contributed by an MCP server — the reducer is a\nno-op if the tool call's `contributor` is not\n{@link ToolCallContributorKind.MCP | MCP-kind}.",
      "properties": {
        "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": {
          "const": "chat/toolCallAuthRequired"
        },
        "auth": {
          "$ref": "#/$defs/McpAuthRequirement",
          "description": "The authentication challenge blocking this invocation."
        }
      },
      "required": [
        "turnId",
        "toolCallId",
        "type",
        "auth"
      ]
    },
    "ChatToolCallAuthResolvedAction": {
      "type": "object",
      "description": "The authentication challenge blocking a tool call has been resolved (the\nclient pushed a token via `authenticate` and the host validated it).\nTransitions the tool call from `auth-required` back to `running`,\npreserving the fields it had before pausing.\n\nThe host SHOULD remove the corresponding `session/inputNeededSet` entry\n(kind `toolAuthentication`) once this is dispatched.",
      "properties": {
        "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": {
          "const": "chat/toolCallAuthResolved"
        }
      },
      "required": [
        "turnId",
        "toolCallId",
        "type"
      ]
    },
    "ChatTurnCompleteAction": {
      "type": "object",
      "description": "Turn finished — the assistant is idle.",
      "properties": {
        "type": {
          "const": "chat/turnComplete"
        },
        "turnId": {
          "type": "string",
          "description": "Turn identifier"
        },
        "duration": {
          "type": "number",
          "description": "Elapsed turn duration in milliseconds, measured by the producer's own\nclock. Clients MUST NOT derive this by subtracting timestamps — cross-\nclient clocks may differ — and MUST treat it as opaque, producer-supplied\ndata."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this action.\n\nClients MAY look for well-known keys here to provide enhanced UI, and\nagent hosts MAY use it to carry per-event context that does not fit any\nother field — for example, attributing the event to a specific agent\n(such as a sub-agent acting within the turn). Mirrors the MCP `_meta`\nconvention."
        }
      },
      "required": [
        "type",
        "turnId",
        "duration"
      ]
    },
    "ChatTurnCancelledAction": {
      "type": "object",
      "description": "Turn was aborted; server stops processing.",
      "properties": {
        "type": {
          "const": "chat/turnCancelled"
        },
        "turnId": {
          "type": "string",
          "description": "Turn identifier"
        },
        "duration": {
          "type": "number",
          "description": "Elapsed turn duration in milliseconds, measured by the producer's own\nclock. Clients MUST NOT derive this by subtracting timestamps — cross-\nclient clocks may differ — and MUST treat it as opaque, producer-supplied\ndata."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this action.\n\nClients MAY look for well-known keys here to provide enhanced UI, and\nagent hosts MAY use it to carry per-event context that does not fit any\nother field — for example, attributing the event to a specific agent\n(such as a sub-agent acting within the turn). Mirrors the MCP `_meta`\nconvention."
        }
      },
      "required": [
        "type",
        "turnId",
        "duration"
      ]
    },
    "ChatErrorAction": {
      "type": "object",
      "description": "Error during turn processing.",
      "properties": {
        "type": {
          "const": "chat/error"
        },
        "turnId": {
          "type": "string",
          "description": "Turn identifier"
        },
        "duration": {
          "type": "number",
          "description": "Elapsed turn duration in milliseconds, measured by the producer's own\nclock. Clients MUST NOT derive this by subtracting timestamps — cross-\nclient clocks may differ — and MUST treat it as opaque, producer-supplied\ndata."
        },
        "part": {
          "$ref": "#/$defs/ErrorResponsePart",
          "description": "Error part to append to the response stream before finalizing the turn.\nIts optional `resumable` flag indicates whether the turn can be resumed."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this action.\n\nClients MAY look for well-known keys here to provide enhanced UI, and\nagent hosts MAY use it to carry per-event context that does not fit any\nother field — for example, attributing the event to a specific agent\n(such as a sub-agent acting within the turn). Mirrors the MCP `_meta`\nconvention."
        }
      },
      "required": [
        "type",
        "turnId",
        "duration",
        "part"
      ]
    },
    "ChatTurnResumeAction": {
      "type": "object",
      "description": "Resumes the latest errored turn without adding another message.\n\nThe turn MUST be the latest turn, its state MUST be `error`, and its final\nresponse part MUST be a resumable error. The reducer reopens the same turn\nwith its existing message, response parts, and usage intact. The host then\nresumes the provider's execution for that turn.",
      "properties": {
        "type": {
          "const": "chat/turnResume"
        },
        "turnId": {
          "type": "string",
          "description": "Identifier of the errored turn."
        }
      },
      "required": [
        "type",
        "turnId"
      ]
    },
    "ChatActivityChangedAction": {
      "type": "object",
      "description": "The activity description of this chat changed.\n\nDispatched by the server to indicate what the chat is currently doing\n(e.g. running a tool, thinking). Clear activity by omitting it or setting it\nto `undefined`.\nProducers SHOULD also update the parent session's chat catalog with\n`session/chatUpdated` so `ChatSummary.activity` stays in sync.",
      "properties": {
        "type": {
          "const": "chat/activityChanged"
        },
        "activity": {
          "type": "string",
          "description": "Human-readable description of current activity; omit or set `undefined` to clear"
        }
      },
      "required": [
        "type"
      ]
    },
    "ChatWorkingDirectorySetAction": {
      "type": "object",
      "description": "A working directory was added to this chat's\n{@link ChatState.workingDirectories} subset.\n\nMembership semantics keyed by the directory URI: the reducer appends\n`directory` when the chat's subset does not already contain it (creating the\nsubset if absent) and is a no-op when it is already present. `directory` MUST\nbe one of the owning session's {@link SessionState.workingDirectories}; a host\nMUST reject a directory that is not. Only valid when the agent advertises\n{@link AgentCapabilities.multipleWorkingDirectories}.",
      "properties": {
        "type": {
          "const": "chat/workingDirectorySet"
        },
        "directory": {
          "$ref": "#/$defs/URI",
          "description": "The working directory to add to this chat's subset."
        }
      },
      "required": [
        "type",
        "directory"
      ]
    },
    "ChatWorkingDirectoryRemovedAction": {
      "type": "object",
      "description": "A working directory was removed from this chat's\n{@link ChatState.workingDirectories} subset.\n\nRemoves `directory` from the chat's subset; a no-op when it is not present.\nIdempotent, mirroring `session/workingDirectoryRemoved`. Only affects the\nchat's subset — the directory remains in the session's set.",
      "properties": {
        "type": {
          "const": "chat/workingDirectoryRemoved"
        },
        "directory": {
          "$ref": "#/$defs/URI",
          "description": "The working directory to remove from this chat's subset."
        }
      },
      "required": [
        "type",
        "directory"
      ]
    },
    "ChatUsageAction": {
      "type": "object",
      "description": "Token usage report for a turn.",
      "properties": {
        "type": {
          "const": "chat/usage"
        },
        "turnId": {
          "type": "string",
          "description": "Turn identifier"
        },
        "usage": {
          "$ref": "#/$defs/UsageInfo",
          "description": "Token usage data"
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this action.\n\nClients MAY look for well-known keys here to provide enhanced UI, and\nagent hosts MAY use it to carry per-event context that does not fit any\nother field — for example, attributing the event to a specific agent\n(such as a sub-agent acting within the turn). Mirrors the MCP `_meta`\nconvention."
        }
      },
      "required": [
        "type",
        "turnId",
        "usage"
      ]
    },
    "ChatReasoningAction": {
      "type": "object",
      "description": "Reasoning/thinking text from the model, appended to a specific reasoning response part.\n\nThe server MUST first emit a `chat/responsePart` to create the target\nreasoning part, then use this action to append text to it.",
      "properties": {
        "type": {
          "const": "chat/reasoning"
        },
        "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"
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this action.\n\nClients MAY look for well-known keys here to provide enhanced UI, and\nagent hosts MAY use it to carry per-event context that does not fit any\nother field — for example, attributing the event to a specific agent\n(such as a sub-agent acting within the turn). Mirrors the MCP `_meta`\nconvention."
        }
      },
      "required": [
        "type",
        "turnId",
        "partId",
        "content"
      ]
    },
    "ChatTruncatedAction": {
      "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 chat status\nreturns to `idle`.\n\nCommon use-case: truncate old data then dispatch a new\n`chat/turnStarted` with an edited message.",
      "properties": {
        "type": {
          "const": "chat/truncated"
        },
        "turnId": {
          "type": "string",
          "description": "Keep turns up to and including this turn. Omit to clear all turns."
        }
      },
      "required": [
        "type"
      ]
    },
    "ChatTurnsLoadedAction": {
      "type": "object",
      "description": "Loads older completed turns into this chat's state.\n\nHosts dispatch this before responding to `fetchTurns`, and before applying\nany operation that references a turn older than the currently loaded window.\n`turns` is ordered oldest-first and is prepended to the current `turns`\nwindow. `turnsNextCursor` replaces the state's cursor; omit it when all\nretained turns are now loaded.",
      "properties": {
        "type": {
          "const": "chat/turnsLoaded"
        },
        "turns": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Turn"
          },
          "description": "Older completed turns loaded into the state, ordered oldest-first."
        },
        "turnsNextCursor": {
          "type": "string",
          "description": "Opaque cursor for loading the next older page, if one remains."
        }
      },
      "required": [
        "type",
        "turns"
      ]
    },
    "ChatPendingMessageSetAction": {
      "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 chat is\nidle when a queued message is set, the server SHOULD immediately consume it\nand start a new turn.\n\nA client is only allowed to send {@link MessageKind.User} messages.",
      "properties": {
        "type": {
          "const": "chat/pendingMessageSet"
        },
        "kind": {
          "$ref": "#/$defs/PendingMessageKind",
          "description": "Whether this is a steering or queued message"
        },
        "id": {
          "type": "string",
          "description": "Unique identifier for this pending message"
        },
        "message": {
          "$ref": "#/$defs/Message",
          "description": "The message content"
        }
      },
      "required": [
        "type",
        "kind",
        "id",
        "message"
      ]
    },
    "ChatPendingMessageRemovedAction": {
      "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": {
          "const": "chat/pendingMessageRemoved"
        },
        "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",
        "kind",
        "id"
      ]
    },
    "ChatQueuedMessagesReorderedAction": {
      "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": {
          "const": "chat/queuedMessagesReordered"
        },
        "order": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Queued message IDs in the desired order"
        }
      },
      "required": [
        "type",
        "order"
      ]
    },
    "ChatDraftChangedAction": {
      "type": "object",
      "description": "The chat's draft input changed.\n\nClients MAY periodically sync their local input state — the message the user\nis composing, including its {@link Message.model | model} /\n{@link Message.agent | agent} selection and attachments — into the chat's\n{@link ChatState.draft | `draft`} so it survives reloads and is visible to\nother clients viewing the same chat. Eager syncing is **not** required;\nclients SHOULD debounce and MAY sync only at convenient points. Set `draft`\nto `undefined` to clear it (e.g. once the message is sent).\n\nA client is only allowed to draft {@link MessageKind.User} messages.",
      "properties": {
        "type": {
          "const": "chat/draftChanged"
        },
        "draft": {
          "$ref": "#/$defs/Message",
          "description": "New draft message, or `undefined` to clear it"
        }
      },
      "required": [
        "type"
      ]
    },
    "ChatInputRequestedAction": {
      "type": "object",
      "description": "A session requested input from the user.\n\nCreates an unresolved {@link InputRequestResponsePart} in the active turn,\nor replaces the unresolved part with the same request `id`. Answer drafts\nare preserved unless `request.answers` is provided.",
      "properties": {
        "type": {
          "const": "chat/inputRequested"
        },
        "request": {
          "$ref": "#/$defs/ChatInputRequest",
          "description": "Input request to create or replace"
        }
      },
      "required": [
        "type",
        "request"
      ]
    },
    "ChatInputAnswerChangedAction": {
      "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": {
          "const": "chat/inputAnswerChanged"
        },
        "requestId": {
          "type": "string",
          "description": "Input request identifier"
        },
        "questionId": {
          "type": "string",
          "description": "Question identifier within the input request"
        },
        "answer": {
          "$ref": "#/$defs/ChatInputAnswer",
          "description": "Updated answer, or `undefined` to clear an answer draft"
        }
      },
      "required": [
        "type",
        "requestId",
        "questionId"
      ]
    },
    "ChatInputCompletedAction": {
      "type": "object",
      "description": "A client submitted an accept, decline, or cancel response to an input request.\n\nIf accepted, the server uses `answers` (when provided) plus the request's\nsynced answer state to resume the blocked operation. The reducer records the\nresponse and final answers on the existing {@link InputRequestResponsePart}.",
      "properties": {
        "type": {
          "const": "chat/inputCompleted"
        },
        "requestId": {
          "type": "string",
          "description": "Input request identifier"
        },
        "response": {
          "$ref": "#/$defs/ChatInputResponseKind",
          "description": "Completion outcome"
        },
        "answers": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/ChatInputAnswer"
          },
          "description": "Optional final answer replacement, keyed by question ID"
        }
      },
      "required": [
        "type",
        "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": {
          "const": "terminal/data"
        },
        "data": {
          "type": "string",
          "description": "Output data (may contain ANSI escape sequences)"
        }
      },
      "required": [
        "type",
        "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": {
          "const": "terminal/input"
        },
        "data": {
          "type": "string",
          "description": "Input data to send to the pty"
        }
      },
      "required": [
        "type",
        "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": {
          "const": "terminal/resized"
        },
        "cols": {
          "type": "number",
          "description": "Terminal width in columns"
        },
        "rows": {
          "type": "number",
          "description": "Terminal height in rows"
        }
      },
      "required": [
        "type",
        "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": {
          "const": "terminal/claimed"
        },
        "claim": {
          "$ref": "#/$defs/TerminalClaim",
          "description": "The new claim"
        }
      },
      "required": [
        "type",
        "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": {
          "const": "terminal/titleChanged"
        },
        "title": {
          "type": "string",
          "description": "New terminal title"
        }
      },
      "required": [
        "type",
        "title"
      ]
    },
    "TerminalCwdChangedAction": {
      "type": "object",
      "description": "Terminal working directory changed.",
      "properties": {
        "type": {
          "const": "terminal/cwdChanged"
        },
        "cwd": {
          "$ref": "#/$defs/URI",
          "description": "New working directory"
        }
      },
      "required": [
        "type",
        "cwd"
      ]
    },
    "TerminalExitedAction": {
      "type": "object",
      "description": "Terminal process exited.",
      "properties": {
        "type": {
          "const": "terminal/exited"
        },
        "exitCode": {
          "type": "number",
          "description": "Process exit code. `undefined` if the process was killed without an exit code."
        }
      },
      "required": [
        "type"
      ]
    },
    "TerminalClearedAction": {
      "type": "object",
      "description": "Terminal scrollback buffer cleared.",
      "properties": {
        "type": {
          "const": "terminal/cleared"
        }
      },
      "required": [
        "type"
      ]
    },
    "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": {
          "const": "terminal/commandDetectionAvailable"
        }
      },
      "required": [
        "type"
      ]
    },
    "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": {
          "const": "terminal/commandExecuted"
        },
        "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",
        "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": {
          "const": "terminal/commandFinished"
        },
        "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",
        "commandId"
      ]
    },
    "ChangesetStatusChangedAction": {
      "type": "object",
      "description": "The {@link ChangesetState.status} for this changeset transitioned (e.g.\n`computing → ready`). The error payload is set together with `status`\nwhenever it transitions to {@link ChangesetStatus.Error | Error}.",
      "properties": {
        "type": {
          "const": "changeset/statusChanged"
        },
        "status": {
          "$ref": "#/$defs/ChangesetStatus",
          "description": "New computation lifecycle status."
        },
        "error": {
          "$ref": "#/$defs/ErrorInfo",
          "description": "Cause when `status === ChangesetStatus.Error`; otherwise omitted."
        }
      },
      "required": [
        "type",
        "status"
      ]
    },
    "ChangesetFileSetAction": {
      "type": "object",
      "description": "Upsert a {@link ChangesetFile} in the changeset — adds a new entry, or\nreplaces an existing one identified by {@link ChangesetFile.id}.",
      "properties": {
        "type": {
          "const": "changeset/fileSet"
        },
        "file": {
          "$ref": "#/$defs/ChangesetFile",
          "description": "The new or replacement file entry."
        }
      },
      "required": [
        "type",
        "file"
      ]
    },
    "ChangesetFileRemovedAction": {
      "type": "object",
      "description": "Remove a {@link ChangesetFile} from the changeset by its id.\n\nTypically dispatched when a file is reverted, staged out, or otherwise\nno longer in scope (e.g. a renamed file is replaced by a new entry).",
      "properties": {
        "type": {
          "const": "changeset/fileRemoved"
        },
        "fileId": {
          "type": "string",
          "description": "The {@link ChangesetFile.id} of the file to remove."
        }
      },
      "required": [
        "type",
        "fileId"
      ]
    },
    "ChangesetFilesReviewChangedAction": {
      "type": "object",
      "description": "Set the {@link ChangesetFile.reviewed} flag for one or more files — the\nGitHub-style \"Viewed\" toggle, applied in a single batch.\n\nTargets files by their {@link ChangesetFile.id}. Ids in {@link files} that\ndo not match a file currently present in the changeset are ignored; if none\nmatch, the action is a no-op. Only the {@link ChangesetFile.reviewed} field\nof each matched file is affected; the files' {@link ChangesetFile.edit | edit}\nand {@link ChangesetFile._meta | _meta} are left untouched.\n\nOnly meaningful on a changeset that advertises\n{@link ChangesetCapabilities.review}. Unlike every other `changeset/*` action\nthis one is **client-dispatchable**: a reviewer toggles review state directly,\napplying it optimistically through the write-ahead reducer and letting the\nserver echo it back on the normal `action` envelope stream. The server MAY\nalso originate it (e.g. an agent marking its own output reviewed).\n\nThere is no protocol-level content version, so review is not reset\nautomatically when a file's contents change under a stable id. The server,\nwhich is the authority on what changed, resets review explicitly — either by\nre-emitting the file without `reviewed: true`, or by dispatching this action\nwith `reviewed: false`.",
      "properties": {
        "type": {
          "const": "changeset/filesReviewChanged"
        },
        "files": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The {@link ChangesetFile.id | ids} of the files whose review state changed."
        },
        "reviewed": {
          "type": "boolean",
          "description": "New review state applied to every listed file: `true` once reviewed, `false` to clear it."
        }
      },
      "required": [
        "type",
        "files",
        "reviewed"
      ]
    },
    "ChangesetContentChangedAction": {
      "type": "object",
      "description": "The changeset's full content changed. Full replacement semantics: `files`\nreplaces the previous file list, and `operations`, when present, replaces\nthe previous operation list.\n\nProducers SHOULD use this action for initial snapshots and bulk refreshes;\nuse {@link ChangesetFileSetAction}, {@link ChangesetFileRemovedAction}, and\n{@link ChangesetOperationsChangedAction} for incremental updates.",
      "properties": {
        "type": {
          "const": "changeset/contentChanged"
        },
        "files": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChangesetFile"
          },
          "description": "Full replacement file list."
        },
        "operations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChangesetOperation"
          },
          "description": "Full replacement operation list. Omit when operations are unchanged."
        }
      },
      "required": [
        "type",
        "files"
      ]
    },
    "ChangesetOperationsChangedAction": {
      "type": "object",
      "description": "The set of operations available on this changeset changed. Full\nreplacement semantics: `operations` replaces the previous list (or\nremoves it entirely when `operations` is `undefined`).",
      "properties": {
        "type": {
          "const": "changeset/operationsChanged"
        },
        "operations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChangesetOperation"
          },
          "description": "Updated operation list. Pass `undefined` to clear all operations."
        }
      },
      "required": [
        "type"
      ]
    },
    "ChangesetOperationStatusChangedAction": {
      "type": "object",
      "description": "The {@link ChangesetOperation.status} for a single operation transitioned\n(e.g. `idle → running → idle`, or `running → error`). The error payload\nis set together with `status` whenever it transitions to\n{@link ChangesetOperationStatus.Error | Error}, and cleared on any other\ntransition.\n\nTargets one operation by its {@link ChangesetOperation.id}. If no\noperation with that id is currently present in the changeset, the action\nis a no-op. Use {@link ChangesetOperationsChangedAction} to add, remove,\nor otherwise replace the operation list itself.",
      "properties": {
        "type": {
          "const": "changeset/operationStatusChanged"
        },
        "operationId": {
          "type": "string",
          "description": "The {@link ChangesetOperation.id} whose status changed."
        },
        "status": {
          "$ref": "#/$defs/ChangesetOperationStatus",
          "description": "New execution status."
        },
        "error": {
          "$ref": "#/$defs/ErrorInfo",
          "description": "Cause when `status === ChangesetOperationStatus.Error`; otherwise omitted."
        }
      },
      "required": [
        "type",
        "operationId",
        "status"
      ]
    },
    "ChangesetClearedAction": {
      "type": "object",
      "description": "Drop every file from the changeset.\n\nTwo cases use this:\n1. The underlying source moved (branch switched, fork point invalidated,\n   …) and the server is recomputing from scratch — subsequent\n   {@link ChangesetFileSetAction} entries will repopulate it.\n2. The owning session has ended and the URI is becoming\n   un-subscribable — the server will unsubscribe all clients shortly\n   after dispatching this action.\n\nClients SHOULD release any references on receipt and SHOULD NOT\ndistinguish the two cases from the action alone — instead, react to\nthe corresponding session-level lifecycle signal (e.g.\n`root/sessionRemoved`) for the \"going away\" case.",
      "properties": {
        "type": {
          "const": "changeset/cleared"
        }
      },
      "required": [
        "type"
      ]
    },
    "AnnotationsSetAction": {
      "type": "object",
      "description": "Upsert an {@link Annotation} in the annotations channel — adds a new\nannotation, or replaces an existing one identified by\n{@link Annotation.id}.\n\nDispatched by a client to create an annotation (together with its\nmandatory first entry) or to re-anchor / resolve an existing one; the\ndispatching client assigns the {@link Annotation.id} and the id of any\nnew entry. When replacing, the full annotation payload (including its\n{@link Annotation.entries | entries} list) is substituted; producers\nSHOULD prefer {@link AnnotationsEntrySetAction} for per-entry edits, and\n{@link AnnotationsUpdatedAction} to resolve / re-anchor an existing\nannotation, to keep wire updates small.",
      "properties": {
        "type": {
          "const": "annotations/set"
        },
        "annotation": {
          "$ref": "#/$defs/Annotation",
          "description": "The new or replacement annotation. MUST contain at least one entry."
        }
      },
      "required": [
        "type",
        "annotation"
      ]
    },
    "AnnotationsUpdatedAction": {
      "type": "object",
      "description": "Partially update an existing {@link Annotation}'s own properties — a narrow\nalternative to {@link AnnotationsSetAction} for the common case of resolving\n/ re-opening or re-anchoring an annotation without resending its\n{@link Annotation.entries | entries}.\n\nTargets one annotation by its {@link annotationId}. Only the fields present\non the action are written; omitted fields leave the corresponding\n{@link Annotation} property unchanged. The annotation's\n{@link Annotation.entries | entries}, {@link Annotation.id | id}, and\n{@link Annotation._meta | _meta} are never touched — dispatch\n{@link AnnotationsSetAction} to replace those, to clear {@link range}\n(re-anchor to the whole file), or {@link AnnotationsEntrySetAction} /\n{@link AnnotationsEntryRemovedAction} to edit individual entries.\n\nIf {@link annotationId} does not match any current annotation the action is\na no-op.",
      "properties": {
        "type": {
          "const": "annotations/updated"
        },
        "annotationId": {
          "type": "string",
          "description": "The {@link Annotation.id} of the annotation to update."
        },
        "origin": {
          "$ref": "#/$defs/AnnotationOrigin",
          "description": "Replaces the annotation's provenance. Omit to leave it unchanged."
        },
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "Re-anchors the annotation to this file. Omit to leave the current\n{@link Annotation.resource} unchanged."
        },
        "range": {
          "$ref": "#/$defs/TextRange",
          "description": "Narrows the annotation to this range within {@link resource}. Omit to\nleave the current {@link Annotation.range} unchanged; this action cannot\nclear an existing range — dispatch {@link AnnotationsSetAction} to\nre-anchor to the whole file."
        },
        "resolved": {
          "type": "boolean",
          "description": "Marks the annotation resolved (`true`) or re-opens it (`false`). Omit to\nleave the current {@link Annotation.resolved} state unchanged."
        }
      },
      "required": [
        "type",
        "annotationId"
      ]
    },
    "AnnotationsRemovedAction": {
      "type": "object",
      "description": "Remove an {@link Annotation} from the channel by its id.\n\nDispatched to delete an entire annotation and every entry it contains.\nBecause the protocol forbids empty annotations, a client that wants to\nremove the last remaining entry dispatches this action — collapsing the\nannotation — rather than {@link AnnotationsEntryRemovedAction}.",
      "properties": {
        "type": {
          "const": "annotations/removed"
        },
        "annotationId": {
          "type": "string",
          "description": "The {@link Annotation.id} of the annotation to remove."
        }
      },
      "required": [
        "type",
        "annotationId"
      ]
    },
    "AnnotationsEntrySetAction": {
      "type": "object",
      "description": "Upsert an {@link AnnotationEntry} within an existing annotation — adds a\nnew entry, or replaces one identified by {@link AnnotationEntry.id}. The\ndispatching client assigns the {@link AnnotationEntry.id} of a new entry.\nIf {@link annotationId} does not match any current annotation the action\nis a no-op.",
      "properties": {
        "type": {
          "const": "annotations/entrySet"
        },
        "annotationId": {
          "type": "string",
          "description": "The {@link Annotation.id} the entry belongs to."
        },
        "entry": {
          "$ref": "#/$defs/AnnotationEntry",
          "description": "The new or replacement entry."
        }
      },
      "required": [
        "type",
        "annotationId",
        "entry"
      ]
    },
    "AnnotationsEntryRemovedAction": {
      "type": "object",
      "description": "Remove a single {@link AnnotationEntry} from an annotation without\ncollapsing the annotation itself. Used when more than one entry remains —\nto remove the last entry a client dispatches {@link AnnotationsRemovedAction}\ninstead, since the protocol forbids empty annotations.\n\nIf either {@link annotationId} or {@link entryId} does not match the\ncurrent state the action is a no-op.",
      "properties": {
        "type": {
          "const": "annotations/entryRemoved"
        },
        "annotationId": {
          "type": "string",
          "description": "The {@link Annotation.id} the entry belongs to."
        },
        "entryId": {
          "type": "string",
          "description": "The {@link AnnotationEntry.id} to remove."
        }
      },
      "required": [
        "type",
        "annotationId",
        "entryId"
      ]
    },
    "ResourceWatchChangedAction": {
      "type": "object",
      "description": "A batch of resource changes observed by the watcher.\n\nWatch events are coalesced into batches by the server to keep the\naction stream tractable; an empty `changes.items` list MUST NOT be\ndispatched. The reducer does not retain change history — these\nactions exist purely to deliver events to subscribers, who consume\nthem directly off the action stream and apply their own logic.",
      "properties": {
        "type": {
          "const": "resourceWatch/changed"
        },
        "changes": {
          "type": "object",
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/ResourceChange"
              }
            }
          },
          "required": [
            "items"
          ],
          "description": "The set of changes in this batch, wrapped for forward compatibility."
        }
      },
      "required": [
        "type",
        "changes"
      ]
    },
    "AutomationDefinitionPatch": {
      "type": "object",
      "description": "Partial replacement of editable {@link AutomationDefinition} fields.\n\nOmitted fields are unchanged. Supplied arrays and objects replace their\ncorresponding values in full; they are not merged recursively.",
      "properties": {
        "title": {
          "type": "string",
          "description": "Replacement {@link AutomationDefinition.title}."
        },
        "message": {
          "$ref": "#/$defs/Message",
          "description": "Replacement {@link AutomationDefinition.message}."
        },
        "session": {
          "$ref": "#/$defs/AutomationSessionTemplate",
          "description": "Replacement {@link AutomationDefinition.session}. The host revalidates\naffected event triggers when their discovery context changes."
        },
        "enabled": {
          "type": "boolean",
          "description": "Replacement {@link AutomationDefinition.enabled}."
        },
        "triggers": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AutomationTrigger"
          },
          "description": "Complete replacement {@link AutomationDefinition.triggers}. The host\nvalidates event ids and normalizes event-trigger titles and descriptions."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Complete replacement {@link AutomationDefinition._meta}."
        }
      }
    },
    "AutomationCreateRequestedAction": {
      "type": "object",
      "description": "Ask the host to create a durable automation at a client-chosen resource.\n\nClients may dispatch this action only when the host advertises its `create`\nautomation capability. {@link AutomationCreateRequestedAction.resource |\n`resource`} MUST use the `ahp-automation:` scheme and MUST NOT already\nidentify an unrelated automation.\n\nThis side-effect request leaves optimistic catalogue state unchanged. The\nhost validates trigger ids and configuration, normalizes event-trigger\ntitles and descriptions, persists the definition, then publishes the\nauthoritative result with {@link AutomationSetAction | `automation/set`}.\nRejections leave the catalogue unchanged.",
      "properties": {
        "type": {
          "const": "automation/createRequested"
        },
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "Client-chosen `ahp-automation:` URI that becomes {@link AutomationEntry.resource}."
        },
        "definition": {
          "$ref": "#/$defs/AutomationDefinition",
          "description": "Complete initial {@link AutomationEntry.definition}."
        }
      },
      "required": [
        "type",
        "resource",
        "definition"
      ]
    },
    "AutomationUpdateRequestedAction": {
      "type": "object",
      "description": "Ask the host to update editable fields of an existing automation.\n\nClients may dispatch this action only while the target advertises\n{@link AutomationOperation.Update}. The host revalidates that operation and\nthe client's authorization.\n\nThis side-effect request leaves optimistic catalogue state unchanged. The\nhost applies accepted patches to its current authoritative definition in\naction order, revalidates and normalizes affected event triggers, then\npublishes the result with\n{@link AutomationSetAction | `automation/set`}. Omitted fields remain\nunchanged; when accepted actions replace the same field, the later action in\nserver order wins.",
      "properties": {
        "type": {
          "const": "automation/updateRequested"
        },
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "Target {@link AutomationEntry.resource}."
        },
        "changes": {
          "$ref": "#/$defs/AutomationDefinitionPatch",
          "description": "Editable {@link AutomationDefinition} fields to replace."
        }
      },
      "required": [
        "type",
        "resource",
        "changes"
      ]
    },
    "AutomationSetAction": {
      "type": "object",
      "description": "Add or replace one full automation state in\n{@link AutomationState.entries}.\n\nExisting entries are matched by {@link AutomationEntry.resource} and\nreplaced in place. A previously unseen resource is appended.",
      "properties": {
        "type": {
          "const": "automation/set"
        },
        "automation": {
          "$ref": "#/$defs/AutomationEntry",
          "description": "Full new or replacement automation state."
        }
      },
      "required": [
        "type",
        "automation"
      ]
    },
    "AutomationRemovedAction": {
      "type": "object",
      "description": "Remove one automation from {@link AutomationState.entries}.\n\nClients may dispatch this action only while the target advertises\n{@link AutomationOperation.Remove}. The host revalidates that operation\nbefore permanently deleting the automation. A rejected action leaves the\nauthoritative catalogue and durable definition unchanged.\n\nRemoving an unknown resource is a no-op.",
      "properties": {
        "type": {
          "const": "automation/removed"
        },
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "{@link AutomationEntry.resource} to remove."
        }
      },
      "required": [
        "type",
        "resource"
      ]
    },
    "AutomationRunLifecycleChangedAction": {
      "type": "object",
      "description": "Replace the run lifecycle.\n\nThe host dispatches this action for every lifecycle transition.",
      "properties": {
        "type": {
          "const": "automationRun/lifecycleChanged"
        },
        "lifecycle": {
          "$ref": "#/$defs/AutomationRunLifecycle",
          "description": "Complete replacement {@link AutomationRunState.lifecycle}."
        }
      },
      "required": [
        "type",
        "lifecycle"
      ]
    },
    "AutomationRunSessionSetAction": {
      "type": "object",
      "description": "Add a session to {@link AutomationRunState.sessions}.\n\nSession URIs are unique. Setting an existing URI is a no-op.",
      "properties": {
        "type": {
          "const": "automationRun/sessionSet"
        },
        "session": {
          "$ref": "#/$defs/URI",
          "description": "Session URI to append to {@link AutomationRunState.sessions} when not already linked."
        }
      },
      "required": [
        "type",
        "session"
      ]
    },
    "AutomationRunSessionRemovedAction": {
      "type": "object",
      "description": "Remove a linked session from the run.\n\nRemoving the current primary session also clears\n{@link AutomationRunState.primarySession}. An unknown URI is a no-op.",
      "properties": {
        "type": {
          "const": "automationRun/sessionRemoved"
        },
        "session": {
          "$ref": "#/$defs/URI",
          "description": "Entry in {@link AutomationRunState.sessions} to remove."
        }
      },
      "required": [
        "type",
        "session"
      ]
    },
    "AutomationRunPrimarySessionChangedAction": {
      "type": "object",
      "description": "Select or clear the session clients should open first for this run.",
      "properties": {
        "type": {
          "const": "automationRun/primarySessionChanged"
        },
        "primarySession": {
          "$ref": "#/$defs/URI",
          "description": "New {@link AutomationRunState.primarySession}, or omitted to clear the selection."
        }
      },
      "required": [
        "type"
      ]
    },
    "AutomationRunCancelRequestedAction": {
      "type": "object",
      "description": "Ask the host to cancel this run.\n\nThis is the only client-dispatchable automation-run action. It is a\nside-effect request and deliberately leaves optimistic state unchanged. The\nclient may dispatch it only when the host advertises its `runCancellation`\ncapability and the current lifecycle is `pending` or `running`. The host\nrevalidates that the run is non-terminal. The authoritative outcome arrives\nlater through\n{@link AutomationRunLifecycleChangedAction}: cancellation may transition to\n`cancelled`, or the run may complete or fail before cancellation takes\neffect.",
      "properties": {
        "type": {
          "const": "automationRun/cancelRequested"
        }
      },
      "required": [
        "type"
      ]
    },
    "ChatToolCallConfirmedAction": {
      "oneOf": [
        {
          "$ref": "#/$defs/ChatToolCallApprovedAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallDeniedAction"
        }
      ],
      "description": "Client confirms or denies a pending tool call."
    },
    "ChatAction": {
      "oneOf": [
        {
          "$ref": "#/$defs/ChatTurnStartedAction"
        },
        {
          "$ref": "#/$defs/ChatDeltaAction"
        },
        {
          "$ref": "#/$defs/ChatResponsePartAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallStartAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallDeltaAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallReadyAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallConfirmedAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallCompleteAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallResultConfirmedAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallContentChangedAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallAuthRequiredAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallAuthResolvedAction"
        },
        {
          "$ref": "#/$defs/ChatTurnCompleteAction"
        },
        {
          "$ref": "#/$defs/ChatTurnCancelledAction"
        },
        {
          "$ref": "#/$defs/ChatErrorAction"
        },
        {
          "$ref": "#/$defs/ChatTurnResumeAction"
        },
        {
          "$ref": "#/$defs/ChatActivityChangedAction"
        },
        {
          "$ref": "#/$defs/ChatWorkingDirectorySetAction"
        },
        {
          "$ref": "#/$defs/ChatWorkingDirectoryRemovedAction"
        },
        {
          "$ref": "#/$defs/ChatUsageAction"
        },
        {
          "$ref": "#/$defs/ChatReasoningAction"
        },
        {
          "$ref": "#/$defs/ChatTruncatedAction"
        },
        {
          "$ref": "#/$defs/ChatTurnsLoadedAction"
        },
        {
          "$ref": "#/$defs/ChatPendingMessageSetAction"
        },
        {
          "$ref": "#/$defs/ChatPendingMessageRemovedAction"
        },
        {
          "$ref": "#/$defs/ChatQueuedMessagesReorderedAction"
        },
        {
          "$ref": "#/$defs/ChatDraftChangedAction"
        },
        {
          "$ref": "#/$defs/ChatInputRequestedAction"
        },
        {
          "$ref": "#/$defs/ChatInputAnswerChangedAction"
        },
        {
          "$ref": "#/$defs/ChatInputCompletedAction"
        }
      ]
    },
    "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_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"
      ]
    },
    "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": {
            "$ref": "#/$defs/JsonPrimitive"
          },
          "description": "JSON Schema: allowed values. May be primitives of any JSON 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'`)"
        },
        "additionalProperties": {
          "$ref": "#/$defs/ConfigPropertySchema",
          "description": "JSON Schema: schema for additional properties not listed in `properties` (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"
      ]
    },
    "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"
      ]
    },
    "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"
        },
        "nonce": {
          "type": "string",
          "description": "Content nonce"
        }
      },
      "required": [
        "uri"
      ]
    },
    "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": {
              "$ref": "#/$defs/URI"
            },
            "content": {
              "$ref": "#/$defs/ContentRef"
            }
          },
          "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": {
              "$ref": "#/$defs/URI"
            },
            "content": {
              "$ref": "#/$defs/ContentRef"
            }
          },
          "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"
        }
      }
    },
    "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"
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this error.\nClients MAY look for well-known optional keys here to provide enhanced UI\n(e.g. a structured chat fetch error for richer, localized messaging)."
        }
      },
      "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 channel URI (e.g. `ahp-root://`, `ahp-session:/<uuid>`, or `ahp-chat:/<uuid>`)"
        },
        "state": {
          "oneOf": [
            {
              "$ref": "#/$defs/RootState"
            },
            {
              "$ref": "#/$defs/SessionState"
            },
            {
              "$ref": "#/$defs/TerminalState"
            },
            {
              "$ref": "#/$defs/ChangesetState"
            },
            {
              "$ref": "#/$defs/ResourceWatchState"
            },
            {
              "$ref": "#/$defs/AnnotationsState"
            },
            {
              "$ref": "#/$defs/ChatState"
            },
            {
              "$ref": "#/$defs/AutomationState"
            },
            {
              "$ref": "#/$defs/AutomationRunState"
            }
          ],
          "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"
      ]
    },
    "RootState": {
      "type": "object",
      "description": "Global state shared with every client subscribed to `ahp-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"
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional implementation-defined metadata about the agent host itself.\n\nClients MAY look for well-known keys here to provide enhanced UI."
        }
      },
      "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/Customization"
          },
          "description": "Customizations associated with this agent.\n\nEither container customizations —\n{@link PluginCustomization | `PluginCustomization`} entries the agent\nbundles, plus {@link DirectoryCustomization | `DirectoryCustomization`}\nentries it watches in any workspace it's used with — or top-level\n{@link McpServerCustomization | `McpServerCustomization`} entries\nthe agent host declares directly. When a session is created with\nthis agent, these entries are augmented (e.g. directory URIs are\nresolved against the workspace, children are parsed) and propagated\ninto the session's `customizations` list."
        },
        "capabilities": {
          "$ref": "#/$defs/AgentCapabilities",
          "description": "Static capabilities the agent advertises about itself. Clients use these\nto gate features (multi-chat, fork) instead of switching on the provider\nid."
        }
      },
      "required": [
        "provider",
        "displayName",
        "description",
        "models"
      ]
    },
    "AgentCapabilities": {
      "type": "object",
      "description": "Static capabilities an {@link AgentInfo} advertises. Modelled after MCP\ncapabilities: each field is opt-in and its presence (an empty object `{}`)\nsignals support, while absence means the feature is unsupported and the\ncorresponding client commands MUST NOT be used. Sub-fields carry\nper-capability options.",
      "properties": {
        "multipleChats": {
          "$ref": "#/$defs/MultipleChatsCapability",
          "description": "The agent can host more than one concurrent chat per session. When absent,\nclients MUST NOT call `createChat` to open chats beyond the default one the\nsession starts with. An empty object `{}` advertises multi-chat without\nsource-based creation; set {@link MultipleChatsCapability.fork} or\n{@link MultipleChatsCapability.sideChat} to allow the corresponding mode."
        },
        "multipleWorkingDirectories": {
          "$ref": "#/$defs/MultipleWorkingDirectoriesCapability",
          "description": "The session's agent can be granted tool access to more than one working\ndirectory. The directories are treated as equal peers except where the\nagent advertises a protected primary-slot option (some backends pin or\nreplace their first directory as a process root).\n\nWhen absent, clients MUST NOT mutate a session's or chat's working-directory\nset and MUST NOT set more than one entry in\n{@link CreateSessionParams.workingDirectories}."
        }
      }
    },
    "MultipleChatsCapability": {
      "type": "object",
      "description": "Options for the {@link AgentCapabilities.multipleChats} capability.",
      "properties": {
        "fork": {
          "type": "boolean",
          "description": "The agent can fork a chat from a specific turn. When absent or `false`,\nclients MUST NOT pass a {@link ChatSource} with `kind: \"fork\"` to\n`createChat`.\nForking always implies multi-chat support."
        },
        "sideChat": {
          "type": "boolean",
          "description": "The agent can create a side chat from a specific turn. When absent or\n`false`, clients MUST NOT pass a {@link ChatSource} with\n`kind: \"sideChat\"` to `createChat`.\n\nA side chat receives the source turn as context without copying the source\ntranscript into its own visible history. The source is identified by a\nstable `turnId`, which the host resolves against the source chat's current\n`activeTurn` or retained history. When it names the current active turn,\nthe host snapshots the available partial assistant response at creation\ntime. Side-chat support always implies multi-chat support."
        }
      }
    },
    "MultipleWorkingDirectoriesCapability": {
      "type": "object",
      "description": "Options for the {@link AgentCapabilities.multipleWorkingDirectories} capability.",
      "properties": {
        "immutablePrimary": {
          "type": "boolean",
          "description": "The agent's **first** working directory (index `0` of\n{@link CreateSessionParams.workingDirectories}) is an immutable primary:\nits URI is fixed for the lifetime of the session — clients MUST NOT remove,\nreorder, or replace it. Additional directories after it remain equal peers\nthat can be added and removed freely. When\n{@link primaryReplacement} is also `true`, clients that recognize that\ncapability MUST instead treat the primary as protected and replaceable.\n\nAdvertised by backends whose agent process is rooted at a single directory\nthat cannot change once the session has started. A backend MAY also\nadvertise this with {@link primaryReplacement} for compatibility with\nclients that do not recognize the newer capability: those clients retain\nthe safe immutable-primary behavior, while newer clients allow only the\ntargeted replacement action. When both are absent or `false`, all\ndirectories are equal peers."
        },
        "primaryReplacement": {
          "type": "boolean",
          "description": "The agent's first working-directory slot (index `0`) is a protected primary\nwhose URI can be atomically replaced with\n`session/workingDirectoryReplaced`. Clients MUST NOT remove that slot with\ngeneric membership actions; additional directories remain equal peers.\n\nBackends use this when their cwd-bearing directory can move during a\nsession. It MAY be `true` together with {@link immutablePrimary}; this\npreserves the immutable-primary guarantee for older clients that do not\nrecognize this capability. Clients that recognize this capability MUST\nallow a targeted replacement even when `immutablePrimary` is also `true`."
        }
      }
    },
    "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"
        },
        "maxOutputTokens": {
          "type": "number",
          "description": "Maximum number of output tokens the model can generate"
        },
        "maxPromptTokens": {
          "type": "number",
          "description": "Maximum number of prompt (input) tokens the model accepts"
        },
        "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": {
            "$ref": "#/$defs/JsonPrimitive"
          },
          "description": "Model-specific configuration values. Values are JSON primitives: most\npickers produce strings, but some (e.g. a numeric context-size picker)\nproduce numbers or booleans, which are carried through as-is."
        }
      },
      "required": [
        "id"
      ]
    },
    "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"
      ]
    },
    "AutomationSessionOrigin": {
      "type": "object",
      "description": "Provenance recorded on a session created for an automation run.\n\nThe links let clients navigate from an ordinary session to the task-level\nrun and its durable definition. The session channel remains authoritative\nfor this session's transcript, tools, confirmations, and changes.",
      "properties": {
        "kind": {
          "const": "automation"
        },
        "automation": {
          "$ref": "#/$defs/URI",
          "description": "Owning {@link AutomationEntry.resource}."
        },
        "run": {
          "$ref": "#/$defs/URI",
          "description": "Owning {@link AutomationRunState.resource}."
        }
      },
      "required": [
        "kind",
        "automation",
        "run"
      ]
    },
    "SessionMetadata": {
      "type": "object",
      "description": "Metadata shared between the full {@link SessionState} (delivered when a\nclient subscribes to a session's URI) and the lightweight\n{@link SessionSummary} (carried in the root-channel session catalog).\n\nThese fields describe the session at a glance and appear in both places.\n`SessionState` owns the authoritative values for a subscribed session;\n`SessionSummary` mirrors them into the catalog so clients that only render a\nsession list don't have to subscribe to every session URI. The host keeps\nthe catalog in sync via `root/sessionSummaryChanged`.",
      "properties": {
        "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"
        },
        "origin": {
          "$ref": "#/$defs/SessionOrigin",
          "description": "Durable {@link AutomationSessionOrigin}, when an automation run created this session."
        },
        "project": {
          "$ref": "#/$defs/ProjectInfo",
          "description": "Server-owned project for this session"
        },
        "workingDirectories": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/URI"
          },
          "description": "The working directories the session's agent has tool access to, as\nmaintained by working-directory actions. Directories are equal peers except\nwhen the agent advertises\n{@link MultipleWorkingDirectoriesCapability.immutablePrimary} without\n{@link MultipleWorkingDirectoriesCapability.primaryReplacement} (the first\nentry is then a fixed process root), or advertises `primaryReplacement`\n(the first entry is a protected, replaceable primary slot). Individual chats\nMAY restrict to a subset via\n{@link ChatSummary.workingDirectories | their own `workingDirectories`}; a\nchat that sets none operates against this full set."
        },
        "annotations": {
          "$ref": "#/$defs/AnnotationsSummary",
          "description": "Lightweight summary of this session's inline annotations channel\n(`ahp-session:/<uuid>/annotations`). Surfaced so badge UI can render\nannotation / entry counts without subscribing. Absent when the session\ndoes not expose an annotations channel."
        }
      },
      "required": [
        "provider",
        "title",
        "status"
      ]
    },
    "SessionState": {
      "type": "object",
      "description": "Full state for a single session, loaded when a client subscribes to the session's URI.\n\nInlines (denormalizes) every {@link SessionMetadata} field directly onto\nitself so subscribers receive one flat object instead of a nested summary.\nThe lightweight catalog representation is {@link SessionSummary}, surfaced on\nthe root channel; the host keeps the two in sync via\n`root/sessionSummaryChanged`.",
      "properties": {
        "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"
        },
        "origin": {
          "$ref": "#/$defs/SessionOrigin",
          "description": "Durable {@link AutomationSessionOrigin}, when an automation run created this session."
        },
        "project": {
          "$ref": "#/$defs/ProjectInfo",
          "description": "Server-owned project for this session"
        },
        "workingDirectories": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/URI"
          },
          "description": "The working directories the session's agent has tool access to, as\nmaintained by working-directory actions. Directories are equal peers except\nwhen the agent advertises\n{@link MultipleWorkingDirectoriesCapability.immutablePrimary} without\n{@link MultipleWorkingDirectoriesCapability.primaryReplacement} (the first\nentry is then a fixed process root), or advertises `primaryReplacement`\n(the first entry is a protected, replaceable primary slot). Individual chats\nMAY restrict to a subset via\n{@link ChatSummary.workingDirectories | their own `workingDirectories`}; a\nchat that sets none operates against this full set."
        },
        "annotations": {
          "$ref": "#/$defs/AnnotationsSummary",
          "description": "Lightweight summary of this session's inline annotations channel\n(`ahp-session:/<uuid>/annotations`). Surfaced so badge UI can render\nannotation / entry counts without subscribing. Absent when the session\ndoes not expose an annotations channel."
        },
        "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"
        },
        "activeClients": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SessionActiveClient"
          },
          "description": "The clients currently providing tools and interactive capabilities to this\nsession. If multiple tools or customizations are provided by the same\nactive client, an agent host MAY deduplicate them when exposed to a model,\nwith a preference given to the client that started the turn.\n\nMembership is host-managed: clients add (or refresh) themselves with\n`session/activeClientSet`, and the host removes them with\n`session/activeClientRemoved` when they unsubscribe, disconnect without\nreconnecting in time, or reconnect without resubscribing to the session."
        },
        "chats": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChatSummary"
          },
          "description": "Catalog of chats in this session."
        },
        "defaultChat": {
          "$ref": "#/$defs/URI",
          "description": "The chat that receives input when the user addresses the session without\nselecting a specific chat. This is a UI routing hint, not a hierarchy\nmarker — chats remain equal peers at the protocol level. Hosts MAY change\nthis over the session's lifetime."
        },
        "config": {
          "$ref": "#/$defs/SessionConfigState",
          "description": "Session configuration schema and current values"
        },
        "customizations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Customization"
          },
          "description": "Top-level customizations active in this session.\n\nAlways one of the {@link Customization} variants:\n\n- Container customizations ({@link PluginCustomization},\n  {@link DirectoryCustomization}) whose children — agents, skills,\n  prompts, rules, hooks, MCP servers — live in each container's\n  {@link ContainerCustomizationBase.children | `children`} array.\n- Top-level {@link McpServerCustomization} entries the host\n  surfaces directly (for example a globally-configured MCP server\n  that isn't bundled in a plugin or directory). MCP servers may\n  also appear as children of a container.\n\nClient-published plugins arrive via\n{@link SessionActiveClient.customizations | `activeClients[].customizations`}\nand the host propagates them into this list (typically with the\ncontainer's `clientId` set and `children` populated). Clients\npublish in container shape only; bare MCP servers at the top level\nare server-originated."
        },
        "changesets": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Changeset"
          },
          "description": "Catalogue of changesets the server can produce for this session. Each\nentry advertises a subscribable view of file changes (uncommitted,\nsession-wide, per-turn, etc.) and the URI template the client expands\nbefore subscribing. See {@link Changeset} for the full shape and\n{@link /guide/changesets | Changesets} for an overview of the model."
        },
        "inputNeeded": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SessionInputRequest"
          },
          "description": "Outstanding input the session is blocked on, aggregated across every chat\nso a client can discover and answer it from the session channel alone,\nwithout subscribing to individual chats.\n\nEach entry is self-sufficient: it carries the owning chat's URI plus every\nidentifier the client needs to respond. A client answers by dispatching the\nordinary `chat/*` action to that chat's channel — see\n{@link SessionInputRequest} for the per-variant response path. A list\nholding any entry other than\n{@link SessionInputRequestKind.ToolClientExecution} implies\n{@link SessionStatus.InputNeeded} on {@link SessionSummary.status};\nclient-execution entries are work delegated to a client rather than a\nprompt, so they leave the session's activity unchanged.\n\nHost-managed: the host upserts entries with `session/inputNeededSet` as\nchats raise requests and removes them with `session/inputNeededRemoved`\nonce the underlying request resolves."
        },
        "_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\nworking directories."
        }
      },
      "required": [
        "provider",
        "title",
        "status",
        "lifecycle",
        "activeClients",
        "chats"
      ]
    },
    "SessionActiveClient": {
      "type": "object",
      "description": "A client currently providing tools and interactive capabilities to a session.\n\nA session MAY have several active clients at once; entries in\n{@link SessionState.activeClients} are keyed by `clientId`. The server SHOULD\nautomatically remove an active client when 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/ClientPluginCustomization"
          },
          "description": "Plugin customizations this client contributes to the session.\n\nClients publish in [Open Plugins](https://open-plugins.com/) format\n— i.e. always container-shaped plugins. They MAY synthesize virtual\nplugins in memory and rely on the host to expand them into concrete\nchildren inside {@link SessionState.customizations}."
        }
      },
      "required": [
        "clientId",
        "tools"
      ]
    },
    "SessionInputRequestBase": {
      "type": "object",
      "description": "Fields common to every {@link SessionInputRequest} variant.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable key for this entry, unique within the session's\n{@link SessionState.inputNeeded} list. The host derives it however it likes\n(for example from the chat URI plus the underlying request or tool-call\nid); consumers MUST treat it as opaque. It is the key for the\n`session/inputNeededSet` / `session/inputNeededRemoved` upsert convention."
        },
        "chat": {
          "$ref": "#/$defs/URI",
          "description": "The chat the underlying request lives in. This is the channel a client\ndispatches its response to — it does not need to have subscribed to that\nchat first."
        }
      },
      "required": [
        "id",
        "chat"
      ]
    },
    "SessionChatInputRequest": {
      "type": "object",
      "description": "A user-input elicitation surfaced at the session level, mirroring the request\nfrom an unresolved {@link InputRequestResponsePart} in the owning chat.\n\nRespond by dispatching `chat/inputCompleted` (or syncing drafts with\n`chat/inputAnswerChanged`) to {@link SessionInputRequestBase.chat | `chat`},\nkeyed by {@link ChatInputRequest.id | `request.id`}.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable key for this entry, unique within the session's\n{@link SessionState.inputNeeded} list. The host derives it however it likes\n(for example from the chat URI plus the underlying request or tool-call\nid); consumers MUST treat it as opaque. It is the key for the\n`session/inputNeededSet` / `session/inputNeededRemoved` upsert convention."
        },
        "chat": {
          "$ref": "#/$defs/URI",
          "description": "The chat the underlying request lives in. This is the channel a client\ndispatches its response to — it does not need to have subscribed to that\nchat first."
        },
        "kind": {
          "const": "chatInput"
        },
        "request": {
          "$ref": "#/$defs/ChatInputRequest",
          "description": "The mirrored chat input request."
        }
      },
      "required": [
        "id",
        "chat",
        "kind",
        "request"
      ]
    },
    "SessionToolConfirmationRequest": {
      "type": "object",
      "description": "A tool call blocked on confirmation — either parameter confirmation before\nexecution or result confirmation after — surfaced at the session level.\n\nRespond by dispatching `chat/toolCallConfirmed` (for\n{@link ToolCallPendingConfirmationState}) or `chat/toolCallResultConfirmed`\n(for {@link ToolCallPendingResultConfirmationState}) to\n{@link SessionInputRequestBase.chat | `chat`}, keyed by `turnId` and\n`toolCall.toolCallId`.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable key for this entry, unique within the session's\n{@link SessionState.inputNeeded} list. The host derives it however it likes\n(for example from the chat URI plus the underlying request or tool-call\nid); consumers MUST treat it as opaque. It is the key for the\n`session/inputNeededSet` / `session/inputNeededRemoved` upsert convention."
        },
        "chat": {
          "$ref": "#/$defs/URI",
          "description": "The chat the underlying request lives in. This is the channel a client\ndispatches its response to — it does not need to have subscribed to that\nchat first."
        },
        "kind": {
          "const": "toolConfirmation"
        },
        "turnId": {
          "type": "string",
          "description": "The turn the tool call belongs to."
        },
        "toolCall": {
          "$ref": "#/$defs/ToolCallConfirmationState",
          "description": "The tool call awaiting confirmation."
        }
      },
      "required": [
        "id",
        "chat",
        "kind",
        "turnId",
        "toolCall"
      ]
    },
    "SessionToolClientExecutionRequest": {
      "type": "object",
      "description": "A running tool whose execution is delegated to an active client. Surfaced so\na client that provides the tool can pick up the work without subscribing to\nthe owning chat.\n\nThe {@link toolCall} is always a {@link ToolCallRunningState} (a\n{@link ToolCallState} in `running` status) whose\n{@link ToolCallRunningState.contributor | `contributor`} is a client\n{@link ToolCallClientContributor} whose `clientId` matches the denormalized\n{@link clientId} here. Execute and report the result by dispatching\n`chat/toolCallComplete` (and optionally streaming with\n`chat/toolCallContentChanged`) to {@link SessionInputRequestBase.chat |\n`chat`}, keyed by `turnId` and `toolCall.toolCallId`.\n\nUnlike the other variants this does **not** raise\n{@link SessionStatus.InputNeeded}: the call has already cleared its\nconfirmation gate and is merely executing elsewhere, so the session stays\n{@link SessionStatus.InProgress} while it runs.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable key for this entry, unique within the session's\n{@link SessionState.inputNeeded} list. The host derives it however it likes\n(for example from the chat URI plus the underlying request or tool-call\nid); consumers MUST treat it as opaque. It is the key for the\n`session/inputNeededSet` / `session/inputNeededRemoved` upsert convention."
        },
        "chat": {
          "$ref": "#/$defs/URI",
          "description": "The chat the underlying request lives in. This is the channel a client\ndispatches its response to — it does not need to have subscribed to that\nchat first."
        },
        "kind": {
          "const": "toolClientExecution"
        },
        "turnId": {
          "type": "string",
          "description": "The turn the tool call belongs to."
        },
        "clientId": {
          "type": "string",
          "description": "The `clientId` expected to execute the tool. Matches the `clientId` of the\ntool call's client {@link ToolCallContributor}."
        },
        "toolCall": {
          "$ref": "#/$defs/ToolCallRunningState",
          "description": "The running tool call the session wants the owning client to execute. The\nhost only ever populates this with a {@link ToolCallRunningState}."
        }
      },
      "required": [
        "id",
        "chat",
        "kind",
        "turnId",
        "clientId",
        "toolCall"
      ]
    },
    "SessionToolAuthenticationRequest": {
      "type": "object",
      "description": "A tool call blocked on MCP authentication mid-execution, surfaced at the\nsession level.\n\nThe {@link toolCall} is always a {@link ToolCallAuthRequiredState} (a\n{@link ToolCallState} in `auth-required` status). Unlike\n{@link SessionToolConfirmationRequest}, this is **not** answered by\ndispatching a `chat/*` action directly: the client obtains a token for\n{@link ToolCallAuthRequiredState.auth | `toolCall.auth`}`.resource` and\npushes it via the existing `authenticate` command (see\n{@link /specification/authentication | Authentication}). The host resumes\nthe tool call and dispatches `chat/toolCallAuthResolved` once the token is\naccepted, at which point it also removes this entry with\n`session/inputNeededRemoved`.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable key for this entry, unique within the session's\n{@link SessionState.inputNeeded} list. The host derives it however it likes\n(for example from the chat URI plus the underlying request or tool-call\nid); consumers MUST treat it as opaque. It is the key for the\n`session/inputNeededSet` / `session/inputNeededRemoved` upsert convention."
        },
        "chat": {
          "$ref": "#/$defs/URI",
          "description": "The chat the underlying request lives in. This is the channel a client\ndispatches its response to — it does not need to have subscribed to that\nchat first."
        },
        "kind": {
          "const": "toolAuthentication"
        },
        "turnId": {
          "type": "string",
          "description": "The turn the tool call belongs to."
        },
        "toolCall": {
          "$ref": "#/$defs/ToolCallAuthRequiredState",
          "description": "The tool call awaiting authentication."
        }
      },
      "required": [
        "id",
        "chat",
        "kind",
        "turnId",
        "toolCall"
      ]
    },
    "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",
      "description": "Lightweight catalog entry summarizing one session. Surfaced via\n{@link RootChannelCommands.listSessions | `root/listSessions`} and\n`root/sessionAdded`/`root/sessionSummaryChanged` notifications.\n\n**Aggregation across chats.** Once a session contains more than one chat,\nseveral `SessionSummary` fields are derived from the underlying\n{@link SessionState.chats | chat catalog}. Producers SHOULD follow these\nrules so clients that only consume the session summary (e.g. a session\nlist) still see meaningful state:\n\n- `status`: take the activity bits (`Idle` / `InProgress` / `InputNeeded` /\n  `Error` — bits 0–4) from the\n  {@link SessionState.defaultChat | default chat} when present, else from\n  the most recently modified chat. **Promote** `InputNeeded` whenever any\n  chat in the session needs input, and **promote** `Error` whenever any\n  chat is in an error state — both override the default-chat bits. The\n  orthogonal flag bits (`IsRead`, `IsArchived`) remain session-scoped.\n- `activity`: mirror the activity string of the default chat, or of the\n  chat currently driving the promoted status bits when a non-default chat\n  wins (e.g. the chat that raised `InputNeeded`).\n- `modifiedAt`: the max of all chats' `modifiedAt`.\n- `workingDirectories`: the session-level set. Individual chats MAY restrict\n  to a subset via {@link ChatSummary.workingDirectories}; aggregating these\n  up is meaningless and SHOULD NOT be attempted.\n- `changes`: optional roll-up across all chats. Producers MAY sum the\n  per-chat changeset stats or report the most expensive chat's stats —\n  whichever is cheaper for the host to compute.\n\nSessions with a single chat trivially satisfy all of the above (the chat's\nvalues pass through unchanged). The rules only matter once a session\ncarries multiple chats.",
      "properties": {
        "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"
        },
        "origin": {
          "$ref": "#/$defs/SessionOrigin",
          "description": "Durable {@link AutomationSessionOrigin}, when an automation run created this session."
        },
        "project": {
          "$ref": "#/$defs/ProjectInfo",
          "description": "Server-owned project for this session"
        },
        "workingDirectories": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/URI"
          },
          "description": "The working directories the session's agent has tool access to, as\nmaintained by working-directory actions. Directories are equal peers except\nwhen the agent advertises\n{@link MultipleWorkingDirectoriesCapability.immutablePrimary} without\n{@link MultipleWorkingDirectoriesCapability.primaryReplacement} (the first\nentry is then a fixed process root), or advertises `primaryReplacement`\n(the first entry is a protected, replaceable primary slot). Individual chats\nMAY restrict to a subset via\n{@link ChatSummary.workingDirectories | their own `workingDirectories`}; a\nchat that sets none operates against this full set."
        },
        "annotations": {
          "$ref": "#/$defs/AnnotationsSummary",
          "description": "Lightweight summary of this session's inline annotations channel\n(`ahp-session:/<uuid>/annotations`). Surfaced so badge UI can render\nannotation / entry counts without subscribing. Absent when the session\ndoes not expose an annotations channel."
        },
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "Session URI"
        },
        "createdAt": {
          "type": "string",
          "description": "Creation timestamp (ISO 8601, e.g. `\"2025-03-10T18:42:03.123Z\"`)"
        },
        "modifiedAt": {
          "type": "string",
          "description": "Last modification timestamp (ISO 8601, e.g. `\"2025-03-10T18:42:03.123Z\"`)"
        },
        "changes": {
          "$ref": "#/$defs/ChangesSummary",
          "description": "Aggregate summary of file changes associated with this session. Servers\nmay populate this to give clients a quick at-a-glance view of the\nsession's footprint (e.g., for list rendering) without requiring the\nclient to subscribe to a changeset."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Lightweight server-defined metadata clients may use for the session\npresentation. The protocol does not interpret these values; producers\nSHOULD keep the payload small because summaries appear in session lists\nand session notifications."
        },
        "chats": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SessionChatSummary"
          },
          "description": "Lightweight ordered chat catalog for session-list presentation.\n\nThis intentionally omits volatile chat state such as status and activity,\nwhile retaining interactivity so generic clients can hide chats or present\nthem as read-only without subscribing to the session channel."
        },
        "defaultChat": {
          "$ref": "#/$defs/URI",
          "description": "Chat that receives input when no specific chat is selected."
        }
      },
      "required": [
        "provider",
        "title",
        "status",
        "resource",
        "createdAt",
        "modifiedAt"
      ]
    },
    "SessionChatSummary": {
      "type": "object",
      "description": "Lightweight chat information suitable for listing a session without\nsubscribing to its session channel.",
      "properties": {
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "Canonical chat URI"
        },
        "title": {
          "type": "string",
          "description": "Human-readable chat title"
        },
        "origin": {
          "$ref": "#/$defs/ChatOrigin",
          "description": "How this chat was created, when known"
        },
        "interactivity": {
          "$ref": "#/$defs/ChatInteractivity",
          "description": "How the user can interact with this chat.\n\nGeneric clients use this to omit hidden chats and disable input for\nread-only chats. Absence defaults to {@link ChatInteractivity.Full} for\nbackward compatibility."
        }
      },
      "required": [
        "resource",
        "title"
      ]
    },
    "ChangesSummary": {
      "type": "object",
      "description": "Aggregate counts describing the file changes associated with a session.\n\nAll fields are optional so servers can populate only the metrics they\ncheaply have available.",
      "properties": {
        "additions": {
          "type": "number",
          "description": "Total number of inserted lines across all changed files."
        },
        "deletions": {
          "type": "number",
          "description": "Total number of deleted lines across all changed files."
        },
        "files": {
          "type": "number",
          "description": "Number of files that have changes."
        }
      }
    },
    "AgentSelection": {
      "type": "object",
      "description": "A selected custom agent for a session.\n\nThe `uri` identifies a specific custom agent (matching an\n{@link AgentCustomization.uri | `AgentCustomization.uri`} exposed via\nthe session's effective customizations). Consumers resolve the agent's\ndisplay name by looking up `uri` in the session's customization tree.\n\nA message with no `agent` selected uses the provider's default behavior.",
      "properties": {
        "uri": {
          "$ref": "#/$defs/URI",
          "description": "Stable agent URI (matches an {@link AgentCustomization.uri})."
        }
      },
      "required": [
        "uri"
      ]
    },
    "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": {
            "$ref": "#/$defs/JsonPrimitive"
          },
          "description": "JSON Schema: allowed values. May be primitives of any JSON 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'`)"
        },
        "additionalProperties": {
          "$ref": "#/$defs/ConfigPropertySchema",
          "description": "JSON Schema: schema for additional properties not listed in `properties` (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"
      ]
    },
    "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",
              "enum": [
                "object"
              ]
            },
            "properties": {
              "type": "object",
              "additionalProperties": {
                "type": "object"
              }
            },
            "required": {
              "type": "array",
              "items": {
                "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",
              "enum": [
                "object"
              ]
            },
            "properties": {
              "type": "object",
              "additionalProperties": {
                "type": "object"
              }
            },
            "required": {
              "type": "array",
              "items": {
                "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)"
        }
      }
    },
    "CustomizationBase": {
      "type": "object",
      "description": "Fields shared by every customization variant.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Session-unique opaque identifier. Used by every action that targets a\nspecific customization. Minted by whoever publishes the customization\n(typically the agent host)."
        },
        "uri": {
          "$ref": "#/$defs/URI",
          "description": "Source URI for this customization. A plugin URL, a file URI, or a\ndirectory URI.\n\nFor declarations that live inside a larger file — e.g. an MCP\nserver declared inline in a `plugins.json` manifest — `uri` points\nto the containing file and {@link CustomizationBase.range | `range`}\nnarrows it to the declaration's span."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name."
        },
        "icons": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Icon"
          },
          "description": "Icons for UI display."
        },
        "range": {
          "$ref": "#/$defs/TextRange",
          "description": "Optional span within {@link CustomizationBase.uri | `uri`} when this\ncustomization is a subset of a larger file (for example, one entry\nin an inline `mcpServers` block of a `plugins.json` manifest).\nAbsent when the customization covers the whole resource."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this customization.\n\nMirrors the MCP `_meta` convention. Optional and opaque to the\nprotocol; producers and consumers agree on its contents\nout-of-band."
        }
      },
      "required": [
        "id",
        "uri",
        "name"
      ]
    },
    "CustomizationLoadingState": {
      "type": "object",
      "description": "Container is being loaded by the host.",
      "properties": {
        "kind": {
          "const": "loading"
        }
      },
      "required": [
        "kind"
      ]
    },
    "CustomizationLoadedState": {
      "type": "object",
      "description": "Container loaded successfully.",
      "properties": {
        "kind": {
          "const": "loaded"
        }
      },
      "required": [
        "kind"
      ]
    },
    "CustomizationDegradedState": {
      "type": "object",
      "description": "Container partially loaded but has warnings.",
      "properties": {
        "kind": {
          "const": "degraded"
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of the warning."
        }
      },
      "required": [
        "kind",
        "message"
      ]
    },
    "CustomizationErrorState": {
      "type": "object",
      "description": "Container failed to load.",
      "properties": {
        "kind": {
          "const": "error"
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message."
        }
      },
      "required": [
        "kind",
        "message"
      ]
    },
    "ContainerCustomizationBase": {
      "type": "object",
      "description": "Fields shared by container customizations.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Session-unique opaque identifier. Used by every action that targets a\nspecific customization. Minted by whoever publishes the customization\n(typically the agent host)."
        },
        "uri": {
          "$ref": "#/$defs/URI",
          "description": "Source URI for this customization. A plugin URL, a file URI, or a\ndirectory URI.\n\nFor declarations that live inside a larger file — e.g. an MCP\nserver declared inline in a `plugins.json` manifest — `uri` points\nto the containing file and {@link CustomizationBase.range | `range`}\nnarrows it to the declaration's span."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name."
        },
        "icons": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Icon"
          },
          "description": "Icons for UI display."
        },
        "range": {
          "$ref": "#/$defs/TextRange",
          "description": "Optional span within {@link CustomizationBase.uri | `uri`} when this\ncustomization is a subset of a larger file (for example, one entry\nin an inline `mcpServers` block of a `plugins.json` manifest).\nAbsent when the customization covers the whole resource."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this customization.\n\nMirrors the MCP `_meta` convention. Optional and opaque to the\nprotocol; producers and consumers agree on its contents\nout-of-band."
        },
        "clientId": {
          "type": "string",
          "description": "`clientId` of the client that contributed this container. Absent for\nserver-originated entries."
        },
        "load": {
          "$ref": "#/$defs/CustomizationLoadState",
          "description": "Host-reported load state. Absent means the host has not yet reported\na load state for this container."
        },
        "children": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChildCustomization"
          },
          "description": "Children discovered inside this container.\n\nAbsent means the host has not parsed this container yet. An empty\narray means the host parsed the container and it contributes\nnothing."
        }
      },
      "required": [
        "id",
        "uri",
        "name"
      ]
    },
    "PluginCustomization": {
      "type": "object",
      "description": "An [Open Plugins](https://open-plugins.com/) plugin.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Session-unique opaque identifier. Used by every action that targets a\nspecific customization. Minted by whoever publishes the customization\n(typically the agent host)."
        },
        "uri": {
          "$ref": "#/$defs/URI",
          "description": "Source URI for this customization. A plugin URL, a file URI, or a\ndirectory URI.\n\nFor declarations that live inside a larger file — e.g. an MCP\nserver declared inline in a `plugins.json` manifest — `uri` points\nto the containing file and {@link CustomizationBase.range | `range`}\nnarrows it to the declaration's span."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name."
        },
        "icons": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Icon"
          },
          "description": "Icons for UI display."
        },
        "range": {
          "$ref": "#/$defs/TextRange",
          "description": "Optional span within {@link CustomizationBase.uri | `uri`} when this\ncustomization is a subset of a larger file (for example, one entry\nin an inline `mcpServers` block of a `plugins.json` manifest).\nAbsent when the customization covers the whole resource."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this customization.\n\nMirrors the MCP `_meta` convention. Optional and opaque to the\nprotocol; producers and consumers agree on its contents\nout-of-band."
        },
        "clientId": {
          "type": "string",
          "description": "`clientId` of the client that contributed this container. Absent for\nserver-originated entries."
        },
        "load": {
          "$ref": "#/$defs/CustomizationLoadState",
          "description": "Host-reported load state. Absent means the host has not yet reported\na load state for this container."
        },
        "children": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChildCustomization"
          },
          "description": "Children discovered inside this container.\n\nAbsent means the host has not parsed this container yet. An empty\narray means the host parsed the container and it contributes\nnothing."
        },
        "type": {
          "const": "plugin"
        },
        "enablement": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/CustomizationEnablement"
          },
          "description": "Explicit enablement decisions. See {@link McpServerCustomization.enablement}."
        },
        "version": {
          "type": "string",
          "description": "Version of the plugin, sourced from the\n[Open Plugins](https://open-plugins.com/) manifest's optional\n`version` field (semver, e.g. `\"1.2.0\"`). Absent when the manifest\ndeclares no version — the field is optional there — or the source\nhas no version concept. Provenance / display only: the host neither\nparses nor enforces it."
        }
      },
      "required": [
        "id",
        "uri",
        "name",
        "type"
      ]
    },
    "ClientPluginCustomization": {
      "type": "object",
      "description": "A {@link PluginCustomization} as published by a client. Extends the\nserver-facing shape with an opaque `nonce` so the host can detect when\nthe client's view of a plugin has changed and re-parse only as needed.\n\nClients SHOULD include a `nonce`. Server-side fields like\n{@link ContainerCustomizationBase.children | `children`} and\n{@link ContainerCustomizationBase.load | `load`} are typically left\nabsent on publication and populated by the host when the resolved\nplugin appears in {@link SessionState.customizations}.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Session-unique opaque identifier. Used by every action that targets a\nspecific customization. Minted by whoever publishes the customization\n(typically the agent host)."
        },
        "uri": {
          "$ref": "#/$defs/URI",
          "description": "Source URI for this customization. A plugin URL, a file URI, or a\ndirectory URI.\n\nFor declarations that live inside a larger file — e.g. an MCP\nserver declared inline in a `plugins.json` manifest — `uri` points\nto the containing file and {@link CustomizationBase.range | `range`}\nnarrows it to the declaration's span."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name."
        },
        "icons": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Icon"
          },
          "description": "Icons for UI display."
        },
        "range": {
          "$ref": "#/$defs/TextRange",
          "description": "Optional span within {@link CustomizationBase.uri | `uri`} when this\ncustomization is a subset of a larger file (for example, one entry\nin an inline `mcpServers` block of a `plugins.json` manifest).\nAbsent when the customization covers the whole resource."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this customization.\n\nMirrors the MCP `_meta` convention. Optional and opaque to the\nprotocol; producers and consumers agree on its contents\nout-of-band."
        },
        "clientId": {
          "type": "string",
          "description": "`clientId` of the client that contributed this container. Absent for\nserver-originated entries."
        },
        "load": {
          "$ref": "#/$defs/CustomizationLoadState",
          "description": "Host-reported load state. Absent means the host has not yet reported\na load state for this container."
        },
        "children": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChildCustomization"
          },
          "description": "Children discovered inside this container.\n\nAbsent means the host has not parsed this container yet. An empty\narray means the host parsed the container and it contributes\nnothing."
        },
        "type": {
          "const": "plugin"
        },
        "enablement": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/CustomizationEnablement"
          },
          "description": "Explicit enablement decisions. See {@link McpServerCustomization.enablement}."
        },
        "version": {
          "type": "string",
          "description": "Version of the plugin, sourced from the\n[Open Plugins](https://open-plugins.com/) manifest's optional\n`version` field (semver, e.g. `\"1.2.0\"`). Absent when the manifest\ndeclares no version — the field is optional there — or the source\nhas no version concept. Provenance / display only: the host neither\nparses nor enforces it."
        },
        "nonce": {
          "type": "string",
          "description": "Opaque version token used by the host to detect changes."
        },
        "childEnablement": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/CustomizationEnablement"
            }
          },
          "description": "Explicit enablement decisions for children this plugin contributes,\nkeyed by child name (for MCP servers, the server name as it appears in\nthe bundled `.mcp.json`).\n\nBundled children are discovered by the host rather than published by the\nclient, so the client cannot attach `enablement` to them directly. This\ncarries the client's global decision for each one; the host applies it\nunder the child's durable key."
        }
      },
      "required": [
        "id",
        "uri",
        "name",
        "type"
      ]
    },
    "DirectoryCustomization": {
      "type": "object",
      "description": "A directory the host watches for this session.\n\nPresence in the customization list signals that the host may discover\ncustomizations from this directory. When `writable` is `true`, clients\nMAY persist new customizations into the directory using\n[`resourceWrite`](/reference/common#resourcewrite); the host will\nthen surface the resulting child via the customization actions.\n\nThe directory may not yet exist on disk.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Session-unique opaque identifier. Used by every action that targets a\nspecific customization. Minted by whoever publishes the customization\n(typically the agent host)."
        },
        "uri": {
          "$ref": "#/$defs/URI",
          "description": "Source URI for this customization. A plugin URL, a file URI, or a\ndirectory URI.\n\nFor declarations that live inside a larger file — e.g. an MCP\nserver declared inline in a `plugins.json` manifest — `uri` points\nto the containing file and {@link CustomizationBase.range | `range`}\nnarrows it to the declaration's span."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name."
        },
        "icons": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Icon"
          },
          "description": "Icons for UI display."
        },
        "range": {
          "$ref": "#/$defs/TextRange",
          "description": "Optional span within {@link CustomizationBase.uri | `uri`} when this\ncustomization is a subset of a larger file (for example, one entry\nin an inline `mcpServers` block of a `plugins.json` manifest).\nAbsent when the customization covers the whole resource."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this customization.\n\nMirrors the MCP `_meta` convention. Optional and opaque to the\nprotocol; producers and consumers agree on its contents\nout-of-band."
        },
        "clientId": {
          "type": "string",
          "description": "`clientId` of the client that contributed this container. Absent for\nserver-originated entries."
        },
        "load": {
          "$ref": "#/$defs/CustomizationLoadState",
          "description": "Host-reported load state. Absent means the host has not yet reported\na load state for this container."
        },
        "children": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChildCustomization"
          },
          "description": "Children discovered inside this container.\n\nAbsent means the host has not parsed this container yet. An empty\narray means the host parsed the container and it contributes\nnothing."
        },
        "type": {
          "const": "directory"
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether this container is currently enabled."
        },
        "contents": {
          "$ref": "#/$defs/ChildCustomizationType",
          "description": "Which child customization type this directory holds."
        },
        "writable": {
          "type": "boolean",
          "description": "Whether clients may write into this directory."
        }
      },
      "required": [
        "id",
        "uri",
        "name",
        "type",
        "enabled",
        "contents",
        "writable"
      ]
    },
    "ChildCustomizationBase": {
      "type": "object",
      "description": "Fields shared by the leaf child customizations that live inside a\ncontainer — {@link AgentCustomization}, {@link SkillCustomization},\n{@link PromptCustomization}, {@link RuleCustomization}, and\n{@link HookCustomization}.\n\n{@link McpServerCustomization} is also a child but does not extend this\nbase because it can appear as a top-level customization too.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Session-unique opaque identifier. Used by every action that targets a\nspecific customization. Minted by whoever publishes the customization\n(typically the agent host)."
        },
        "uri": {
          "$ref": "#/$defs/URI",
          "description": "Source URI for this customization. A plugin URL, a file URI, or a\ndirectory URI.\n\nFor declarations that live inside a larger file — e.g. an MCP\nserver declared inline in a `plugins.json` manifest — `uri` points\nto the containing file and {@link CustomizationBase.range | `range`}\nnarrows it to the declaration's span."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name."
        },
        "icons": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Icon"
          },
          "description": "Icons for UI display."
        },
        "range": {
          "$ref": "#/$defs/TextRange",
          "description": "Optional span within {@link CustomizationBase.uri | `uri`} when this\ncustomization is a subset of a larger file (for example, one entry\nin an inline `mcpServers` block of a `plugins.json` manifest).\nAbsent when the customization covers the whole resource."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this customization.\n\nMirrors the MCP `_meta` convention. Optional and opaque to the\nprotocol; producers and consumers agree on its contents\nout-of-band."
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether this child is individually enabled. Absent means enabled, so a\nproducer only needs to set it to surface a child that exists but is\nturned off on its own.\n\nThis flag is independent of the parent container's: the **effective**\nenabled state of a plugin child is the plugin's derived enabled value and\n`(child.enabled ?? true)`, so a disabled plugin disables every child\nregardless of each child's own flag. A directory child instead uses the\ndirectory's `enabled` value and its own flag.\n\nA child is turned on or off by id with\n{@link SessionCustomizationToggledAction | `session/customizationToggled`}."
        }
      },
      "required": [
        "id",
        "uri",
        "name"
      ]
    },
    "AgentCustomization": {
      "type": "object",
      "description": "A custom agent contributed by a plugin or directory.\n\nMirrors the [Open Plugins agent](https://open-plugins.com/agent-builders/components/agents)\nformat: a markdown file with YAML frontmatter, where the body is the\nagent's system prompt.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Session-unique opaque identifier. Used by every action that targets a\nspecific customization. Minted by whoever publishes the customization\n(typically the agent host)."
        },
        "uri": {
          "$ref": "#/$defs/URI",
          "description": "Source URI for this customization. A plugin URL, a file URI, or a\ndirectory URI.\n\nFor declarations that live inside a larger file — e.g. an MCP\nserver declared inline in a `plugins.json` manifest — `uri` points\nto the containing file and {@link CustomizationBase.range | `range`}\nnarrows it to the declaration's span."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name."
        },
        "icons": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Icon"
          },
          "description": "Icons for UI display."
        },
        "range": {
          "$ref": "#/$defs/TextRange",
          "description": "Optional span within {@link CustomizationBase.uri | `uri`} when this\ncustomization is a subset of a larger file (for example, one entry\nin an inline `mcpServers` block of a `plugins.json` manifest).\nAbsent when the customization covers the whole resource."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this customization.\n\nMirrors the MCP `_meta` convention. Optional and opaque to the\nprotocol; producers and consumers agree on its contents\nout-of-band."
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether this child is individually enabled. Absent means enabled, so a\nproducer only needs to set it to surface a child that exists but is\nturned off on its own.\n\nThis flag is independent of the parent container's: the **effective**\nenabled state of a plugin child is the plugin's derived enabled value and\n`(child.enabled ?? true)`, so a disabled plugin disables every child\nregardless of each child's own flag. A directory child instead uses the\ndirectory's `enabled` value and its own flag.\n\nA child is turned on or off by id with\n{@link SessionCustomizationToggledAction | `session/customizationToggled`}."
        },
        "type": {
          "const": "agent"
        },
        "description": {
          "type": "string",
          "description": "Short description of what the agent specializes in and when to\ninvoke it. Sourced from the agent file's frontmatter `description`."
        },
        "model": {
          "type": "string",
          "description": "Model the agent is pinned to, sourced from the agent file's\nfrontmatter `model`. Absent means the agent inherits the session's\ndefault model."
        },
        "tools": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Allowlist of tool names the agent is scoped to, sourced from the\nagent file's frontmatter `tools`. A non-empty list restricts the\nagent to exactly those tools. Absent — or an empty list — imposes no\nrestriction beyond the session default: the agent may use any\navailable tool. Producers express \"no restriction\" by omitting the\nfield rather than sending an empty array, so an empty list carries no\nmeaning distinct from absence."
        },
        "disableModelInvocation": {
          "type": "boolean",
          "description": "When `true`, the agent will not auto-delegate to this custom agent\nas a sub-agent; it can only be selected by the user. Absent or\n`false` means the agent may delegate to it."
        },
        "disableUserInvocation": {
          "type": "boolean",
          "description": "When `true`, the user cannot select this custom agent (for example,\nin a picker); it remains available for the agent to auto-delegate\nto. Absent or `false` means the user may select it."
        }
      },
      "required": [
        "id",
        "uri",
        "name",
        "type"
      ]
    },
    "SkillCustomization": {
      "type": "object",
      "description": "A skill contributed by a plugin or directory.\n\nCovers both [Open Plugins skill formats](https://open-plugins.com/agent-builders/components/skills)\n— the `skills/` directory layout (one subdirectory per skill, each with\na `SKILL.md`) and the flatter `commands/` directory of slash-command\nskills.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Session-unique opaque identifier. Used by every action that targets a\nspecific customization. Minted by whoever publishes the customization\n(typically the agent host)."
        },
        "uri": {
          "$ref": "#/$defs/URI",
          "description": "Source URI for this customization. A plugin URL, a file URI, or a\ndirectory URI.\n\nFor declarations that live inside a larger file — e.g. an MCP\nserver declared inline in a `plugins.json` manifest — `uri` points\nto the containing file and {@link CustomizationBase.range | `range`}\nnarrows it to the declaration's span."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name."
        },
        "icons": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Icon"
          },
          "description": "Icons for UI display."
        },
        "range": {
          "$ref": "#/$defs/TextRange",
          "description": "Optional span within {@link CustomizationBase.uri | `uri`} when this\ncustomization is a subset of a larger file (for example, one entry\nin an inline `mcpServers` block of a `plugins.json` manifest).\nAbsent when the customization covers the whole resource."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this customization.\n\nMirrors the MCP `_meta` convention. Optional and opaque to the\nprotocol; producers and consumers agree on its contents\nout-of-band."
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether this child is individually enabled. Absent means enabled, so a\nproducer only needs to set it to surface a child that exists but is\nturned off on its own.\n\nThis flag is independent of the parent container's: the **effective**\nenabled state of a plugin child is the plugin's derived enabled value and\n`(child.enabled ?? true)`, so a disabled plugin disables every child\nregardless of each child's own flag. A directory child instead uses the\ndirectory's `enabled` value and its own flag.\n\nA child is turned on or off by id with\n{@link SessionCustomizationToggledAction | `session/customizationToggled`}."
        },
        "type": {
          "const": "skill"
        },
        "description": {
          "type": "string",
          "description": "Short description used for help text and auto-invocation matching.\nSourced from the skill's frontmatter `description`."
        },
        "disableModelInvocation": {
          "type": "boolean",
          "description": "When `true`, only the user can invoke this skill — the agent will not\nauto-invoke it. Sourced from the command skill's frontmatter\n`disable-model-invocation` flag."
        },
        "disableUserInvocation": {
          "type": "boolean",
          "description": "When `true`, the user cannot directly invoke this skill (for example,\nas a slash command); it remains available for the agent to\nauto-invoke. Absent or `false` means the user may invoke it."
        }
      },
      "required": [
        "id",
        "uri",
        "name",
        "type"
      ]
    },
    "PromptCustomization": {
      "type": "object",
      "description": "A prompt contributed by a plugin or directory.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Session-unique opaque identifier. Used by every action that targets a\nspecific customization. Minted by whoever publishes the customization\n(typically the agent host)."
        },
        "uri": {
          "$ref": "#/$defs/URI",
          "description": "Source URI for this customization. A plugin URL, a file URI, or a\ndirectory URI.\n\nFor declarations that live inside a larger file — e.g. an MCP\nserver declared inline in a `plugins.json` manifest — `uri` points\nto the containing file and {@link CustomizationBase.range | `range`}\nnarrows it to the declaration's span."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name."
        },
        "icons": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Icon"
          },
          "description": "Icons for UI display."
        },
        "range": {
          "$ref": "#/$defs/TextRange",
          "description": "Optional span within {@link CustomizationBase.uri | `uri`} when this\ncustomization is a subset of a larger file (for example, one entry\nin an inline `mcpServers` block of a `plugins.json` manifest).\nAbsent when the customization covers the whole resource."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this customization.\n\nMirrors the MCP `_meta` convention. Optional and opaque to the\nprotocol; producers and consumers agree on its contents\nout-of-band."
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether this child is individually enabled. Absent means enabled, so a\nproducer only needs to set it to surface a child that exists but is\nturned off on its own.\n\nThis flag is independent of the parent container's: the **effective**\nenabled state of a plugin child is the plugin's derived enabled value and\n`(child.enabled ?? true)`, so a disabled plugin disables every child\nregardless of each child's own flag. A directory child instead uses the\ndirectory's `enabled` value and its own flag.\n\nA child is turned on or off by id with\n{@link SessionCustomizationToggledAction | `session/customizationToggled`}."
        },
        "type": {
          "const": "prompt"
        },
        "description": {
          "type": "string",
          "description": "Short description of what the prompt does."
        }
      },
      "required": [
        "id",
        "uri",
        "name",
        "type"
      ]
    },
    "RuleCustomization": {
      "type": "object",
      "description": "A rule contributed by a plugin or directory.\n\nMirrors the [Open Plugins rule](https://open-plugins.com/agent-builders/components/rules)\nformat: a markdown file (e.g. `.mdc`) whose body is injected into\ncontext while the rule is active. This type also covers tool-specific\n\"instruction\" formats (e.g. VS Code Copilot's\n`.github/instructions/*.md`), which differ only in naming — they\nshare the same semantics of `description`, optional always-on\nactivation, and optional glob scoping.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Session-unique opaque identifier. Used by every action that targets a\nspecific customization. Minted by whoever publishes the customization\n(typically the agent host)."
        },
        "uri": {
          "$ref": "#/$defs/URI",
          "description": "Source URI for this customization. A plugin URL, a file URI, or a\ndirectory URI.\n\nFor declarations that live inside a larger file — e.g. an MCP\nserver declared inline in a `plugins.json` manifest — `uri` points\nto the containing file and {@link CustomizationBase.range | `range`}\nnarrows it to the declaration's span."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name."
        },
        "icons": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Icon"
          },
          "description": "Icons for UI display."
        },
        "range": {
          "$ref": "#/$defs/TextRange",
          "description": "Optional span within {@link CustomizationBase.uri | `uri`} when this\ncustomization is a subset of a larger file (for example, one entry\nin an inline `mcpServers` block of a `plugins.json` manifest).\nAbsent when the customization covers the whole resource."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this customization.\n\nMirrors the MCP `_meta` convention. Optional and opaque to the\nprotocol; producers and consumers agree on its contents\nout-of-band."
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether this child is individually enabled. Absent means enabled, so a\nproducer only needs to set it to surface a child that exists but is\nturned off on its own.\n\nThis flag is independent of the parent container's: the **effective**\nenabled state of a plugin child is the plugin's derived enabled value and\n`(child.enabled ?? true)`, so a disabled plugin disables every child\nregardless of each child's own flag. A directory child instead uses the\ndirectory's `enabled` value and its own flag.\n\nA child is turned on or off by id with\n{@link SessionCustomizationToggledAction | `session/customizationToggled`}."
        },
        "type": {
          "const": "rule"
        },
        "description": {
          "type": "string",
          "description": "Description of what the rule enforces."
        },
        "alwaysApply": {
          "type": "boolean",
          "description": "When `true`, the rule is always active (subject to `globs` if any).\nWhen `false` or absent, the agent or user decides whether to apply\nthe rule."
        },
        "globs": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Glob patterns the rule applies to. When present, the rule is only\nactive for matching files."
        }
      },
      "required": [
        "id",
        "uri",
        "name",
        "type"
      ]
    },
    "HookCustomization": {
      "type": "object",
      "description": "A hook manifest contributed by a plugin or directory.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Session-unique opaque identifier. Used by every action that targets a\nspecific customization. Minted by whoever publishes the customization\n(typically the agent host)."
        },
        "uri": {
          "$ref": "#/$defs/URI",
          "description": "Source URI for this customization. A plugin URL, a file URI, or a\ndirectory URI.\n\nFor declarations that live inside a larger file — e.g. an MCP\nserver declared inline in a `plugins.json` manifest — `uri` points\nto the containing file and {@link CustomizationBase.range | `range`}\nnarrows it to the declaration's span."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name."
        },
        "icons": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Icon"
          },
          "description": "Icons for UI display."
        },
        "range": {
          "$ref": "#/$defs/TextRange",
          "description": "Optional span within {@link CustomizationBase.uri | `uri`} when this\ncustomization is a subset of a larger file (for example, one entry\nin an inline `mcpServers` block of a `plugins.json` manifest).\nAbsent when the customization covers the whole resource."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this customization.\n\nMirrors the MCP `_meta` convention. Optional and opaque to the\nprotocol; producers and consumers agree on its contents\nout-of-band."
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether this child is individually enabled. Absent means enabled, so a\nproducer only needs to set it to surface a child that exists but is\nturned off on its own.\n\nThis flag is independent of the parent container's: the **effective**\nenabled state of a plugin child is the plugin's derived enabled value and\n`(child.enabled ?? true)`, so a disabled plugin disables every child\nregardless of each child's own flag. A directory child instead uses the\ndirectory's `enabled` value and its own flag.\n\nA child is turned on or off by id with\n{@link SessionCustomizationToggledAction | `session/customizationToggled`}."
        },
        "type": {
          "const": "hook"
        }
      },
      "required": [
        "id",
        "uri",
        "name",
        "type"
      ]
    },
    "McpServerCustomization": {
      "type": "object",
      "description": "An MCP server contributed by a plugin or directory.\n\nWhen the server is declared inline in the containing plugin manifest,\n`uri` points at the manifest file and\n{@link CustomizationBase.range | `range`} narrows it to the\ndeclaration's span.\n\nThe MCP server customization also reflects its current status.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Session-unique opaque identifier. Used by every action that targets a\nspecific customization. Minted by whoever publishes the customization\n(typically the agent host)."
        },
        "uri": {
          "$ref": "#/$defs/URI",
          "description": "Source URI for this customization. A plugin URL, a file URI, or a\ndirectory URI.\n\nFor declarations that live inside a larger file — e.g. an MCP\nserver declared inline in a `plugins.json` manifest — `uri` points\nto the containing file and {@link CustomizationBase.range | `range`}\nnarrows it to the declaration's span."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name."
        },
        "icons": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Icon"
          },
          "description": "Icons for UI display."
        },
        "range": {
          "$ref": "#/$defs/TextRange",
          "description": "Optional span within {@link CustomizationBase.uri | `uri`} when this\ncustomization is a subset of a larger file (for example, one entry\nin an inline `mcpServers` block of a `plugins.json` manifest).\nAbsent when the customization covers the whole resource."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this customization.\n\nMirrors the MCP `_meta` convention. Optional and opaque to the\nprotocol; producers and consumers agree on its contents\nout-of-band."
        },
        "type": {
          "const": "mcpServer"
        },
        "enablement": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/CustomizationEnablement"
          },
          "description": "Explicit enablement decisions for this customization, one entry per scope\nthat has one. This is a wire contract: producers MUST publish entries\nsorted by descending specificity (Session, Workspace, then Global).\nThe agent host emits at most one Workspace entry, for the session's primary\nworking directory. Consumers MAY treat\n`enablement[0]` as the decisive decision and\n`enablement?.[0]?.enabled ?? true` as the effective enabled value. An\nabsent or empty array means no explicit decision exists, so the\ncustomization is enabled by default.\n\nFlows in both directions. A client publishes this alongside a customization\nto assert its global decision, which is authoritative for the Global scope;\na client always includes its global entry, even when enabled. The host\npublishes the fully resolved set across all scopes, and consumers derive\nthe effective enabled value from that set."
        },
        "state": {
          "$ref": "#/$defs/McpServerState",
          "description": "Current lifecycle state of the MCP server."
        },
        "channel": {
          "$ref": "#/$defs/URI",
          "description": "An `mcp://`-protocol channel the client uses to side-channel traffic\ninto the upstream MCP server itself. The channel is NOT a fresh raw MCP\nconnection: it piggybacks on the AHP transport\nand skips the MCP `initialize` sequence.\n\nThe agent host MAY only serve a subset of MCP on this\nchannel; the served subset is described by domain-specific\ncapabilities such as those in\n{@link McpServerCustomizationApps.capabilities}.\n\nThe channel URI SHOULD be stable across the server's lifetime, but\nthe agent host MAY change it (for example across a restart) and\nMAY only expose it while the server is in\n{@link McpServerStatus.Ready | `Ready`}. Absence means no\nside-channel is currently available."
        },
        "mcpApp": {
          "$ref": "#/$defs/McpServerCustomizationApps",
          "description": "MCP App support. This property SHOULD be advertised for MCP servers\nwhich support apps."
        }
      },
      "required": [
        "id",
        "uri",
        "name",
        "type",
        "state"
      ]
    },
    "McpServerCustomizationApps": {
      "type": "object",
      "description": "Information from the agent host needed to render MCP Apps served\nby this MCP server.",
      "properties": {
        "capabilities": {
          "$ref": "#/$defs/AhpMcpUiHostCapabilities",
          "description": "The subset of MCP App\n[`HostCapabilities`](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx)\nthe AHP host can satisfy for Views backed by this server. The\nclient feeds these straight through into the `hostCapabilities` of\nthe `ui/initialize` response delivered to the View."
        }
      },
      "required": [
        "capabilities"
      ]
    },
    "AhpMcpUiHostCapabilities": {
      "type": "object",
      "description": "The subset of MCP App\n[`HostCapabilities`](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx)\nan AHP host can derive from the upstream MCP server (and from AHP's own\nforwarding plumbing). Advertised on\n{@link McpServerCustomizationApps.capabilities} so clients can pass it\nthrough into the `hostCapabilities` of the `ui/initialize` response\ndelivered to an MCP App View.\n\nField names mirror the MCP Apps spec exactly, so the AHP-side producer\ncan pass them straight through into the `hostCapabilities` of the\n`ui/initialize` response delivered to the View.\n\nCapabilities outside this set (`openLinks`, `downloadFile`, `sandbox`,\n`experimental`) are decided locally by whichever AHP client renders the\nView and are NOT part of this AHP-level advertisement — only the\nserver-derived subset is.\n\nAn agent host MUST only advertise a capability when it actually accepts the\ncorresponding methods/notifications on the `mcp://` channel:\n\n- {@link serverTools}: host proxies `tools/list` and `tools/call` to\n  the MCP server. When `listChanged` is `true`, the host also forwards\n  `notifications/tools/list_changed`.\n- {@link serverResources}: host proxies `resources/read`,\n  `resources/list`, and `resources/templates/list` to the MCP server.\n  When `listChanged` is `true`, the host also forwards\n  `notifications/resources/list_changed`.\n- {@link logging}: host accepts `notifications/message` log entries\n  from the App and forwards them via `mcpNotification` (and forwards\n  `logging/setLevel` calls to the server).\n- {@link sampling}: host serves `sampling/createMessage` via\n  `mcpMethodCall`. When `sampling.tools` is present, the host also\n  accepts SEP-1577 `tools` / `toolChoice` / `tool_use` content blocks\n  inside `CreateMessageRequest`.",
      "properties": {
        "serverTools": {
          "type": "object",
          "properties": {
            "listChanged": {
              "type": "boolean"
            }
          },
          "description": "Producer proxies the MCP `tools/*` methods to the upstream server."
        },
        "serverResources": {
          "type": "object",
          "properties": {
            "listChanged": {
              "type": "boolean"
            }
          },
          "description": "Producer proxies the MCP `resources/*` methods to the upstream server."
        },
        "logging": {
          "type": "object",
          "additionalProperties": {},
          "description": "Producer accepts `notifications/message` log entries from the App via `mcpNotification`."
        },
        "sampling": {
          "type": "object",
          "properties": {
            "tools": {
              "type": "object",
              "additionalProperties": {}
            }
          },
          "description": "Producer serves `sampling/createMessage` via `mcpMethodCall`."
        }
      }
    },
    "McpServerStartingState": {
      "type": "object",
      "description": "Server is registered with the host but has not yet started.",
      "properties": {
        "kind": {
          "const": "starting"
        }
      },
      "required": [
        "kind"
      ]
    },
    "McpServerReadyState": {
      "type": "object",
      "description": "Server is running and serving requests.",
      "properties": {
        "kind": {
          "const": "ready"
        }
      },
      "required": [
        "kind"
      ]
    },
    "McpOAuthClient": {
      "type": "object",
      "description": "A pre-registered OAuth client that clients use instead of dynamic client\nregistration when resolving an MCP authentication challenge.",
      "properties": {
        "clientId": {
          "type": "string",
          "description": "OAuth client identifier registered with the authorization server."
        },
        "clientSecret": {
          "type": "string",
          "description": "OAuth client secret for a confidential client. Absence means the client is\npublic and uses a secretless flow such as authorization code with PKCE."
        }
      },
      "required": [
        "clientId"
      ]
    },
    "McpAuthRequirement": {
      "type": "object",
      "description": "Reusable MCP authentication challenge — the RFC 9728 discovery info a\nclient needs to obtain a token and push it via the `authenticate` command.\nDeliberately carries **no token**: this describes what is being asked for,\nnever the bearer token itself.\n\nShared by two independent state machines that describe the same OAuth\nchallenge from different vantage points:\n\n- {@link McpServerAuthRequiredState} — the MCP server itself cannot serve\n  *any* request until the client authenticates.\n- {@link ToolCallAuthRequiredState} — a specific in-flight tool call is\n  paused pending authentication (typically\n  {@link McpAuthRequiredReason.InsufficientScope} step-up auth\n  mid-execution). The server state and the tool-call state remain\n  separate on purpose: the server saying \"I need auth\" and a tool\n  invocation saying \"I am waiting on that auth\" are different facts that\n  can be true independently.",
      "properties": {
        "reason": {
          "$ref": "#/$defs/McpAuthRequiredReason",
          "description": "Why authentication is required."
        },
        "oauthClient": {
          "$ref": "#/$defs/McpOAuthClient",
          "description": "Pre-registered OAuth client to use for authorization. When present, clients\nMUST use these credentials instead of dynamic client registration."
        },
        "resource": {
          "$ref": "#/$defs/ProtectedResourceMetadata",
          "description": "RFC 9728 Protected Resource Metadata. The `resource` field is the\ncanonical MCP server URI per RFC 8707, used as the OAuth `resource`\nindicator. `authorization_servers` is REQUIRED by the MCP\nauthorization spec."
        },
        "requiredScopes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Scopes required for the current challenge, parsed from the\n`WWW-Authenticate: Bearer scope=\"…\"` header (or `scopes_supported`\nfallback). Authoritative for the next authorization request — clients\nMUST NOT assume any subset/superset relationship to\n`resource.scopes_supported`."
        },
        "description": {
          "type": "string",
          "description": "Human-readable hint, typically from the OAuth `error_description`."
        }
      },
      "required": [
        "reason",
        "resource"
      ]
    },
    "McpServerAuthRequiredState": {
      "type": "object",
      "description": "Server is reachable but cannot serve requests until the client\nauthenticates. Mirrors the discovery flow defined by\n[RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)\n(Protected Resource Metadata) and the OAuth 2.1 / RFC 6750 challenge\nsemantics required by the MCP authorization spec.\n\nClients react to this state by calling the existing `authenticate`\ncommand with the {@link ProtectedResourceMetadata.resource | resource}\ncarried here. There is **no** `notify/authRequired` notification for\nMCP servers — the action stream is the single source of truth.\n\nWhen the transition is triggered by a request issued during a turn\n— most commonly\n{@link McpAuthRequiredReason.InsufficientScope | `InsufficientScope`}\nsurfacing mid-tool-call — the host SHOULD also raise\n{@link SessionStatus.InputNeeded} on the session so the block is\nvisible at the summary level. Clients SHOULD watch this status on\nany MCP server backing a running tool call and surface an explicit\naffordance (e.g. a \"grant additional access\" prompt) tied to that\ntool call, rather than relying on the user to notice the\ncustomization’s status badge.",
      "properties": {
        "reason": {
          "$ref": "#/$defs/McpAuthRequiredReason",
          "description": "Why authentication is required."
        },
        "oauthClient": {
          "$ref": "#/$defs/McpOAuthClient",
          "description": "Pre-registered OAuth client to use for authorization. When present, clients\nMUST use these credentials instead of dynamic client registration."
        },
        "resource": {
          "$ref": "#/$defs/ProtectedResourceMetadata",
          "description": "RFC 9728 Protected Resource Metadata. The `resource` field is the\ncanonical MCP server URI per RFC 8707, used as the OAuth `resource`\nindicator. `authorization_servers` is REQUIRED by the MCP\nauthorization spec."
        },
        "requiredScopes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Scopes required for the current challenge, parsed from the\n`WWW-Authenticate: Bearer scope=\"…\"` header (or `scopes_supported`\nfallback). Authoritative for the next authorization request — clients\nMUST NOT assume any subset/superset relationship to\n`resource.scopes_supported`."
        },
        "description": {
          "type": "string",
          "description": "Human-readable hint, typically from the OAuth `error_description`."
        },
        "kind": {
          "const": "authRequired"
        }
      },
      "required": [
        "reason",
        "resource",
        "kind"
      ]
    },
    "McpServerErrorState": {
      "type": "object",
      "description": "Server failed to start, crashed, or otherwise transitioned to a\nnon-recoverable error. Use {@link McpServerStatus.AuthRequired}\nfor authentication failures.",
      "properties": {
        "kind": {
          "const": "error"
        },
        "error": {
          "$ref": "#/$defs/ErrorInfo",
          "description": "Error details."
        }
      },
      "required": [
        "kind",
        "error"
      ]
    },
    "McpServerStoppedState": {
      "type": "object",
      "description": "Server has been shut down. The host MAY remove the server from the\nsession entirely shortly after this state.",
      "properties": {
        "kind": {
          "const": "stopped"
        }
      },
      "required": [
        "kind"
      ]
    },
    "ChatState": {
      "type": "object",
      "description": "Full state for a single chat, loaded when a client subscribes to the chat's\nURI.\n\nThe lightweight catalog representation of a chat is {@link ChatSummary},\ncarried in {@link SessionState.chats | `SessionState.chats`}. `ChatState`\n**denormalizes** every {@link ChatSummary} field directly onto itself so\nsubscribers receive one flat object instead of having to merge a nested\n`summary` sub-object. Producers MUST keep the two representations\nconsistent: any change to the inlined fields below SHOULD also be\nannounced on the parent session via the matching\n{@link SessionChatUpdatedAction | `session/chatUpdated`} action.",
      "properties": {
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "Chat URI"
        },
        "title": {
          "type": "string",
          "description": "Chat title"
        },
        "status": {
          "$ref": "#/$defs/SessionStatus",
          "description": "Current chat status (reuses SessionStatus shape)"
        },
        "activity": {
          "type": "string",
          "description": "Human-readable description of what the chat is currently doing"
        },
        "modifiedAt": {
          "type": "string",
          "description": "Last modification timestamp (ISO 8601, e.g. `\"2025-03-10T18:42:03.123Z\"`)"
        },
        "origin": {
          "$ref": "#/$defs/ChatOrigin",
          "description": "How this chat came into existence"
        },
        "interactivity": {
          "$ref": "#/$defs/ChatInteractivity",
          "description": "How the user can interact with this chat. See {@link ChatInteractivity}.\n\nSupports agent-team patterns where worker chats are read-only or hidden.\nAbsence defaults to {@link ChatInteractivity.Full} for backward\ncompatibility."
        },
        "workingDirectories": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/URI"
          },
          "description": "The subset of the session's\n{@link SessionState.workingDirectories | `workingDirectories`} that this\nchat's agent has tool access to. Every entry MUST be present in the owning\nsession's `workingDirectories`; servers MUST reject a\n`chat/workingDirectorySet` action that violates this constraint.\n\nWhen absent, the chat inherits the full session set. When present but empty\n(not recommended), the chat has no working-directory tool access at all.\n\nDispatch `chat/workingDirectorySet` / `chat/workingDirectoryRemoved` to\nupdate the subset on a running chat."
        },
        "turns": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Turn"
          },
          "description": "Completed turns"
        },
        "turnsNextCursor": {
          "type": "string",
          "description": "Cursor for loading older completed turns into this chat state.\n\nPresence means `turns` is a tail window and more historical turns are\navailable. Pass this opaque cursor to `fetchTurns`; the host MUST insert\nthe loaded turns into state and update or clear this cursor before\nresponding. Absence means the state contains all retained 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"
        },
        "draft": {
          "$ref": "#/$defs/Message",
          "description": "The user's in-progress draft input for this chat — the message they are\ncomposing but have not sent yet, including its\n{@link Message.model | model} / {@link Message.agent | agent} selection\nand attachments.\n\nClients MAY periodically sync their local input state into this field so\na draft survives reloads and is visible to other clients viewing the same\nchat. Eager syncing is **not** required — clients SHOULD debounce and MAY\nsync only at convenient points. When presenting input UI for an existing\nchat, clients SHOULD use any `draft` to initialize their input state.\nCleared (set to `undefined`) once the message is sent."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this chat."
        }
      },
      "required": [
        "resource",
        "title",
        "status",
        "modifiedAt",
        "turns"
      ]
    },
    "ChatSummary": {
      "type": "object",
      "description": "Lightweight catalog entry for a chat, carried in\n{@link SessionState.chats | `SessionState.chats`}. The full conversation\nlives in {@link ChatState}, which inlines (denormalizes) every field below.",
      "properties": {
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "Chat URI"
        },
        "title": {
          "type": "string",
          "description": "Chat title"
        },
        "status": {
          "$ref": "#/$defs/SessionStatus",
          "description": "Current chat status (reuses SessionStatus shape)"
        },
        "activity": {
          "type": "string",
          "description": "Human-readable description of what the chat is currently doing"
        },
        "modifiedAt": {
          "type": "string",
          "description": "Last modification timestamp (ISO 8601, e.g. `\"2025-03-10T18:42:03.123Z\"`)"
        },
        "origin": {
          "$ref": "#/$defs/ChatOrigin",
          "description": "How this chat came into existence"
        },
        "interactivity": {
          "$ref": "#/$defs/ChatInteractivity",
          "description": "How the user can interact with this chat. See {@link ChatInteractivity}.\n\nSupports agent-team patterns where worker chats are read-only or hidden.\nAbsence defaults to {@link ChatInteractivity.Full} for backward\ncompatibility."
        },
        "workingDirectories": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/URI"
          },
          "description": "The subset of the session's working directories this chat uses.\nSee {@link ChatState.workingDirectories} for the full semantics."
        }
      },
      "required": [
        "resource",
        "title",
        "status",
        "modifiedAt"
      ]
    },
    "SideChatSelection": {
      "type": "object",
      "description": "Immutable selected-text snapshot captured when a side chat is created.\n\nThe host records this exact text when it accepts `createChat`; later changes\nto the source chat do not alter it.",
      "properties": {
        "text": {
          "type": "string",
          "description": "Exact selected-text snapshot captured at `createChat` acceptance.\n\nMUST be non-empty."
        },
        "responsePartId": {
          "type": "string",
          "description": "Optional provenance for the response part that contained {@link text} when\nthe host took the snapshot.\n\nAdvisory only: this is not a live range or offset and MUST NOT be used to\nrecompute `text`."
        }
      },
      "required": [
        "text"
      ]
    },
    "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"
        },
        "message": {
          "$ref": "#/$defs/Message",
          "description": "The message that will start the next turn"
        }
      },
      "required": [
        "id",
        "message"
      ]
    },
    "ChatInputOption": {
      "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"
      ]
    },
    "ChatInputQuestionBase": {
      "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"
      ]
    },
    "ChatInputTextQuestion": {
      "type": "object",
      "description": "Text question within a chat 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": {
          "const": "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"
      ]
    },
    "ChatInputNumberQuestion": {
      "type": "object",
      "description": "Numeric question within a chat 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": [
            {
              "const": "number"
            },
            {
              "const": "integer"
            }
          ]
        },
        "min": {
          "type": "number",
          "description": "Minimum value"
        },
        "max": {
          "type": "number",
          "description": "Maximum value"
        },
        "defaultValue": {
          "type": "number",
          "description": "Default numeric value"
        }
      },
      "required": [
        "id",
        "message",
        "kind"
      ]
    },
    "ChatInputBooleanQuestion": {
      "type": "object",
      "description": "Boolean question within a chat 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": {
          "const": "boolean"
        },
        "defaultValue": {
          "type": "boolean",
          "description": "Default boolean value"
        }
      },
      "required": [
        "id",
        "message",
        "kind"
      ]
    },
    "ChatInputSingleSelectQuestion": {
      "type": "object",
      "description": "Single-select question within a chat 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": {
          "const": "single-select"
        },
        "options": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChatInputOption"
          },
          "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"
      ]
    },
    "ChatInputMultiSelectQuestion": {
      "type": "object",
      "description": "Multi-select question within a chat 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": {
          "const": "multi-select"
        },
        "options": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChatInputOption"
          },
          "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"
      ]
    },
    "ChatInputRequest": {
      "type": "object",
      "description": "The request payload carried by an {@link InputRequestResponsePart}.\n\nThe server creates or replaces the containing response part with\n`chat/inputRequested`. Clients sync drafts with `chat/inputAnswerChanged`\nand submit responses with `chat/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/ChatInputQuestion"
          },
          "description": "Ordered questions to ask the user"
        },
        "answers": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/ChatInputAnswer"
          },
          "description": "Current draft or submitted answers, keyed by question ID"
        }
      },
      "required": [
        "id"
      ]
    },
    "ChatInputTextAnswerValue": {
      "type": "object",
      "description": "Value captured for one answer.",
      "properties": {
        "kind": {
          "const": "text"
        },
        "value": {
          "type": "string"
        }
      },
      "required": [
        "kind",
        "value"
      ]
    },
    "ChatInputNumberAnswerValue": {
      "type": "object",
      "properties": {
        "kind": {
          "const": "number"
        },
        "value": {
          "type": "number"
        }
      },
      "required": [
        "kind",
        "value"
      ]
    },
    "ChatInputBooleanAnswerValue": {
      "type": "object",
      "properties": {
        "kind": {
          "const": "boolean"
        },
        "value": {
          "type": "boolean"
        }
      },
      "required": [
        "kind",
        "value"
      ]
    },
    "ChatInputSelectedAnswerValue": {
      "type": "object",
      "properties": {
        "kind": {
          "const": "selected"
        },
        "value": {
          "type": "string"
        },
        "freeformValues": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Free-form text entered instead of selecting an option"
        }
      },
      "required": [
        "kind",
        "value"
      ]
    },
    "ChatInputSelectedManyAnswerValue": {
      "type": "object",
      "properties": {
        "kind": {
          "const": "selected-many"
        },
        "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"
      ]
    },
    "ChatInputAnswered": {
      "type": "object",
      "properties": {
        "state": {
          "oneOf": [
            {
              "const": "draft"
            },
            {
              "const": "submitted"
            }
          ],
          "description": "Answer state"
        },
        "value": {
          "$ref": "#/$defs/ChatInputAnswerValue",
          "description": "Answer value"
        }
      },
      "required": [
        "state",
        "value"
      ]
    },
    "ChatInputSkipped": {
      "type": "object",
      "properties": {
        "state": {
          "const": "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"
        },
        "startedAt": {
          "type": "string",
          "description": "ISO 8601 timestamp when this turn started."
        },
        "duration": {
          "type": "number",
          "description": "Turn duration in milliseconds."
        },
        "message": {
          "$ref": "#/$defs/Message",
          "description": "The message that initiated the turn"
        },
        "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"
        }
      },
      "required": [
        "id",
        "message",
        "responseParts",
        "state"
      ]
    },
    "ActiveTurn": {
      "type": "object",
      "description": "An in-progress turn — the assistant is actively streaming.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Turn identifier"
        },
        "startedAt": {
          "type": "string",
          "description": "ISO 8601 timestamp when this turn started."
        },
        "message": {
          "$ref": "#/$defs/Message",
          "description": "The message that initiated the turn"
        },
        "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",
        "startedAt",
        "message",
        "responseParts"
      ]
    },
    "MessageOrigin": {
      "type": "object",
      "description": "Identifies the origin of a {@link Message} — who produced it. For the message\nthat initiates a turn ({@link Turn.message}), this is also the origin of the\nturn; for steering or queued messages it is just the origin of that message.",
      "properties": {
        "kind": {
          "$ref": "#/$defs/MessageKind",
          "description": "The kind of actor that produced the message."
        }
      },
      "required": [
        "kind"
      ]
    },
    "Message": {
      "type": "object",
      "description": "A message that initiates or steers a turn. Messages can originate from the\nuser, the agent, a tool, an automation, or be system-generated (see\n{@link MessageOrigin}).\n\nAttachments MAY be referenced inside {@link Message.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"
        },
        "origin": {
          "$ref": "#/$defs/MessageOrigin",
          "description": "The origin of the message"
        },
        "attachments": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/MessageAttachment"
          },
          "description": "File/selection attachments"
        },
        "model": {
          "$ref": "#/$defs/ModelSelection",
          "description": "The model this message was, or will be, sent with.\n\nFor historic user/agent messages this records the model actually used, so\na client editing or resending the message can retain that selection. For a\n{@link ChatState.draft | draft} it carries the model the user picked for\nthe message they are composing. Absent means the agent host's default\nmodel applies."
        },
        "agent": {
          "$ref": "#/$defs/AgentSelection",
          "description": "The custom agent this message was, or will be, sent with.\n\nFor historic messages this records the agent actually used; for a\n{@link ChatState.draft | draft} it carries the agent the user picked.\nAbsent means no custom agent — the provider's default behavior applies."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this message.\n\nClients MAY look for well-known keys here to provide enhanced UI, and\nagent hosts MAY use it to carry context that does not fit any other\nfield. Mirrors the MCP `_meta` convention."
        }
      },
      "required": [
        "text",
        "origin"
      ]
    },
    "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 Message.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"
      ]
    },
    "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 Message.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": {
          "const": "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 Message.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": {
          "const": "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 Message.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"
        },
        "nonce": {
          "type": "string",
          "description": "Content nonce"
        },
        "type": {
          "const": "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"
      ]
    },
    "MessageAnnotationsAttachment": {
      "type": "object",
      "description": "An attachment that references annotations on a session's annotations\nchannel (see {@link AnnotationsState}).\n\nWhen {@link annotationIds} is omitted the attachment references every\nannotation on the channel; when present it references only the listed\n{@link Annotation.id | annotation ids}.",
      "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 Message.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": {
          "const": "annotations",
          "description": "Discriminant"
        },
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "The annotations channel URI (typically `ahp-session:/<uuid>/annotations`).\nMatches {@link AnnotationsSummary.resource}."
        },
        "annotationIds": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Specific {@link Annotation.id | annotation ids} to reference. When\nomitted, the attachment references all annotations on the channel."
        }
      },
      "required": [
        "label",
        "type",
        "resource"
      ]
    },
    "MessageChatAttachment": {
      "type": "object",
      "description": "An attachment that references a chat transcript through a fixed completed\nturn.\n\nThe referenced chat MAY belong to a different session than the message's\nchat. The attachment's model representation identifies the chat in a way\nthat hosts can resolve regardless of the session that owns it.\n\nWhen `endTurn` is omitted, the host MUST resolve and pin the referenced\nchat's latest completed turn when accepting the message. This lets clients\nattach a chat without knowing its turn identifiers. When provided, `endTurn`\nMUST reference a completed, retained turn. The host resolves the transcript\nfrom its first retained turn through the pinned turn, inclusive. Later turns\ndo not change the context represented by an already-sent attachment.\n\nWhen the referenced chat has no completed retained turns, the resolved\ntranscript is empty and hosts MUST NOT reject the attachment on that basis.\n\nHosts MUST NOT recursively expand chat attachments found inside the\nreferenced transcript. Clients SHOULD keep rendering `label` if the\nreferenced chat is later pruned, and treat opening `resource` as best-effort.",
      "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 Message.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": {
          "const": "chat",
          "description": "Discriminant"
        },
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "URI of the referenced chat."
        },
        "endTurn": {
          "type": "string",
          "description": "Last completed turn included in the referenced transcript. When omitted,\nthe host pins the latest completed turn when accepting the message."
        }
      },
      "required": [
        "label",
        "type",
        "resource"
      ]
    },
    "MarkdownResponsePart": {
      "type": "object",
      "properties": {
        "kind": {
          "const": "markdown",
          "description": "Discriminant"
        },
        "id": {
          "type": "string",
          "description": "Part identifier, used by `chat/delta` to target this part for content appends"
        },
        "content": {
          "type": "string",
          "description": "Markdown content"
        }
      },
      "required": [
        "kind",
        "id",
        "content"
      ]
    },
    "ResourceResponsePart": {
      "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"
        },
        "nonce": {
          "type": "string",
          "description": "Content nonce"
        },
        "kind": {
          "const": "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": {
          "const": "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": {
          "const": "reasoning",
          "description": "Discriminant"
        },
        "id": {
          "type": "string",
          "description": "Part identifier, used by `chat/reasoning` to target this part for content appends"
        },
        "content": {
          "type": "string",
          "description": "Accumulated reasoning text"
        }
      },
      "required": [
        "kind",
        "id",
        "content"
      ]
    },
    "InputRequestResponsePart": {
      "type": "object",
      "description": "A live or resolved input request (elicitation) in the turn response stream.\n\nThe server inserts the part with `chat/inputRequested`. While\n{@link response} is absent, clients can update answer drafts with\n`chat/inputAnswerChanged` and submit a response with `chat/inputCompleted`.\nCompletion updates this part in place so its stream position is stable and\nthe full interaction remains durable and backfillable via `fetchTurns`.\n\nIf the turn ends without a submitted response, the unresolved part remains\nin the completed turn transcript with {@link response} absent.",
      "properties": {
        "kind": {
          "const": "inputRequest",
          "description": "Discriminant"
        },
        "request": {
          "$ref": "#/$defs/ChatInputRequest",
          "description": "The request, carrying its `id`, `message`, `url`, `questions`, and current\ndraft or submitted `answers`."
        },
        "response": {
          "$ref": "#/$defs/ChatInputResponseKind",
          "description": "How the request was resolved. Absent until a client submits `accept`,\n`decline`, or `cancel` with `chat/inputCompleted`."
        }
      },
      "required": [
        "kind",
        "request"
      ]
    },
    "ErrorResponsePart": {
      "type": "object",
      "description": "An error encountered while processing a turn.\n\nThis is the detailed source of truth for the error. {@link Turn.state}\nremains {@link TurnState.Error} while the turn is stopped at this error so\nclients can detect the terminal state without inspecting response parts.\n\nWhen {@link resumable} is `true`, a client may dispatch `chat/turnResume`\nwhile this is the latest turn and its state is {@link TurnState.Error}.\nClients decide whether and how to present that affordance.",
      "properties": {
        "kind": {
          "const": "error",
          "description": "Discriminant"
        },
        "error": {
          "$ref": "#/$defs/ErrorInfo",
          "description": "Error details."
        },
        "resumable": {
          "type": "boolean",
          "description": "Whether the host can resume the turn from this error. Only `true` enables resume."
        }
      },
      "required": [
        "kind",
        "error"
      ]
    },
    "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": {
          "const": "systemNotification",
          "description": "Discriminant"
        },
        "content": {
          "$ref": "#/$defs/StringOrMarkdown",
          "description": "The text of the system notification"
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this notification.\n\nA host MAY attach a machine-readable descriptor of what triggered the\nnotification so clients can categorize, icon, group, filter, or localize\nit without parsing `content`. Clients MAY look for well-known keys here to\nprovide enhanced UI, and MUST render coherently from `content` alone when\n`_meta` is absent or unrecognized."
        }
      },
      "required": [
        "kind",
        "content"
      ]
    },
    "ToolCallRiskAssessmentBase": {
      "type": "object",
      "properties": {
        "kind": {
          "$ref": "#/$defs/ToolCallRiskAssessmentKind"
        }
      },
      "required": [
        "kind"
      ]
    },
    "ToolCallRiskAssessmentLoadingState": {
      "type": "object",
      "description": "The model judge is still evaluating the tool call.",
      "properties": {
        "kind": {
          "$ref": "#/$defs/ToolCallRiskAssessmentKind"
        },
        "status": {
          "const": "loading"
        }
      },
      "required": [
        "kind",
        "status"
      ]
    },
    "ToolCallRiskAssessmentCompleteState": {
      "type": "object",
      "description": "The model judge has completed its evaluation.",
      "properties": {
        "kind": {
          "$ref": "#/$defs/ToolCallRiskAssessmentKind"
        },
        "status": {
          "const": "complete"
        },
        "reason": {
          "$ref": "#/$defs/StringOrMarkdown"
        },
        "safety": {
          "type": "number",
          "description": "The judge's normalized safety score, where `0` is unsafe and `1` is safe."
        }
      },
      "required": [
        "kind",
        "status",
        "reason",
        "safety"
      ]
    },
    "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"
      ]
    },
    "ToolCallClientContributor": {
      "type": "object",
      "properties": {
        "kind": {
          "const": "client"
        },
        "clientId": {
          "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 `chat/toolCallComplete` with the result."
        }
      },
      "required": [
        "kind",
        "clientId"
      ]
    },
    "ToolCallMcpContributor": {
      "type": "object",
      "properties": {
        "kind": {
          "const": "mcp"
        },
        "customizationId": {
          "type": "string",
          "description": "Customization ID of the corresponding MCP server in {@link SessionState.customizations}."
        }
      },
      "required": [
        "kind",
        "customizationId"
      ]
    },
    "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"
        },
        "intention": {
          "type": "string",
          "description": "Human-readable description of what the tool invocation intends to do"
        },
        "contributor": {
          "$ref": "#/$defs/ToolCallContributor",
          "description": "Reference to the contributor of the tool being called."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this tool call.\n\nThis MAY include a `ui` field corresponding to the MCP Apps (SEP-1865)\n`McpUiToolMeta` found in MCP tool calls, which may be used in combination\nwith the {@link contributor} to serve MCP Apps."
        }
      },
      "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": {
          "$ref": "#/$defs/ToolInput",
          "description": "Final tool input.\n\nReferenced input is mutable until the tool call leaves\n`pending-confirmation`. When the client confirms with `editedToolInput`,\nthe host MUST replace the resource contents before echoing the accepted\nconfirmation action. Clients MUST NOT cache tool input across confirmation."
        }
      },
      "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"
        },
        "intention": {
          "type": "string",
          "description": "Human-readable description of what the tool invocation intends to do"
        },
        "contributor": {
          "$ref": "#/$defs/ToolCallContributor",
          "description": "Reference to the contributor of the tool being called."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this tool call.\n\nThis MAY include a `ui` field corresponding to the MCP Apps (SEP-1865)\n`McpUiToolMeta` found in MCP tool calls, which may be used in combination\nwith the {@link contributor} to serve MCP Apps."
        },
        "status": {
          "const": "streaming"
        },
        "partialInput": {
          "type": "string",
          "description": "Partial parameters accumulated from tool-call deltas."
        },
        "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"
        },
        "intention": {
          "type": "string",
          "description": "Human-readable description of what the tool invocation intends to do"
        },
        "contributor": {
          "$ref": "#/$defs/ToolCallContributor",
          "description": "Reference to the contributor of the tool being called."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this tool call.\n\nThis MAY include a `ui` field corresponding to the MCP Apps (SEP-1865)\n`McpUiToolMeta` found in MCP tool calls, which may be used in combination\nwith the {@link contributor} to serve MCP Apps."
        },
        "invocationMessage": {
          "$ref": "#/$defs/StringOrMarkdown",
          "description": "Message describing what the tool will do"
        },
        "toolInput": {
          "$ref": "#/$defs/ToolInput",
          "description": "Final tool input.\n\nReferenced input is mutable until the tool call leaves\n`pending-confirmation`. When the client confirms with `editedToolInput`,\nthe host MUST replace the resource contents before echoing the accepted\nconfirmation action. Clients MUST NOT cache tool input across confirmation."
        },
        "status": {
          "const": "pending-confirmation"
        },
        "confirmationTitle": {
          "$ref": "#/$defs/StringOrMarkdown",
          "description": "Short title for the confirmation prompt (e.g. `\"Run in terminal\"`, `\"Write file\"`)"
        },
        "riskAssessment": {
          "$ref": "#/$defs/ToolCallRiskAssessment",
          "description": "Risk assessment that informed the confirmation requirement."
        },
        "edits": {
          "type": "object",
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/FileEdit"
              }
            }
          },
          "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"
      ]
    },
    "ToolCallPostConfirmationFields": {
      "type": "object",
      "description": "Fields present on every tool call state that exists **after** confirmation\nhas been resolved: {@link ToolCallRunningState}, {@link ToolCallAuthRequiredState},\n{@link ToolCallPendingResultConfirmationState}, and {@link ToolCallCompletedState}.\n`ToolCallPendingConfirmationState` (not yet confirmed) and\n`ToolCallCancelledState` (the denial path — never ran) don't satisfy this\ninvariant, so they keep their own `selectedOption` field independently\nrather than extending this one.",
      "properties": {
        "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": [
        "confirmed"
      ]
    },
    "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"
        },
        "intention": {
          "type": "string",
          "description": "Human-readable description of what the tool invocation intends to do"
        },
        "contributor": {
          "$ref": "#/$defs/ToolCallContributor",
          "description": "Reference to the contributor of the tool being called."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this tool call.\n\nThis MAY include a `ui` field corresponding to the MCP Apps (SEP-1865)\n`McpUiToolMeta` found in MCP tool calls, which may be used in combination\nwith the {@link contributor} to serve MCP Apps."
        },
        "invocationMessage": {
          "$ref": "#/$defs/StringOrMarkdown",
          "description": "Message describing what the tool will do"
        },
        "toolInput": {
          "$ref": "#/$defs/ToolInput",
          "description": "Final tool input.\n\nReferenced input is mutable until the tool call leaves\n`pending-confirmation`. When the client confirms with `editedToolInput`,\nthe host MUST replace the resource contents before echoing the accepted\nconfirmation action. Clients MUST NOT cache tool input across confirmation."
        },
        "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"
        },
        "status": {
          "const": "running"
        },
        "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",
        "confirmed",
        "status"
      ]
    },
    "ToolCallAuthRequiredState": {
      "type": "object",
      "description": "A running tool call is paused because the MCP server backing it needs\nauthentication — most commonly {@link McpAuthRequirement.reason |\n`insufficientScope`} step-up auth triggered by the `tools/call` request\nitself. Only ever reached from {@link ToolCallRunningState}, and normally\nreturns there once authenticated: `running` → `auth-required` → `running`\n→ …. A client MAY instead cancel the invocation without authenticating by\ndispatching a `chat/toolCallComplete` with a **failed** result, always\nmoving straight to {@link ToolCallCompletedState} —\n`requiresResultConfirmation` is ignored on this path, so it can never\nenter {@link ToolCallPendingResultConfirmationState}. A **successful**\nresult dispatched from this state is invalid and MUST be rejected/ignored\nas a no-op by the reducer, since execution never resumed after the\nchallenge.\n\nThis is the tool-call-level counterpart to\n{@link McpServerAuthRequiredState} — that state means the MCP *server*\ncannot serve any request; this one means *this specific invocation* is\nwaiting on the same kind of challenge. The two are dispatched\nindependently and MAY be true at the same time, or not: an\n`insufficientScope` challenge triggered by a single tool call, for\nexample, need not block the whole server.\n\nBecause the challenge is always resolved by pushing a token via the\nexisting `authenticate` command, this state can only originate from a\ntool call {@link ToolCallContributorKind.MCP | contributed by an MCP\nserver} — `contributor` is narrowed accordingly (unlike the optional,\nmulti-kind `contributor` on other 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"
        },
        "intention": {
          "type": "string",
          "description": "Human-readable description of what the tool invocation intends to do"
        },
        "contributor": {
          "$ref": "#/$defs/ToolCallMcpContributor",
          "description": "The MCP server that contributed this tool call — always MCP, never a client tool."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this tool call.\n\nThis MAY include a `ui` field corresponding to the MCP Apps (SEP-1865)\n`McpUiToolMeta` found in MCP tool calls, which may be used in combination\nwith the {@link contributor} to serve MCP Apps."
        },
        "invocationMessage": {
          "$ref": "#/$defs/StringOrMarkdown",
          "description": "Message describing what the tool will do"
        },
        "toolInput": {
          "$ref": "#/$defs/ToolInput",
          "description": "Final tool input.\n\nReferenced input is mutable until the tool call leaves\n`pending-confirmation`. When the client confirms with `editedToolInput`,\nthe host MUST replace the resource contents before echoing the accepted\nconfirmation action. Clients MUST NOT cache tool input across confirmation."
        },
        "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"
        },
        "status": {
          "const": "auth-required"
        },
        "auth": {
          "$ref": "#/$defs/McpAuthRequirement",
          "description": "The authentication challenge blocking this invocation."
        },
        "content": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ToolResultContent"
          },
          "description": "Partial content produced before the call paused for authentication."
        }
      },
      "required": [
        "toolCallId",
        "toolName",
        "displayName",
        "contributor",
        "invocationMessage",
        "confirmed",
        "status",
        "auth"
      ]
    },
    "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"
        },
        "intention": {
          "type": "string",
          "description": "Human-readable description of what the tool invocation intends to do"
        },
        "contributor": {
          "$ref": "#/$defs/ToolCallContributor",
          "description": "Reference to the contributor of the tool being called."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this tool call.\n\nThis MAY include a `ui` field corresponding to the MCP Apps (SEP-1865)\n`McpUiToolMeta` found in MCP tool calls, which may be used in combination\nwith the {@link contributor} to serve MCP Apps."
        },
        "invocationMessage": {
          "$ref": "#/$defs/StringOrMarkdown",
          "description": "Message describing what the tool will do"
        },
        "toolInput": {
          "$ref": "#/$defs/ToolInput",
          "description": "Final tool input.\n\nReferenced input is mutable until the tool call leaves\n`pending-confirmation`. When the client confirms with `editedToolInput`,\nthe host MUST replace the resource contents before echoing the accepted\nconfirmation action. Clients MUST NOT cache tool input across confirmation."
        },
        "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"
        },
        "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"
        },
        "status": {
          "const": "pending-result-confirmation"
        }
      },
      "required": [
        "toolCallId",
        "toolName",
        "displayName",
        "invocationMessage",
        "success",
        "pastTenseMessage",
        "confirmed",
        "status"
      ]
    },
    "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"
        },
        "intention": {
          "type": "string",
          "description": "Human-readable description of what the tool invocation intends to do"
        },
        "contributor": {
          "$ref": "#/$defs/ToolCallContributor",
          "description": "Reference to the contributor of the tool being called."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this tool call.\n\nThis MAY include a `ui` field corresponding to the MCP Apps (SEP-1865)\n`McpUiToolMeta` found in MCP tool calls, which may be used in combination\nwith the {@link contributor} to serve MCP Apps."
        },
        "invocationMessage": {
          "$ref": "#/$defs/StringOrMarkdown",
          "description": "Message describing what the tool will do"
        },
        "toolInput": {
          "$ref": "#/$defs/ToolInput",
          "description": "Final tool input.\n\nReferenced input is mutable until the tool call leaves\n`pending-confirmation`. When the client confirms with `editedToolInput`,\nthe host MUST replace the resource contents before echoing the accepted\nconfirmation action. Clients MUST NOT cache tool input across confirmation."
        },
        "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"
        },
        "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"
        },
        "status": {
          "const": "completed"
        }
      },
      "required": [
        "toolCallId",
        "toolName",
        "displayName",
        "invocationMessage",
        "success",
        "pastTenseMessage",
        "confirmed",
        "status"
      ]
    },
    "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"
        },
        "intention": {
          "type": "string",
          "description": "Human-readable description of what the tool invocation intends to do"
        },
        "contributor": {
          "$ref": "#/$defs/ToolCallContributor",
          "description": "Reference to the contributor of the tool being called."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Additional provider-specific metadata for this tool call.\n\nThis MAY include a `ui` field corresponding to the MCP Apps (SEP-1865)\n`McpUiToolMeta` found in MCP tool calls, which may be used in combination\nwith the {@link contributor} to serve MCP Apps."
        },
        "invocationMessage": {
          "$ref": "#/$defs/StringOrMarkdown",
          "description": "Message describing what the tool will do"
        },
        "toolInput": {
          "$ref": "#/$defs/ToolInput",
          "description": "Final tool input.\n\nReferenced input is mutable until the tool call leaves\n`pending-confirmation`. When the client confirms with `editedToolInput`,\nthe host MUST replace the resource contents before echoing the accepted\nconfirmation action. Clients MUST NOT cache tool input across confirmation."
        },
        "status": {
          "const": "cancelled"
        },
        "reason": {
          "$ref": "#/$defs/ToolCallCancellationReason",
          "description": "Why the tool was cancelled"
        },
        "reasonMessage": {
          "$ref": "#/$defs/StringOrMarkdown",
          "description": "Optional message explaining the cancellation"
        },
        "userSuggestion": {
          "$ref": "#/$defs/Message",
          "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"
      ]
    },
    "ToolResultTextContent": {
      "type": "object",
      "description": "Text content in a tool result.\n\nMirrors MCP `TextContent`.",
      "properties": {
        "type": {
          "const": "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": {
          "const": "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"
        },
        "nonce": {
          "type": "string",
          "description": "Content nonce"
        },
        "type": {
          "const": "resource"
        }
      },
      "required": [
        "uri",
        "type"
      ]
    },
    "ToolResultFileEditContent": {
      "type": "object",
      "description": "Describes a file modification performed by a tool.",
      "properties": {
        "before": {
          "type": "object",
          "properties": {
            "uri": {
              "$ref": "#/$defs/URI"
            },
            "content": {
              "$ref": "#/$defs/ContentRef"
            }
          },
          "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": {
              "$ref": "#/$defs/URI"
            },
            "content": {
              "$ref": "#/$defs/ContentRef"
            }
          },
          "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": {
          "const": "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.\n\nWhen the command exits, {@link result} is filled in on the completed\nresult, retaining the outcome for clients that did not subscribe. This\nrecords the command's exit, not the terminal's — the terminal may keep\nrunning afterwards.",
      "properties": {
        "type": {
          "const": "terminal"
        },
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "Terminal URI (subscribable for full terminal state)"
        },
        "title": {
          "type": "string",
          "description": "Display title for the terminal content"
        },
        "isPty": {
          "type": "boolean",
          "description": "Whether this terminal-style resource is backed by a pseudoterminal.\nWhen `false`, output is plain text and clients do not need to parse\nVT sequences."
        },
        "result": {
          "$ref": "#/$defs/TerminalCommandResult",
          "description": "Outcome of the command, present once it has exited."
        }
      },
      "required": [
        "type",
        "resource",
        "title"
      ]
    },
    "TerminalCommandResult": {
      "type": "object",
      "description": "Outcome of a command run in a terminal-style tool, filled in on\n{@link ToolResultTerminalContent.result} once the command exits.",
      "properties": {
        "exitCode": {
          "type": "number",
          "description": "Exit code from the completed command, if reported by the runtime"
        },
        "preview": {
          "type": "string",
          "description": "Preview of the command's output, for clients that are not subscribed\nto the terminal or that arrive after it is disposed. When `isPty` is\n`true` the preview may contain VT sequences; when `false` it is plain\ntext."
        },
        "truncated": {
          "type": "boolean",
          "description": "Whether `preview` is known to be incomplete or truncated"
        }
      }
    },
    "ToolResultSubagentContent": {
      "type": "object",
      "description": "A reference, embedded in a tool result, to a worker chat spawned by the tool\ncall (a sub-agent delegation), referenced by a chat URI (`ahp-chat:/...`).\n\nThis is the spawning tool call's forward view of the worker. The worker chat\nrecords the same edge in reverse via its {@link ChatOrigin} (`kind: 'tool'`),\nwhose `toolCallId` identifies the tool call that emitted this content.",
      "properties": {
        "type": {
          "const": "subagent"
        },
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "Worker chat URI (subscribable for full chat 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"
      ]
    },
    "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"
        },
        "lifecycle": {
          "$ref": "#/$defs/TerminalLifecycleState",
          "description": "Current terminal process lifecycle."
        }
      },
      "required": [
        "resource",
        "title",
        "claim",
        "lifecycle"
      ]
    },
    "TerminalRunningLifecycleState": {
      "type": "object",
      "description": "A terminal process that is still running.",
      "properties": {
        "status": {
          "const": "running"
        }
      },
      "required": [
        "status"
      ]
    },
    "TerminalExitedLifecycleState": {
      "type": "object",
      "description": "A terminal process that has exited.",
      "properties": {
        "status": {
          "const": "exited"
        },
        "exitCode": {
          "type": "number",
          "description": "Process exit code, if the runtime reported one."
        }
      },
      "required": [
        "status"
      ]
    },
    "TerminalClientClaim": {
      "type": "object",
      "description": "A terminal claimed by a connected client.",
      "properties": {
        "kind": {
          "const": "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": {
          "const": "session",
          "description": "Discriminant"
        },
        "session": {
          "$ref": "#/$defs/URI",
          "description": "Session URI that claimed the terminal"
        },
        "chat": {
          "$ref": "#/$defs/URI",
          "description": "Chat URI that claimed the terminal."
        },
        "turnId": {
          "type": "string",
          "description": "Optional turn identifier within the chat."
        },
        "toolCallId": {
          "type": "string",
          "description": "Optional tool call identifier within the turn"
        }
      },
      "required": [
        "kind",
        "session",
        "chat"
      ]
    },
    "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."
        },
        "lifecycle": {
          "$ref": "#/$defs/TerminalLifecycleState",
          "description": "Current terminal process lifecycle."
        },
        "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."
        },
        "isPty": {
          "type": "boolean",
          "description": "Whether this terminal-style resource is backed by a pseudoterminal.\nWhen `false`, output is plain text and clients do not need to parse\nVT sequences."
        }
      },
      "required": [
        "title",
        "content",
        "lifecycle",
        "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"
      ]
    },
    "Changeset": {
      "type": "object",
      "description": "Catalogue entry describing one changeset the server can produce for a\nsession.\n\nCatalogue entries are intentionally lightweight — just enough to render a\nchip or list row without subscribing. Full per-changeset detail\n({@link ChangesetState}) lives on the subscribable URI obtained by\nexpanding {@link uriTemplate}.",
      "properties": {
        "label": {
          "type": "string",
          "description": "Human-readable label, e.g. `\"Uncommitted Changes\"`."
        },
        "uriTemplate": {
          "type": "string",
          "description": "RFC 6570 URI template. Clients parse the variables directly out of the\ntemplate using the standard `{name}` syntax — they are not redeclared\nhere.\n\nOnly the following template shapes are defined by this protocol; any\nother variable name MUST be ignored by clients (there is no\nprotocol-defined way to obtain values for unknown variables):\n\n| Variables in template                       | Meaning                                                                              |\n| ------------------------------------------- | ------------------------------------------------------------------------------------ |\n| _(none)_                                    | A static, session-wide changeset. The template is itself a subscribable URI.         |\n| `{turnId}`                                  | Per-turn slice. Expand with a `Turn.id` from the session.                            |\n| `{originalTurnId}` and `{modifiedTurnId}`   | Diff between two turns. Both variables MUST be present.                              |\n\nFuture protocol versions MAY add new well-known variables."
        },
        "description": {
          "type": "string",
          "description": "Optional longer description."
        },
        "changeKind": {
          "type": "string",
          "description": "Advisory hint describing what kind of changeset this is, so clients can\ngroup, sort, or render an appropriate icon without parsing\n{@link uriTemplate}. Recognized values include:\n\n- `'session'`: a static, session-wide changeset covering all changes the\n  agent has produced in this session.\n- `'branch'`: changes relative to a base branch (e.g. a feature branch\n  diffed against `main`).\n- `'uncommitted'`: the workspace's current uncommitted changes.\n- `'turn'`: changes produced by a single turn. Typically paired with a\n  `{turnId}` variable in {@link uriTemplate}.\n- `'compare-turns'`: a diff between two turns. Typically paired with\n  `{originalTurnId}` and `{modifiedTurnId}` variables in\n  {@link uriTemplate}.\n\nImplementations MAY provide additional values; clients SHOULD fall back\nto a reasonable default when an unknown value is encountered."
        },
        "capabilities": {
          "$ref": "#/$defs/ChangesetCapabilities",
          "description": "Optional capability declarations for this changeset. Absent (or an empty\nobject) means the changeset advertises no optional capabilities.\n\nBecause the catalogue entry is delivered up-front on\n{@link ChangesetState | the session's changeset list}, clients can decide\nwhether to surface capability-gated UI (such as review checkboxes) without\nfirst subscribing to the changeset URI. Mirrors the presence-flag\nconvention of `ClientCapabilities`."
        }
      },
      "required": [
        "label",
        "uriTemplate",
        "changeKind"
      ]
    },
    "ChangesetCapabilities": {
      "type": "object",
      "description": "Optional capabilities a changeset advertises on its catalogue\n{@link Changeset} entry.\n\nEach field is a presence flag: an empty object `{}` means \"supported\",\nabsence means \"not supported\". Sub-fields on individual capabilities are\nreserved for future per-capability options.",
      "properties": {
        "review": {
          "type": "object",
          "additionalProperties": {},
          "description": "The changeset supports the per-file **review** workflow. When declared,\nclients MAY surface a GitHub-style \"Viewed\" toggle per file and dispatch\n{@link ChangesetFilesReviewChangedAction | `changeset/filesReviewChanged`} to\nset each file's {@link ChangesetFile.reviewed} flag. Clients that omit\nhandling MUST treat the changeset as non-reviewable."
        }
      }
    },
    "ChangesetState": {
      "type": "object",
      "description": "Full state for a single changeset, returned when a client subscribes to\nan expanded changeset URI.\n\nThe client already knows the URI it subscribed to, so this state does\nnot redundantly carry it (or the catalogue's `id`, `label`, etc.).\nAggregate counts (`additions`, `deletions`, `files`) are likewise\nomitted: clients trivially compute them from `files[].edit.diff`.",
      "properties": {
        "status": {
          "$ref": "#/$defs/ChangesetStatus",
          "description": "Computation lifecycle."
        },
        "error": {
          "$ref": "#/$defs/ErrorInfo",
          "description": "Present iff `status === ChangesetStatus.Error`."
        },
        "files": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChangesetFile"
          },
          "description": "Files in this changeset, keyed by {@link ChangesetFile.id}."
        },
        "operations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChangesetOperation"
          },
          "description": "Operations the client may invoke against this changeset. Omit when no\noperations are available."
        }
      },
      "required": [
        "status",
        "files"
      ]
    },
    "ChangesetFile": {
      "type": "object",
      "description": "One file entry within a {@link ChangesetState}.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier within the changeset. Typically `after.uri`\n(or `before.uri` for deletions)."
        },
        "edit": {
          "$ref": "#/$defs/FileEdit",
          "description": "Reuses the existing {@link FileEdit} shape. Clients derive line\nadditions, deletions, and rename/create/delete semantics from this."
        },
        "reviewed": {
          "type": "boolean",
          "description": "Whether a reviewer has marked this file as reviewed (the GitHub-style\n\"Viewed\" checkbox). Absent is equivalent to `false` — clients MUST treat\na missing value as not-yet-reviewed.\n\nRequires the changeset to advertise {@link ChangesetCapabilities.review}.\nClients toggle it by dispatching\n{@link ChangesetFilesReviewChangedAction | `changeset/filesReviewChanged`};\nthe server MAY also originate it (e.g. an agent self-reviewing its own\noutput).\n\nThere is no content version in the protocol, so review is **not** reset\nautomatically when a file's contents change under a stable id. The server,\nwhich is the authority on what changed, resets review explicitly — either\nby re-emitting the file (via {@link ChangesetFileSetAction} or\n{@link ChangesetContentChangedAction}) without `reviewed: true`, or by\ndispatching `changeset/filesReviewChanged` with `reviewed: false`."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Server-defined opaque metadata, surfaced to operations and tooling\nbut not interpreted by the protocol."
        }
      },
      "required": [
        "id",
        "edit"
      ]
    },
    "ChangesetOperation": {
      "type": "object",
      "description": "A server-declared invokable verb the client can run against a\nchangeset, a file, or a range — `\"stage\"`, `\"revert\"`, `\"create-pr\"`,\nand so on.\n\nThe term \"operation\" is used deliberately to avoid colliding with the\nprotocol-level [Actions](/guide/actions) that mutate state.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier, unique within this changeset."
        },
        "label": {
          "type": "string",
          "description": "Human-readable button/menu label."
        },
        "description": {
          "type": "string",
          "description": "Optional longer description shown on hover or in tooltips."
        },
        "scopes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChangesetOperationScope"
          },
          "description": "Where this operation can be invoked."
        },
        "confirmation": {
          "$ref": "#/$defs/StringOrMarkdown",
          "description": "Optional confirmation prompt to show before invoking. When present,\nthe client MUST display this message to the user (typically in a\nconfirmation dialog) and only invoke the operation after the user\naccepts. The presence of this field also signals that the operation\nis destructive — clients SHOULD style the affirmative button\naccordingly (e.g. with a warning colour)."
        },
        "icon": {
          "type": "string",
          "description": "Optional generic icon hint, e.g. `\"check\"`, `\"trash\"`."
        },
        "group": {
          "type": "string",
          "description": "Optional group identifier, used to group related operations together."
        },
        "status": {
          "$ref": "#/$defs/ChangesetOperationStatus",
          "description": "Current execution status. The server sets\n{@link ChangesetOperationStatus.Running | Running} while an invocation\nis in flight, {@link ChangesetOperationStatus.Error | Error} when the\nmost recent invocation failed, and\n{@link ChangesetOperationStatus.Idle | Idle} otherwise.\n\nClients SHOULD reflect this state in the UI — e.g. disabling the\ncontrol or showing a spinner while `Running`, and surfacing\n{@link error} while `Error`."
        },
        "error": {
          "$ref": "#/$defs/ErrorInfo",
          "description": "Cause of failure. Present iff\n`status === ChangesetOperationStatus.Error`; otherwise omitted."
        }
      },
      "required": [
        "id",
        "label",
        "scopes",
        "status"
      ]
    },
    "AnnotationsSummary": {
      "type": "object",
      "description": "Lightweight per-session summary of the annotations channel, surfaced on\n{@link SessionSummary.annotations} so badge UI can render annotation /\nentry counts without subscribing to the channel itself.",
      "properties": {
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "The subscribable annotations channel URI for the owning session\n(typically `ahp-session:/<uuid>/annotations`). Surfaced explicitly even\nthough it is derivable from the session URI so badge UI does not need\nto know the derivation rule."
        },
        "annotationCount": {
          "type": "number",
          "description": "Total number of {@link Annotation} entries in the channel."
        },
        "entryCount": {
          "type": "number",
          "description": "Total number of {@link AnnotationEntry} entries across every annotation."
        }
      },
      "required": [
        "resource",
        "annotationCount",
        "entryCount"
      ]
    },
    "AnnotationsState": {
      "type": "object",
      "description": "Full state for a session's annotations channel, returned when a client\nsubscribes to an `ahp-session:/<uuid>/annotations` URI.",
      "properties": {
        "annotations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Annotation"
          },
          "description": "Annotations in this channel, keyed by {@link Annotation.id}."
        }
      },
      "required": [
        "annotations"
      ]
    },
    "AnnotationOrigin": {
      "type": "object",
      "description": "Provenance of the content an annotation is anchored to.",
      "properties": {
        "session": {
          "$ref": "#/$defs/URI",
          "description": "Owning session URI."
        },
        "chat": {
          "$ref": "#/$defs/URI",
          "description": "Owning chat URI, when the annotation is scoped to a chat."
        },
        "turnId": {
          "type": "string",
          "description": "Turn identifier within {@link chat}, when the annotation is scoped to a turn."
        }
      },
      "required": [
        "session"
      ]
    },
    "Annotation": {
      "type": "object",
      "description": "A conversation anchored to a specific file in a session, optionally scoped\nto a chat and turn and narrowed to a range within that file.\n\n{@link origin} identifies the owning session and, when available, the chat\nand turn that produced the file version. When {@link range} is omitted the\nannotation is anchored to the entire file.\n\nEvery annotation MUST contain at least one {@link AnnotationEntry}. An\n{@link AnnotationsSetAction} that creates an annotation therefore carries\nits mandatory first entry, and removing the last remaining entry collapses\nthe annotation via {@link AnnotationsRemovedAction} rather than leaving an\nempty annotation behind.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier within the annotations channel. Assigned by the client\nthat dispatches the creating {@link AnnotationsSetAction}."
        },
        "origin": {
          "$ref": "#/$defs/AnnotationOrigin",
          "description": "Provenance of the content this annotation is anchored to."
        },
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "The file the annotation is anchored to."
        },
        "range": {
          "$ref": "#/$defs/TextRange",
          "description": "Range within {@link resource} the annotation is anchored to. When\nomitted the annotation is anchored to the entire file."
        },
        "resolved": {
          "type": "boolean",
          "description": "Whether the annotation has been resolved. Newly created annotations are\nalways unresolved (`false`); a client marks an annotation resolved (or\nre-opens it) by dispatching an {@link AnnotationsUpdatedAction} carrying\nthe updated flag (or an {@link AnnotationsSetAction} when replacing the\nwhole annotation)."
        },
        "entries": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AnnotationEntry"
          },
          "description": "Entries in this annotation, in dispatch order (oldest first). MUST\ncontain at least one entry."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Producer-defined opaque metadata, surfaced to tooling but not\ninterpreted by the protocol."
        }
      },
      "required": [
        "id",
        "origin",
        "resource",
        "resolved",
        "entries"
      ]
    },
    "AnnotationEntry": {
      "type": "object",
      "description": "A single entry within an {@link Annotation}.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier within the enclosing annotation. Assigned by the client\nthat dispatches the {@link AnnotationsEntrySetAction} (or the enclosing\n{@link AnnotationsSetAction}) introducing the entry."
        },
        "text": {
          "$ref": "#/$defs/StringOrMarkdown",
          "description": "Entry body. A bare `string` is rendered as plain text; pass\n`{ markdown: \"…\" }` to opt into Markdown rendering. See\n{@link StringOrMarkdown}."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Producer-defined opaque metadata, surfaced to tooling but not\ninterpreted by the protocol."
        }
      },
      "required": [
        "id",
        "text"
      ]
    },
    "TelemetryCapabilities": {
      "type": "object",
      "description": "OTLP telemetry channels the agent host emits.\n\nEach field, when present, is either a literal channel URI or an\n[RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570) URI template\na client expands and then subscribes to. Absent fields indicate the host\ndoes not emit that signal.\n\nChannel URIs use the `ahp-otlp:` scheme. The scheme identifies the\nprotocol (OpenTelemetry over AHP) so clients can recognise the channel\ntype by URI alone; the host is free to choose any authority/path that\nmakes sense for its implementation. Clients MUST treat the URI as\nopaque (apart from expanding any well-known template variables defined\nbelow) and subscribe with the resulting concrete URI.\n\nPayloads delivered on these channels are OTLP/JSON values — see\n[opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto)\nfor the wire shapes (`ExportLogsServiceRequest`,\n`ExportTraceServiceRequest`, `ExportMetricsServiceRequest`).",
      "properties": {
        "logs": {
          "$ref": "#/$defs/URI",
          "description": "Channel URI (or RFC 6570 URI template) for OTLP log records\n(`otlp/exportLogs` notifications).\n\nThe following template variables are defined by this protocol; any\nother variable name MUST be ignored by clients (there is no\nprotocol-defined way to obtain values for unknown variables):\n\n| Variables in template | Meaning                                                                                                 |\n| --------------------- | ------------------------------------------------------------------------------------------------------- |\n| _(none)_              | The host does not support subscriber-side severity filtering. The template is itself a subscribable URI. |\n| `{level}`             | Minimum OTLP severity to deliver. Expand to one of the [OTLP `SeverityNumber`](https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber) short names (case-insensitive): `trace`, `debug`, `info`, `warn`, `error`, `fatal`. The server delivers log records whose `severityNumber` falls in the corresponding band or above. |\n\nHosts SHOULD honour the expanded `{level}`; clients MUST still filter\ndefensively in case a host ignores the parameter. Hosts that do not\nadvertise `{level}` deliver all severities.\n\nFuture protocol versions MAY add new well-known variables (e.g. scope\nor attribute filters)."
        },
        "traces": {
          "$ref": "#/$defs/URI",
          "description": "Channel URI for OTLP spans (`otlp/exportTraces` notifications). No\ntemplate variables are defined by this protocol version."
        },
        "metrics": {
          "$ref": "#/$defs/URI",
          "description": "Channel URI for OTLP metric data points (`otlp/exportMetrics`\nnotifications). No template variables are defined by this protocol\nversion."
        }
      }
    },
    "ResourceWatchState": {
      "type": "object",
      "description": "Full state for a single resource watch, returned when a client subscribes\nto an `ahp-resource-watch:` URI.\n\nWatches are otherwise stateless: the watcher exists to deliver\n{@link ResourceWatchChangedAction} events. The state carries only the\ndescriptor of what is being watched so a re-subscribing client can\nrecover the watch configuration after reconnecting.",
      "properties": {
        "root": {
          "$ref": "#/$defs/URI",
          "description": "The URI being watched. For recursive watches this is the root of the\nsubtree; for non-recursive watches this is the single file or\ndirectory."
        },
        "recursive": {
          "type": "boolean",
          "description": "`true` if the watcher reports changes for descendants of `root`;\n`false` if it only reports changes to `root` itself (and, when\n`root` is a directory, its direct children)."
        },
        "excludes": {
          "type": "object",
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "items"
          ],
          "description": "Optional glob patterns or paths relative to `root` to exclude from\nchange reporting."
        },
        "includes": {
          "type": "object",
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "items"
          ],
          "description": "Optional glob patterns or paths relative to `root` to restrict\nchange reporting to. Omit to report every change under `root`\nsubject to `excludes`."
        }
      },
      "required": [
        "root",
        "recursive"
      ]
    },
    "ResourceChange": {
      "type": "object",
      "description": "A single change observed by a resource watcher.",
      "properties": {
        "uri": {
          "$ref": "#/$defs/URI",
          "description": "The URI of the resource that changed."
        },
        "type": {
          "$ref": "#/$defs/ResourceChangeType",
          "description": "The kind of change observed."
        }
      },
      "required": [
        "uri",
        "type"
      ]
    },
    "AutomationSchedule": {
      "type": "object",
      "description": "A portable recurring schedule evaluated in a named time zone.\n\nThe expression uses exactly five whitespace-separated fields, in this\norder:\n\n| Field | Values |\n| --- | --- |\n| minute | `0`–`59` |\n| hour | `0`–`23` |\n| day of month | `1`–`31` |\n| month | `1`–`12` or `JAN`–`DEC` |\n| day of week | `0`–`7` or `SUN`–`SAT`; both `0` and `7` mean Sunday |\n\nMonth and weekday names are ASCII and case-insensitive. Each field accepts\n`*`, a single value, an inclusive range (`1-5`), a comma-separated list of\nvalues or ranges (`1,3,8-10`), or a step applied to `*` or a range (for\nexample, &#42;/15 or `1-30/2`). A step MUST be a positive integer. AHP does\nnot support seconds, years, macros such as `@daily`, or Quartz extensions\nsuch as `?`, `L`, `W`, and `#`.\n\nMinute, hour, and month must all match. When both day-of-month and\nday-of-week are restricted (not `*`), an occurrence matches when either day\nfield matches, following Unix cron semantics.",
      "properties": {
        "expression": {
          "type": "string",
          "description": "Five-field AHP cron expression described by {@link AutomationSchedule}."
        },
        "timeZone": {
          "type": "string",
          "description": "IANA Time Zone Database identifier used to interpret the expression, for\nexample `\"UTC\"` or `\"Europe/Berlin\"`."
        }
      },
      "required": [
        "expression",
        "timeZone"
      ]
    },
    "AutomationScheduleTrigger": {
      "type": "object",
      "description": "Starts runs from a recurring cron schedule evaluated by the host.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Identifier unique and stable within this automation definition. Recorded in\n{@link AutomationTriggeredRunOrigin.triggerId} when this trigger creates a\nrun."
        },
        "kind": {
          "const": "schedule"
        },
        "schedule": {
          "$ref": "#/$defs/AutomationSchedule",
          "description": "Recurrence and time zone evaluated by the host."
        },
        "misfirePolicy": {
          "$ref": "#/$defs/AutomationMisfirePolicy",
          "description": "Policy for missed occurrences. Omission is equivalent to\n{@link AutomationMisfirePolicy.RunOnce}."
        }
      },
      "required": [
        "id",
        "kind",
        "schedule"
      ]
    },
    "AutomationEventTrigger": {
      "type": "object",
      "description": "Starts runs from events understood by the owning host.\n\nEvent trigger types, events, and configuration are discovered through\n{@link ListAutomationTriggerDefinitionsParams |\nlistAutomationTriggerDefinitions}. The saved trigger includes the matching\nhuman-readable metadata so it remains displayable without repeating\ndiscovery.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Identifier unique and stable within this automation definition. Recorded in\n{@link AutomationTriggeredRunOrigin.triggerId} when this trigger creates a\nrun."
        },
        "kind": {
          "const": "event"
        },
        "type": {
          "type": "string",
          "description": "Matches {@link AutomationTriggerDefinition.type}."
        },
        "title": {
          "type": "string",
          "description": "Host-normalized human-readable trigger type name."
        },
        "description": {
          "type": "string",
          "description": "Optional host-normalized explanation of the trigger source."
        },
        "events": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AutomationTriggerEventDefinition"
          },
          "description": "Selected events for this trigger type.\n\nEvent ids carry the trigger semantics. Titles and descriptions are\nlast-known display metadata and do not indicate current availability."
        },
        "config": {
          "type": "object",
          "additionalProperties": {},
          "description": "Values described by {@link AutomationTriggerDefinition.configSchema}.\nClients MUST preserve unknown entries when editing other fields."
        }
      },
      "required": [
        "id",
        "kind",
        "type",
        "title",
        "events"
      ]
    },
    "AutomationTriggerEventDefinition": {
      "type": "object",
      "description": "Describes one host-defined trigger event.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable event id."
        },
        "title": {
          "type": "string",
          "description": "Human-readable event name."
        },
        "description": {
          "type": "string",
          "description": "Optional longer explanation of when this event fires."
        }
      },
      "required": [
        "id",
        "title"
      ]
    },
    "AutomationTriggerDefinition": {
      "type": "object",
      "description": "Describes one host-defined event trigger type available for a prospective\nautomation session template.\n\nTrigger definitions are discovery metadata, not durable automation state.\nHosts may return different definitions for different providers, working\ndirectories, or session configuration.",
      "properties": {
        "type": {
          "type": "string",
          "description": "Stable type id stored in {@link AutomationEventTrigger.type}."
        },
        "title": {
          "type": "string",
          "description": "Human-readable trigger type name."
        },
        "description": {
          "type": "string",
          "description": "Optional longer explanation of the trigger source."
        },
        "events": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AutomationTriggerEventDefinition"
          },
          "description": "Events available for selection. Saved triggers retain their selected event descriptors."
        },
        "configSchema": {
          "$ref": "#/$defs/ConfigSchema",
          "description": "Optional schema for {@link AutomationEventTrigger.config}."
        }
      },
      "required": [
        "type",
        "title",
        "events"
      ]
    },
    "AutomationSessionTemplate": {
      "type": "object",
      "description": "Template from which the host creates a fresh session for each automation run.\n\nThe host revalidates every selection when the run starts. Definitions never\ncarry credentials, confirmation decisions, or durable permission grants.",
      "properties": {
        "provider": {
          "type": "string",
          "description": "Provider id matching {@link AgentInfo.provider}. Omit to use the host's default provider."
        },
        "model": {
          "$ref": "#/$defs/ModelSelection",
          "description": "Optional model selection resolved when a run starts. Its\n{@link ModelSelection.id} matches a {@link SessionModelInfo.id} advertised\nby the selected provider."
        },
        "agent": {
          "$ref": "#/$defs/AgentSelection",
          "description": "Optional custom agent selection identified by {@link AgentSelection.uri}."
        },
        "workingDirectories": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/URI"
          },
          "description": "Ordered working-directory URIs for each created session, equivalent to\n{@link CreateSessionParams.workingDirectories}. Absence means a\nworkspace-less session."
        },
        "config": {
          "type": "object",
          "additionalProperties": {},
          "description": "Session configuration values equivalent to\n{@link CreateSessionParams.config}, normally obtained from\n{@link ResolveSessionConfigResult.values}."
        }
      }
    },
    "AutomationDefinition": {
      "type": "object",
      "description": "Durable, client-editable definition of an automation.\n\nA definition combines the initial automation message, the session template\nused for each run, and zero or more automatic triggers. Run history,\ntimestamps, and currently allowed operations live on\n{@link AutomationEntry} rather than in the definition.",
      "properties": {
        "title": {
          "type": "string",
          "description": "Human-readable automation name."
        },
        "message": {
          "$ref": "#/$defs/Message",
          "description": "Initial message sent to every newly created run session. Its\n{@link Message.origin} kind MUST be {@link MessageKind.Automation}."
        },
        "session": {
          "$ref": "#/$defs/AutomationSessionTemplate",
          "description": "Template used to create fresh sessions for each run."
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether automatic triggers may create runs. Manual runs remain available\nwhenever {@link AutomationOperation.Run} is advertised."
        },
        "triggers": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AutomationTrigger"
          },
          "description": "Automatic triggers. An empty list means manual-only."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Opaque implementation-defined metadata. Clients MUST preserve unknown\nentries when updating the definition."
        }
      },
      "required": [
        "title",
        "message",
        "session",
        "enabled",
        "triggers"
      ]
    },
    "AutomationEntry": {
      "type": "object",
      "description": "Authoritative state of one automation in {@link AutomationState.entries}.\n\nThe host owns trigger evaluation, run claims, run retention, and operation\navailability. Clients render this state and submit actions or commands; they\nnever run a fallback scheduler for a host-owned definition.",
      "properties": {
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "Stable `ahp-automation:/<id>` resource identifier."
        },
        "definition": {
          "$ref": "#/$defs/AutomationDefinition",
          "description": "Current durable definition."
        },
        "nextRunAt": {
          "type": "string",
          "description": "Earliest schedule occurrence awaiting evaluation, as an ISO 8601 timestamp. It may be in the past while catch-up is pending."
        },
        "runs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AutomationRunSummary"
          },
          "description": "Newest-first retained run summaries. This is a bounded window; use\n{@link FetchAutomationRunsParams | fetchAutomationRuns} when\n{@link AutomationEntry.runsNextCursor} is present."
        },
        "runsNextCursor": {
          "type": "string",
          "description": "Opaque cursor passed as {@link FetchAutomationRunsParams.cursor} for the next older run-history page."
        },
        "operations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AutomationOperation"
          },
          "description": "Operations currently permitted for this automation."
        },
        "createdAt": {
          "type": "string",
          "description": "Creation timestamp in ISO 8601 format."
        },
        "modifiedAt": {
          "type": "string",
          "description": "Last definition modification timestamp in ISO 8601 format."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Opaque host-defined state metadata."
        }
      },
      "required": [
        "resource",
        "definition",
        "runs",
        "operations",
        "createdAt",
        "modifiedAt"
      ]
    },
    "AutomationState": {
      "type": "object",
      "description": "Authoritative automation catalogue exposed on the `ahp-automations://`\nchannel.\n\nA subscription snapshot contains every automation visible to the client.\nSubsequent {@link AutomationSetAction | `automation/set`} and\n{@link AutomationRemovedAction | `automation/removed`} actions keep the\ncatalogue synchronized and participate in normal reconnect replay.",
      "properties": {
        "entries": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AutomationEntry"
          },
          "description": "Full automation entries keyed by {@link AutomationEntry.resource}."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Opaque host-defined catalogue metadata."
        }
      },
      "required": [
        "entries"
      ]
    },
    "AutomationManualRunOrigin": {
      "type": "object",
      "description": "Origin recorded for a client-requested manual run.",
      "properties": {
        "kind": {
          "const": "manual"
        }
      },
      "required": [
        "kind"
      ]
    },
    "AutomationTriggeredRunOrigin": {
      "type": "object",
      "description": "Origin recorded for a run created by one of the automation's triggers.",
      "properties": {
        "kind": {
          "const": "trigger"
        },
        "triggerId": {
          "type": "string",
          "description": "Matches the stable {@link AutomationScheduleTrigger.id} or\n{@link AutomationEventTrigger.id} in the definition."
        },
        "scheduledFor": {
          "type": "string",
          "description": "Intended schedule occurrence as an ISO 8601 timestamp. Present for\nschedule triggers and normally absent for event triggers."
        },
        "catchUp": {
          "type": "boolean",
          "description": "`true` when this is a catch-up run created by\n{@link AutomationMisfirePolicy.RunOnce}."
        },
        "event": {
          "type": "object",
          "additionalProperties": {},
          "description": "Host-defined, non-secret event provenance suitable for display or audit.\nThis is descriptive context, not an input that clients replay."
        }
      },
      "required": [
        "kind",
        "triggerId"
      ]
    },
    "AutomationPendingRunLifecycle": {
      "type": "object",
      "description": "A durable run exists but has not begun external execution.",
      "properties": {
        "status": {
          "const": "pending"
        },
        "createdAt": {
          "type": "string",
          "description": "Run creation timestamp in ISO 8601 format."
        }
      },
      "required": [
        "status",
        "createdAt"
      ]
    },
    "AutomationRunningRunLifecycle": {
      "type": "object",
      "description": "The run is executing linked sessions or awaiting interaction on them.\n\nLinked {@link SessionState.status} and {@link SessionState.inputNeeded}\nremain authoritative for whether user attention or client-side work is\nrequired.",
      "properties": {
        "status": {
          "const": "running"
        },
        "createdAt": {
          "type": "string",
          "description": "Run creation timestamp in ISO 8601 format."
        },
        "startedAt": {
          "type": "string",
          "description": "First execution start timestamp in ISO 8601 format."
        }
      },
      "required": [
        "status",
        "createdAt",
        "startedAt"
      ]
    },
    "AutomationCompletedRunLifecycle": {
      "type": "object",
      "description": "Terminal lifecycle for a successfully completed run.",
      "properties": {
        "status": {
          "const": "completed"
        },
        "createdAt": {
          "type": "string",
          "description": "Run creation timestamp in ISO 8601 format."
        },
        "startedAt": {
          "type": "string",
          "description": "First execution start timestamp in ISO 8601 format."
        },
        "completedAt": {
          "type": "string",
          "description": "Completion timestamp in ISO 8601 format."
        },
        "usage": {
          "$ref": "#/$defs/UsageInfo",
          "description": "Optional aggregate model usage across all linked sessions."
        }
      },
      "required": [
        "status",
        "createdAt",
        "startedAt",
        "completedAt"
      ]
    },
    "AutomationFailedRunLifecycle": {
      "type": "object",
      "description": "Terminal lifecycle for a run that ended with an error.\n\n`startedAt` is absent when failure occurred before execution began, such as\nsession-template validation or workspace preparation.",
      "properties": {
        "status": {
          "const": "failed"
        },
        "createdAt": {
          "type": "string",
          "description": "Run creation timestamp in ISO 8601 format."
        },
        "startedAt": {
          "type": "string",
          "description": "First execution start timestamp in ISO 8601 format, when execution began."
        },
        "completedAt": {
          "type": "string",
          "description": "Failure timestamp in ISO 8601 format."
        },
        "error": {
          "$ref": "#/$defs/ErrorInfo",
          "description": "Stable machine-readable and human-readable failure information."
        }
      },
      "required": [
        "status",
        "createdAt",
        "completedAt",
        "error"
      ]
    },
    "AutomationCancelledRunLifecycle": {
      "type": "object",
      "description": "Terminal lifecycle for a cancelled run.\n\n`startedAt` is absent when cancellation completed while the run was still\npending.",
      "properties": {
        "status": {
          "const": "cancelled"
        },
        "createdAt": {
          "type": "string",
          "description": "Run creation timestamp in ISO 8601 format."
        },
        "startedAt": {
          "type": "string",
          "description": "First execution start timestamp in ISO 8601 format, when execution began."
        },
        "completedAt": {
          "type": "string",
          "description": "Cancellation completion timestamp in ISO 8601 format."
        }
      },
      "required": [
        "status",
        "createdAt",
        "completedAt"
      ]
    },
    "AutomationRunSummary": {
      "type": "object",
      "description": "Lightweight projection of a run retained in its automation's history.\n\nA summary contains enough information to render run history without\nsubscribing to every `ahp-automation-run:` resource.",
      "properties": {
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "Subscribable `ahp-automation-run:` URI matching {@link AutomationRunState.resource}."
        },
        "automation": {
          "$ref": "#/$defs/URI",
          "description": "Owning `ahp-automation:` URI matching {@link AutomationRunState.automation}."
        },
        "origin": {
          "$ref": "#/$defs/AutomationRunOrigin",
          "description": "Immutable provenance matching {@link AutomationRunState.origin}."
        },
        "lifecycle": {
          "$ref": "#/$defs/AutomationRunLifecycle",
          "description": "Current or terminal lifecycle snapshot matching {@link AutomationRunState.lifecycle}."
        },
        "primarySession": {
          "$ref": "#/$defs/URI",
          "description": "Session matching {@link AutomationRunState.primarySession}, when selected."
        },
        "sessionCount": {
          "type": "number",
          "description": "Number of entries in {@link AutomationRunState.sessions}."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Opaque host-defined summary metadata."
        }
      },
      "required": [
        "resource",
        "automation",
        "origin",
        "lifecycle",
        "sessionCount"
      ]
    },
    "AutomationRunState": {
      "type": "object",
      "description": "Authoritative state of one subscribed `ahp-automation-run:` resource.\n\nThe run channel owns task-level lifecycle, provenance, and linked-session\nmembership. Linked session and chat channels remain authoritative for\ntranscripts, tools, interaction requirements, changesets, and per-session\nlifecycle.",
      "properties": {
        "resource": {
          "$ref": "#/$defs/URI",
          "description": "URI of this automation-run channel."
        },
        "automation": {
          "$ref": "#/$defs/URI",
          "description": "Owning `ahp-automation:` URI matching {@link AutomationEntry.resource}."
        },
        "origin": {
          "$ref": "#/$defs/AutomationRunOrigin",
          "description": "Immutable provenance describing how this run was created."
        },
        "lifecycle": {
          "$ref": "#/$defs/AutomationRunLifecycle",
          "description": "Current or terminal lifecycle."
        },
        "sessions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/URI"
          },
          "description": "Ordered, unique session URIs belonging to this run, each matching\n{@link SessionState.resource}. Entries may represent retries, parallel\nworkers, or delegated attempts."
        },
        "primarySession": {
          "$ref": "#/$defs/URI",
          "description": "Member of {@link AutomationRunState.sessions} that the host recommends opening first."
        },
        "_meta": {
          "type": "object",
          "additionalProperties": {},
          "description": "Opaque host-defined run metadata."
        }
      },
      "required": [
        "resource",
        "automation",
        "origin",
        "lifecycle",
        "sessions"
      ]
    },
    "StringOrMarkdown": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "properties": {
            "markdown": {
              "type": "string"
            }
          },
          "required": [
            "markdown"
          ]
        }
      ],
      "description": "A string that may optionally be rendered as Markdown.\n\n- A plain `string` is rendered as-is (no Markdown processing).\n- An object with `{ markdown: string }` is rendered with Markdown formatting."
    },
    "JsonPrimitive": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "A primitive JSON value: a string, number, boolean, or `null`."
    },
    "SessionOrigin": {
      "$ref": "#/$defs/AutomationSessionOrigin",
      "description": "Durable provenance for sessions created by a higher-level AHP workflow."
    },
    "SessionInputRequest": {
      "oneOf": [
        {
          "$ref": "#/$defs/SessionChatInputRequest"
        },
        {
          "$ref": "#/$defs/SessionToolConfirmationRequest"
        },
        {
          "$ref": "#/$defs/SessionToolClientExecutionRequest"
        },
        {
          "$ref": "#/$defs/SessionToolAuthenticationRequest"
        }
      ],
      "description": "One outstanding piece of input a session is blocked on, aggregated across all\nchats in {@link SessionState.inputNeeded}.\n\nEach entry is self-sufficient: it carries the owning\n{@link SessionInputRequestBase.chat | `chat`} URI plus every identifier needed\nto construct the response, so a client can answer by dispatching the ordinary\n`chat/*` action (`chat/inputCompleted`, `chat/toolCallConfirmed`,\n`chat/toolCallComplete`, …) to that chat's channel **without having subscribed\nto the chat** — except {@link SessionToolAuthenticationRequest}, which is\nresolved via the `authenticate` command instead. The host removes the entry\nwith `session/inputNeededRemoved` once the underlying request resolves."
    },
    "CustomizationEnablement": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "global"
            },
            "enabled": {
              "type": "boolean"
            }
          },
          "required": [
            "kind",
            "enabled"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "workspace"
            },
            "uri": {
              "$ref": "#/$defs/URI"
            },
            "enabled": {
              "type": "boolean"
            }
          },
          "required": [
            "kind",
            "uri",
            "enabled"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "session"
            },
            "enabled": {
              "type": "boolean"
            }
          },
          "required": [
            "kind",
            "enabled"
          ]
        }
      ],
      "description": "A single explicit enablement decision."
    },
    "ChildCustomizationType": {
      "oneOf": [
        {
          "const": "agent"
        },
        {
          "const": "skill"
        },
        {
          "const": "prompt"
        },
        {
          "const": "rule"
        },
        {
          "const": "hook"
        },
        {
          "const": "mcpServer"
        }
      ],
      "description": "Customization types that appear as children of a\n{@link PluginCustomization} or {@link DirectoryCustomization}."
    },
    "CustomizationLoadState": {
      "oneOf": [
        {
          "$ref": "#/$defs/CustomizationLoadingState"
        },
        {
          "$ref": "#/$defs/CustomizationLoadedState"
        },
        {
          "$ref": "#/$defs/CustomizationDegradedState"
        },
        {
          "$ref": "#/$defs/CustomizationErrorState"
        }
      ],
      "description": "Discriminated load state for a container customization\n({@link PluginCustomization} or {@link DirectoryCustomization})."
    },
    "ChildCustomization": {
      "oneOf": [
        {
          "$ref": "#/$defs/AgentCustomization"
        },
        {
          "$ref": "#/$defs/SkillCustomization"
        },
        {
          "$ref": "#/$defs/PromptCustomization"
        },
        {
          "$ref": "#/$defs/RuleCustomization"
        },
        {
          "$ref": "#/$defs/HookCustomization"
        },
        {
          "$ref": "#/$defs/McpServerCustomization"
        }
      ],
      "description": "Child customizations that live inside a {@link PluginCustomization} or\n{@link DirectoryCustomization}."
    },
    "Customization": {
      "oneOf": [
        {
          "$ref": "#/$defs/PluginCustomization"
        },
        {
          "$ref": "#/$defs/DirectoryCustomization"
        },
        {
          "$ref": "#/$defs/McpServerCustomization"
        }
      ],
      "description": "A top-level customization active in a session. Either a container\n({@link PluginCustomization} or {@link DirectoryCustomization}) whose\nleaf customizations live in its\n{@link ContainerCustomizationBase.children | `children`} array, or a\nbare {@link McpServerCustomization} surfaced directly by the host."
    },
    "McpServerState": {
      "oneOf": [
        {
          "$ref": "#/$defs/McpServerStartingState"
        },
        {
          "$ref": "#/$defs/McpServerReadyState"
        },
        {
          "$ref": "#/$defs/McpServerAuthRequiredState"
        },
        {
          "$ref": "#/$defs/McpServerErrorState"
        },
        {
          "$ref": "#/$defs/McpServerStoppedState"
        }
      ],
      "description": "Discriminated union of all MCP server lifecycle states.\nDiscriminated by `kind` (a {@link McpServerStatus} value)."
    },
    "ChatOrigin": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "user"
            }
          },
          "required": [
            "kind"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "fork"
            },
            "chat": {
              "$ref": "#/$defs/URI"
            },
            "turnId": {
              "type": "string"
            }
          },
          "required": [
            "kind",
            "chat",
            "turnId"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "sideChat"
            },
            "chat": {
              "$ref": "#/$defs/URI"
            },
            "turnId": {
              "type": "string"
            },
            "selection": {
              "$ref": "#/$defs/SideChatSelection"
            }
          },
          "required": [
            "kind",
            "chat",
            "turnId"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "tool"
            },
            "chat": {
              "$ref": "#/$defs/URI"
            },
            "toolCallId": {
              "type": "string"
            }
          },
          "required": [
            "kind",
            "chat",
            "toolCallId"
          ]
        }
      ],
      "description": "How a chat came into existence. Clients MAY use it to render\ncontextual UI (parent indicators, fork markers, \"spawned by tool\" badges).\n\nFork and side-chat origins both carry a stable top-level `turnId` alongside\ntheir discriminated `kind` value instead of snapshotting whether that turn\nwas active or historical at creation time. Consumers resolve the identifier\nagainst the\nsource chat's current `activeTurn` or retained `turns` as needed.\n\nWhen a host accepts side-chat creation from the source chat's current active\nturn, it snapshots the retained history plus that turn's current user\nmessage and any partial assistant response already available. Later\nsource-turn deltas do not retroactively change the created side chat's\nstarting context, and once the source turn completes it is still referenced\nby the same `turnId`. Side-chat origins MAY also retain an immutable\n{@link SideChatSelection | selected-text snapshot} captured at acceptance\ntime; any `responsePartId` there is provenance only, not a range.\n\nThe `tool` variant records a tool-spawned worker from the worker's side: its\n`chat`/`toolCallId` identify the spawning tool call in the parent chat. This\nis the canonical record of the spawn relationship. The same edge is surfaced\nfrom the parent's side by {@link ToolResultSubagentContent}, whose `resource`\nis this chat's URI; hosts MUST keep the two consistent."
    },
    "ChatInputQuestion": {
      "oneOf": [
        {
          "$ref": "#/$defs/ChatInputTextQuestion"
        },
        {
          "$ref": "#/$defs/ChatInputNumberQuestion"
        },
        {
          "$ref": "#/$defs/ChatInputBooleanQuestion"
        },
        {
          "$ref": "#/$defs/ChatInputSingleSelectQuestion"
        },
        {
          "$ref": "#/$defs/ChatInputMultiSelectQuestion"
        }
      ],
      "description": "One question within a chat input request."
    },
    "ChatInputAnswerValue": {
      "oneOf": [
        {
          "$ref": "#/$defs/ChatInputTextAnswerValue"
        },
        {
          "$ref": "#/$defs/ChatInputNumberAnswerValue"
        },
        {
          "$ref": "#/$defs/ChatInputBooleanAnswerValue"
        },
        {
          "$ref": "#/$defs/ChatInputSelectedAnswerValue"
        },
        {
          "$ref": "#/$defs/ChatInputSelectedManyAnswerValue"
        }
      ]
    },
    "ChatInputAnswer": {
      "oneOf": [
        {
          "$ref": "#/$defs/ChatInputAnswered"
        },
        {
          "$ref": "#/$defs/ChatInputSkipped"
        }
      ],
      "description": "Draft, submitted, or skipped answer for one question."
    },
    "MessageAttachment": {
      "oneOf": [
        {
          "$ref": "#/$defs/SimpleMessageAttachment"
        },
        {
          "$ref": "#/$defs/MessageEmbeddedResourceAttachment"
        },
        {
          "$ref": "#/$defs/MessageResourceAttachment"
        },
        {
          "$ref": "#/$defs/MessageAnnotationsAttachment"
        },
        {
          "$ref": "#/$defs/MessageChatAttachment"
        }
      ],
      "description": "An attachment associated with a {@link Message}."
    },
    "ResponsePart": {
      "oneOf": [
        {
          "$ref": "#/$defs/MarkdownResponsePart"
        },
        {
          "$ref": "#/$defs/ResourceResponsePart"
        },
        {
          "$ref": "#/$defs/ToolCallResponsePart"
        },
        {
          "$ref": "#/$defs/ReasoningResponsePart"
        },
        {
          "$ref": "#/$defs/SystemNotificationResponsePart"
        },
        {
          "$ref": "#/$defs/InputRequestResponsePart"
        },
        {
          "$ref": "#/$defs/ErrorResponsePart"
        }
      ]
    },
    "ToolCallRiskAssessment": {
      "oneOf": [
        {
          "$ref": "#/$defs/ToolCallRiskAssessmentLoadingState"
        },
        {
          "$ref": "#/$defs/ToolCallRiskAssessmentCompleteState"
        }
      ]
    },
    "ToolCallContributor": {
      "oneOf": [
        {
          "$ref": "#/$defs/ToolCallClientContributor"
        },
        {
          "$ref": "#/$defs/ToolCallMcpContributor"
        }
      ]
    },
    "ToolInput": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "$ref": "#/$defs/ContentRef"
        }
      ],
      "description": "Tool input represented inline or by reference."
    },
    "ToolCallState": {
      "oneOf": [
        {
          "$ref": "#/$defs/ToolCallStreamingState"
        },
        {
          "$ref": "#/$defs/ToolCallPendingConfirmationState"
        },
        {
          "$ref": "#/$defs/ToolCallRunningState"
        },
        {
          "$ref": "#/$defs/ToolCallAuthRequiredState"
        },
        {
          "$ref": "#/$defs/ToolCallPendingResultConfirmationState"
        },
        {
          "$ref": "#/$defs/ToolCallCompletedState"
        },
        {
          "$ref": "#/$defs/ToolCallCancelledState"
        }
      ],
      "description": "Discriminated union of all tool call lifecycle states.\n\nSee the [state model guide](/guide/state-model.html#tool-call-lifecycle)\nfor the full state machine diagram."
    },
    "ToolCallConfirmationState": {
      "oneOf": [
        {
          "$ref": "#/$defs/ToolCallPendingConfirmationState"
        },
        {
          "$ref": "#/$defs/ToolCallPendingResultConfirmationState"
        }
      ],
      "description": "The two tool-call states that block on a client confirmation: parameter\nconfirmation before execution ({@link ToolCallPendingConfirmationState}) and\nresult confirmation after execution\n({@link ToolCallPendingResultConfirmationState}).\n\n{@link ToolCallAuthRequiredState} is intentionally **not** part of this\nunion: it doesn't block on a `chat/toolCallConfirmed`-style client\ndecision, it blocks on the client completing an OAuth flow and calling\n`authenticate`. See {@link SessionToolAuthenticationRequest} for its\nsession-level surfacing.\n\nSurfaced at the session level by {@link SessionToolConfirmationRequest}."
    },
    "ToolResultContent": {
      "oneOf": [
        {
          "$ref": "#/$defs/ToolResultTextContent"
        },
        {
          "$ref": "#/$defs/ToolResultEmbeddedResourceContent"
        },
        {
          "$ref": "#/$defs/ToolResultResourceContent"
        },
        {
          "$ref": "#/$defs/ToolResultFileEditContent"
        },
        {
          "$ref": "#/$defs/ToolResultTerminalContent"
        },
        {
          "$ref": "#/$defs/ToolResultSubagentContent"
        }
      ],
      "description": "Content block in a tool result.\n\nMirrors the content blocks in MCP `CallToolResult.content`, plus\n`ToolResultResourceContent` for lazy-loading large results,\n`ToolResultFileEditContent` for file edit diffs,\n`ToolResultTerminalContent` for live terminal output and\ncommand completion metadata, and\n`ToolResultSubagentContent` for tool-spawned worker chats (AHP extensions)."
    },
    "TerminalLifecycleState": {
      "oneOf": [
        {
          "$ref": "#/$defs/TerminalRunningLifecycleState"
        },
        {
          "$ref": "#/$defs/TerminalExitedLifecycleState"
        }
      ],
      "description": "Current lifecycle of a terminal process."
    },
    "TerminalClaim": {
      "oneOf": [
        {
          "$ref": "#/$defs/TerminalClientClaim"
        },
        {
          "$ref": "#/$defs/TerminalSessionClaim"
        }
      ],
      "description": "Describes who currently holds a terminal. A terminal may be claimed by\neither a connected client or a session (e.g. during a tool call)."
    },
    "TerminalContentPart": {
      "oneOf": [
        {
          "$ref": "#/$defs/TerminalUnclassifiedPart"
        },
        {
          "$ref": "#/$defs/TerminalCommandPart"
        }
      ],
      "description": "A content part within terminal output."
    },
    "AutomationTrigger": {
      "oneOf": [
        {
          "$ref": "#/$defs/AutomationScheduleTrigger"
        },
        {
          "$ref": "#/$defs/AutomationEventTrigger"
        }
      ],
      "description": "An automatic trigger that can create runs for an enabled automation.\n\nManual execution is not represented as a trigger. An empty trigger list\ntherefore means the automation is manual-only."
    },
    "AutomationRunOrigin": {
      "oneOf": [
        {
          "$ref": "#/$defs/AutomationManualRunOrigin"
        },
        {
          "$ref": "#/$defs/AutomationTriggeredRunOrigin"
        }
      ],
      "description": "Immutable provenance describing why a run was created."
    },
    "AutomationRunLifecycle": {
      "oneOf": [
        {
          "$ref": "#/$defs/AutomationPendingRunLifecycle"
        },
        {
          "$ref": "#/$defs/AutomationRunningRunLifecycle"
        },
        {
          "$ref": "#/$defs/AutomationCompletedRunLifecycle"
        },
        {
          "$ref": "#/$defs/AutomationFailedRunLifecycle"
        },
        {
          "$ref": "#/$defs/AutomationCancelledRunLifecycle"
        }
      ],
      "description": "Discriminated lifecycle of an automation run."
    },
    "StateAction": {
      "description": "Discriminated union of all state actions.",
      "oneOf": [
        {
          "$ref": "#/$defs/"
        },
        {
          "$ref": "#/$defs/RootAgentsChangedAction"
        },
        {
          "$ref": "#/$defs/RootActiveSessionsChangedAction"
        },
        {
          "$ref": "#/$defs/RootTerminalsChangedAction"
        },
        {
          "$ref": "#/$defs/RootConfigChangedAction"
        },
        {
          "$ref": "#/$defs/SessionReadyAction"
        },
        {
          "$ref": "#/$defs/SessionCreationFailedAction"
        },
        {
          "$ref": "#/$defs/SessionChatAddedAction"
        },
        {
          "$ref": "#/$defs/SessionChatRemovedAction"
        },
        {
          "$ref": "#/$defs/SessionChatUpdatedAction"
        },
        {
          "$ref": "#/$defs/SessionDefaultChatChangedAction"
        },
        {
          "$ref": "#/$defs/SessionTitleChangedAction"
        },
        {
          "$ref": "#/$defs/SessionServerToolsChangedAction"
        },
        {
          "$ref": "#/$defs/SessionActiveClientSetAction"
        },
        {
          "$ref": "#/$defs/SessionActiveClientRemovedAction"
        },
        {
          "$ref": "#/$defs/SessionWorkingDirectorySetAction"
        },
        {
          "$ref": "#/$defs/SessionWorkingDirectoryRemovedAction"
        },
        {
          "$ref": "#/$defs/SessionWorkingDirectoryReplacedAction"
        },
        {
          "$ref": "#/$defs/SessionInputNeededSetAction"
        },
        {
          "$ref": "#/$defs/SessionInputNeededRemovedAction"
        },
        {
          "$ref": "#/$defs/SessionCustomizationsChangedAction"
        },
        {
          "$ref": "#/$defs/SessionCustomizationToggledAction"
        },
        {
          "$ref": "#/$defs/SessionCustomizationUpdatedAction"
        },
        {
          "$ref": "#/$defs/SessionCustomizationRemovedAction"
        },
        {
          "$ref": "#/$defs/SessionMcpServerStateChangedAction"
        },
        {
          "$ref": "#/$defs/SessionMcpServerStartRequestedAction"
        },
        {
          "$ref": "#/$defs/SessionMcpServerStopRequestedAction"
        },
        {
          "$ref": "#/$defs/SessionIsReadChangedAction"
        },
        {
          "$ref": "#/$defs/SessionIsArchivedChangedAction"
        },
        {
          "$ref": "#/$defs/SessionActivityChangedAction"
        },
        {
          "$ref": "#/$defs/SessionChangesetsChangedAction"
        },
        {
          "$ref": "#/$defs/SessionConfigChangedAction"
        },
        {
          "$ref": "#/$defs/SessionMetaChangedAction"
        },
        {
          "$ref": "#/$defs/ChatTurnStartedAction"
        },
        {
          "$ref": "#/$defs/ChatDeltaAction"
        },
        {
          "$ref": "#/$defs/ChatResponsePartAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallStartAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallDeltaAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallReadyAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallConfirmedAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallCompleteAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallResultConfirmedAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallContentChangedAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallAuthRequiredAction"
        },
        {
          "$ref": "#/$defs/ChatToolCallAuthResolvedAction"
        },
        {
          "$ref": "#/$defs/ChatTurnCompleteAction"
        },
        {
          "$ref": "#/$defs/ChatTurnCancelledAction"
        },
        {
          "$ref": "#/$defs/ChatErrorAction"
        },
        {
          "$ref": "#/$defs/ChatTurnResumeAction"
        },
        {
          "$ref": "#/$defs/ChatActivityChangedAction"
        },
        {
          "$ref": "#/$defs/ChatWorkingDirectorySetAction"
        },
        {
          "$ref": "#/$defs/ChatWorkingDirectoryRemovedAction"
        },
        {
          "$ref": "#/$defs/ChatUsageAction"
        },
        {
          "$ref": "#/$defs/ChatReasoningAction"
        },
        {
          "$ref": "#/$defs/ChatPendingMessageSetAction"
        },
        {
          "$ref": "#/$defs/ChatPendingMessageRemovedAction"
        },
        {
          "$ref": "#/$defs/ChatQueuedMessagesReorderedAction"
        },
        {
          "$ref": "#/$defs/ChatDraftChangedAction"
        },
        {
          "$ref": "#/$defs/ChatInputRequestedAction"
        },
        {
          "$ref": "#/$defs/ChatInputAnswerChangedAction"
        },
        {
          "$ref": "#/$defs/ChatInputCompletedAction"
        },
        {
          "$ref": "#/$defs/ChatTruncatedAction"
        },
        {
          "$ref": "#/$defs/ChatTurnsLoadedAction"
        },
        {
          "$ref": "#/$defs/ChangesetStatusChangedAction"
        },
        {
          "$ref": "#/$defs/ChangesetFileSetAction"
        },
        {
          "$ref": "#/$defs/ChangesetFileRemovedAction"
        },
        {
          "$ref": "#/$defs/ChangesetFilesReviewChangedAction"
        },
        {
          "$ref": "#/$defs/ChangesetContentChangedAction"
        },
        {
          "$ref": "#/$defs/ChangesetOperationsChangedAction"
        },
        {
          "$ref": "#/$defs/ChangesetOperationStatusChangedAction"
        },
        {
          "$ref": "#/$defs/ChangesetClearedAction"
        },
        {
          "$ref": "#/$defs/AnnotationsSetAction"
        },
        {
          "$ref": "#/$defs/AnnotationsUpdatedAction"
        },
        {
          "$ref": "#/$defs/AnnotationsRemovedAction"
        },
        {
          "$ref": "#/$defs/AnnotationsEntrySetAction"
        },
        {
          "$ref": "#/$defs/AnnotationsEntryRemovedAction"
        },
        {
          "$ref": "#/$defs/TerminalDataAction"
        },
        {
          "$ref": "#/$defs/TerminalInputAction"
        },
        {
          "$ref": "#/$defs/TerminalResizedAction"
        },
        {
          "$ref": "#/$defs/TerminalClaimedAction"
        },
        {
          "$ref": "#/$defs/TerminalTitleChangedAction"
        },
        {
          "$ref": "#/$defs/TerminalCwdChangedAction"
        },
        {
          "$ref": "#/$defs/TerminalExitedAction"
        },
        {
          "$ref": "#/$defs/TerminalClearedAction"
        },
        {
          "$ref": "#/$defs/TerminalCommandDetectionAvailableAction"
        },
        {
          "$ref": "#/$defs/TerminalCommandExecutedAction"
        },
        {
          "$ref": "#/$defs/TerminalCommandFinishedAction"
        },
        {
          "$ref": "#/$defs/ResourceWatchChangedAction"
        },
        {
          "$ref": "#/$defs/AutomationCreateRequestedAction"
        },
        {
          "$ref": "#/$defs/AutomationUpdateRequestedAction"
        },
        {
          "$ref": "#/$defs/AutomationSetAction"
        },
        {
          "$ref": "#/$defs/AutomationRemovedAction"
        },
        {
          "$ref": "#/$defs/AutomationRunLifecycleChangedAction"
        },
        {
          "$ref": "#/$defs/AutomationRunSessionSetAction"
        },
        {
          "$ref": "#/$defs/AutomationRunSessionRemovedAction"
        },
        {
          "$ref": "#/$defs/AutomationRunPrimarySessionChangedAction"
        },
        {
          "$ref": "#/$defs/AutomationRunCancelRequestedAction"
        }
      ]
    },
    "URI": {
      "type": "string",
      "description": "A URI string (e.g. `ahp-root://`, `ahp-session:/<uuid>`, or `ahp-chat:/<uuid>`)."
    },
    "SessionStatus": {
      "enum": [
        1,
        2,
        8,
        24,
        32,
        64
      ],
      "type": "number",
      "description": "Bitset of summary-level session status flags.\n\nUse bitwise checks instead of equality for non-terminal activity. For example,\n`status & SessionStatus.InProgress` matches both ordinary in-progress turns\nand turns that are paused waiting for input."
    },
    "ChatInteractivity": {
      "enum": [
        "full",
        "read-only",
        "hidden"
      ],
      "type": "string",
      "description": "How a user can interact with a chat.\n\n- `Full` — user can send messages and watch (default when absent)\n- `ReadOnly` — user can watch but not send messages (e.g. agent team workers)\n- `Hidden` — internal worker not shown in UI at all\n\nSupports the agent-team pattern where a lead chat is fully interactive and\nworker chats are read-only (visible for observability) or hidden (internal\nimplementation detail). The harness sets this based on the chat's role;\nthe UI uses it to show appropriate controls."
    },
    "ToolCallConfirmationReason": {
      "enum": [
        "not-needed",
        "user-action",
        "setting"
      ],
      "type": "string",
      "description": "How a tool call was confirmed for execution.\n\n- `NotNeeded` — No confirmation required (auto-approved)\n- `UserAction` — User explicitly approved\n- `Setting` — Approved by a persistent user setting"
    },
    "PendingMessageKind": {
      "enum": [
        "steering",
        "queued"
      ],
      "type": "string",
      "description": "Discriminant for pending message kinds."
    },
    "ChatInputResponseKind": {
      "enum": [
        "accept",
        "decline",
        "cancel"
      ],
      "type": "string",
      "description": "How a client completed an input request."
    },
    "ChangesetStatus": {
      "enum": [
        "computing",
        "ready",
        "error"
      ],
      "type": "string",
      "description": "Computation lifecycle of a {@link ChangesetState}."
    },
    "ChangesetOperationStatus": {
      "enum": [
        "idle",
        "running",
        "error",
        "disabled"
      ],
      "type": "string",
      "description": "Execution lifecycle of a {@link ChangesetOperation}.\n\nAn operation is invoked imperatively via `invokeChangesetOperation`, but\nits progress and outcome are reflected back into changeset state so that\nevery subscriber observes a consistent view (e.g. a spinner on a \"Create\nPull Request\" button, or an inline error after a failed \"revert\")."
    },
    "PolicyState": {
      "enum": [
        "enabled",
        "disabled",
        "unconfigured"
      ],
      "type": "string",
      "description": "Policy configuration state for a model."
    },
    "SessionLifecycle": {
      "enum": [
        "creating",
        "ready",
        "failed"
      ],
      "type": "string",
      "description": "Session initialization state."
    },
    "McpAuthRequiredReason": {
      "enum": [
        "required",
        "expired",
        "insufficientScope"
      ],
      "type": "string",
      "description": "Why an MCP server is currently in the {@link McpServerStatus.AuthRequired}\nstate. Mirrors the three failure modes defined by the\n[MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization.md)."
    },
    "TurnState": {
      "enum": [
        "complete",
        "cancelled",
        "error"
      ],
      "type": "string",
      "description": "How a turn ended."
    },
    "MessageKind": {
      "enum": [
        "user",
        "agent",
        "tool",
        "automation",
        "systemNotification"
      ],
      "type": "string",
      "description": "Discriminant for {@link MessageOrigin} — identifies who produced a message."
    },
    "ToolCallRiskAssessmentKind": {
      "enum": [
        "judge"
      ],
      "type": "string",
      "description": "Identifies a model judge as the source of a confirmation requirement."
    },
    "ConfirmationOptionKind": {
      "enum": [
        "approve",
        "deny"
      ],
      "type": "string",
      "description": "Whether a confirmation option represents an approval or denial action."
    },
    "ToolCallCancellationReason": {
      "enum": [
        "denied",
        "skipped",
        "result-denied"
      ],
      "type": "string",
      "description": "Why a tool call was cancelled."
    },
    "ChangesetOperationScope": {
      "enum": [
        "changeset",
        "resource",
        "range"
      ],
      "type": "string",
      "description": "Where a {@link ChangesetOperation} can be invoked."
    },
    "ResourceChangeType": {
      "enum": [
        "added",
        "updated",
        "deleted"
      ],
      "type": "string",
      "description": "Discriminant for {@link ResourceChange.type}."
    },
    "AutomationMisfirePolicy": {
      "enum": [
        "skip",
        "runOnce"
      ],
      "type": "string",
      "description": "How a host handles schedule occurrences missed while automatic execution was\nunavailable."
    },
    "AutomationOperation": {
      "enum": [
        "update",
        "remove",
        "run"
      ],
      "type": "string",
      "description": "Operations the host currently permits for an automation.\n\nThe list on {@link AutomationEntry.operations} is authoritative and may\nchange over time. Clients MUST NOT infer permission from capabilities alone:\ncapabilities describe what the host implementation can support, while\noperations describe what is allowed for this particular automation now."
    }
  }
}