@codingame/monaco-vscode-api 37.6.1 → 38.0.0

package/vscode/src/vs/platform/agentHost/common/agent.d.ts

@@ -2,15 +2,23 @@ import { Event } from "../../../base/common/event.js";
 import { CancellationToken } from "../../../base/common/cancellation.js";
 import { DisposableStore, IDisposable } from "../../../base/common/lifecycle.js";
 import { IChannelClient } from "../../../base/parts/ipc/common/ipc.js";
-import type { IObservable } from "../../../base/common/observable.js";
+import type { IObservable, IReader } from "../../../base/common/observable.js";
 import { URI } from "../../../base/common/uri.js";
 import type { IAgentServerToolHost } from "./agentServerTools.js";
 import type { AgentHostClientType } from "./agentHostClientInfo.js";
-import type { IAgentHostClientTelemetryContext } from "./agentHostTelemetry.js";
+import type { CodexModelProvider, IAgentTurnTelemetryCorrelation, IAgentHostClientTelemetryContext, IAgentProviderSendStageRecorder, IAgentProviderTurnTelemetryContext } from "./agentHostTelemetry.js";
+import type { AgentPermissionDecisionSource } from "./meta/agentPermissionResponseMeta.js";
 import type { ResolveSessionConfigResult, SessionConfigCompletionsResult } from "./state/protocol/commands.js";
-import { ProtectedResourceMetadata, type Changeset, type ChatOrigin, type ConfigSchema, type MessageAttachment, type ModelSelection, type AgentSelection, type SessionActiveClient, type ToolCallPendingConfirmationState, type ToolDefinition, ChangesSummary } from "./state/protocol/state.js";
-import type { AuthRequiredParams, SessionAction, ChatAction } from "./state/sessionActions.js";
-import { ChatInputResponseKind, SessionStatus, type AgentCapabilities, type ClientPluginCustomization, type Customization, type ISessionFolderPickerDecision, type Message, type PendingMessage, type ChatInputAnswer, type SessionMeta, type ToolCallResult, type Turn, type PolicyState } from "./state/sessionState.js";
+import type { CanvasState } from "./state/protocol/channels-canvas/state.js";
+import { ProtectedResourceMetadata, type BackgroundWork, type Changeset, type ChatInteractivity, type ChatOrigin, type ConfigSchema, type MessageAttachment, type ModelSelection, type AgentSelection, type SessionActiveClient, type ToolCallPendingConfirmationState, type ToolDefinition, ChangesSummary } from "./state/protocol/state.js";
+import type { ActionOrigin, AuthRequiredParams, SessionAction, ChatAction } from "./state/sessionActions.js";
+import { ChatInputResponseKind, SessionStatus, type AgentCapabilities, type ClientPluginCustomization, type Customization, type ErrorInfo, type ISessionFolderPickerDecision, type Message, type PendingMessage, type ChatInputAnswer, type SessionMeta, type ToolCallResult, type Turn, type PolicyState } from "./state/sessionState.js";
+/** Permission response provenance and its originating client. */
+export interface IAgentPermissionResponseContext {
+    readonly selectedOptionId?: string;
+    readonly origin?: ActionOrigin;
+    readonly decisionSource?: AgentPermissionDecisionSource;
+}
 /** Error returned when the Agent Host process cannot be started. */
 export declare class AgentHostStartError extends Error {
     readonly fatal: boolean;
@@ -70,6 +78,17 @@ export interface IAgentHostManagedSettingsSnapshot {
     readonly sandboxEnabledByUndeterminedPolicy?: boolean;
     readonly managedKeys: readonly string[];
     readonly settings?: unknown;
+    /** Sessionless resolution layers; session client contributions and policy-helper execution are not included. */
+    readonly layers?: readonly {
+        readonly source: string;
+        readonly settings?: unknown;
+    }[];
+    /** Includes source failures and cache-fallback warnings, independently of failClosed. */
+    readonly diagnostics?: readonly {
+        readonly path: string;
+        readonly severity: "error" | "warning";
+        readonly message: string;
+    }[];
 }
 export interface IAgentChatMetadata {
     readonly chat: URI;
@@ -93,12 +112,10 @@ export interface IAgentChatMetadata {
      */
     readonly changes?: ChangesSummary;
     /**
-     * Catalogue of changesets the agent can produce for this session — the
-     * {@link Changeset | catalogue} that travels on
-     * `SessionSummary.changesets`. Lightweight summary entries (id / label /
-     * URI template / aggregate counts) without per-file detail; clients
-     * subscribe to a specific expanded changeset URI when they need the full
-     * file list.
+     * Catalogue of changesets the agent can produce for this chat or session. These are
+     * lightweight summary entries without per-file detail; clients subscribe
+     * to a specific expanded changeset URI for the full file list. Chat metadata
+     * carries chat-owned entries while session metadata carries session-wide entries.
      */
     readonly changesets?: readonly Changeset[];
     /**
@@ -123,10 +140,40 @@ export interface IAgentChatMetadataOptions {
 export interface IAgentDiscoveredChat extends IAgentChatMetadata {
     readonly external: boolean;
 }
+/** A fresh provider transcript for a chat being observed without running a host turn. */
+export interface IAgentChatHistoryChange {
+    readonly chat: URI;
+    readonly turns: readonly Turn[];
+}
 /** Returns the candidate session URI keys already present in the host registry. */
 export type IAgentKnownSessionsFilter = (sessions: readonly URI[]) => Promise<ReadonlySet<string>>;
+/** Lightweight ordered chat metadata for session-list presentation. */
+export interface IAgentSessionChatMetadata {
+    readonly chat: URI;
+    readonly summary?: string;
+    readonly kind: "default" | "peer";
+    readonly origin?: ChatOrigin;
+    readonly interactivity?: ChatInteractivity;
+    readonly archived?: boolean;
+    /** Exact chat read state when known; absence means the provider did not supply it. */
+    readonly isRead?: boolean;
+    readonly changes?: ChangesSummary;
+    /**
+     * The chat's live status from the session catalog, including activity bits.
+     * Absence means the host did not supply it. Clients must not persist the
+     * activity bits, which are only valid while connected.
+     */
+    readonly status?: SessionStatus;
+    /** Last known modification time of the chat (ms since epoch); client-cache only. */
+    readonly modifiedTime?: number;
+    /** Last known host-side working directories of the chat (protocol URI strings); client-cache only. */
+    readonly workingDirectories?: readonly string[];
+}
 export interface IAgentSessionMetadata extends Omit<IAgentChatMetadata, "chat"> {
     readonly session: URI;
+    /** Host-advertised agent identity; older cached metadata may omit it. */
+    readonly provider?: string;
+    readonly chats?: readonly IAgentSessionChatMetadata[];
 }
 export interface IAgentSessionProjectInfo {
     readonly uri: URI;
@@ -183,6 +230,129 @@ export interface IAgentMaterializeChatEvent {
     readonly project: IAgentSessionProjectInfo | undefined;
 }
 export type AgentProvider = string;
+export interface IAgentPluginUninstallRequest {
+    readonly name: string;
+    readonly marketplace: string;
+    readonly directSourceId?: string;
+}
+export type AgentCanvasExtensionSource = "user" | "project" | "session" | "plugin" | "unknown";
+/** One canvas declaration available to an initialized provider chat. */
+export interface IAgentCanvasInfo {
+    readonly canvasId: string;
+    readonly extensionId: string;
+    readonly extensionSource: AgentCanvasExtensionSource;
+    readonly extensionName?: string;
+    readonly displayName: string;
+    readonly description: string;
+    readonly requiresInput: boolean;
+    readonly actionCount: number;
+}
+/** Opens or focuses one stable canvas instance in an initialized provider chat. */
+export interface IAgentCanvasOpenRequest {
+    readonly canvasId: string;
+    readonly extensionId?: string;
+    readonly instanceId: string;
+}
+export interface IAgentCustomizationInstallationCatalogue {
+    readonly resourceId?: string;
+    readonly itemUrl?: string;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly publisher?: string;
+    readonly version?: string;
+    readonly source: string;
+}
+export type IAgentCustomizationInstallation = {
+    readonly installationId: string;
+    readonly mediaType: string;
+    readonly catalogue?: IAgentCustomizationInstallationCatalogue;
+    readonly state: "installed" | "missing" | "error";
+    readonly errorMessage?: string;
+} & ({
+    readonly kind: "skill";
+    readonly name: string;
+    readonly targetUri?: URI;
+} | {
+    readonly kind: "mcp";
+    readonly serverName: string;
+});
+export interface IAgentCustomizationInstallationRequest {
+    readonly mediaType: string;
+    readonly identifier: string;
+    readonly displayName: string;
+    readonly description: string;
+    readonly version?: string;
+    readonly itemUrl?: string;
+    readonly selectionId?: string;
+    readonly installation: {
+        readonly kind: "skill" | "mcp";
+    } | {
+        readonly kind: "plugin";
+        readonly repository: string;
+        readonly ref: string;
+        readonly path: string;
+    } | {
+        readonly kind: "configuredPlugin";
+        readonly name: string;
+        readonly marketplace: string;
+    };
+}
+export interface IAgentCustomizationMarketplaceSearchRequest {
+    readonly query: string;
+    readonly mediaType?: string;
+    readonly limit: number;
+    readonly cursor?: string;
+}
+export interface IAgentCustomizationMarketplaceSearchItem {
+    readonly selectionId: string;
+    readonly kind: "skill" | "mcp" | "plugin";
+    readonly displayName: string;
+    readonly description?: string;
+    readonly publisher?: string;
+    readonly pluginName?: string;
+    readonly marketplace?: string;
+    readonly marketplaceSource?: string;
+    readonly itemUrl?: string;
+    readonly version?: string;
+    readonly repository?: string;
+    readonly path?: string;
+    readonly installable: boolean;
+    readonly unavailableMessage?: string;
+}
+export type IAgentCustomizationMarketplaceSearchResult = {
+    readonly kind: "page";
+    readonly items: readonly IAgentCustomizationMarketplaceSearchItem[];
+    readonly nextCursor?: string;
+} | {
+    readonly kind: "unavailable";
+    readonly reason: "session" | "unsupported" | "authentication";
+};
+export type IAgentCustomizationInstallationReview = {
+    readonly operationId: string;
+    readonly action: "install" | "uninstall";
+    readonly kind: "skill";
+    readonly displayName: string;
+    readonly description?: string;
+    readonly source: string;
+    readonly target: string;
+    readonly fileCount: number;
+    readonly totalBytes: number;
+    readonly filesModified?: boolean;
+} | {
+    readonly operationId: string;
+    readonly action: "install" | "uninstall";
+    readonly kind: "mcp";
+    readonly displayName: string;
+    readonly serverName: string;
+    readonly target: string;
+    readonly endpoint?: string;
+    readonly configurationFields: readonly string[];
+    readonly restoresPreviousConfiguration?: boolean;
+    readonly preservesSharedAuthentication?: boolean;
+};
+export interface IAgentPluginInstallRequest {
+    readonly source: string;
+}
 export type AgentTurnProviderCallState = "notStarted" | "pending" | "resolved" | "rejected";
 export type AgentTurnProviderSessionState = "active" | "disconnecting" | "disconnected" | "shutdown";
 /** Provider-observed records, not an assertion that every network call reported usage. */
@@ -215,6 +385,8 @@ export type IAgentTurnDiagnosticSnapshot = {
 export declare const CLAUDE_AGENT_PROVIDER_ID: "claude";
 /** Well-known agent provider id for the Codex agent-host backend. */
 export declare const CODEX_AGENT_PROVIDER_ID: "codex";
+/** Well-known agent provider id for the Copilot CLI agent-host backend. */
+export declare const COPILOT_CLI_AGENT_PROVIDER_ID: "copilotcli";
 /**
  * Static capability facts an agent backend advertises about itself. Each flag
  * is opt-in (absent means unsupported) so single-chat agents (e.g. Codex) can omit
@@ -258,6 +430,8 @@ export interface AuthenticateParams {
     readonly token: string;
     /** The access token's remaining lifetime in seconds, when known. */
     readonly expiresIn?: number;
+    /** Optional client metadata. Hosts must remain usable when it is absent. */
+    readonly _meta?: Record<string, unknown>;
 }
 /** Request for a previously accepted bearer token. */
 export interface IAgentHostAuthTokenRequest {
@@ -380,6 +554,11 @@ export interface IAgentChatContext {
     readonly resource: URI;
     readonly configurationResource: URI;
     readonly clientTelemetryContext?: IAgentHostClientTelemetryContext;
+    /** The owning turn's immutable admission snapshot, supplied only for its send. */
+    readonly turnTelemetryContext?: IAgentProviderTurnTelemetryContext;
+    readonly turnTelemetryCorrelation?: IAgentTurnTelemetryCorrelation;
+    /** Records provider-owned dispatch facts on the addressed turn, before progress can complete it. */
+    readonly reportCodexModelProvider?: (provider: CodexModelProvider) => void;
     /**
      * The addressed chat's origin, taken verbatim from the host-owned chat
      * catalog, and exhaustive across every way a chat comes into existence:
@@ -406,6 +585,8 @@ export interface IAgentChatContext {
     readonly customizations?: readonly Customization[];
     /** Per-operation host instructions that providers add to model context without persisting as user content. */
     readonly hostInstructions?: readonly string[];
+    /** Records provider timing for the current send or resumed execution. */
+    readonly sendStageRecorder?: IAgentProviderSendStageRecorder;
     /** Whether the current turn is an automated Agent Merge repair turn. */
     readonly agentMergeTurn?: boolean;
 }
@@ -588,14 +769,7 @@ export interface IAgentSpawnChatEvent {
     readonly parent?: IAgentSpawnedChatParent;
     readonly title?: string;
 }
-/**
- * Builds the tab title for a subagent peer chat. Prefers the concise
- * per-task description (so two subagents of the same type still get
- * distinct, meaningful names), truncating it so an over-long value never
- * blows out the tab strip or the Subagents dropdown; falls back to the
- * agent type's display name, then a generic label. Shared by the live
- * spawn path and the restore path so both name subagent tabs identically.
- */
+/** Builds the shared title for subagent chats and activity messages, preferring a concise task description over the agent type's name. */
 export declare function subagentChatTitle(taskDescription: string | undefined, agentDisplayName: string | undefined): string;
 /**
  * Maps agent `subagent_started` signals to the unified chat catalog's spawn
@@ -611,6 +785,10 @@ export declare namespace SubagentChatSignal {
      */
     function toSpawnEvent(signal: AgentSignal): IAgentSpawnChatEvent | undefined;
 }
+/** A provider's preparation can block input without adding a conversation turn. */
+export interface IAgentPrepareChatResult {
+    readonly error?: ErrorInfo;
+}
 /**
  * The chat-addressed operation surface an agent exposes for the chats
  * within a session.
@@ -621,6 +799,17 @@ export declare namespace SubagentChatSignal {
  * the provider needs the owning session or storage scope.
  */
 export interface IAgentChats {
+    /**
+     * Optional pre-send preparation, such as materializing a deferred provider
+     * session, after the turn's model/agent selection and working directories
+     * are resolved. The host may run it concurrently with the turn-start
+     * checkpoint capture and awaits both before {@link sendMessage} for the same
+     * `turnId`, so implementations must not send a prompt or modify the working
+     * tree. Preparation that is not needed must resolve without doing work.
+     */
+    prepareTurn?(chat: URI, turnId: string, workingDirectories: readonly URI[] | undefined, context: AgentChatOperationContext): Promise<void>;
+    /** Prepare an existing chat for input without sending a turn. May acquire its native writer lock. */
+    prepareChat?(chat: URI, context: AgentChatOperationContext): Promise<IAgentPrepareChatResult>;
     /**
      * Create a fresh additional chat within an already-provisioned `session`,
      * using the complete working directory and config supplied in
@@ -660,6 +849,15 @@ export interface IAgentChats {
     /** Reconstruct the turns for `chat` (used on restore). */
     getMessages(chat: URI, context: AgentChatOperationContext): Promise<readonly Turn[]>;
 }
+/** Provider-native metadata events, before protocol translation. */
+export interface IAgentChatSessionEvent {
+    readonly chat: URI;
+    readonly id: string;
+    readonly timestamp: string;
+    readonly persisted: boolean;
+    readonly type: string;
+    readonly data: unknown;
+}
 export interface IAgentResolveChatConfigParams {
     readonly provider?: AgentProvider;
     readonly workingDirectory?: URI;
@@ -693,7 +891,7 @@ export interface IAgentModelInfo {
  * auto-approval, subagent session creation, steering acknowledgment, and
  * host-owned model-call telemetry) remain as discriminated non-action signals.
  */
-export type AgentSignal = IAgentActionSignal | IAgentModelCallCompletedSignal | IAgentModelCallFinishedSignal | IAgentToolPendingConfirmationSignal | IAgentSubagentStartedSignal | IAgentSubagentResumedSignal | IAgentSubagentCompletedSignal | IAgentSteeringConsumedSignal;
+export type AgentSignal = IAgentActionSignal | IAgentCanvasSignal | IAgentModelCallCompletedSignal | IAgentModelCallFinishedSignal | IAgentToolPendingConfirmationSignal | IAgentSubagentStartedSignal | IAgentSubagentResumedSignal | IAgentSubagentCompletedSignal | IAgentSteeringConsumedSignal;
 /**
  * Carries a protocol {@link SessionAction} produced by an agent. The host
  * dispatches the action through the state manager after routing via
@@ -711,6 +909,13 @@ export interface IAgentActionSignal {
     /** If set, route the action to the subagent session belonging to this tool call. */
     readonly parentToolCallId?: string;
 }
+/** Materializes or updates a chat-owned live canvas channel. */
+export interface IAgentCanvasSignal {
+    readonly kind: "canvas";
+    readonly chat: URI;
+    readonly resource: URI;
+    readonly state: CanvasState;
+}
 /** Reports one completed upstream model response for host-owned turn telemetry. */
 export interface IAgentModelCallCompletedSignal {
     readonly kind: "model_call_completed";
@@ -760,23 +965,30 @@ export interface IAgentToolPendingConfirmationSignal {
     readonly kind: "pending_confirmation";
     /** Target chat channel URI containing the tool call. */
     readonly chat: URI;
+    /** Whether this request supports a runtime-authorized session sandbox opt-out. */
+    readonly canAllowSessionSandboxBypass?: boolean;
     /** Protocol-shaped pending-confirmation state, dispatched verbatim into `ChatToolCallReady`. */
     readonly state: ToolCallPendingConfirmationState;
     /** Host-only auto-approval kind (not part of the dispatched action). */
-    readonly permissionKind?: "shell" | "write" | "mcp" | "read" | "url" | "skill" | "custom-tool" | "hook" | "memory" | "factory" | "extension-management" | "extension-permission-access" | "extension-env-access";
+    readonly permissionKind?: "shell" | "write" | "mcp" | "read" | "url" | "skill" | "custom-tool" | "hook" | "memory" | "workflow" | "extension-management" | "extension-permission-access" | "extension-env-access";
     /** Host-only auto-approval path target (not part of the dispatched action). */
     readonly permissionPath?: string;
+    /** Host-only command for shell approval when the displayed tool input contains structured arguments. */
+    readonly shellCommand?: string;
     /**
      * Host-only flag requiring the client to show a confirmation instead of applying host auto-approval.
      * The runtime currently sets it for managed Shell, Read, Edit, and Domain selector asks.
      */
     readonly managedApprovalRequired?: boolean;
     /**
-     * Host-only flag (not part of the dispatched action): the model requested
-     * this shell command run OUTSIDE the sandbox (and the host opted in via
-     * `sandbox.allowBypass`).
+     * Host-only flag indicating that the runtime requested sandbox escalation.
      */
     readonly requestSandboxBypass?: boolean;
+    /**
+     * Host-only flag indicating that the sandbox escalation keeps the sandbox attached
+     * while file and process restrictions record instead of block.
+     */
+    readonly requestSandboxPermissive?: boolean;
     /**
      * Host-only shell language for terminal auto-approval.
      * Only `bash` and `powershell` are eligible for terminal-rule analysis;
@@ -793,6 +1005,8 @@ export interface IAgentToolPendingConfirmationSignal {
     readonly parentToolCallId?: string;
 }
 export type AgentSubagentTaskModelSource = "task_argument" | "subagent_configuration" | "custom_agent_definition" | "unset";
+/** `task` is a delegated subagent; `fusionPhase` is a presentation-only chat for one HydraFusion phase of the parent turn. */
+export type AgentSubagentKind = "task" | "fusionPhase";
 /**
  * A subagent was spawned by a tool call. The host creates a child session
  * silently and routes subsequent inner-tool events to it.
@@ -808,6 +1022,10 @@ export interface IAgentSubagentStartedSignal {
     readonly agentDisplayName: string;
     readonly agentDescription?: string;
     readonly taskModelSource?: AgentSubagentTaskModelSource;
+    /** Absent means `task`. */
+    readonly subagentKind?: AgentSubagentKind;
+    /** For telemetry, when the chat reports no usage of its own. */
+    readonly model?: string;
     /**
      * The spawning Task tool's short (typically 3-5 word) `description`
      * input, e.g. "Review package.json structure". Distinct from
@@ -880,8 +1098,7 @@ export declare namespace AgentSession {
      */
     function id(session: URI | string): string;
     /**
-     * Extracts the provider name from a session URI scheme.
-     * Accepts both a URI object and a URI string.
+     * Legacy provider-scheme fallback; standard sessions require explicit provider metadata.
      */
     function provider(session: URI | string): AgentProvider | undefined;
 }
@@ -952,10 +1169,65 @@ export interface IAgentChatAdoptionResult {
     readonly eligible: boolean;
     /** Whether the chat already has Agent Host metadata, i.e. it is ours regardless of adoption. */
     readonly native?: boolean;
+    /** Host-owned list-visible values recovered from the predecessor format. */
+    readonly listVisible?: ({
+        readonly title: string;
+        readonly titleSource: "user" | "agent" | "auto";
+    } | {
+        readonly title?: undefined;
+        readonly titleSource?: undefined;
+    }) & {
+        readonly isRead?: boolean;
+    };
     /** Set when the adopted chat ran in a worktree that no longer exists and can be recreated. */
     readonly worktree?: IAgentAdoptedWorktree;
     /** Diagnostic reason behind {@link adopted}. */
     readonly reason?: AgentChatAdoptionReason;
+    /** Bounded provenance evidence; a missing marker alone does not prove an external session. */
+    readonly diagnostics?: {
+        readonly markerStatus: "valid" | "missing" | "invalid" | "readError";
+        readonly provenance: "legacy" | "external" | "unknown";
+        readonly markerFromCache: boolean;
+        readonly markerOrigin?: "vscode" | "other" | "missing" | "unrecognized" | "invalidType" | "unavailable";
+        readonly sessionIdStatus?: "opaque" | "empty" | "controlCharacters" | "pathSeparators" | "dotSegment";
+        readonly copilotHomeSource?: "environment" | "userHome";
+        readonly sessionStateRootStatus?: "directory" | "file" | "other" | "missing" | "readError" | "notChecked";
+        readonly sessionDirectoryStatus?: "directory" | "file" | "other" | "missing" | "readError" | "notChecked";
+        readonly eventsFileStatus?: "directory" | "file" | "other" | "missing" | "readError" | "notChecked";
+        readonly workspaceMetadataStatus?: "valid" | "missing" | "invalid" | "readError" | "tooLarge" | "notFile" | "notChecked";
+        /** Persisted runtime client, which can change on resume; not immutable creator provenance. */
+        readonly lastKnownClient?: "vscode" | "vscode-agent-host" | "github/cli" | "github/autopilot" | "missing" | "unrecognized" | "invalidType" | "unavailable";
+        readonly errorCode?: string;
+        readonly errorMessage?: string;
+    };
+}
+/** Identifies the client that submitted a pending message. */
+export interface IAgentPendingMessageSender {
+    readonly clientId: string | undefined;
+    readonly clientContext: IAgentHostClientTelemetryContext;
+}
+/** Account-scoped telemetry metadata; captured contexts become empty when their credentials are superseded. */
+export interface IAgentTelemetryContext {
+    readonly copilotSku: string | undefined;
+    /** Analytics ID from the same account discovery as the SKU, without an additional hash. */
+    readonly copilotTrackingId?: string;
+}
+export interface IAgentSessionPlan {
+    readonly plan: {
+        readonly exists: boolean;
+        readonly content: string | null;
+        readonly path: string | null;
+    };
+    readonly todos: readonly {
+        readonly id: string | null;
+        readonly title: string | null;
+        readonly status: string | null;
+        readonly description: string | null;
+    }[];
+    readonly dependencies: readonly {
+        readonly todoId: string;
+        readonly dependsOn: string;
+    }[];
 }
 /**
  * Implemented by each agent backend (e.g. Copilot SDK).
@@ -973,8 +1245,42 @@ export interface IAgent {
     readonly models: IObservable<readonly IAgentModelInfo[]>;
     /** Optional refresh for providers whose model catalog can change at runtime. */
     refreshModels?(): Promise<void>;
+    /** Refresh live sessions after account-backed Connector membership changes. */
+    refreshConnectorSessions?(): Promise<void>;
+    /** Uninstall a plugin through the provider that owns its installation state. */
+    uninstallPlugin?(request: IAgentPluginUninstallRequest): Promise<void>;
+    /** List canvas declarations available to one initialized provider chat. */
+    listSessionCanvases?(session: URI, chat: URI, context: AgentChatOperationContext): Promise<readonly IAgentCanvasInfo[]>;
+    /** Open or focus one canvas instance in an initialized provider chat. */
+    openSessionCanvas?(session: URI, request: IAgentCanvasOpenRequest, chat: URI, context: AgentChatOperationContext): Promise<void>;
+    /** Install a plugin through the provider that owns its installation state. */
+    installPlugin?(request: IAgentPluginInstallRequest): Promise<void>;
+    /** Search the provider-native customization catalog for an exact session. */
+    searchCustomizationMarketplace?(session: URI, request: IAgentCustomizationMarketplaceSearchRequest): Promise<IAgentCustomizationMarketplaceSearchResult>;
+    /** List receipt-owned Skill and MCP installations through the provider SDK. */
+    listCustomizationInstallations?(session: URI): Promise<readonly IAgentCustomizationInstallation[]>;
+    /** Prepare an exact receipt-owned install or uninstall for explicit review. */
+    prepareCustomizationInstallation?(session: URI, request: IAgentCustomizationInstallationRequest | {
+        readonly installationId: string;
+    }): Promise<IAgentCustomizationInstallationReview>;
+    /** Apply an exact operation previously returned for explicit review. */
+    applyCustomizationInstallation?(operationId: string): Promise<void>;
+    /** Reconcile receipt-owned installations and return the refreshed inventory. */
+    recoverCustomizationInstallations?(session: URI): Promise<readonly IAgentCustomizationInstallation[]>;
+    /** Capture the current account without allowing a later account to relabel an in-flight turn. */
+    getTelemetryContext?(): IAgentTelemetryContext;
+    /** Reads the owning session's provider-native plan and structured todos. */
+    getSessionPlan?(session: URI): Promise<IAgentSessionPlan>;
+    /** Applies a legacy boolean approval selection through the provider's runtime permission policy. */
+    setSessionApproveAll?(session: URI, enabled: boolean): Promise<void>;
     /** Streamed progress for an exact chat. */
     readonly onDidChatProgress: Event<AgentSignal>;
+    /** Optional admitted native metadata stream for environment-owned session mirroring. */
+    readonly onDidChatSessionEvent?: Event<IAgentChatSessionEvent>;
+    /** Read genuine persisted metadata without creating or resuming a provider session. */
+    readChatSessionEvents?(chat: URI, context: IAgentChatContext, token: CancellationToken, afterEventId?: string, onDidReadEventId?: (id: string) => void): AsyncIterable<IAgentChatSessionEvent>;
+    /** Synchronize a host-owned title into an already-live provider session. */
+    synchronizeChatSessionTitle?(chat: URI, title: string): Promise<boolean>;
     /** Fires when a provisional chat acquires its SDK backing and durable metadata. */
     readonly onDidMaterializeChat: Event<IAgentMaterializeChatEvent>;
     /** Fires when an opaque chat backing changes and must be persisted again. */
@@ -986,9 +1292,14 @@ export interface IAgent {
     /** Re-attach an exact chat from opaque provider data without inferring its role. */
     materializeChat(chat: URI, context: URI | IAgentChatContext, providerData: string | undefined): Promise<IAgentCreateChatResult | void>;
     /** Optional steering hook for providers that can accept messages during an active turn. */
-    setPendingMessages?(chat: URI, steeringMessage: PendingMessage | undefined, queuedMessages: readonly PendingMessage[]): void;
+    setPendingMessages?(chat: URI, steeringMessage: PendingMessage | undefined, queuedMessages: readonly PendingMessage[], steeringSender?: IAgentPendingMessageSender): void;
     /** Optional history mutation for providers with a native truncation operation. */
     truncateChat?(chat: URI, turnId: string | undefined, context?: URI | IAgentChatContext): Promise<void>;
+    /**
+     * Stops an entry of the chat's background work that this provider marked
+     * stoppable. Resolves false when the entry is unknown or had already finished.
+     */
+    stopBackgroundWork?(chat: URI, id: string): Promise<boolean>;
     /**
      * Changes the working directory of an exact chat's existing provider-native
      * backing. Callers MUST gate this operation on
@@ -996,8 +1307,14 @@ export interface IAgent {
      * not advertise the capability MUST reject the call.
      */
     setWorkingDirectory(chat: URI, context: URI | IAgentChatContext, workingDirectory: URI): Promise<void>;
+    /** Changes the addressed chat's backing. Shared roots may change only under the host's single-chat catalog lock. */
+    setChatWorkingDirectory?(chat: URI, context: IAgentChatContext, workingDirectory: URI, options?: {
+        readonly replaceSessionWorkspace: boolean;
+    }): Promise<void>;
     /** Return bounded diagnostics for an in-flight turn when supported. */
     getTurnDiagnosticSnapshot?(chat: URI, turnId: string): IAgentTurnDiagnosticSnapshot | undefined;
+    /** Capture bounded provider context from cached state without I/O. */
+    captureTurnTelemetryContext?(): IAgentProviderTurnTelemetryContext;
     /** Read observed usage at terminal dispatch for this exact owning turn, excluding descendants and later delivery. */
     getTurnTokenUsage?(chat: URI, turnId: string, parentToolCallId?: string): IAgentTurnTokenUsage | undefined;
     /** Record the host-remapped turn for a completed provider model call. */
@@ -1012,7 +1329,7 @@ export interface IAgent {
     /** Complete a client tool call on its host-resolved provider chat. */
     onClientToolCallComplete(chat: URI, toolCallId: string, result: ToolCallResult, context?: IAgentChatContext): void;
     /** Respond to a pending permission request from the SDK. */
-    respondToPermissionRequest(requestId: string, approved: boolean): void;
+    respondToPermissionRequest(requestId: string, approved: boolean, context?: IAgentPermissionResponseContext): void;
     /** Respond to a pending user input request from the SDK's ask_user tool. */
     respondToUserInputRequest(requestId: string, response: ChatInputResponseKind, answers?: Record<string, ChatInputAnswer>): void;
     /** Resolve provider-owned chat configuration; host-owned worktree fields are omitted. */
@@ -1043,7 +1360,18 @@ export interface IAgent {
     computeFolderPickerDecision?(workingDirectories: readonly URI[], token?: CancellationToken): Promise<ISessionFolderPickerDecision | undefined>;
     /** Provides chats that are ready to be registered as Agent Host sessions. */
     readonly onDidDiscoverChats: Event<readonly IAgentDiscoveredChat[]>;
-    /** Starts the provider's memoized native chat discovery pass. */
+    /** Passive transcript changes from another client; these must not start host-side turn execution. */
+    readonly onDidChangeChatHistory?: Event<IAgentChatHistoryChange>;
+    /** Observe another client's persisted transcript while a host client subscribes to this chat. */
+    watchChatHistory?(chat: URI): IDisposable;
+    /**
+     * Refresh the chat's background work while a client observes an already-hydrated chat.
+     * `published` reads the list the chat currently shows, so a session that replaced an
+     * earlier one, for example after a client restart, can remove entries its runtime no
+     * longer reports.
+     */
+    watchChatBackgroundWork?(chat: URI, published: () => readonly BackgroundWork[]): IDisposable;
+    /** Starts provider-owned native chat discovery; repeated calls are idempotent. */
     startChatDiscovery?(): Promise<void>;
     /** Lets discovery drop registered candidates before per-session I/O. */
     setKnownSessionsFilter?(filter: IAgentKnownSessionsFilter): void;
@@ -1056,14 +1384,10 @@ export interface IAgent {
     /** Optional migration codec for providers that persisted peer backings before the host catalog. */
     listLegacyChatBackings?(configurationResource: URI): Promise<readonly IAgentLegacyChat[]>;
     /**
-     * Warms a short-lived, in-memory cache of per-session metadata from a single
-     * bulk provider call, so a subsequent burst of {@link getChatMetadata} calls
-     * (e.g. a `listSessions` pass over a large catalogue) can be served without
-     * one provider round-trip per session. Returns a disposable that clears the
-     * cache; callers dispose it once the burst is complete. Optional: providers
-     * without a cheap bulk read simply omit it and pay per session.
+     * Optionally warms metadata for a burst of {@link getChatMetadata} calls; the expected count lets providers avoid bulk reads for small bursts.
+     * Callers release the returned lease after the burst; providers may retain a bounded cache across bursts.
      */
-    prewarmSessionMetadata?(): Promise<IDisposable>;
+    prewarmSessionMetadata?(expectedSessionCount: number): Promise<IDisposable>;
     /** Retrieve metadata for an exact registered chat. Ambient catalogue reads never set {@link IAgentChatMetadataOptions.activation}. */
     getChatMetadata(chat: URI, context: URI | IAgentChatContext, providerData?: string, options?: IAgentChatMetadataOptions): Promise<IAgentChatMetadata | undefined>;
     getProtectedResources(): ProtectedResourceMetadata[];
@@ -1073,22 +1397,30 @@ export interface IAgent {
     handleAuthenticationToken?(params: AuthenticateParams): Promise<boolean>;
     /** Optional current authentication requirement for providers that can require re-authentication after startup. */
     readonly authenticationRequired?: IObservable<Omit<AuthRequiredParams, "channel"> | undefined>;
+    /** Whether model-dependent prerequisites for unattended execution are ready; absent means no additional readiness gate. */
+    isReadyForAutomation?(model: ModelSelection | undefined, reader?: IReader): boolean;
     /** Optional endpoint list when the provider owns probeable network traffic. */
     getNetworkDiagnosticsEndpoints?(): Promise<readonly IAgentHostNetworkEndpoint[]>;
     /** Optional account label when the provider can resolve one. */
     getNetworkDiagnosticsAccount?(): Promise<string | undefined>;
     /** Optional managed-settings snapshot for providers with an enterprise policy surface. */
     getManagedSettingsDiagnostics?(): Promise<IAgentHostManagedSettingsSnapshot>;
+    /** Canonical device remote-control policy; absence is distinct from a failed read. */
+    getRemoteControlManagedSettings?(): Promise<Record<string, unknown> | undefined>;
     /** Return the provider-owned state file for a session, when one exists. */
     getSessionStateFile?(session: URI, chat?: URI): Promise<URI | undefined>;
+    /** Return the exact provider-owned plan file, resolving the chat's native backing identity. */
+    getSessionPlanFile?(session: URI, chat: URI): URI | undefined;
     /** Add provider-owned diagnostics to an Agent Host debug-log staging directory. */
     collectDebugLogs?(session: URI | undefined, outputDirectory: URI, chat?: URI): Promise<boolean>;
     /** Optional host wiring for providers that advertise Agent Host server tools. */
     setServerToolHost?(host: IAgentServerToolHost): void;
-    /** Optional lifecycle operation for providers exposing controllable MCP servers. */
-    startMcpServer?(session: URI, id: string): Promise<void>;
+    /** Starts a controllable MCP server; providers may cooperatively honor cancellation, but in-flight SDK operations may not be cancellable. */
+    startMcpServer?(session: URI, id: string, token: CancellationToken): Promise<void>;
     /** Optional lifecycle operation paired with {@link startMcpServer}. */
     stopMcpServer?(session: URI, id: string): Promise<void>;
+    /** Releases turns waiting for MCP startup while the provider continues connecting servers. */
+    backgroundMcpServerStartup?(session: URI, id: string): Promise<void>;
     /** Optional `mcp://` router for providers that advertise chat-scoped MCP side-channel resources. */
     handleMcpRequest?(chat: URI, serverName: string, method: string, params: Record<string, unknown> | undefined): Promise<unknown>;
     /** Optional notification stream paired with {@link handleMcpRequest}. */

package/vscode/src/vs/platform/agentHost/common/agent.js

@@ -6,6 +6,7 @@ import { parseRequiredSessionUriFromChatUri, buildSubagentChatUri } from './stat
 
 const CLAUDE_AGENT_PROVIDER_ID = "claude";
 const CODEX_AGENT_PROVIDER_ID = "codex";
+const COPILOT_CLI_AGENT_PROVIDER_ID = "copilotcli";
 const GITHUB_COPILOT_PROTECTED_RESOURCE = {
     resource: "https://api.github.com"};
 function protectedResourcesRequireGitHubCopilotSignIn(resources) {
@@ -61,9 +62,9 @@ var AgentSession;
     AgentSession.id = id;
     function provider(session) {
         const parsed = typeof session === "string" ? ( URI.parse(session)) : session;
-        return parsed.scheme || undefined;
+        return parsed.scheme === "ahp-session" ? undefined : parsed.scheme || undefined;
     }
     AgentSession.provider = provider;
 })(AgentSession || (AgentSession = {}));
 
-export { AgentSession, CLAUDE_AGENT_PROVIDER_ID, CODEX_AGENT_PROVIDER_ID, GITHUB_COPILOT_PROTECTED_RESOURCE, SubagentChatSignal, protectedResourcesRequireGitHubCopilotSignIn, subagentChatTitle };
+export { AgentSession, CLAUDE_AGENT_PROVIDER_ID, CODEX_AGENT_PROVIDER_ID, COPILOT_CLI_AGENT_PROVIDER_ID, GITHUB_COPILOT_PROTECTED_RESOURCE, SubagentChatSignal, protectedResourcesRequireGitHubCopilotSignIn, subagentChatTitle };