@codingame/monaco-vscode-api 33.0.9 → 34.0.0

package/vscode/src/vs/platform/agentHost/common/state/protocol/channels-resource-watch/commands.d.ts

@@ -0,0 +1,80 @@
+import type { URI } from "../common/state.js";
+import type { BaseParams } from "../common/commands.js";
+/**
+ * Creates a resource watcher on the receiver's filesystem.
+ *
+ * The receiver allocates an `ahp-resource-watch:/<id>` channel URI and
+ * returns it on {@link CreateResourceWatchResult.channel}. The caller then
+ * [`subscribe`](./subscriptions)s to that channel to receive
+ * `resourceWatch/changed` actions over the standard action envelope.
+ *
+ * The watch lifecycle is tied to subscription: when every subscriber has
+ * unsubscribed (or the underlying connection drops), the receiver MUST
+ * release the watcher. There is no explicit dispose command — `unsubscribe`
+ * is the only handle the caller needs.
+ *
+ * Like the rest of the `resource*` family, `createResourceWatch` is
+ * symmetrical and MAY be sent in either direction. Access is gated through
+ * the same permission flow as `resourceRead`/`resourceWrite`.
+ *
+ * @category Commands
+ * @method createResourceWatch
+ * @direction Client ↔ Server
+ * @messageType Request
+ * @version 1
+ * @throws `NotFound` (`-32008`) if `uri` does not exist.
+ * @throws `PermissionDenied` (`-32009`) if the caller is not permitted to watch the URI.
+ * @example
+ * ```jsonc
+ * // Client → Server
+ * { "jsonrpc": "2.0", "id": 30, "method": "createResourceWatch",
+ *   "params": {
+ *     "channel": "ahp-root://",
+ *     "uri": "file:///workspace",
+ *     "recursive": true,
+ *     "excludes": { "items": ["**\u002f.git/**", "**\u002fnode_modules/**"] }
+ *   } }
+ *
+ * // Server → Client
+ * { "jsonrpc": "2.0", "id": 30, "result": {
+ *   "channel": "ahp-resource-watch:/d3a9f1e0-…"
+ * } }
+ * ```
+ */
+export interface CreateResourceWatchParams extends BaseParams {
+    channel: "ahp-root://";
+    /** URI to watch. */
+    uri: URI;
+    /**
+     * If `true`, the receiver MUST report changes for descendants of `uri`.
+     * If `false` (default), only changes to `uri` itself — and, when `uri`
+     * is a directory, its direct children — are reported.
+     */
+    recursive?: boolean;
+    /**
+     * Glob patterns or paths relative to `uri` to exclude from reporting.
+     * Wrapped in `{ items }` for forward compatibility.
+     */
+    excludes?: {
+        items: string[];
+    };
+    /**
+     * Glob patterns or paths relative to `uri` to restrict reporting to.
+     * Omit to report every change under `uri` subject to `excludes`.
+     * Wrapped in `{ items }` for forward compatibility.
+     */
+    includes?: {
+        items: string[];
+    };
+}
+/**
+ * Result of the `createResourceWatch` command.
+ */
+export interface CreateResourceWatchResult {
+    /**
+     * Receiver-assigned watch channel URI (`ahp-resource-watch:/<id>`). The
+     * caller subscribes to this URI to start receiving change events and
+     * unsubscribes to release the watcher.
+     */
+    channel: URI;
+}

package/vscode/src/vs/platform/agentHost/common/state/protocol/channels-resource-watch/state.d.ts

@@ -0,0 +1,62 @@
+import type { URI } from "../common/state.js";
+/**
+ * Full state for a single resource watch, returned when a client subscribes
+ * to an `ahp-resource-watch:` URI.
+ *
+ * Watches are otherwise stateless: the watcher exists to deliver
+ * {@link ResourceWatchChangedAction} events. The state carries only the
+ * descriptor of what is being watched so a re-subscribing client can
+ * recover the watch configuration after reconnecting.
+ *
+ * @category Resource Watch Types
+ */
+export interface ResourceWatchState {
+    /**
+     * The URI being watched. For recursive watches this is the root of the
+     * subtree; for non-recursive watches this is the single file or
+     * directory.
+     */
+    root: URI;
+    /**
+     * `true` if the watcher reports changes for descendants of `root`;
+     * `false` if it only reports changes to `root` itself (and, when
+     * `root` is a directory, its direct children).
+     */
+    recursive: boolean;
+    /**
+     * Optional glob patterns or paths relative to `root` to exclude from
+     * change reporting.
+     */
+    excludes?: {
+        items: string[];
+    };
+    /**
+     * Optional glob patterns or paths relative to `root` to restrict
+     * change reporting to. Omit to report every change under `root`
+     * subject to `excludes`.
+     */
+    includes?: {
+        items: string[];
+    };
+}
+/**
+ * Discriminant for {@link ResourceChange.type}.
+ *
+ * @category Resource Watch Types
+ */
+export declare enum ResourceChangeType {
+    Added = "added",
+    Updated = "updated",
+    Deleted = "deleted"
+}
+/**
+ * A single change observed by a resource watcher.
+ *
+ * @category Resource Watch Types
+ */
+export interface ResourceChange {
+    /** The URI of the resource that changed. */
+    uri: URI;
+    /** The kind of change observed. */
+    type: ResourceChangeType;
+}

package/vscode/src/vs/platform/agentHost/common/state/protocol/channels-resource-watch/state.js

@@ -0,0 +1,10 @@
+
+
+var ResourceChangeType;
+(function (ResourceChangeType) {
+    ResourceChangeType["Added"] = "added";
+    ResourceChangeType["Updated"] = "updated";
+    ResourceChangeType["Deleted"] = "deleted";
+})(ResourceChangeType || (ResourceChangeType = {}));
+
+export { ResourceChangeType };

package/vscode/src/vs/platform/agentHost/common/state/protocol/channels-root/actions.d.ts

@@ -0,0 +1,56 @@
+import type { AgentInfo } from "./state.js";
+import type { TerminalInfo } from "../channels-terminal/state.js";
+import { ActionType } from "../common/actions.js";
+/**
+ * Fired when available agent backends or their models change.
+ *
+ * @category Root Actions
+ * @version 1
+ */
+export interface RootAgentsChangedAction {
+    type: ActionType.RootAgentsChanged;
+    /** Updated agent list */
+    agents: AgentInfo[];
+}
+/**
+ * Fired when the number of active sessions changes.
+ *
+ * @category Root Actions
+ * @version 1
+ */
+export interface RootActiveSessionsChangedAction {
+    type: ActionType.RootActiveSessionsChanged;
+    /** Current count of active sessions */
+    activeSessions: number;
+}
+/**
+ * Fired when the list of known terminals changes.
+ *
+ * Full-replacement semantics: the `terminals` array replaces the previous
+ * `terminals` entirely.
+ *
+ * @category Root Actions
+ * @version 1
+ */
+export interface RootTerminalsChangedAction {
+    type: ActionType.RootTerminalsChanged;
+    /** Updated terminal list (full replacement) */
+    terminals: TerminalInfo[];
+}
+/**
+ * Fired when agent-host configuration values change.
+ *
+ * By default, the reducer merges the new values into `state.config.values`.
+ * Set `replace` to `true` to replace all values instead of merging.
+ *
+ * @category Root Actions
+ * @version 1
+ * @clientDispatchable
+ */
+export interface RootConfigChangedAction {
+    type: ActionType.RootConfigChanged;
+    /** Updated config values */
+    config: Record<string, unknown>;
+    /** When `true`, replaces all config values instead of merging */
+    replace?: boolean;
+}

package/vscode/src/vs/platform/agentHost/common/state/protocol/channels-root/commands.d.ts

@@ -0,0 +1,164 @@
+import type { URI } from "../common/state.js";
+import type { BaseParams } from "../common/commands.js";
+import type { SessionSummary, SessionConfigSchema } from "../channels-session/state.js";
+export type { ConfigPropertySchema, ConfigSchema } from "../common/state.js";
+export type { SessionConfigPropertySchema, SessionConfigSchema } from "../channels-session/state.js";
+/**
+ * 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
+ * `root/sessionAdded` and `root/sessionRemoved` notifications.
+ *
+ * @category Commands
+ * @method listSessions
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ */
+export interface ListSessionsParams extends BaseParams {
+    channel: "ahp-root://";
+    /** Optional filter criteria */
+    filter?: object;
+}
+/** Result of the `listSessions` command. */
+export interface ListSessionsResult {
+    /** The list of session summaries. */
+    items: SessionSummary[];
+}
+/**
+ * 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 extends BaseParams {
+    channel: "ahp-root://";
+    /** 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>;
+}
+/**
+ * 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 extends BaseParams {
+    channel: "ahp-root://";
+    /** 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[];
+}

package/vscode/src/vs/platform/agentHost/common/state/protocol/channels-root/notifications.d.ts

@@ -0,0 +1,129 @@
+import type { URI } from "../common/state.js";
+import type { SessionSummary } from "../channels-session/state.js";
+/**
+ * Broadcast to all clients subscribed to the root channel when a new session
+ * is created.
+ *
+ * @category Protocol Notifications
+ * @method root/sessionAdded
+ * @direction Server → Client
+ * @messageType Notification
+ * @version 1
+ * @example
+ * ```json
+ * {
+ *   "jsonrpc": "2.0",
+ *   "method": "root/sessionAdded",
+ *   "params": {
+ *     "channel": "ahp-root://",
+ *     "summary": {
+ *       "resource": "ahp-session:/<uuid>",
+ *       "provider": "copilot",
+ *       "title": "New Session",
+ *       "status": 1,
+ *       "createdAt": 1710000000000,
+ *       "modifiedAt": 1710000000000
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export interface SessionAddedParams {
+    /** Channel URI this notification belongs to (the root channel) */
+    channel: URI;
+    /** Summary of the new session */
+    summary: SessionSummary;
+}
+/**
+ * Broadcast to all clients subscribed to the root channel when a session is
+ * disposed.
+ *
+ * @category Protocol Notifications
+ * @method root/sessionRemoved
+ * @direction Server → Client
+ * @messageType Notification
+ * @version 1
+ * @example
+ * ```json
+ * {
+ *   "jsonrpc": "2.0",
+ *   "method": "root/sessionRemoved",
+ *   "params": {
+ *     "channel": "ahp-root://",
+ *     "session": "ahp-session:/<uuid>"
+ *   }
+ * }
+ * ```
+ */
+export interface SessionRemovedParams {
+    /** Channel URI this notification belongs to (the root channel) */
+    channel: URI;
+    /** URI of the removed session */
+    session: URI;
+}
+/**
+ * Broadcast to all clients subscribed to the root channel when an existing
+ * session's summary changes (title, status, `modifiedAt`, model, working
+ * directory, read/done state, or diff statistics).
+ *
+ * This notification lets clients that maintain a cached session list — for
+ * example, the result of a previous `listSessions()` call — stay in sync with
+ * in-flight sessions without having to subscribe to every session URI
+ * individually. It is complementary to, not a replacement for,
+ * `root/sessionAdded` and `root/sessionRemoved`: those signal lifecycle
+ * (creation/disposal), while this signals summary-level mutations on an
+ * already-known session.
+ *
+ * Semantics:
+ *
+ * - Only fields present in `changes` have new values; omitted fields are
+ *   unchanged on the client's cached summary.
+ * - Identity fields (`resource`, `provider`, `createdAt`) never change and
+ *   are not carried.
+ * - Like all protocol notifications, this is ephemeral: it is **not**
+ *   replayed on reconnect. On reconnect, clients should re-fetch the full
+ *   catalog via `listSessions()` as usual.
+ * - The server SHOULD emit this notification whenever any mutable field on
+ *   {@link SessionSummary | `SessionSummary`} changes for a session the
+ *   server has surfaced via `listSessions()` or `root/sessionAdded`.
+ *   Servers MAY coalesce or debounce updates for noisy fields (for example,
+ *   `modifiedAt` bumps while a turn is streaming, or rapidly changing
+ *   `changesets`) at their discretion.
+ * - Clients that have no cached entry for `session` MAY ignore the
+ *   notification; it is not a substitute for `root/sessionAdded`.
+ *
+ * @category Protocol Notifications
+ * @method root/sessionSummaryChanged
+ * @direction Server → Client
+ * @messageType Notification
+ * @version 1
+ * @example
+ * ```json
+ * {
+ *   "jsonrpc": "2.0",
+ *   "method": "root/sessionSummaryChanged",
+ *   "params": {
+ *     "channel": "ahp-root://",
+ *     "session": "ahp-session:/<uuid>",
+ *     "changes": {
+ *       "title": "Refactor auth middleware",
+ *       "status": 8,
+ *       "modifiedAt": 1710000123456
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export interface SessionSummaryChangedParams {
+    /** Channel URI this notification belongs to (the root channel) */
+    channel: URI;
+    /** URI of the session whose summary changed */
+    session: URI;
+    /**
+     * Mutable summary fields that changed; omitted fields are unchanged.
+     *
+     * Identity fields (`resource`, `provider`, `createdAt`) never change and
+     * MUST be omitted by senders; receivers SHOULD ignore them if present.
+     */
+    changes: Partial<SessionSummary>;
+}

package/vscode/src/vs/platform/agentHost/common/state/protocol/channels-root/state.d.ts

@@ -0,0 +1,130 @@
+import type { ConfigSchema, ProtectedResourceMetadata } from "../common/state.js";
+import type { TerminalInfo } from "../channels-terminal/state.js";
+import type { Customization } from "../channels-session/state.js";
+/**
+ * Policy configuration state for a model.
+ *
+ * @category Root State
+ */
+export declare enum PolicyState {
+    Enabled = "enabled",
+    Disabled = "disabled",
+    Unconfigured = "unconfigured"
+}
+/**
+ * Global state shared with every client subscribed to `ahp-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;
+    /**
+     * Additional implementation-defined metadata about the agent host itself.
+     *
+     * Clients MAY look for well-known keys here to provide enhanced UI.
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * @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 associated with this agent.
+     *
+     * Either container customizations —
+     * {@link PluginCustomization | `PluginCustomization`} entries the agent
+     * bundles, plus {@link DirectoryCustomization | `DirectoryCustomization`}
+     * entries it watches in any workspace it's used with — or top-level
+     * {@link McpServerCustomization | `McpServerCustomization`} entries
+     * the agent host declares directly. When a session is created with
+     * this agent, these entries are augmented (e.g. directory URIs are
+     * resolved against the workspace, children are parsed) and propagated
+     * into the session's `customizations` list.
+     */
+    customizations?: Customization[];
+}
+/**
+ * @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;
+    /**
+     * Additional provider-specific metadata for this model.
+     *
+     * Clients MAY look for well-known keys here to provide enhanced UI.
+     * For example, a `pricing` key may carry model pricing metadata.
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * 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>;
+}
+/**
+ * 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>;
+}

package/vscode/src/vs/platform/agentHost/common/state/protocol/channels-root/state.js

@@ -0,0 +1,10 @@
+
+
+var PolicyState;
+(function (PolicyState) {
+    PolicyState["Enabled"] = "enabled";
+    PolicyState["Disabled"] = "disabled";
+    PolicyState["Unconfigured"] = "unconfigured";
+})(PolicyState || (PolicyState = {}));
+
+export { PolicyState };