commands.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

import type { URI, Snapshot, SessionConfigSchema, SessionSummary, ModelSelection, Turn, TerminalClaim, SessionActiveClient } from './state.js';
import type { ActionEnvelope, StateAction } from './actions.js';

export type { ConfigPropertySchema, ConfigSchema, SessionConfigPropertySchema, SessionConfigSchema } from './state.js';

// ─── initialize ──────────────────────────────────────────────────────────────

/**
 * Establishes a new connection and negotiates the protocol version.
 * This MUST be the first message sent by the client.
 *
 * @category Commands
 * @method initialize
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @see {@link /specification/lifecycle | Lifecycle} for the full handshake flow.
 */
export interface InitializeParams {
	/** Protocol version the client speaks */
	protocolVersion: number;
	/** Unique client identifier */
	clientId: string;
	/** URIs to subscribe to during handshake */
	initialSubscriptions?: URI[];
	/**
	 * IETF BCP 47 language tag indicating the client's preferred locale
	 * (e.g. `"en-US"`, `"ja"`). The server SHOULD use this to localise
	 * user-facing strings such as confirmation option labels.
	 */
	locale?: string;
}

/**
 * Result of the `initialize` command.
 *
 * If the server does not support the client's protocol version, it MUST return
 * error code `-32005` (`UnsupportedProtocolVersion`).
 */
export interface InitializeResult {
	/** Protocol version the server speaks */
	protocolVersion: number;
	/** Current server sequence number */
	serverSeq: number;
	/** Snapshots for each `initialSubscriptions` URI */
	snapshots: Snapshot[];
	/** Suggested default directory for remote filesystem browsing */
	defaultDirectory?: URI;
}

// ─── reconnect ───────────────────────────────────────────────────────────────

/**
 * Discriminant for reconnect result types.
 *
 * @category Commands
 */
export const enum ReconnectResultType {
	Replay = 'replay',
	Snapshot = 'snapshot',
}

/**
 * Re-establishes a dropped connection. The server replays missed actions or
 * provides fresh snapshots.
 *
 * @category Commands
 * @method reconnect
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @see {@link /specification/lifecycle | Lifecycle} for details.
 */
export interface ReconnectParams {
	/** Client identifier from the original connection */
	clientId: string;
	/** Last `serverSeq` the client received */
	lastSeenServerSeq: number;
	/** URIs the client was subscribed to */
	subscriptions: URI[];
}

/**
 * Reconnect result when the server can replay from the requested sequence.
 *
 * The server MUST include all replayed data in the response.
 */
export interface ReconnectReplayResult {
	/** Discriminant */
	type: ReconnectResultType.Replay;
	/** Missed action envelopes since `lastSeenServerSeq` */
	actions: ActionEnvelope[];
}

/**
 * Reconnect result when the gap exceeds the replay buffer.
 */
export interface ReconnectSnapshotResult {
	/** Discriminant */
	type: ReconnectResultType.Snapshot;
	/** Fresh snapshots for each subscription */
	snapshots: Snapshot[];
}

/** Result of the `reconnect` command. */
export type ReconnectResult = ReconnectReplayResult | ReconnectSnapshotResult;

// ─── subscribe ───────────────────────────────────────────────────────────────

/**
 * Subscribe to a URI-identified state resource.
 *
 * @category Commands
 * @method subscribe
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @see {@link /specification/subscriptions | Subscriptions}
 */
export interface SubscribeParams {
	/** URI to subscribe to */
	resource: URI;
}

/**
 * Result of the `subscribe` command.
 */
export interface SubscribeResult {
	/** Snapshot of the subscribed resource */
	snapshot: Snapshot;
}

// ─── createSession ───────────────────────────────────────────────────────────

/**
 * Creates a new session with the specified agent provider.
 *
 * If the session URI already exists, the server MUST return an error with code
 * `-32003` (`SessionAlreadyExists`).
 *
 * After creation, the client should subscribe to the session URI to receive state
 * updates. The server also broadcasts a `notify/sessionAdded` notification to all
 * clients.
 *
 * @category Commands
 * @method createSession
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @example
 * ```jsonc
 * // Client → Server
 * { "jsonrpc": "2.0", "id": 2, "method": "createSession",
 *   "params": { "session": "copilot:/<uuid>", "provider": "copilot", "model": "gpt-4o" } }
 *
 * // Server → Client (success)
 * { "jsonrpc": "2.0", "id": 2, "result": null }
 *
 * // Server → Client (failure — provider not found)
 * { "jsonrpc": "2.0", "id": 2, "error": { "code": -32002, "message": "No agent for provider" } }
 *
 * // Server → Client (failure — session already exists)
 * { "jsonrpc": "2.0", "id": 2, "error": { "code": -32003, "message": "Session already exists" } }
 * ```
 */
/**
 * Identifies a source session and turn to fork from.
 *
 * When provided in `createSession`, the server populates the new session with
 * content from the source session up to and including the response of the
 * specified turn.
 */
export interface SessionForkSource {
	/** URI of the existing session to fork from */
	session: URI;
	/** Turn ID in the source session; content up to and including this turn's response is copied */
	turnId: string;
}

export interface CreateSessionParams {
	/** Session URI (client-chosen, e.g. `copilot:/<uuid>`) */
	session: URI;
	/** Agent provider ID */
	provider?: string;
	/** Model selection (ID and optional model-specific configuration) */
	model?: ModelSelection;
	/** Working directory for the session */
	workingDirectory?: URI;
	/**
	 * Fork from an existing session. The new session is populated with content
	 * from the source session up to and including the specified turn's response.
	 */
	fork?: SessionForkSource;
	/**
	 * Agent-specific configuration values collected via `resolveSessionConfig`.
	 * Keys and values correspond to the schema returned by the server.
	 */
	config?: Record<string, unknown>;
	/**
	 * Eagerly claim the active client role for the new session.
	 *
	 * When provided, the server initializes the session with this client as the
	 * active client, equivalent to dispatching a `session/activeClientChanged`
	 * action immediately after creation. The `clientId` MUST match the
	 * `clientId` the creating client supplied in `initialize`.
	 */
	activeClient?: SessionActiveClient;
}

// ─── disposeSession ──────────────────────────────────────────────────────────

/**
 * Disposes a session and cleans up server-side resources.
 *
 * The server broadcasts a `notify/sessionRemoved` notification to all clients.
 *
 * @category Commands
 * @method disposeSession
 * @direction Client → Server
 * @messageType Request
 * @version 1
 */
export interface DisposeSessionParams {
	/** Session URI to dispose */
	session: URI;
}

// ─── createTerminal ──────────────────────────────────────────────────────────

/**
 * Creates a new terminal on the server.
 *
 * After creation, the client should subscribe to the terminal URI to receive
 * state updates. The server dispatches `root/terminalsChanged` to update the
 * root terminal list.
 *
 * @category Commands
 * @method createTerminal
 * @direction Client → Server
 * @messageType Request
 * @version 1
 */
export interface CreateTerminalParams {
	/** Terminal URI (client-chosen) */
	terminal: URI;
	/** Initial owner of the terminal */
	claim: TerminalClaim;
	/** Human-readable terminal name */
	name?: string;
	/** Initial working directory URI */
	cwd?: URI;
	/** Initial terminal width in columns */
	cols?: number;
	/** Initial terminal height in rows */
	rows?: number;
}

// ─── disposeTerminal ─────────────────────────────────────────────────────────

/**
 * Disposes a terminal and kills its process if still running.
 *
 * The server dispatches `root/terminalsChanged` to remove the terminal from
 * the root terminal list.
 *
 * @category Commands
 * @method disposeTerminal
 * @direction Client → Server
 * @messageType Request
 * @version 1
 */
export interface DisposeTerminalParams {
	/** Terminal URI to dispose */
	terminal: URI;
}

// ─── listSessions ────────────────────────────────────────────────────────────

/**
 * Returns a list of session summaries. Used to populate session lists and sidebars.
 *
 * The session list is **not** part of the state tree because it can be arbitrarily
 * large. Clients fetch it imperatively and maintain a local cache updated by
 * `notify/sessionAdded` and `notify/sessionRemoved` notifications.
 *
 * @category Commands
 * @method listSessions
 * @direction Client → Server
 * @messageType Request
 * @version 1
 */
export interface ListSessionsParams {
	/** Optional filter criteria */
	filter?: object;
}

/** Result of the `listSessions` command. */
export interface ListSessionsResult {
	/** The list of session summaries. */
	items: SessionSummary[];
}

// ─── resourceRead ────────────────────────────────────────────────────────

/**
 * Encoding of fetched content data.
 *
 * @category Commands
 */
export const enum ContentEncoding {
	Base64 = 'base64',
	Utf8 = 'utf-8',
}

/**
 * Reads the content of a resource by URI.
 *
 * Content references keep the state tree small by storing large data (images,
 * long tool outputs) by reference rather than inline.
 *
 * Binary content (images, etc.) MUST use `base64` encoding. Text content MAY
 * use `utf-8` encoding.
 *
 * @category Commands
 * @method resourceRead
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @throws `NotFound` (`-32008`) if the URI does not exist.
 * @throws `PermissionDenied` (`-32009`) if the client is not permitted to read the URI.
 * @example
 * ```jsonc
 * // Client → Server
 * { "jsonrpc": "2.0", "id": 10, "method": "resourceRead",
 *   "params": { "uri": "copilot:/<uuid>/content/img-1" } }
 *
 * // Server → Client
 * { "jsonrpc": "2.0", "id": 10, "result": {
 *   "data": "iVBORw0KGgo...",
 *   "encoding": "base64",
 *   "contentType": "image/png"
 * }}
 * ```
 */
export interface ResourceReadParams {
	/** Content URI from a `ContentRef` */
	uri: string;
	/** Preferred encoding for the returned data (default: server-chosen) */
	encoding?: ContentEncoding;
}

/**
 * Result of the `resourceRead` command.
 *
 * The server SHOULD honor the `encoding` requested in the params. If the
 * server cannot provide the requested encoding, it MUST fall back to either
 * `base64` or `utf-8`.
 */
export interface ResourceReadResult {
	/** Content encoded as a string */
	data: string;
	/** How `data` is encoded */
	encoding: ContentEncoding;
	/** Content type (e.g. `"image/png"`, `"text/plain"`) */
	contentType?: string;
}

// ─── resourceWrite ───────────────────────────────────────────────────────────

/**
 * Writes content to a file on the server's filesystem.
 *
 * Binary content (images, etc.) MUST use `base64` encoding. Text content MAY
 * use `utf-8` encoding.
 *
 * If the file does not exist, it is created. If the file already exists, it is
 * overwritten unless `createOnly` is set.
 *
 * @category Commands
 * @method resourceWrite
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @throws `NotFound` (`-32008`) if the parent directory does not exist.
 * @throws `PermissionDenied` (`-32009`) if the client is not permitted to write to the path.
 * @throws `AlreadyExists` (`-32010`) if `createOnly` is set and the file already exists.
 * @example
 * ```jsonc
 * // Client → Server
 * { "jsonrpc": "2.0", "id": 11, "method": "resourceWrite",
 *   "params": { "uri": "file:///workspace/hello.txt", "data": "SGVsbG8=",
 *              "encoding": "base64", "contentType": "text/plain" } }
 *
 * // Server → Client
 * { "jsonrpc": "2.0", "id": 11, "result": {} }
 * ```
 */
export interface ResourceWriteParams {
	/** Target file URI on the server filesystem */
	uri: URI;
	/** Content encoded as a string */
	data: string;
	/** How `data` is encoded */
	encoding: ContentEncoding;
	/** Content type (e.g. `"text/plain"`, `"image/png"`) */
	contentType?: string;
	/**
	 * If `true`, the server MUST fail if the file already exists instead of
	 * overwriting it. Useful for safe creation of new files.
	 */
	createOnly?: boolean;
}

/**
 * Result of the `resourceWrite` command.
 *
 * An empty object on success.
 */
export interface ResourceWriteResult {
}

// ─── resourceList ────────────────────────────────────────────────────────

/**
 * Lists directory entries at a file URI on the server's filesystem.
 *
 * This is intended for remote folder pickers and similar UI that needs to let
 * users navigate the server's local filesystem.
 *
 * The server MUST return success only if the target exists and is a directory.
 * If the target does not exist, is not a directory, or cannot be accessed, the
 * server MUST return a JSON-RPC error.
 *
 * @category Commands
 * @method resourceList
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @throws `NotFound` (`-32008`) if the directory does not exist.
 * @throws `PermissionDenied` (`-32009`) if the client is not permitted to browse the directory.
 */
export interface ResourceListParams {
	/** Directory URI on the server filesystem */
	uri: URI;
}

/**
 * Directory entry returned by `resourceList`.
 */
export interface DirectoryEntry {
	/** Base name of the entry */
	name: string;
	/** Whether the entry is a file or directory */
	type: 'file' | 'directory';
}

/**
 * Result of the `resourceList` command.
 */
export interface ResourceListResult {
	/** Entries directly contained in the requested directory */
	entries: DirectoryEntry[];
}

// ─── fetchTurns ──────────────────────────────────────────────────────────────

/**
 * Fetches historical turns for a session. Used for lazy loading of conversation
 * history.
 *
 * @category Commands
 * @method fetchTurns
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @example
 * ```jsonc
 * // Client → Server (fetch the 20 most recent turns)
 * { "jsonrpc": "2.0", "id": 8, "method": "fetchTurns",
 *   "params": { "session": "copilot:/<uuid>", "limit": 20 } }
 *
 * // Server → Client
 * { "jsonrpc": "2.0", "id": 8, "result": {
 *   "turns": [ { "id": "t1", ... }, { "id": "t2", ... } ],
 *   "hasMore": true
 * }}
 *
 * // Client → Server (fetch 20 turns before t1)
 * { "jsonrpc": "2.0", "id": 9, "method": "fetchTurns",
 *   "params": { "session": "copilot:/<uuid>", "before": "t1", "limit": 20 } }
 * ```
 */
export interface FetchTurnsParams {
	/** Session URI */
	session: URI;
	/** Turn ID to fetch before (exclusive). Omit to fetch from the most recent turn. */
	before?: string;
	/** Maximum number of turns to return. Server MAY impose its own upper bound. */
	limit?: number;
}

/**
 * Result of the `fetchTurns` command.
 */
export interface FetchTurnsResult {
	/** The requested turns, ordered oldest-first */
	turns: Turn[];
	/** Whether more turns exist before the returned range */
	hasMore: boolean;
}

// ─── unsubscribe ─────────────────────────────────────────────────────────────

/**
 * Stop receiving updates for a URI.
 *
 * @category Commands
 * @method unsubscribe
 * @direction Client → Server
 * @messageType Notification
 * @version 1
 * @see {@link /specification/subscriptions | Subscriptions}
 */
export interface UnsubscribeParams {
	/** URI to unsubscribe from */
	resource: URI;
}

// ─── dispatchAction ──────────────────────────────────────────────────────────

/**
 * Fire-and-forget action dispatch (write-ahead). The client applies actions
 * optimistically to local state.
 *
 * @category Commands
 * @method dispatchAction
 * @direction Client → Server
 * @messageType Notification
 * @version 1
 * @see {@link /guide/actions | Actions} for the full list of client-dispatchable actions.
 */
export interface DispatchActionParams {
	/** Client sequence number */
	clientSeq: number;
	/** The action to dispatch */
	action: StateAction;
}

// ─── resourceCopy ────────────────────────────────────────────────────────────

/**
 * Copies a resource from one URI to another on the server's filesystem.
 *
 * If the destination already exists, it is overwritten unless `failIfExists`
 * is set.
 *
 * @category Commands
 * @method resourceCopy
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @throws `NotFound` (`-32008`) if the source does not exist.
 * @throws `PermissionDenied` (`-32009`) if the client is not permitted to read the source or write to the destination.
 * @throws `AlreadyExists` (`-32010`) if `failIfExists` is set and the destination already exists.
 */
export interface ResourceCopyParams {
	/** Source URI to copy from */
	source: URI;
	/** Destination URI to copy to */
	destination: URI;
	/**
	 * If `true`, the server MUST fail if the destination already exists instead
	 * of overwriting it.
	 */
	failIfExists?: boolean;
}

/**
 * Result of the `resourceCopy` command.
 *
 * An empty object on success.
 */
export interface ResourceCopyResult {
}

// ─── resourceDelete ──────────────────────────────────────────────────────────

/**
 * Deletes a resource at a URI on the server's filesystem.
 *
 * @category Commands
 * @method resourceDelete
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @throws `NotFound` (`-32008`) if the resource does not exist.
 * @throws `PermissionDenied` (`-32009`) if the client is not permitted to delete the resource.
 */
export interface ResourceDeleteParams {
	/** URI of the resource to delete */
	uri: URI;
	/**
	 * If `true` and the target is a directory, delete it and all its contents
	 * recursively. If `false` (default), deleting a non-empty directory MUST fail.
	 */
	recursive?: boolean;
}

/**
 * Result of the `resourceDelete` command.
 *
 * An empty object on success.
 */
export interface ResourceDeleteResult {
}

// ─── resourceMove ────────────────────────────────────────────────────────────

/**
 * Moves (renames) a resource from one URI to another on the server's filesystem.
 *
 * If the destination already exists, it is overwritten unless `failIfExists`
 * is set.
 *
 * @category Commands
 * @method resourceMove
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @throws `NotFound` (`-32008`) if the source does not exist.
 * @throws `PermissionDenied` (`-32009`) if the client is not permitted to move the resource.
 * @throws `AlreadyExists` (`-32010`) if `failIfExists` is set and the destination already exists.
 */
export interface ResourceMoveParams {
	/** Source URI to move from */
	source: URI;
	/** Destination URI to move to */
	destination: URI;
	/**
	 * If `true`, the server MUST fail if the destination already exists instead
	 * of overwriting it.
	 */
	failIfExists?: boolean;
}

/**
 * Result of the `resourceMove` command.
 *
 * An empty object on success.
 */
export interface ResourceMoveResult {
}

// ─── authenticate ────────────────────────────────────────────────────────────

/**
 * Pushes a Bearer token for a protected resource. The `resource` field MUST
 * match a `ProtectedResourceMetadata.resource` value declared by an agent
 * in `AgentInfo.protectedResources`.
 *
 * Tokens are delivered using [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)
 * (Bearer Token Usage) semantics. The client obtains the token from the
 * authorization server(s) listed in the resource's metadata and pushes it
 * to the server via this command.
 *
 * @category Commands
 * @method authenticate
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @see {@link /specification/authentication | Authentication}
 * @example
 * ```jsonc
 * // Client → Server
 * { "jsonrpc": "2.0", "id": 3, "method": "authenticate",
 *   "params": { "resource": "https://api.github.com", "token": "gho_xxxx" } }
 *
 * // Server → Client (success)
 * { "jsonrpc": "2.0", "id": 3, "result": {} }
 *
 * // Server → Client (failure — invalid token)
 * { "jsonrpc": "2.0", "id": 3, "error": { "code": -32007, "message": "Invalid token" } }
 * ```
 */
export interface AuthenticateParams {
	/**
	 * The protected resource identifier. MUST match a `resource` value from
	 * `ProtectedResourceMetadata` declared in `AgentInfo.protectedResources`.
	 */
	resource: string;
	/** Bearer token obtained from the resource's authorization server */
	token: string;
}

/**
 * Result of the `authenticate` command.
 *
 * An empty object on success. If the token is invalid or the resource is
 * unrecognized, the server MUST return a JSON-RPC error (e.g. `AuthRequired`
 * `-32007` or `InvalidParams` `-32602`).
 */
export interface AuthenticateResult {
}

// ─── resolveSessionConfig ────────────────────────────────────────────────────

/**
 * Iteratively resolves the session configuration schema. The client sends the
 * current partial session config and any user-filled metadata values. The server
 * returns a property schema describing what additional metadata is needed,
 * contextual to the current selections.
 *
 * The client calls this command whenever the user changes a significant input
 * (e.g. picks a working directory, toggles a property). Each response returns
 * the full current property set (not a delta). The returned `values` contain
 * server-resolved defaults to pass to `createSession`.
 *
 * @category Commands
 * @method resolveSessionConfig
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @example
 * ```jsonc
 * // Step 1: Client picks a working directory
 * // Client → Server
 * { "jsonrpc": "2.0", "id": 5, "method": "resolveSessionConfig",
 *   "params": { "workingDirectory": "file:///home/user/my-project" } }
 *
 * // Server → Client (git repo detected, offers worktree option)
 * { "jsonrpc": "2.0", "id": 5, "result": {
 *   "schema": {
 *     "type": "object",
 *     "properties": {
 *       "target": { "type": "string", "title": "Target", "enum": ["workspace", "worktree"] }
 *     }
 *   },
 *   "values": {}
 * }}
 *
 * // Step 2: User enables worktree
 * // Client → Server
 * { "jsonrpc": "2.0", "id": 6, "method": "resolveSessionConfig",
 *   "params": { "workingDirectory": "file:///home/user/my-project",
 *               "config": { "target": "worktree" } } }
 *
 * // Server → Client (now requires branch selection)
 * { "jsonrpc": "2.0", "id": 6, "result": {
 *   "schema": {
 *     "type": "object",
 *     "properties": {
 *       "target": { "type": "string", "title": "Target", "enum": ["workspace", "worktree"] },
 *       "baseBranch": { "type": "string", "title": "Base Branch",
 *                       "enum": ["main", "develop"],
 *                       "enumLabels": ["main", "develop"] }
 *     },
 *     "required": ["baseBranch"]
 *   },
 *   "values": { "target": "worktree" }
 * }}
 * ```
 */
export interface ResolveSessionConfigParams {
	/** Agent provider ID */
	provider?: string;
	/** Working directory for the session */
	workingDirectory?: URI;
	/** Current user-filled configuration values */
	config?: Record<string, unknown>;
}

/**
 * Result of the `resolveSessionConfig` command.
 */
export interface ResolveSessionConfigResult {
	/** JSON Schema describing available configuration properties given the current context */
	schema: SessionConfigSchema;
	/** Current configuration values (echoed back with server-resolved defaults applied) */
	values: Record<string, unknown>;
}

// ─── sessionConfigCompletions ────────────────────────────────────────────────

/**
 * A single value item returned by `sessionConfigCompletions`.
 *
 * @category Commands
 */
export interface SessionConfigValueItem {
	/** The value to store in config */
	value: string;
	/** Human-readable display label */
	label: string;
	/** Optional secondary description */
	description?: string;
}

/**
 * Queries the server for allowed values of a dynamic session config property.
 *
 * Used when a property in the schema returned by `resolveSessionConfig` has
 * `enumDynamic: true`. The client sends a search query and receives matching
 * values with display metadata.
 *
 * @category Commands
 * @method sessionConfigCompletions
 * @direction Client → Server
 * @messageType Request
 * @version 1
 * @example
 * ```jsonc
 * // Client → Server (user types "ma" in branch picker)
 * { "jsonrpc": "2.0", "id": 7, "method": "sessionConfigCompletions",
 *   "params": { "workingDirectory": "file:///home/user/my-project",
 *               "config": { "target": "worktree" },
 *               "property": "baseBranch", "query": "ma" } }
 *
 * // Server → Client
 * { "jsonrpc": "2.0", "id": 7, "result": {
 *   "items": [
 *     { "value": "main", "label": "main", "icon": "git-branch" },
 *     { "value": "main-v2", "label": "main-v2", "icon": "git-branch" }
 *   ]
 * }}
 * ```
 */
export interface SessionConfigCompletionsParams {
	/** Agent provider ID */
	provider?: string;
	/** Working directory for the session */
	workingDirectory?: URI;
	/** Current user-filled configuration values (provides context for the query) */
	config?: Record<string, unknown>;
	/** Property id from the schema to query values for */
	property: string;
	/** Search filter text (empty or omitted returns default/recent values) */
	query?: string;
}

/**
 * Result of the `sessionConfigCompletions` command.
 */
export interface SessionConfigCompletionsResult {
	/** Matching value items */
	items: SessionConfigValueItem[];
}