state.ts

/*---------------------------------------------------------------------------------------------
 *  Copyright (c) Microsoft Corporation. All rights reserved.
 *  Licensed under the MIT License. See License.txt in the project root for license information.
 *--------------------------------------------------------------------------------------------*/

// allow-any-unicode-comment-file
// DO NOT EDIT -- auto-generated by scripts/sync-agent-host-protocol.ts

// ─── Type Aliases ────────────────────────────────────────────────────────────

/** A URI string (e.g. `agenthost:/root` or `copilot:/<uuid>`). */
export type URI = string;

/**
 * A string that may optionally be rendered as Markdown.
 *
 * - A plain `string` is rendered as-is (no Markdown processing).
 * - An object with `{ markdown: string }` is rendered with Markdown formatting.
 */
export type StringOrMarkdown = string | { markdown: string };

// ─── Icon ────────────────────────────────────────────────────────────────────

/**
 * An optionally-sized icon that can be displayed in a user interface.
 *
 * @category Common Types
 */
export interface Icon {
	/**
	 * A standard URI pointing to an icon resource. May be an HTTP/HTTPS URL or a
	 * `data:` URI with Base64-encoded image data.
	 *
	 * Consumers SHOULD take steps to ensure URLs serving icons are from the
	 * same domain as the client/server or a trusted domain.
	 *
	 * Consumers SHOULD take appropriate precautions when consuming SVGs as they can contain
	 * executable JavaScript.
	 */
	src: URI;

	/**
	 * Optional MIME type override if the source MIME type is missing or generic.
	 * For example: `"image/png"`, `"image/jpeg"`, or `"image/svg+xml"`.
	 */
	contentType?: string;

	/**
	 * Optional array of strings that specify sizes at which the icon can be used.
	 * Each string should be in WxH format (e.g., `"48x48"`, `"96x96"`) or `"any"` for scalable formats like SVG.
	 *
	 * If not provided, the client should assume that the icon can be used at any size.
	 */
	sizes?: string[];

	/**
	 * Optional specifier for the theme this icon is designed for. `"light"` indicates
	 * the icon is designed to be used with a light background, and `"dark"` indicates
	 * the icon is designed to be used with a dark background.
	 *
	 * If not provided, the client should assume the icon can be used with any theme.
	 */
	theme?: 'light' | 'dark';
}

// ─── Protected Resource Metadata (RFC 9728) ─────────────────────────────────

/**
 * Describes a protected resource's authentication requirements using
 * [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) (OAuth 2.0
 * Protected Resource Metadata) semantics.
 *
 * Field names use snake_case to match the RFC 9728 JSON format.
 *
 * @category Authentication
 * @see {@link https://datatracker.ietf.org/doc/html/rfc9728 | RFC 9728}
 */
export interface ProtectedResourceMetadata {
	/**
	 * REQUIRED. The protected resource's resource identifier, a URL using the
	 * `https` scheme with no fragment component (e.g. `"https://api.github.com"`).
	 */
	resource: string;

	/** OPTIONAL. Human-readable name of the protected resource. */
	resource_name?: string;

	/** OPTIONAL. JSON array of OAuth authorization server identifier URLs. */
	authorization_servers?: string[];

	/** OPTIONAL. URL of the protected resource's JWK Set document. */
	jwks_uri?: string;

	/** RECOMMENDED. JSON array of OAuth 2.0 scope values used in authorization requests. */
	scopes_supported?: string[];

	/** OPTIONAL. JSON array of Bearer Token presentation methods supported. */
	bearer_methods_supported?: string[];

	/** OPTIONAL. JSON array of JWS signing algorithms supported. */
	resource_signing_alg_values_supported?: string[];

	/** OPTIONAL. JSON array of JWE encryption algorithms (alg) supported. */
	resource_encryption_alg_values_supported?: string[];

	/** OPTIONAL. JSON array of JWE encryption algorithms (enc) supported. */
	resource_encryption_enc_values_supported?: string[];

	/** OPTIONAL. URL of human-readable documentation for the resource. */
	resource_documentation?: string;

	/** OPTIONAL. URL of the resource's data-usage policy. */
	resource_policy_uri?: string;

	/** OPTIONAL. URL of the resource's terms of service. */
	resource_tos_uri?: string;

	/**
	 * AHP extension. Whether authentication is required for this resource.
	 *
	 * - `true` (default) — the agent cannot be used without a valid token.
	 *   The server SHOULD return `AuthRequired` (`-32007`) if the client
	 *   attempts to use the agent without authenticating.
	 * - `false` — the agent works without authentication but MAY offer
	 *   enhanced capabilities when a token is provided.
	 *
	 * Clients SHOULD treat an absent field the same as `true`.
	 */
	required?: boolean;
}

// ─── Root State ──────────────────────────────────────────────────────────────

/**
 * Policy configuration state for a model.
 *
 * @category Root State
 */
export const enum PolicyState {
	Enabled = 'enabled',
	Disabled = 'disabled',
	Unconfigured = 'unconfigured',
}

/**
 * Global state shared with every client subscribed to `agenthost:/root`.
 *
 * @category Root State
 */
export interface RootState {
	/** Available agent backends and their models */
	agents: AgentInfo[];
	/** Number of active (non-disposed) sessions on the server */
	activeSessions?: number;
	/** Known terminals on the server. Subscribe to individual terminal URIs for full state. */
	terminals?: TerminalInfo[];
	/** Agent host configuration schema and current values */
	config?: RootConfigState;
}

/**
 * @category Root State
 */
export interface AgentInfo {
	/** Agent provider ID (e.g. `'copilot'`) */
	provider: string;
	/** Human-readable name */
	displayName: string;
	/** Description string */
	description: string;
	/** Available models for this agent */
	models: SessionModelInfo[];
	/**
	 * Protected resources this agent requires authentication for.
	 *
	 * Each entry describes an OAuth 2.0 protected resource using
	 * [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) semantics.
	 * Clients should obtain tokens from the declared `authorization_servers`
	 * and push them via the `authenticate` command before creating sessions
	 * with this agent.
	 *
	 * @see {@link /specification/authentication | Authentication}
	 */
	protectedResources?: ProtectedResourceMetadata[];
	/**
	 * Customizations (Open Plugins) associated with this agent.
	 *
	 * Each entry is a reference to an [Open Plugins](https://open-plugins.com/)
	 * plugin that the agent host can activate for sessions using this agent.
	 */
	customizations?: CustomizationRef[];
}

/**
 * @category Root State
 */
export interface SessionModelInfo {
	/** Model identifier */
	id: string;
	/** Provider this model belongs to */
	provider: string;
	/** Human-readable model name */
	name: string;
	/** Maximum context window size */
	maxContextWindow?: number;
	/** Whether the model supports vision */
	supportsVision?: boolean;
	/** Policy configuration state */
	policyState?: PolicyState;
	/**
	 * Configuration schema describing model-specific options (e.g. thinking
	 * level). Clients present this as a form and pass the resolved values in
	 * {@link ModelSelection.config} when creating or changing sessions.
	 */
	configSchema?: ConfigSchema;
}

/**
 * A model selection: the chosen model ID together with any model-specific
 * configuration values whose keys correspond to the model's
 * {@link SessionModelInfo.configSchema}.
 *
 * @category Root State
 */
export interface ModelSelection {
	/** Model identifier */
	id: string;
	/** Model-specific configuration values */
	config?: Record<string, string>;
}

// ─── Pending Message Types ───────────────────────────────────────────────────

/**
 * Discriminant for pending message kinds.
 *
 * @category Pending Message Types
 */
export const enum PendingMessageKind {
	/** Injected into the current turn at a convenient point */
	Steering = 'steering',
	/** Sent automatically as a new turn after the current turn finishes */
	Queued = 'queued',
}

/**
 * A message queued for future delivery to the agent.
 *
 * Steering messages are injected into the current turn mid-flight.
 * Queued messages are automatically started as new turns after the
 * current turn naturally finishes.
 *
 * @category Pending Message Types
 */
export interface PendingMessage {
	/** Unique identifier for this pending message */
	id: string;
	/** The message content */
	userMessage: UserMessage;
}

// ─── Session State ───────────────────────────────────────────────────────────

/**
 * Session initialization state.
 *
 * @category Session State
 */
export const enum SessionLifecycle {
	Creating = 'creating',
	Ready = 'ready',
	CreationFailed = 'creationFailed',
}

/**
 * Bitset of summary-level session status flags.
 *
 * Use bitwise checks instead of equality for non-terminal activity. For example,
 * `status & SessionStatus.InProgress` matches both ordinary in-progress turns
 * and turns that are paused waiting for input.
 *
 * @category Session State
 */
export const enum SessionStatus {
	/** Session is idle — no turn is active. */
	Idle = 1,
	/** Session ended with an error. */
	Error = 1 << 1,
	/** A turn is actively streaming. */
	InProgress = 1 << 3,
	/** A turn is in progress but blocked waiting for user input or tool confirmation. */
	InputNeeded = (1 << 3) | (1 << 4),
	/** The client has viewed this session since its last modification. */
	IsRead = 1 << 5,
	/** The session has been archived by the client. */
	IsArchived = 1 << 6,
}

/**
 * Full state for a single session, loaded when a client subscribes to the session's URI.
 *
 * @category Session State
 */
export interface SessionState {
	/** Lightweight session metadata */
	summary: SessionSummary;
	/** Session initialization state */
	lifecycle: SessionLifecycle;
	/** Error details if creation failed */
	creationError?: ErrorInfo;
	/** Tools provided by the server (agent host) for this session */
	serverTools?: ToolDefinition[];
	/** The client currently providing tools and interactive capabilities to this session */
	activeClient?: SessionActiveClient;
	/** Completed turns */
	turns: Turn[];
	/** Currently in-progress turn */
	activeTurn?: ActiveTurn;
	/** Message to inject into the current turn at a convenient point */
	steeringMessage?: PendingMessage;
	/** Messages to send automatically as new turns after the current turn finishes */
	queuedMessages?: PendingMessage[];
	/** Requests for user input that are currently blocking or informing session progress */
	inputRequests?: SessionInputRequest[];
	/** Session configuration schema and current values */
	config?: SessionConfigState;
	/**
	 * Server-provided customizations active in this session.
	 *
	 * Client-provided customizations are available on
	 * {@link SessionActiveClient.customizations | activeClient.customizations}.
	 */
	customizations?: SessionCustomization[];
	/**
	 * Additional provider-specific metadata for this session.
	 *
	 * Clients MAY look for well-known keys here to provide enhanced UI.
	 * For example, a `git` key may provide extra git metadata about the session's
	 * workingDirectory.
	 */
	_meta?: Record<string, unknown>;
}

/**
 * The client currently providing tools and interactive capabilities to a session.
 *
 * Only one client may be active per session at a time. The server SHOULD
 * automatically unset the active client if that client disconnects.
 *
 * @category Session State
 */
export interface SessionActiveClient {
	/** Client identifier (matches `clientId` from `initialize`) */
	clientId: string;
	/** Human-readable client name (e.g. `"VS Code"`) */
	displayName?: string;
	/** Tools this client provides to the session */
	tools: ToolDefinition[];
	/** Customizations this client contributes to the session */
	customizations?: CustomizationRef[];
}

/**
 * Server-owned project metadata for a session.
 *
 * @category Session State
 */
export interface ProjectInfo {
	/** Project URI */
	uri: URI;
	/** Human-readable project name */
	displayName: string;
}

/**
 * @category Session State
 */
export interface SessionSummary {
	/** Session URI */
	resource: URI;
	/** Agent provider ID */
	provider: string;
	/** Session title */
	title: string;
	/** Current session status */
	status: SessionStatus;
	/** Human-readable description of what the session is currently doing */
	activity?: string;
	/** Creation timestamp */
	createdAt: number;
	/** Last modification timestamp */
	modifiedAt: number;
	/** Server-owned project for this session */
	project?: ProjectInfo;
	/** Currently selected model */
	model?: ModelSelection;
	/** The working directory URI for this session */
	workingDirectory?: URI;
	/** Files changed during this session with diff statistics */
	diffs?: FileEdit[];
}

// ─── Config Schema Types ─────────────────────────────────────────────────────

/**
 * A JSON Schema-compatible property descriptor with display extensions.
 *
 * Standard JSON Schema fields (`type`, `title`, `description`, `default`,
 * `enum`) allow validators to process the schema. Display extensions
 * (`enumLabels`, `enumDescriptions`) are parallel arrays that provide UI
 * metadata for each `enum` value.
 *
 * This is the generic base type. See {@link SessionConfigPropertySchema} for
 * session-specific extensions.
 *
 * @category Config Schema Types
 */
export interface ConfigPropertySchema {
	/** JSON Schema: property type */
	type: 'string' | 'number' | 'boolean' | 'array' | 'object';
	/** JSON Schema: human-readable label for the property */
	title: string;
	/** JSON Schema: description / tooltip */
	description?: string;
	/** JSON Schema: default value */
	default?: unknown;
	/** JSON Schema: allowed values (typically used with `string` type) */
	enum?: string[];
	/** Display extension: human-readable label per enum value (parallel array) */
	enumLabels?: string[];
	/** Display extension: description per enum value (parallel array) */
	enumDescriptions?: string[];
	/** JSON Schema: when `true`, the property is displayed but cannot be modified by the user */
	readOnly?: boolean;
	/** JSON Schema: schema for array items (used when `type` is `'array'`) */
	items?: ConfigPropertySchema;
	/** JSON Schema: property descriptors for object properties (used when `type` is `'object'`) */
	properties?: Record<string, ConfigPropertySchema>;
	/** JSON Schema: list of required property ids (used when `type` is `'object'`) */
	required?: string[];
}

/**
 * A JSON Schema object describing available configuration properties.
 *
 * This is the generic base type. See {@link SessionConfigSchema} for
 * session-specific usage.
 *
 * @category Config Schema Types
 */
export interface ConfigSchema {
	/** JSON Schema: always `'object'` */
	type: 'object';
	/** JSON Schema: property descriptors keyed by property id */
	properties: Record<string, ConfigPropertySchema>;
	/** JSON Schema: list of required property ids */
	required?: string[];
}

// ─── Root Config Types ───────────────────────────────────────────────────────

/**
 * Live agent-host configuration metadata.
 *
 * The schema describes the available configuration properties and the values
 * contain the current value for each resolved property.
 *
 * @category Root State
 */
export interface RootConfigState {
	/** JSON Schema describing available configuration properties */
	schema: ConfigSchema;
	/** Current configuration values */
	values: Record<string, unknown>;
}

// ─── Session Config Types ────────────────────────────────────────────────────

/**
 * A session configuration property descriptor.
 *
 * Extends the generic {@link ConfigPropertySchema} with session-specific
 * display extensions.
 *
 * @category Session Config Types
 */
export interface SessionConfigPropertySchema extends ConfigPropertySchema {
	/**
	 * Display extension: when `true`, the full set of allowed values is too large
	 * to enumerate statically. The client SHOULD use `sessionConfigCompletions`
	 * to fetch matching values based on user input. Any values in `enum` are
	 * seed/recent values for initial display.
	 */
	enumDynamic?: boolean;
	/** When `true`, the user may change this property after session creation */
	sessionMutable?: boolean;
}

/**
 * A JSON Schema object describing available session configuration metadata.
 *
 * @category Session Config Types
 */
export interface SessionConfigSchema {
	/** JSON Schema: always `'object'` */
	type: 'object';
	/** JSON Schema: property descriptors keyed by property id */
	properties: Record<string, SessionConfigPropertySchema>;
	/** JSON Schema: list of required property ids */
	required?: string[];
}

/**
 * Live session configuration metadata.
 *
 * The schema describes the available configuration properties and the values
 * contain the current value for each resolved property.
 *
 * @category Session Config Types
 */
export interface SessionConfigState {
	/** JSON Schema describing available configuration properties */
	schema: SessionConfigSchema;
	/** Current configuration values */
	values: Record<string, unknown>;
}

// ─── Session Input Types ────────────────────────────────────────────────────

/**
 * How a client completed an input request.
 *
 * @category Session Input Types
 */
export const enum SessionInputResponseKind {
	Accept = 'accept',
	Decline = 'decline',
	Cancel = 'cancel',
}

/**
 * Question/input control kind.
 *
 * @category Session Input Types
 */
export const enum SessionInputQuestionKind {
	Text = 'text',
	Number = 'number',
	Integer = 'integer',
	Boolean = 'boolean',
	SingleSelect = 'single-select',
	MultiSelect = 'multi-select',
}

/**
 * A choice in a select-style question.
 *
 * @category Session Input Types
 */
export interface SessionInputOption {
	/** Stable option identifier; for MCP enum values this is the enum string */
	id: string;
	/** Display label */
	label: string;
	/** Optional secondary text */
	description?: string;
	/** Whether this option is the recommended/default choice */
	recommended?: boolean;
}

interface SessionInputQuestionBase {
	/** Stable question identifier used as the key in `answers` */
	id: string;
	/** Short display title */
	title?: string;
	/** Prompt shown to the user */
	message: string;
	/** Whether the user must answer this question to accept the request */
	required?: boolean;
}

/** Text question within a session input request. */
export interface SessionInputTextQuestion extends SessionInputQuestionBase {
	kind: SessionInputQuestionKind.Text;
	/** Format hint for text questions, such as `email`, `uri`, `date`, or `date-time` */
	format?: string;
	/** Minimum string length */
	min?: number;
	/** Maximum string length */
	max?: number;
	/** Default text */
	defaultValue?: string;
}

/** Numeric question within a session input request. */
export interface SessionInputNumberQuestion extends SessionInputQuestionBase {
	kind: SessionInputQuestionKind.Number | SessionInputQuestionKind.Integer;
	/**
	 * Minimum value
	 * @format float
	 */
	min?: number;
	/**
	 * Maximum value
	 * @format float
	 */
	max?: number;
	/**
	 * Default numeric value
	 * @format float
	 */
	defaultValue?: number;
}

/** Boolean question within a session input request. */
export interface SessionInputBooleanQuestion extends SessionInputQuestionBase {
	kind: SessionInputQuestionKind.Boolean;
	/** Default boolean value */
	defaultValue?: boolean;
}

/** Single-select question within a session input request. */
export interface SessionInputSingleSelectQuestion extends SessionInputQuestionBase {
	kind: SessionInputQuestionKind.SingleSelect;
	/** Options the user may select from */
	options: SessionInputOption[];
	/** Whether the user may enter text instead of selecting an option */
	allowFreeformInput?: boolean;
}

/** Multi-select question within a session input request. */
export interface SessionInputMultiSelectQuestion extends SessionInputQuestionBase {
	kind: SessionInputQuestionKind.MultiSelect;
	/** Options the user may select from */
	options: SessionInputOption[];
	/** Whether the user may enter text in addition to selecting options */
	allowFreeformInput?: boolean;
	/** Minimum selected item count */
	min?: number;
	/** Maximum selected item count */
	max?: number;
}

/**
 * One question within a session input request.
 *
 * @category Session Input Types
 */
export type SessionInputQuestion = SessionInputTextQuestion
	| SessionInputNumberQuestion
	| SessionInputBooleanQuestion
	| SessionInputSingleSelectQuestion
	| SessionInputMultiSelectQuestion;

/**
 * A live request for user input.
 *
 * The server creates or replaces requests with `session/inputRequested`.
 * Clients sync drafts with `session/inputAnswerChanged` and complete requests
 * with `session/inputCompleted`.
 *
 * @category Session Input Types
 */
export interface SessionInputRequest {
	/** Stable request identifier */
	id: string;
	/** Display message for the request as a whole */
	message?: string;
	/** URL the user should review or open, for URL-style elicitations */
	url?: URI;
	/** Ordered questions to ask the user */
	questions?: SessionInputQuestion[];
	/** Current draft or submitted answers, keyed by question ID */
	answers?: Record<string, SessionInputAnswer>;
}

/**
 * Answer value kind.
 *
 * @category Session Input Types
 */
export const enum SessionInputAnswerValueKind {
	Text = 'text',
	Number = 'number',
	Boolean = 'boolean',
	Selected = 'selected',
	SelectedMany = 'selected-many',
}

/**
 * Value captured for one answer.
 *
 * @category Session Input Types
 */
export interface SessionInputTextAnswerValue {
	kind: SessionInputAnswerValueKind.Text;
	value: string;
}

export interface SessionInputNumberAnswerValue {
	kind: SessionInputAnswerValueKind.Number;
	/** @format float */
	value: number;
}

export interface SessionInputBooleanAnswerValue {
	kind: SessionInputAnswerValueKind.Boolean;
	value: boolean;
}

export interface SessionInputSelectedAnswerValue {
	kind: SessionInputAnswerValueKind.Selected;
	value: string;
	/** Free-form text entered instead of selecting an option */
	freeformValues?: string[];
}

export interface SessionInputSelectedManyAnswerValue {
	kind: SessionInputAnswerValueKind.SelectedMany;
	value: string[];
	/** Free-form text entered in addition to selected options */
	freeformValues?: string[];
}

export type SessionInputAnswerValue = SessionInputTextAnswerValue
	| SessionInputNumberAnswerValue
	| SessionInputBooleanAnswerValue
	| SessionInputSelectedAnswerValue
	| SessionInputSelectedManyAnswerValue;

export interface SessionInputAnswered {
	/** Answer state */
	state: SessionInputAnswerState.Draft | SessionInputAnswerState.Submitted;
	/** Answer value */
	value: SessionInputAnswerValue;
}

export interface SessionInputSkipped {
	/** Answer state */
	state: SessionInputAnswerState.Skipped;
	/** Free-form reason or value captured while skipping, if any */
	freeformValues?: string[];
}

/**
 * Answer lifecycle state.
 *
 * @category Session Input Types
 */
export const enum SessionInputAnswerState {
	Draft = 'draft',
	Submitted = 'submitted',
	Skipped = 'skipped',
}

/**
 * Draft, submitted, or skipped answer for one question.
 *
 * @category Session Input Types
 */
export type SessionInputAnswer = SessionInputAnswered | SessionInputSkipped;

// ─── Turn Types ──────────────────────────────────────────────────────────────

/**
 * How a turn ended.
 *
 * @category Turn Types
 */
export const enum TurnState {
	Complete = 'complete',
	Cancelled = 'cancelled',
	Error = 'error',
}

/**
 * Type of a message attachment.
 *
 * @category Turn Types
 */
export const enum AttachmentType {
	File = 'file',
	Directory = 'directory',
	Selection = 'selection',
}

/**
 * A completed request/response cycle.
 *
 * @category Turn Types
 */
export interface Turn {
	/** Turn identifier */
	id: string;
	/** The user's input */
	userMessage: UserMessage;
	/**
	 * All response content in stream order: text, tool calls, reasoning, and content refs.
	 *
	 * Consumers should derive display text by concatenating markdown parts,
	 * and find tool calls by filtering for `ToolCall` parts.
	 */
	responseParts: ResponsePart[];
	/** Token usage info */
	usage: UsageInfo | undefined;
	/** How the turn ended */
	state: TurnState;
	/** Error details if state is `'error'` */
	error?: ErrorInfo;
}

/**
 * An in-progress turn — the assistant is actively streaming.
 *
 * @category Turn Types
 */
export interface ActiveTurn {
	/** Turn identifier */
	id: string;
	/** The user's input */
	userMessage: UserMessage;
	/**
	 * All response content in stream order: text, tool calls, reasoning, and content refs.
	 *
	 * Tool call parts include `pendingPermissions` when permissions are awaiting user approval.
	 */
	responseParts: ResponsePart[];
	/** Token usage info */
	usage: UsageInfo | undefined;
}

/**
 * @category Turn Types
 */
export interface UserMessage {
	/** Message text */
	text: string;
	/** File/selection attachments */
	attachments?: MessageAttachment[];
}

/**
 * @category Turn Types
 */
export interface MessageAttachment {
	/** Attachment type */
	type: AttachmentType;
	/** File/directory URI */
	uri: URI;
	/** Display name */
	displayName?: string;
}

// ─── Response Parts ──────────────────────────────────────────────────────────

/**
 * Discriminant for response part types.
 *
 * @category Response Parts
 */
export const enum ResponsePartKind {
	Markdown = 'markdown',
	ContentRef = 'contentRef',
	ToolCall = 'toolCall',
	Reasoning = 'reasoning',
}

/**
 * @category Response Parts
 */
export interface MarkdownResponsePart {
	/** Discriminant */
	kind: ResponsePartKind.Markdown;
	/** Part identifier, used by `session/delta` to target this part for content appends */
	id: string;
	/** Markdown content */
	content: string;
}

/**
 * A reference to large content stored outside the state tree.
 */
export interface ContentRef {
	/** Content URI */
	uri: URI;
	/** Approximate size in bytes */
	sizeHint?: number;
	/** Content MIME type */
	contentType?: string;
}

/**
 * A content part that's a reference to large content stored outside the state tree.
 *
 * @category Response Parts
 */
export interface ResourceReponsePart extends ContentRef {
	/** Discriminant */
	kind: ResponsePartKind.ContentRef;
}

/**
 * A tool call represented as a response part.
 *
 * Tool calls are part of the response stream, interleaved with text and
 * reasoning. The `toolCall.toolCallId` serves as the part identifier for
 * actions that target this part.
 *
 * @category Response Parts
 */
export interface ToolCallResponsePart {
	/** Discriminant */
	kind: ResponsePartKind.ToolCall;
	/** Full tool call lifecycle state */
	toolCall: ToolCallState;
}

/**
 * Reasoning/thinking content from the model.
 *
 * @category Response Parts
 */
export interface ReasoningResponsePart {
	/** Discriminant */
	kind: ResponsePartKind.Reasoning;
	/** Part identifier, used by `session/reasoning` to target this part for content appends */
	id: string;
	/** Accumulated reasoning text */
	content: string;
}

/**
 * @category Response Parts
 */
export type ResponsePart = MarkdownResponsePart | ResourceReponsePart | ToolCallResponsePart | ReasoningResponsePart;

// ─── Tool Call Types ─────────────────────────────────────────────────────────

/**
 * Status of a tool call in the lifecycle state machine.
 *
 * @category Tool Call Types
 */
export const enum ToolCallStatus {
	Streaming = 'streaming',
	PendingConfirmation = 'pending-confirmation',
	Running = 'running',
	PendingResultConfirmation = 'pending-result-confirmation',
	Completed = 'completed',
	Cancelled = 'cancelled',
}

/**
 * How a tool call was confirmed for execution.
 *
 * - `NotNeeded` — No confirmation required (auto-approved)
 * - `UserAction` — User explicitly approved
 * - `Setting` — Approved by a persistent user setting
 *
 * @category Tool Call Types
 */
export const enum ToolCallConfirmationReason {
	NotNeeded = 'not-needed',
	UserAction = 'user-action',
	Setting = 'setting',
}

/**
 * Why a tool call was cancelled.
 *
 * @category Tool Call Types
 */
export const enum ToolCallCancellationReason {
	Denied = 'denied',
	Skipped = 'skipped',
	ResultDenied = 'result-denied',
}

/**
 * Whether a confirmation option represents an approval or denial action.
 *
 * @category Tool Call Types
 */
export const enum ConfirmationOptionKind {
	Approve = 'approve',
	Deny = 'deny',
}

/**
 * A confirmation option that the server offers for a tool call awaiting
 * approval. Allows richer choices beyond simple approve/deny — for example,
 * "Approve in this Session" or "Deny with reason."
 *
 * @category Tool Call Types
 */
export interface ConfirmationOption {
	/** Unique identifier for the option, returned in the confirmed action */
	id: string;
	/** Human-readable label displayed to the user */
	label: string;
	/** Whether this option represents an approval or denial */
	kind: ConfirmationOptionKind;
	/**
	 * Logical group number for visual categorisation.
	 *
	 * Clients SHOULD display options in the order they are defined and MAY
	 * use differing group numbers to insert dividers between logical clusters
	 * of options.
	 */
	group?: number;
}

/**
 * Metadata common to all tool call states.
 *
 * @category Tool Call Types
 * @remarks
 * Fields like `toolName` carry agent-specific identifiers on the wire despite the
 * agent-agnostic design principle. These exist for debugging and logging purposes.
 * A future version may move these to a separate diagnostic channel or namespace them
 * more clearly.
 */
interface ToolCallBase {
	/** Unique tool call identifier */
	toolCallId: string;
	/** Internal tool name (for debugging/logging) */
	toolName: string;
	/** Human-readable tool name */
	displayName: string;
	/**
	 * If this tool is provided by a client, the `clientId` of the owning client.
	 * Absent for server-side tools.
	 *
	 * When set, the identified client is responsible for executing the tool and
	 * dispatching `session/toolCallComplete` with the result.
	 */
	toolClientId?: string;
	/**
	 * Additional provider-specific metadata for this tool call.
	 *
	 * Clients MAY look for well-known keys here to provide enhanced UI.
	 * For example, a `ptyTerminal` key with `{ input: string; output: string }`
	 * indicates the tool operated on a terminal (both `input` and `output` may
	 * contain escape sequences).
	 */
	_meta?: Record<string, unknown>;
}

/**
 * Properties available once tool call parameters are fully received.
 *
 * @category Tool Call Types
 */
interface ToolCallParameterFields {
	/** Message describing what the tool will do */
	invocationMessage: StringOrMarkdown;
	/** Raw tool input */
	toolInput?: string;
}

/**
 * Tool execution result details, available after execution completes.
 *
 * @category Tool Call Types
 */
export interface ToolCallResult {
	/** Whether the tool succeeded */
	success: boolean;
	/** Past-tense description of what the tool did */
	pastTenseMessage: StringOrMarkdown;
	/**
	 * Unstructured result content blocks.
	 *
	 * This mirrors the `content` field of MCP `CallToolResult`.
	 */
	content?: ToolResultContent[];
	/**
	 * Optional structured result object.
	 *
	 * This mirrors the `structuredContent` field of MCP `CallToolResult`.
	 */
	structuredContent?: Record<string, unknown>;
	/** Error details if the tool failed */
	error?: { message: string; code?: string };
}

/**
 * LM is streaming the tool call parameters.
 *
 * @category Tool Call Types
 */
export interface ToolCallStreamingState extends ToolCallBase {
	status: ToolCallStatus.Streaming;
	/** Partial parameters accumulated so far */
	partialInput?: string;
	/** Progress message shown while parameters are streaming */
	invocationMessage?: StringOrMarkdown;
}

/**
 * Parameters are complete, or a running tool requires re-confirmation
 * (e.g. a mid-execution permission check).
 *
 * @category Tool Call Types
 */
export interface ToolCallPendingConfirmationState extends ToolCallBase, ToolCallParameterFields {
	status: ToolCallStatus.PendingConfirmation;
	/** Short title for the confirmation prompt (e.g. `"Run in terminal"`, `"Write file"`) */
	confirmationTitle?: StringOrMarkdown;
	/** File edits that this tool call will perform, for preview before confirmation */
	edits?: { items: FileEdit[] };
	/** Whether the agent host allows the client to edit the tool's input parameters before confirming */
	editable?: boolean;
	/**
	 * Options the server offers for this confirmation. When present, the client
	 * SHOULD render these instead of a plain approve/deny UI. Each option
	 * belongs to a {@link ConfirmationOptionGroup} so the client can still
	 * categorise the choices.
	 */
	options?: ConfirmationOption[];
}

/**
 * Tool is actively executing.
 *
 * @category Tool Call Types
 */
export interface ToolCallRunningState extends ToolCallBase, ToolCallParameterFields {
	status: ToolCallStatus.Running;
	/** How the tool was confirmed for execution */
	confirmed: ToolCallConfirmationReason;
	/** The confirmation option the user selected, if confirmation options were provided */
	selectedOption?: ConfirmationOption;
	/**
	 * Partial content produced while the tool is still executing.
	 *
	 * For example, a terminal content block lets clients subscribe to live
	 * output before the tool completes.
	 */
	content?: ToolResultContent[];
}

/**
 * Tool finished executing, waiting for client to approve the result.
 *
 * @category Tool Call Types
 */
export interface ToolCallPendingResultConfirmationState extends ToolCallBase, ToolCallParameterFields, ToolCallResult {
	status: ToolCallStatus.PendingResultConfirmation;
	/** How the tool was confirmed for execution */
	confirmed: ToolCallConfirmationReason;
	/** The confirmation option the user selected, if confirmation options were provided */
	selectedOption?: ConfirmationOption;
}

/**
 * Tool completed successfully or with an error.
 *
 * @category Tool Call Types
 */
export interface ToolCallCompletedState extends ToolCallBase, ToolCallParameterFields, ToolCallResult {
	status: ToolCallStatus.Completed;
	/** How the tool was confirmed for execution */
	confirmed: ToolCallConfirmationReason;
	/** The confirmation option the user selected, if confirmation options were provided */
	selectedOption?: ConfirmationOption;
}

/**
 * Tool call was cancelled before execution.
 *
 * @category Tool Call Types
 */
export interface ToolCallCancelledState extends ToolCallBase, ToolCallParameterFields {
	status: ToolCallStatus.Cancelled;
	/** Why the tool was cancelled */
	reason: ToolCallCancellationReason;
	/** Optional message explaining the cancellation */
	reasonMessage?: StringOrMarkdown;
	/** What the user suggested doing instead */
	userSuggestion?: UserMessage;
	/** The confirmation option the user selected, if confirmation options were provided */
	selectedOption?: ConfirmationOption;
}

/**
 * Discriminated union of all tool call lifecycle states.
 *
 * See the [state model guide](/guide/state-model.html#tool-call-lifecycle)
 * for the full state machine diagram.
 *
 * @category Tool Call Types
 */
export type ToolCallState =
	| ToolCallStreamingState
	| ToolCallPendingConfirmationState
	| ToolCallRunningState
	| ToolCallPendingResultConfirmationState
	| ToolCallCompletedState
	| ToolCallCancelledState;

// ─── Tool Definition Types ───────────────────────────────────────────────────

/**
 * Describes a tool available in a session, provided by either the server or the active client.
 *
 * @category Tool Definition Types
 */
export interface ToolDefinition {
	/** Unique tool identifier */
	name: string;
	/** Human-readable display name */
	title?: string;
	/** Description of what the tool does */
	description?: string;
	/**
	 * JSON Schema defining the expected input parameters.
	 *
	 * Optional because client-provided tools may not have formal schemas.
	 * Mirrors MCP `Tool.inputSchema`.
	 */
	inputSchema?: {
		type: 'object';
		properties?: Record<string, object>;
		required?: string[];
	};
	/**
	 * JSON Schema defining the structure of the tool's output.
	 *
	 * Mirrors MCP `Tool.outputSchema`.
	 */
	outputSchema?: {
		type: 'object';
		properties?: Record<string, object>;
		required?: string[];
	};
	/** Behavioral hints about the tool. All properties are advisory. */
	annotations?: ToolAnnotations;
	/**
	 * Additional provider-specific metadata.
	 *
	 * Mirrors the MCP `_meta` convention.
	 */
	_meta?: Record<string, unknown>;
}

/**
 * Behavioral hints about a tool. All properties are advisory and not
 * guaranteed to faithfully describe tool behavior.
 *
 * Mirrors MCP `ToolAnnotations` from the Model Context Protocol specification.
 *
 * @category Tool Definition Types
 */
export interface ToolAnnotations {
	/** Alternate human-readable title */
	title?: string;
	/** Tool does not modify its environment (default: false) */
	readOnlyHint?: boolean;
	/** Tool may perform destructive updates (default: true) */
	destructiveHint?: boolean;
	/** Repeated calls with the same arguments have no additional effect (default: false) */
	idempotentHint?: boolean;
	/** Tool may interact with external entities (default: true) */
	openWorldHint?: boolean;
}

// ─── Tool Result Content ─────────────────────────────────────────────────────

/**
 * Discriminant for tool result content types.
 *
 * @category Tool Result Content
 */
export const enum ToolResultContentType {
	Text = 'text',
	EmbeddedResource = 'embeddedResource',
	Resource = 'resource',
	FileEdit = 'fileEdit',
	Terminal = 'terminal',
	Subagent = 'subagent',
}

/**
 * Text content in a tool result.
 *
 * Mirrors MCP `TextContent`.
 *
 * @category Tool Result Content
 */
export interface ToolResultTextContent {
	type: ToolResultContentType.Text;
	/** The text content */
	text: string;
}

/**
 * Base64-encoded binary content embedded in a tool result.
 *
 * Mirrors MCP `EmbeddedResource` for inline binary data.
 *
 * @category Tool Result Content
 */
export interface ToolResultEmbeddedResourceContent {
	type: ToolResultContentType.EmbeddedResource;
	/** Base64-encoded data */
	data: string;
	/** Content type (e.g. `"image/png"`, `"application/pdf"`) */
	contentType: string;
}

/**
 * A reference to a resource stored outside the tool result.
 *
 * Wraps {@link ContentRef} for lazy-loading large results.
 *
 * @category Tool Result Content
 */
export interface ToolResultResourceContent extends ContentRef {
	type: ToolResultContentType.Resource;
}

/**
 * Describes a file modification with before/after state and diff metadata.
 *
 * Supports creates (only `after`), deletes (only `before`), renames/moves
 * (different `uri` in `before` and `after`), and edits (same `uri`, different content).
 *
 * @category Tool Result Content
 */
export interface FileEdit {
	/** The file state before the edit. Absent for file creations or for in-place file edits. */
	before?: {
		/** URI of the file before the edit */
		uri: URI;
		/** Reference to the file content before the edit */
		content: ContentRef;
	};
	/** The file state after the edit. Absent for file deletions. */
	after?: {
		/** URI of the file after the edit */
		uri: URI;
		/** Reference to the file content after the edit */
		content: ContentRef;
	};
	/** Optional diff display metadata */
	diff?: {
		/** Number of items added (e.g., lines for text files, cells for notebooks) */
		added?: number;
		/** Number of items removed (e.g., lines for text files, cells for notebooks) */
		removed?: number;
	};
}

/**
 * Describes a file modification performed by a tool.
 *
 * @category Tool Result Content
 */
export interface ToolResultFileEditContent extends FileEdit {
	type: ToolResultContentType.FileEdit;
}

/**
 * A reference to a terminal whose output is relevant to this tool result.
 *
 * Clients can subscribe to the terminal's URI to stream its output in real
 * time, providing live feedback while a tool is executing.
 *
 * @category Tool Result Content
 */
export interface ToolResultTerminalContent {
	type: ToolResultContentType.Terminal;
	/** Terminal URI (subscribable for full terminal state) */
	resource: URI;
	/** Display title for the terminal content */
	title: string;
}

/**
 * A reference to a subagent session spawned by a tool.
 *
 * Clients can subscribe to the subagent's session URI to stream its
 * progress in real time, including inner tool calls and responses.
 *
 * @category Tool Result Content
 */
export interface ToolResultSubagentContent {
	type: ToolResultContentType.Subagent;
	/** Subagent session URI (subscribable for full session state) */
	resource: URI;
	/** Display title for the subagent */
	title: string;
	/** Internal agent name */
	agentName?: string;
	/** Human-readable description of the subagent's task */
	description?: string;
}

/**
 * Content block in a tool result.
 *
 * Mirrors the content blocks in MCP `CallToolResult.content`, plus
 * `ToolResultResourceContent` for lazy-loading large results,
 * `ToolResultFileEditContent` for file edit diffs,
 * `ToolResultTerminalContent` for live terminal output, and
 * `ToolResultSubagentContent` for subagent sessions (AHP extensions).
 *
 * @category Tool Result Content
 */
export type ToolResultContent =
	| ToolResultTextContent
	| ToolResultEmbeddedResourceContent
	| ToolResultResourceContent
	| ToolResultFileEditContent
	| ToolResultTerminalContent
	| ToolResultSubagentContent;

// ─── Customization Types ─────────────────────────────────────────────────────

/**
 * A reference to an [Open Plugins](https://open-plugins.com/) plugin.
 *
 * This is intentionally thin — AHP specifies plugin identity and metadata
 * but not implementation details, which are defined by the Open Plugins spec.
 *
 * @category Customization Types
 */
export interface CustomizationRef {
	/** Plugin URI (e.g. an HTTPS URL or marketplace identifier) */
	uri: URI;
	/** Human-readable name */
	displayName: string;
	/** Description of what the plugin provides */
	description?: string;
	/** Icons for the plugin */
	icons?: Icon[];
	/**
	 * Opaque version token for this customization.
	 *
	 * Clients SHOULD include a nonce with every customization they provide.
	 * Consumers can compare nonces to detect whether a customization has
	 * changed since it was last seen, avoiding redundant reloads or copies.
	 */
	nonce?: string;
}

/**
 * Loading status for a server-managed customization.
 *
 * @category Customization Types
 */
export const enum CustomizationStatus {
	/** Plugin is being loaded */
	Loading = 'loading',
	/** Plugin is fully operational */
	Loaded = 'loaded',
	/** Plugin partially loaded but has warnings */
	Degraded = 'degraded',
	/** Plugin was unable to load */
	Error = 'error',
}

/**
 * A customization active in a session.
 *
 * @category Customization Types
 */
export interface SessionCustomization {
	/** The plugin this customization refers to */
	customization: CustomizationRef;
	/** Whether this customization is currently enabled */
	enabled: boolean;
	/**
	 * The `clientId` of the client that contributed this customization.
	 * Absent for host-provided customizations.
	 */
	clientId?: string;
	/** Server-reported loading status */
	status?: CustomizationStatus;
	/**
	 * Human-readable status detail (e.g. error message or degradation warning).
	 */
	statusMessage?: string;
}

// ─── Terminal Types ──────────────────────────────────────────────────────────

/**
 * Lightweight terminal metadata exposed on the root state.
 *
 * @category Terminal Types
 */
export interface TerminalInfo {
	/** Terminal URI (subscribable for full terminal state) */
	resource: URI;
	/** Human-readable terminal title */
	title: string;
	/** Who currently holds this terminal */
	claim: TerminalClaim;
	/** Process exit code, if the terminal process has exited */
	exitCode?: number;
}

/**
 * Discriminant for terminal claim kinds.
 *
 * @category Terminal Types
 */
export const enum TerminalClaimKind {
	Client = 'client',
	Session = 'session',
}

/**
 * A terminal claimed by a connected client.
 *
 * @category Terminal Types
 */
export interface TerminalClientClaim {
	/** Discriminant */
	kind: TerminalClaimKind.Client;
	/** The `clientId` of the claiming client */
	clientId: string;
}

/**
 * A terminal claimed by a session, optionally scoped to a specific turn or tool call.
 *
 * @category Terminal Types
 */
export interface TerminalSessionClaim {
	/** Discriminant */
	kind: TerminalClaimKind.Session;
	/** Session URI that claimed the terminal */
	session: URI;
	/** Optional turn identifier within the session */
	turnId?: string;
	/** Optional tool call identifier within the turn */
	toolCallId?: string;
}

/**
 * Describes who currently holds a terminal. A terminal may be claimed by
 * either a connected client or a session (e.g. during a tool call).
 *
 * @category Terminal Types
 */
export type TerminalClaim = TerminalClientClaim | TerminalSessionClaim;

/**
 * Full state for a single terminal, loaded when a client subscribes to the terminal's URI.
 *
 * @category Terminal Types
 */
export interface TerminalState {
	/** Human-readable terminal title */
	title: string;
	/** Current working directory of the terminal process */
	cwd?: URI;
	/** Terminal width in columns */
	cols?: number;
	/** Terminal height in rows */
	rows?: number;
	/**
	 * Typed content parts, replacing the flat `content: string`.
	 *
	 * Naive consumers that only need the raw VT stream can reconstruct it with:
	 *   `content.map(p => p.type === 'command' ? p.output : p.value).join('')`
	 *
	 * Consumers that need command boundaries can filter by part type.
	 */
	content: TerminalContentPart[];
	/** Process exit code, set when the terminal process exits */
	exitCode?: number;
	/** Who currently holds this terminal */
	claim: TerminalClaim;
	/**
	 * Whether this terminal emits `terminal/commandExecuted` and
	 * `terminal/commandFinished` actions and populates `command`-typed parts.
	 *
	 * Clients MUST check this flag before relying on command detection.
	 * Do NOT use the presence of a `command` part as a feature flag — parts
	 * are absent in the normal idle state.
	 */
	supportsCommandDetection?: boolean;
}

// ─── Terminal Content Parts ──────────────────────────────────────────────────

/**
 * A content part within terminal output.
 *
 * @category Terminal Types
 */
export type TerminalContentPart =
	| TerminalUnclassifiedPart
	| TerminalCommandPart;

/**
 * Unstructured terminal output — content before, between, or after commands,
 * or from terminals that do not support command detection.
 *
 * @category Terminal Types
 */
export interface TerminalUnclassifiedPart {
	type: 'unclassified';
	/** Accumulated VT output. Appended to by `terminal/data` when no command is executing. */
	value: string;
}

/**
 * A single command: its command line and the output it produced.
 *
 * While `isComplete` is false the command is still executing; `output` grows
 * as `terminal/data` actions arrive. At `terminal/commandFinished` the part
 * is mutated in-place with `isComplete: true` and the completion metadata.
 *
 * @category Terminal Types
 */
export interface TerminalCommandPart {
	type: 'command';
	/**
	 * Stable id matching the `commandId` on the corresponding
	 * `terminal/commandExecuted` and `terminal/commandFinished` actions.
	 */
	commandId: string;
	/** The command line submitted to the shell. */
	commandLine: string;
	/**
	 * Accumulated VT output. Appended to by `terminal/data` while `isComplete`
	 * is false. Shell integration escape sequences are stripped by the server.
	 */
	output: string;
	/** Unix timestamp (ms) when execution started, as reported by the server. */
	timestamp: number;
	/** Whether the command has finished. */
	isComplete: boolean;
	/** Shell exit code. Set at completion. `undefined` if unknown. */
	exitCode?: number;
	/** Wall-clock duration in milliseconds. Set at completion. */
	durationMs?: number;
}

// ─── Common Types ────────────────────────────────────────────────────────────

/**
 * @category Common Types
 */
export interface UsageInfo {
	/** Input tokens consumed */
	inputTokens?: number;
	/** Output tokens generated */
	outputTokens?: number;
	/** Model used */
	model?: string;
	/** Tokens read from cache */
	cacheReadTokens?: number;
}

/**
 * @category Common Types
 */
export interface ErrorInfo {
	/** Error type identifier */
	errorType: string;
	/** Human-readable error message */
	message: string;
	/** Stack trace */
	stack?: string;
}

/**
 * A point-in-time snapshot of a subscribed resource's state, returned by
 * `initialize`, `reconnect`, and `subscribe`.
 *
 * @category Common Types
 */
export interface Snapshot {
	/** The subscribed resource URI (e.g. `agenthost:/root` or `copilot:/<uuid>`) */
	resource: URI;
	/** The current state of the resource */
	state: RootState | SessionState | TerminalState;
	/** The `serverSeq` at which this snapshot was taken. Subsequent actions will have `serverSeq > fromSeq`. */
	fromSeq: number;
}