@codingame/monaco-vscode-chat-service-override 37.0.0 → 37.1.0

package/vscode/src/vs/workbench/contrib/chat/browser/agentSessions/agentHost/agentHostSessionHandler.d.ts

@@ -0,0 +1,884 @@
+import { CancellationToken } from "@codingame/monaco-vscode-api/vscode/vs/base/common/cancellation";
+import { Disposable } from "@codingame/monaco-vscode-api/vscode/vs/base/common/lifecycle";
+import { URI } from "@codingame/monaco-vscode-api/vscode/vs/base/common/uri";
+import { IModelService } from "@codingame/monaco-vscode-api/vscode/vs/editor/common/services/model.service";
+import { AgentProvider, type IAgentConnection } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/agentService";
+import { IRemoteAgentHostService } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/remoteAgentHostService.service";
+import { ToolResultContentType, type ProtectedResourceMetadata } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/state/protocol/state";
+import { type Message, type ModelSelection, type ChatInputAnswer, type ChatInputQuestion, type StringOrMarkdown } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/state/sessionState";
+import { IInstantiationService } from "@codingame/monaco-vscode-api/vscode/vs/platform/instantiation/common/instantiation";
+import { IConfigurationService } from "@codingame/monaco-vscode-api/vscode/vs/platform/configuration/common/configuration.service";
+import { ILogService } from "@codingame/monaco-vscode-api/vscode/vs/platform/log/common/log.service";
+import { IOpenerService } from "@codingame/monaco-vscode-api/vscode/vs/platform/opener/common/opener.service";
+import { ITelemetryService } from "@codingame/monaco-vscode-api/vscode/vs/platform/telemetry/common/telemetry.service";
+import { IWorkbenchAssignmentService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/services/assignment/common/assignmentService.service";
+import { IPathService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/services/path/common/pathService.service";
+import { IWorkspaceContextService } from "@codingame/monaco-vscode-api/vscode/vs/platform/workspace/common/workspace.service";
+import { IWorkspaceTrustRequestService } from "@codingame/monaco-vscode-api/vscode/vs/platform/workspace/common/workspaceTrust.service";
+import { IWorkspaceTrustManagementService } from "@codingame/monaco-vscode-api/vscode/vs/platform/workspace/common/workspaceTrust.service";
+import { IAgentHostTerminalService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/terminal/browser/agentHostTerminalService.service";
+import { ITerminalChatService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/terminal/browser/terminal.service";
+import { IChatQuestionAnswers } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/chatService/chatService";
+import { IChatService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/chatService/chatService.service";
+import { IChatSession, IChatSessionContentProvider, type IChatInputCompletionsParams, type IChatInputCompletionsResult } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/chatSessionsService";
+import { IChatEntitlementService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/services/chat/common/chatEntitlementService.service";
+import { IWorkingCopyService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/services/workingCopy/common/workingCopyService.service";
+import { IChatEditingService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/editing/chatEditingService.service";
+import { ILanguageModelsService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/languageModels.service";
+import { IChatAgentService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/participants/chatAgents.service";
+import { IToolResult } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/tools/languageModelToolsService";
+import { ILanguageModelToolsService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/tools/languageModelToolsService.service";
+import { IChatWidgetService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/browser/chat.service";
+import { IAgentHostActiveClientService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/browser/agentSessions/agentHost/agentHostActiveClientService.service";
+import { IAgentHostCustomizationService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/browser/agentSessions/agentHost/agentHostCustomizationService.service";
+import { IAgentHostSessionWorkingDirectoryResolver } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/browser/agentSessions/agentHost/agentHostSessionWorkingDirectoryResolver.service";
+import { IAgentHostSessionWorkingDirectorySynchronizer } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/browser/agentSessions/agentHost/agentHostSessionWorkingDirectorySynchronizer.service";
+import { IAgentHostShellInitSynchronizer } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/browser/agentSessions/agentHost/agentHostShellInitSynchronizer.service";
+import { IAgentHostNewSessionFolderService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/browser/agentSessions/agentHost/agentHostNewSessionFolderService.service";
+import type { AgentHostPromptCacheNotification } from "./agentHostPromptCacheNotification.js";
+import { IChatResponseFileChangesService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/browser/chatResponseFileChangesService.service";
+import { toolDataToDefinition } from "./agentHostToolUtils.js";
+import { IAgentHostUntitledProvisionalSessionService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/browser/agentSessions/agentHost/agentHostUntitledProvisionalSessionService.service";
+import { IAgentHostImportConversationStore } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/browser/agentSessions/agentHost/agentHostImportConversationStore.service";
+export { toolDataToDefinition };
+export declare const UNOBSERVED_CLIENT_TOOL_GRACE_MS = 5000;
+/** Whether `err` reports that the host has no such resource (AHP `NotFound`). */
+export declare function isNotFoundError(err: unknown): boolean;
+/**
+ * Extracts a user-facing message from a session-load failure so the actual cause
+ * (e.g. a git worktree-recreation error) is shown instead of a generic message.
+ * Strips the `Failed to restore session <uri>: ` wrapper that `AgentService`
+ * adds around restore failures. Returns `undefined` when no message is available.
+ */
+export declare function unwrapSessionLoadErrorMessage(err: unknown): string | undefined;
+export declare function resolveRestoredSubagentChatResource(parentSession: string, toolCallId: string, catalogResource: string | undefined, persistedResource: string | undefined): string;
+/** The draft the chat channel holds, so we only send real changes and can keep its model. */
+export declare class DraftSyncState {
+    private _synced;
+    private _remoteModel;
+    constructor(remoteDraft: Message | undefined);
+    get synced(): Message | undefined;
+    /**
+     * The chosen model the channel holds, which a local fallback must not overwrite. Recorded on
+     * publish as well as on receive: a window never sees its own draft echo back through the channel.
+     */
+    get remoteModel(): ModelSelection | undefined;
+    applyRemote(remoteDraft: Message | undefined): void;
+    shouldPublish(outgoing: Message | undefined, chosen?: boolean): boolean;
+}
+/**
+ * Converts carousel answers (IChatQuestionAnswers) to protocol
+ * ChatInputAnswer records, handling text, single-select,
+ * boolean, and multi-select answer shapes.
+ */
+export declare function convertCarouselAnswers(raw: IChatQuestionAnswers, questions?: readonly ChatInputQuestion[]): Record<string, ChatInputAnswer>;
+export interface IAgentHostSessionHandlerConfig {
+    readonly provider: AgentProvider;
+    /**
+     * The URI scheme the host addresses sessions under, when it differs from
+     * {@link provider}. Defaults to {@link provider}.
+     *
+     * Session URIs are client-chosen. For agents core spawns, core picks the URI and
+     * uses the provider as the scheme. For sessions core *joins* rather than creates
+     * (cloud sandbox, where Mission Control created the session as `ahp-session:/<id>`),
+     * the creator's scheme must be used because the host's registry is keyed by the
+     * exact URI — while the UI still routes the session to the `copilot` provider.
+     */
+    readonly backendSessionScheme?: string;
+    readonly agentId: string;
+    readonly sessionType: string;
+    readonly fullName: string;
+    readonly description: string;
+    /** The agent connection to use for this handler. */
+    readonly connection: IAgentConnection;
+    /** Sanitized connection authority for constructing vscode-agent-host:// URIs. */
+    readonly connectionAuthority: string;
+    /** Extension identifier for the registered agent. Defaults to 'vscode.agent-host'. */
+    readonly extensionId?: string;
+    /** Extension display name for the registered agent. Defaults to 'Agent Host'. */
+    readonly extensionDisplayName?: string;
+    /**
+     * Optional callback to resolve a working directory for a new session.
+     * If not provided or unresolved, session resource resolvers are consulted before
+     * falling back to the first workspace folder.
+     */
+    readonly resolveWorkingDirectory?: (sessionResource: URI) => URI | undefined;
+    /** Whether a final-looking chat resource is still a client-side draft. */
+    readonly isNewSession?: (sessionResource: URI) => boolean;
+    /** Called after a locally-created session has been accepted by the backend. */
+    readonly onSessionMaterialized?: (sessionResource: URI) => void;
+    /**
+     * Optional callback invoked when the server rejects an operation because
+     * authentication is required. Should trigger interactive authentication
+     * and return true if the user authenticated successfully.
+     *
+     * @param protectedResources The protected resources from the agent's root
+     *   state that require authentication.
+     */
+    readonly resolveAuthentication?: (protectedResources: ProtectedResourceMetadata[]) => Promise<boolean>;
+    readonly promptCacheNotification?: AgentHostPromptCacheNotification;
+}
+export declare class AgentHostSessionHandler extends Disposable implements IChatSessionContentProvider {
+    private readonly _chatAgentService;
+    private readonly _chatService;
+    private readonly _chatEditingService;
+    private readonly _logService;
+    private readonly _workspaceContextService;
+    private readonly _instantiationService;
+    private readonly _terminalChatService;
+    private readonly _agentHostTerminalService;
+    private readonly _workingDirectoryResolver;
+    private readonly _workingDirectorySynchronizer;
+    private readonly _shellInitSynchronizer;
+    private readonly _newSessionFolderService;
+    private readonly _provisionalService;
+    private readonly _importConversationStore;
+    private readonly _toolsService;
+    private readonly _chatWidgetService;
+    private readonly _languageModelsService;
+    private readonly _openerService;
+    private readonly _activeClientService;
+    private readonly _chatEntitlementService;
+    private readonly _workspaceTrustRequestService;
+    private readonly _workspaceTrustManagementService;
+    private readonly _modelService;
+    private readonly _workingCopyService;
+    private readonly _configurationService;
+    private readonly _chatResponseFileChangesService;
+    private readonly _pathService;
+    private readonly _remoteAgentHostService;
+    private readonly _customizationService;
+    private readonly _telemetryService;
+    private static readonly DRAFT_SYNC_DEBOUNCE_MS;
+    private static readonly ACTIVE_CLIENT_RECONCILIATION_DEBOUNCE_MS;
+    private readonly _activeSessions;
+    private readonly _chatURIsBySessionResource;
+    /** Per-session subscription to chat model pending request changes. */
+    private readonly _pendingMessageSubscriptions;
+    private readonly _remotePendingMessageProjections;
+    /** Per-session debounced sync from chat input state to AHP draft state. */
+    private readonly _draftSyncSubscriptions;
+    /** Per-session subscription watching for server-initiated turns. */
+    private readonly _serverTurnWatchers;
+    /** Per-session subscription silently resolving existing MCP authentication grants. */
+    private readonly _mcpAuthWatchers;
+    /**
+     * Ownership of actionable protocol requests, keyed by backend session URI
+     * string. `inputNeeded` is a session-level queue and the single caller of
+     * {@link invokeTool} for client tools, so it must be handled exactly once
+     * per backend session no matter how many sibling chat resources (default
+     * chat, peer chats, subagent chats) are open against it. Each such resource
+     * holds a reference; the shared watcher stays alive while any reference
+     * remains and is disposed only when the last one is released.
+     */
+    private readonly _inputNeededWatchers;
+    /**
+     * Backend session each open resource's {@link _inputNeededWatchers}
+     * reference belongs to, recorded when the reference is installed. Teardown
+     * uses this to release the right reference without re-deriving the backend
+     * session via {@link _resolveSessionUri}, whose provisional mapping may
+     * already be cleared by then.
+     */
+    private readonly _inputNeededWatcherBackends;
+    /** One reconciliation owner per active session. */
+    private readonly _activeClientEntries;
+    /** Historical turns with file edits, pending hydration into the editing session. */
+    private readonly _pendingHistoryTurns;
+    /**
+     * Requests a turn observer is currently rendering, keyed by
+     * {@link _toolCallKey} for tool calls and {@link _inputRequestKey} for chat
+     * input requests (the two key shapes differ in arity, so they cannot
+     * collide). The value is the claiming observer's session resource, which
+     * the session-level responder uses as the chat context when it executes a
+     * client tool so the tool runs against the chat that is actually rendering
+     * it. The session-level responder defers to those observers so the inline
+     * UI stays in charge of answering.
+     */
+    private readonly _renderedRequests;
+    /** Tool calls whose protocol outcome has already been dispatched. */
+    private readonly _resolvedToolCalls;
+    /**
+     * A single {@link ChatToolInvocation} per client tool call, keyed by
+     * {@link _toolCallKey}. Created lazily by whichever of the session-level
+     * watcher or the turn observer arrives first, so both act on one object:
+     * the observer renders it while the watcher executes it. Entries are
+     * dropped once the call resolves so a later call with the same ids is not
+     * mistaken for it.
+     */
+    private readonly _clientToolInvocations;
+    /**
+     * Live `inputNeeded` requests per tool call, keyed by {@link _toolCallKey}.
+     * One tool call is represented by a succession of requests — a confirmation
+     * is replaced by a client execution once approved — so the shared state
+     * above is only released when the last of them goes away.
+     */
+    private readonly _clientToolRetainCounts;
+    /**
+     * Per-session set of MCP server ids that already had an authentication
+     * prompt surfaced in the current conversation. A server is removed from the
+     * set once it reaches the running state ({@link McpServerStatus.Ready}), so
+     * that a later auth requirement for the same server prompts again instead of
+     * the prompt repeating on every message.
+     */
+    private readonly _surfacedMcpAuthServers;
+    private readonly _pendingMcpAutoAuthentication;
+    /** Turn IDs dispatched by this client, used to distinguish server-originated turns. */
+    private readonly _clientDispatchedTurnIds;
+    private readonly _turnStopWatches;
+    private readonly _config;
+    /** Active session subscriptions, keyed by backend session URI string. */
+    private readonly _sessionSubscriptions;
+    /**
+     * Working-directory synchronizer registrations, keyed by session URI. Each
+     * lives exactly as long as that session's {@link _sessionSubscriptions} entry.
+     */
+    private readonly _workingDirectoryRegistrations;
+    private readonly _shellInitRegistrations;
+    /**
+     * Active default-chat subscriptions, keyed by backend session URI string.
+     * Multi-chat is not yet surfaced: every session is served by a single
+     * implicit default chat that carries the conversation contents (turns,
+     * active turn, pending/queued messages, input requests). We subscribe to
+     * it alongside the session and merge both into the {@link ISessionWithDefaultChat}
+     * view returned by {@link _getSessionState}.
+     */
+    private readonly _defaultChatSubscriptions;
+    /**
+     * Active subscriptions for additional (non-default) peer chats, keyed by
+     * the chat channel URI string. Populated when a chat widget is opened for
+     * a resource that carries a chatId fragment.
+     */
+    private readonly _additionalChatSubscriptions;
+    /**
+     * Chat channel URI that owns each observed terminal, keyed by terminal URI.
+     * Recorded while observing a terminal tool call so a later claim (e.g.
+     * "Continue in Background") can attribute itself to the chat the terminal
+     * actually belongs to rather than assuming the session's default chat.
+     */
+    private readonly _terminalChatURIs;
+    /**
+     * Backend session URIs with an in-flight {@link provideChatSessionContent}
+     * call, keyed by session URI string with a refcount value. While a chat is
+     * still hydrating its subscriptions, a sibling chat of the same session
+     * closing must not tear down the shared session subscription out from under
+     * it (see {@link _releaseChatSessionSubscriptions} / {@link _hasOtherSessionHold}).
+     */
+    private readonly _hydratingChatSessions;
+    /**
+     * Whether the `hideAutoExplainability` experiment suppresses Auto's routing
+     * row. `undefined` until the treatment resolves — emitting on a guess would
+     * append rows to a hidden-cohort turn that cannot be retracted afterwards.
+     */
+    private readonly _hideAutoExplainability;
+    /** Settles once {@link _hideAutoExplainability} is known. */
+    private readonly _hideAutoExplainabilityReady;
+    constructor(config: IAgentHostSessionHandlerConfig, _chatAgentService: IChatAgentService, _chatService: IChatService, _chatEditingService: IChatEditingService, _logService: ILogService, _workspaceContextService: IWorkspaceContextService, _instantiationService: IInstantiationService, _terminalChatService: ITerminalChatService, _agentHostTerminalService: IAgentHostTerminalService, _workingDirectoryResolver: IAgentHostSessionWorkingDirectoryResolver, _workingDirectorySynchronizer: IAgentHostSessionWorkingDirectorySynchronizer, _shellInitSynchronizer: IAgentHostShellInitSynchronizer, _newSessionFolderService: IAgentHostNewSessionFolderService, _provisionalService: IAgentHostUntitledProvisionalSessionService, _importConversationStore: IAgentHostImportConversationStore, _toolsService: ILanguageModelToolsService, _chatWidgetService: IChatWidgetService, _languageModelsService: ILanguageModelsService, _openerService: IOpenerService, _activeClientService: IAgentHostActiveClientService, _chatEntitlementService: IChatEntitlementService, _workspaceTrustRequestService: IWorkspaceTrustRequestService, _workspaceTrustManagementService: IWorkspaceTrustManagementService, _modelService: IModelService, _workingCopyService: IWorkingCopyService, _configurationService: IConfigurationService, _chatResponseFileChangesService: IChatResponseFileChangesService, _pathService: IPathService, _remoteAgentHostService: IRemoteAgentHostService, _customizationService: IAgentHostCustomizationService, _telemetryService: ITelemetryService, assignmentService: IWorkbenchAssignmentService);
+    /**
+     * Resolves the signed-in user's plan context for chat error formatting.
+     * The agent host does not know the user's plan, so quota/rate-limit
+     * messages are personalized here from `IChatEntitlementService`.
+     */
+    private _chatErrorContext;
+    provideChatInputCompletions(sessionResource: URI, params: IChatInputCompletionsParams, token: CancellationToken): Promise<IChatInputCompletionsResult | undefined>;
+    provideChatInputCompletionTriggerCharacters(): Promise<readonly string[]>;
+    private _createCompletionItem;
+    private _toChatInputCompletionItem;
+    updateChatSessionMetadata(sessionResource: URI, metadata: Record<string, unknown>): void;
+    provideChatSessionContent(sessionResource: URI, token: CancellationToken): Promise<IChatSession>;
+    private _registerAgent;
+    private _invokeAgent;
+    private _reportInvocationFailure;
+    /**
+     * Builds the {@link IChatResponseErrorDetails} for a failed turn so the
+     * chat response renders a proper error (and, for quota errors, the upgrade
+     * affordance via `ChatQuotaExceededPart`). Returns `undefined` for
+     * non-error turns. Falls back to the raw error when no structured chat
+     * error was forwarded in `_meta`.
+     */
+    private _getTurnErrorDetails;
+    /**
+     * Returns the {@link SessionState} for a session that was eagerly created
+     * at folder-pick time, or `undefined` if no such session exists. Uses the
+     * unmanaged subscription accessor so we don't accidentally open a fresh
+     * subscription (which would issue a duplicate snapshot fetch on the wire,
+     * and in tests would synthesise placeholder state via the mock's auto-
+     * hydration path).
+     *
+     * If the eager subscription exists but hasn't received its first snapshot
+     * yet (creation in flight), waits for it to hydrate or error before
+     * returning. This closes a race where the chat request arrives between
+     * `createSession` resolving and the snapshot landing.
+     */
+    private _readEagerlyCreatedSessionState;
+    /**
+     * Diffs the chat model's pending requests against the protocol state in
+     * `_clientState` and dispatches Set/Removed/Reordered actions as needed.
+     */
+    private _syncPendingMessages;
+    /**
+     * Projects protocol pending messages into the chat model.
+     * The protocol is authoritative, so matching local state is a no-op.
+     */
+    private _applyRemotePendingMessages;
+    private _dispatchAction;
+    private _requireChatURI;
+    private _resolveChatUriFromState;
+    private _setChatURI;
+    private _getChatURI;
+    private _getRenameChatURI;
+    private _getCurrentActiveClient;
+    /**
+     * Drop client-published customizations for a host older than list-shaped enablement, which
+     * rejects the newer shape outright with `invalid params: missing field 'enabled'`. Temporary;
+     * see {@link CUSTOMIZATION_ENABLEMENT_PROTOCOL_VERSION}.
+     */
+    private _withVersionedCustomizations;
+    private _ensureActiveClient;
+    private _ensureActiveClientEntry;
+    private _configureActiveClientReconciliation;
+    private _disposeActiveClientEntry;
+    /**
+     * Sets up a persistent listener on the session's protocol state that
+     * detects server-initiated turns (e.g. auto-consumed queued messages).
+     * When a new `activeTurn` appears whose `turnId` was NOT dispatched by
+     * this client, it signals the {@link AgentHostChatSession} to create a
+     * new request in the chat model, removes the consumed pending request
+     * if applicable, and pipes turn progress through `progressObs`.
+     */
+    private _watchForServerInitiatedTurns;
+    private _watchForMcpAuthentication;
+    private _watchForSessionInputNeeded;
+    private _isOwnedClientToolRequest;
+    /**
+     * Releases this resource's reference to the shared per-backend-session
+     * {@link _watchForSessionInputNeeded} watcher, disposing it only once the
+     * last sibling resource has let go.
+     */
+    private _releaseSessionInputNeeded;
+    /**
+     * Holds the shared state for a tool call while an `inputNeeded` request
+     * references it. Once the host stops asking — the request disappears, or the
+     * watcher is disposed — the outcome is settled, so the dispatch-funnel entry
+     * and the shared invocation are dropped and a later call with the same ids
+     * is never mistaken for this one.
+     */
+    private _retainToolCall;
+    /**
+     * Returns the shared {@link ChatToolInvocation} for a client tool call,
+     * creating it on first use via {@link ILanguageModelToolsService.beginToolCall}.
+     * `sessionResource` is deliberately omitted so `beginToolCall` does not
+     * append progress into a chat model (which throws once the owning request
+     * is complete); it still registers the invocation, so a later `invokeTool`
+     * with a matching `chatStreamToolCallId` attaches to this same object. The
+     * observer that renders the call and the watcher that executes it therefore
+     * act on one invocation.
+     */
+    private _ensureClientToolInvocation;
+    /** The workbench tool a runtime client-tool call maps to, or `undefined` when it is not installed. */
+    private _resolveClientTool;
+    /**
+     * Whether an unclaimed client tool must wait for a rendering observer
+     * before running. There is no protocol field for this, so we use the tool's
+     * static {@link IToolData.canRequestPreApproval} signal: a tool that might
+     * ask for pre-approval could pop a confirmation, which only makes sense
+     * inside a live chat request. Limitation: this is a "might" signal — a tool
+     * may set it yet auto-approve at runtime — so an unclaimed such tool is
+     * conservatively made to wait (and denied on timeout) rather than risk a
+     * headless modal nobody can answer. Only consulted for the unclaimed case;
+     * a claimed call always runs with context regardless.
+     */
+    private _clientToolRequiresConfirmation;
+    /**
+     * The one place a client tool is actually invoked. Ensures the shared
+     * invocation exists, parses the protocol input (preserving the tool-search
+     * candidate handling), invokes the tool, and dispatches the protocol
+     * completion. `contextSessionResource` is set when a turn observer is
+     * rendering the call: a live chat request then exists, so confirmation
+     * renders in the tool part, any pre-approval is honored, and side effects
+     * attribute to that observer's chat. Without it the tool runs headlessly,
+     * independent of whether the owning turn is live.
+     */
+    private _executeClientTool;
+    /**
+     * Denies a client tool call that needs confirmation but that no sub/agent
+     * observer claimed within the grace window: there is no live surface to
+     * answer it, so report a failed completion rather than pop a headless
+     * modal.
+     */
+    private _denyClientTool;
+    /**
+     * Tracks protocol state changes for a specific server-initiated turn and
+     * pushes `IChatProgress[]` items into the session's `progressObs`.
+     * When the turn finishes, sets `isCompleteObs` to true.
+     */
+    private _trackServerTurnProgress;
+    private _completeSessionTurn;
+    private _turnStopWatchKey;
+    private _ensureTurnStopWatch;
+    private _turnDuration;
+    private _clearTurnStopWatch;
+    private _handleTurn;
+    private _handleResumedTurn;
+    /**
+     * Awaits user confirmation on a PendingConfirmation tool call invocation
+     * and dispatches `ChatToolCallConfirmed` back to the server.
+     */
+    private _awaitToolConfirmation;
+    /**
+     * Installs the always-on observable graph that translates session state
+     * into `IChatProgress[]` for a specific turn. The same graph is used for:
+     *   - live turns started by the user via {@link _handleTurn},
+     *   - reconnect to an in-flight turn from {@link provideChatSessionContent},
+     *   - server-initiated turns detected by {@link _watchForServerInitiatedTurns}.
+     *
+     * Differences are captured in {@link IObserveTurnOptions.sink} (where
+     * progress is delivered) and {@link IObserveTurnOptions.snapshotToolCalls} /
+     * {@link IObserveTurnOptions.seedEmittedLengths} (snapshot continuity for
+     * the reconnect case).
+     *
+     * The returned disposable owns turn progress; subagent observations are
+     * retained by the chat session or their root subagent.
+     */
+    private _observeTurn;
+    /**
+     * Surfaces the "MCP server … requires authentication" prompt for a turn.
+     *
+     * Each server is prompted at most once per conversation: {@link mcpAuthRequired$}
+     * is session-wide, so without this guard the prompt would repeat on every
+     * message. The per-session {@link _surfacedMcpAuthServers surfaced set} tracks
+     * which servers were already prompted; it is pruned by
+     * {@link _reconcileSurfacedMcpAuthServers} once a server reaches the running
+     * state, so a server that is re-required after being authenticated (e.g.
+     * after a restart) prompts again.
+     *
+     * The emitted part lists only the servers it introduced and shrinks as they
+     * authenticate.
+     */
+    private _setupMcpAuthPrompt;
+    /**
+     * Returns the mutable set of MCP server ids already surfaced for
+     * authentication in the given session, creating it on first use.
+     */
+    private _getSurfacedMcpAuthServers;
+    /**
+     * Prunes servers that reached the running ({@link McpServerStatus.Ready})
+     * state from every session's {@link _surfacedMcpAuthServers surfaced set} so
+     * a subsequent auth requirement surfaces a fresh prompt instead of being
+     * suppressed. Only the running state counts as actioned — a server that
+     * merely left {@link McpServerStatus.AuthRequired} for an error/stopped
+     * state was not authenticated and stays suppressed.
+     */
+    private _reconcileSurfacedMcpAuthServers;
+    private _filterAutoGrantedMcpAuthentication;
+    private _autoAuthenticateMcpServer;
+    private _setupMarkdownPart;
+    private _setupReasoningPart;
+    private _setupToolCallPart;
+    private _toolCallKey;
+    private _inputRequestKey;
+    /** Claims a request as rendered until the returned disposable is disposed. */
+    private _markRendered;
+    /**
+     * Records that a turn observer is rendering this chat input request, so the
+     * session-level responder leaves its inline elicitation UI in charge.
+     */
+    private _markInputRequestRendered;
+    /**
+     * Records that a turn observer is rendering this tool call, so the
+     * session-level responder leaves its inline UI in charge. Releasing the
+     * claim also forgets the funnel entries, which is the only cleanup a tool
+     * call that never reached `inputNeeded` ever gets.
+     */
+    private _markToolCallRendered;
+    /**
+     * Single funnel for tool-call outcomes, so an inline invocation and the
+     * session-level responder can both offer the action while the protocol
+     * only ever sees the first answer. Confirming and completing are distinct
+     * outcomes, so each is tracked separately.
+     */
+    private _resolveToolCall;
+    private _forgetResolvedToolCall;
+    private _setupOtherClientToolCall;
+    private _otherClientToolInvocationOptions;
+    /**
+     * Per-call setup for a server-driven tool. Adopts a snapshot
+     * {@link ChatToolInvocation} when present (reconnect parity); otherwise
+     * emits a fresh one. Reacts to status transitions for re-confirmation,
+     * terminal revival, finalization, and subagent observation.
+     *
+     * `renderedBySnapshot` marks a settled tool call the reconnect snapshot
+     * already rendered as a serialized part. The invocation is still built so
+     * subagent observation has something to drive, but it is not emitted —
+     * the snapshot's part is the one on screen.
+     */
+    private _setupServerToolCall;
+    /** Transitions an invocation from streaming once its AHP tool call is ready. */
+    private _ensureLeftStreaming;
+    private _createSubagentContext;
+    /** Retains each launch's final state so catalog discovery can continue after its parent turn completes. */
+    private _trackSubagentToolCall;
+    /** Late child activity updates the original response without reopening the completed parent turn. */
+    private _appendSubagentProgress;
+    private _tryObserveSubagentToolCall;
+    /**
+     * Per-call setup for a client-provided tool. The observer only renders: it
+     * obtains the shared {@link ChatToolInvocation} (created by whichever of
+     * this observer or the session-level watcher arrives first), emits it into
+     * this chat so it renders in the correct group, drives subagent
+     * presentation, and dispatches `ChatToolCallConfirmed` from the
+     * invocation's confirmation gate. It never invokes the tool — the
+     * session-level watcher owns execution.
+     */
+    private _setupClientToolCall;
+    private _setupInputRequestPart;
+    private _setupPlanReviewInputRequest;
+    /**
+     * Handle a URL-style {@link ChatInputRequest} by rendering a
+     * {@link ChatElicitationRequestPart} that prompts the user to open the
+     * URL. Clicking the accept button opens the URL via {@link IOpenerService}
+     * and dispatches `ChatInputCompleted` with `Accept`; reject dispatches
+     * `Decline`; abandonment / cancellation dispatches `Cancel`.
+     */
+    private _setupUrlInputRequest;
+    /**
+     * Synchronizes PTY and non-PTY terminal content, including the live-to-retained output handoff, and updates invocation metadata.
+     */
+    private _reviveTerminalIfNeeded;
+    /**
+     * Enriches serialized history with inner tool calls from subagent child
+     * sessions. For each subagent tool call found in the history, subscribes
+     * to the corresponding child session and appends its inner tool calls
+     * (with `subAgentInvocationId` set) to the response parts.
+     */
+    private _enrichHistoryWithSubagentCalls;
+    private _loadSubagentState;
+    /**
+     * Writes a subagent's accumulated cost (AIC) and model — summed across its
+     * child session's turns — onto its serialized subagent tool call so the
+     * hover survives a reload. Mirrors the live observers in
+     * {@link _setupServerToolCall}.
+     */
+    private _applySubagentUsageToHistoryPart;
+    private _refreshRestoredSubagentParts;
+    private _getSubagentInnerParts;
+    /**
+     * Subscribes to a child subagent session and forwards its tool calls
+     * as progress parts into the parent session's response, with
+     * `subAgentInvocationId` set so the renderer groups them under the parent
+     * subagent widget.
+     *
+     * Implementation: builds a per-turn-id keyed observation over the child
+     * session's `turns` and `activeTurn`. Each turn id discovered gets its
+     * own {@link _observeTurn} instance running in subagent mode (which skips
+     * markdown/reasoning/input-request emission and tags tool calls with the
+     * parent tool call id). Each per-turn observer self-disposes when its
+     * turn reaches a terminal state; the outer observation is torn down when
+     * the caller disposes `disposables`.
+     */
+    private _observeSubagentSession;
+    /**
+     * Wires up an ongoing state listener that streams incremental progress
+     * from an already-running turn into the chat session's progressObs.
+     * This is the reconnection counterpart of {@link _handleTurn}, which
+     * handles newly-initiated turns.
+     */
+    private _reconnectToActiveTurn;
+    /**
+     * Ensures the chat model has a snapshot controller bound (creating one
+     * via our registered editing-session provider if needed) and returns it.
+     * Hydrates the controller from any pending history turns on first access.
+     */
+    private _ensureSnapshotController;
+    /**
+     * Records snapshot data for a completed tool call (so restore-snapshot
+     * works) and returns the {@link IChatExternalEdit} progress parts to
+     * render the per-file edit pills.
+     */
+    private _hydrateFileEdits;
+    /**
+     * Attaches to an existing server-side terminal via the agent host
+     * terminal service and registers it with the terminal chat service.
+     *
+     * Returns the terminal instance created or reused by the terminal service.
+     */
+    private _ensureTerminalInstance;
+    /** Maps a UI session resource to a backend provider URI. */
+    private _resolveSessionUri;
+    private _isNewSessionResource;
+    /**
+     * Forks the conversation at the given request point into a new peer chat
+     * of the same session. AHP models forking at the chat level only, so the
+     * fork stays inside the source session and is addressed by a chat
+     * fragment on the session resource.
+     */
+    private _forkSession;
+    private _ensureRequiredAuthentication;
+    /** Creates a new backend session and subscribes to its state. */
+    private _createAndSubscribe;
+    /**
+     * Keeps chat model and protocol pending messages synchronized in both directions.
+     * No-ops if already subscribed.
+     */
+    private _ensurePendingMessageSubscription;
+    private _ensureDraftSyncSubscription;
+    private _acquireOrWaitForSession;
+    private _installDraftSync;
+    /** Applies a remote draft without replacing local input state the protocol does not carry. */
+    private _applyRemoteDraft;
+    private _inputStateToDraft;
+    /**
+     * Check if an error is an "authentication required" error.
+     * Checks for the AHP_AUTH_REQUIRED error code when available,
+     * with a message-based fallback for transports that don't preserve
+     * structured error codes (e.g. ProxyChannel).
+     */
+    private _isAuthRequiredError;
+    private _createModelSelection;
+    private _draftToInputState;
+    /**
+     * Extracts the raw model id from a language-model service identifier.
+     * E.g. "agent-host-copilot:claude-sonnet-4-20250514" → "claude-sonnet-4-20250514".
+     * Foreign extension-host identifiers (`${vendor}/${id}`) are dropped so
+     * the agent host falls back to its default model.
+     */
+    private _extractRawModelId;
+    private _toLanguageModelId;
+    private _getTurnResponseDetails;
+    /**
+     * Builds a per-turn model lookup that namespaces raw AHP model ids into
+     * chat-layer language-model ids and resolves human-readable display
+     * names via the registered language-model providers (so the chat UI's
+     * per-response footer can show e.g. "Claude Opus 4.7" instead of the
+     * raw model id). `fallbackRawModelId` is used when a turn's
+     * `usage?.model` is not yet set (e.g. older sessions or turns that
+     * never reported usage).
+     */
+    private _createTurnModelLookup;
+    private _resolveRequestedWorkingDirectory;
+    /** `undefined` is preserved for createSession to let the host choose its working directories. */
+    private _resolveRequestedWorkingDirectories;
+    /**
+     * Drop working directories whose scheme the host cannot address, falling back to `undefined` so
+     * it picks its own. Schemes are compared as the host receives them, after unwrapping.
+     */
+    private _hostAddressableWorkingDirectories;
+    /**
+     * Scope roots always describe a concrete customization lookup. This differs
+     * from `_resolveRequestedWorkingDirectories`: its `undefined` is protocol
+     * meaningful and lets the host choose working directories for createSession.
+     *
+     * An existing session's roots are fixed at creation and persisted in its
+     * state, so they are read from there rather than recomputed from the current
+     * workspace — otherwise a single-folder session opened inside a multi-root
+     * workspace would pick up the other workspace folders. New sessions have no
+     * state yet, so they fall back to the workspace-derived set they will be
+     * created with.
+     */
+    private _resolveCustomizationScopeRoots;
+    /**
+     * The working directories an already-created session was started with, read
+     * from its authoritative (hydrated) state.
+     *
+     * Returns `undefined` when the session's working directories are absent — no
+     * hydrated state yet, or a session that inherits its directories — so callers
+     * fall back to the workspace-derived set. An explicit empty set is
+     * authoritative and returned as `[]`: a workspace-less session must not
+     * inherit the current workspace's roots. This mirrors the host-side
+     * `undefined` (inherit) vs `[]` (explicitly none) distinction.
+     */
+    private _existingSessionWorkingDirectories;
+    /**
+     * Resolves the local folders the agent will run in, for the workspace-trust
+     * gate: an existing session's persisted working directories, or a new session's
+     * requested ones.
+     *
+     * Returns `undefined` for a workspace-less session (a quick chat) to signal the
+     * caller to skip the folder-trust gate entirely: its only working directory is
+     * an internal scratch dir (`~/.copilot/chats/<id>`), an implementation detail
+     * rather than a user workspace, so it must not be treated as a trust root.
+     * Otherwise an explicit empty set is honored and only a genuinely unresolved set
+     * falls back to the requested/workspace folders.
+     */
+    private _resolveSessionTrustFolders;
+    /**
+     * Grants (and persists) trust for a worktree-isolated session's VS Code-created
+     * worktree when the base repository the user already trusts is trusted, so the
+     * trust gate does not prompt for the worktree.
+     *
+     * This lives in the handler because `_invokeAgent` is the only universal
+     * chokepoint every turn passes through — follow-up turns bypass the sessions
+     * open gate ({@link ISessionsService.canOpenSession}). Protocol `SessionState`
+     * does not carry the sessions layer's `gitRepository.workTreeUri`, so
+     * eligibility uses the isolation config plus a structural guard: only a strict
+     * descendant of the repository's `.worktrees` sibling
+     * ({@link isWorktreeUnderRepository}) can inherit trust — a trusted base URI is
+     * never enough on its own, and the shared `<repo>.worktrees` container is
+     * excluded so a grant can never cascade to every worktree. Mirrors the
+     * sessions-layer `ensureSessionWorktreesTrusted`; kept separate because
+     * `workbench` must not import `sessions`.
+     */
+    private _inheritWorktreeTrust;
+    /**
+     * Ensures every local (file-scheme) folder the agent will run in is trusted
+     * before a session is spawned; returns `false` if the user declines any. Trust
+     * is checked for all folders in parallel and only untrusted folders are prompted
+     * for, one at a time.
+     */
+    private _ensureFoldersTrusted;
+    private _convertVariablesToAttachments;
+    /**
+     * Forward the active editor (which the suggested-context flow omits in agent mode) as ambient context, deduped
+     * against files the user attached explicitly. Gated on
+     * {@link ChatConfiguration.ImplicitContextActiveEditor} (on by default, off in the Agents window).
+     * Unsaved handling lives in {@link _convertVariableToAttachment}.
+     */
+    private _appendActiveEditorAttachments;
+    /** Add the stored outputs for an active notebook cell as a virtual JSON document. */
+    private _appendNotebookCellOutputAttachment;
+    /** Dedupe identity for a file/implicit entry: rebased URI, suffixed with the range for a selection. */
+    private _fileEntryDedupeKey;
+    /** The selection range carried by a file/implicit entry, or `undefined` for whole-document references. */
+    private _entrySelection;
+    /** Dedupe identity: the bare URI for a whole document, suffixed with the range for a selection. */
+    private _attachmentDedupeKey;
+    /**
+     * Whether this backend reads referenced files from disk (rather than seeing the editor's
+     * in-memory buffer) and therefore needs the live text of an unsaved / dirty editor inlined as
+     * an embedded resource. Copilot CLI and Codex both run as separate processes with only disk
+     * access, so a `@path` mention (or an `untitled:` URI) would give them stale or missing content.
+     */
+    private _backendInlinesUnsavedEditors;
+    /** A resource is unsaved when it's untitled or a saved file with in-memory (dirty) changes. */
+    private _isUnsavedResource;
+    /**
+     * Inline the live (in-memory) text of an unsaved editor as an embedded resource so a path-reading backend still
+     * gets current content, preserving the entry's selection, range and `_meta`. Selection entries inline only the
+     * selected text; whole-document entries inline the full buffer. Returns `undefined` when no loaded text model is
+     * available or the inlined text exceeds {@link MAX_INLINED_UNSAVED_EDITOR_BYTES}.
+     */
+    private _buildUnsavedEditorAttachment;
+    /**
+     * The inline text to send for an unsaved editor: the selected text for a selection, else the whole buffer. Uses the
+     * model length APIs so an over-cap buffer is skipped (returns `undefined`) without ever being materialized.
+     */
+    private _getUnsavedEditorAttachmentText;
+    /** The editor range of a file/implicit selection entry, used to slice the live model; `undefined` otherwise. */
+    private _entryModelSelectionRange;
+    /** The {@link Location} of a file/implicit entry that represents a selection, or `undefined` for whole documents. */
+    private _entrySelectionLocation;
+    private _variableEntriesToAttachments;
+    private _convertVariableToAttachment;
+    private _toChatReferenceAttachment;
+    private _toElementImageAttachment;
+    private _toSessionReferenceAttachment;
+    private _toSessionReferenceAttachments;
+    private _toSessionReferenceTrajectoryAttachment;
+    private _toSessionReferenceTrajectoryPath;
+    private _toResourceAttachment;
+    private _toSelectionAttachment;
+    private _toImageAttachment;
+    private _toAgentFeedbackAttachment;
+    private _toSimpleAttachment;
+    private _toEmbeddedTextAttachment;
+    private _toAttachmentReferenceRange;
+    private _toTextRange;
+    /**
+     * Rebase a `file:`-scheme attachment URI from the session's requested
+     * working directory onto the server-resolved working directory. This
+     * matters on the first turn of a worktree-isolated session, where the
+     * provider creates a worktree under a different path than the workspace
+     * folder the workbench attached the file from. Returns the URI unchanged
+     * if the requested and resolved directories match, the URI is not under
+     * the requested directory, or either side is unavailable.
+     */
+    private _rebaseAttachmentUri;
+    /**
+     * Get or create a session subscription. The first call for a given URI
+     * triggers a server subscribe; subsequent calls increment the refcount.
+     */
+    private _ensureSessionSubscription;
+    /**
+     * Get or create the default-chat subscription for a session. Mirrors the
+     * refcount lifecycle of {@link _ensureSessionSubscription}.
+     */
+    private _ensureDefaultChatSubscription;
+    /**
+     * Release the subscriptions held by a single chat session on dispose.
+     *
+     * Unlike {@link _releaseSessionSubscription} (which tears down every chat
+     * of a session at once), this only releases the disposed chat's own
+     * conversation subscription and never touches sibling peer chats: closing
+     * one chat of a multi-chat session must not strand another chat — including
+     * one that is concurrently hydrating in {@link provideChatSessionContent} —
+     * on a disposed subscription. The session summary subscription (and its
+     * lockstep default-chat subscription) is shared by every chat of the
+     * session, so it is only torn down once no sibling chat session is still
+     * active or mid-hydration for the same backend session.
+     */
+    private _releaseChatSessionSubscriptions;
+    /**
+     * Returns whether another chat session for the given backend session URI is
+     * still active or in the middle of hydrating its subscriptions, so the
+     * shared session subscription must be kept alive. Callers invoke this after
+     * removing their own entry from {@link _activeSessions}.
+     */
+    private _hasOtherSessionHold;
+    /**
+     * Read the current optimistic session state for a backend session URI,
+     * merged with its default chat so conversation contents (turns, active
+     * turn, pending/queued messages, input requests) are visible.
+     */
+    /**
+     * Resolves once a subscription has received its first snapshot (its
+     * `value` is no longer `undefined`) — i.e. it has hydrated with state or
+     * an error. Resolves immediately if already hydrated or if cancellation
+     * is requested.
+     */
+    private _whenSubscriptionHydrated;
+    private _getSessionState;
+    private _isChatReadOnly;
+    private _getRawSessionState;
+    private _requireRawSessionState;
+    private _requireDefaultChatUri;
+    /** Read the current optimistic default-chat state for a backend session URI. */
+    private _getDefaultChatState;
+    /** Read the current optimistic state for an additional peer chat URI. */
+    private _getAdditionalChatState;
+    /**
+     * Get or create the subscription for an additional peer chat, keyed by the
+     * chat channel URI. Mirrors {@link _ensureDefaultChatSubscription} but for
+     * non-default chats so their conversation contents hydrate independently.
+     */
+    private _ensureAdditionalChatSubscription;
+    /**
+     * Subscribe to the conversation channel of `sessionResource`'s chat and
+     * return the {@link IAgentSubscription}. Routes to the default-chat
+     * subscription (fragment-less resource) or to an additional peer chat.
+     */
+    private _ensureChatSubscription;
+    resolveChatResponseUri(_sessionResource: URI, href: string, _kind: "link" | "image"): string;
+    /**
+     * Read the current root state.
+     */
+    private _getRootState;
+    dispose(): void;
+}
+/**
+ * Converts an internal {@link IToolResult} to a protocol
+ * {@link import('../../../../../../platform/agentHost/common/state/protocol/state.js').ToolCallResult}.
+ */
+export declare function toolResultToProtocol(result: IToolResult, toolName: string): {
+    success: boolean;
+    pastTenseMessage: StringOrMarkdown;
+    content?: ({
+        type: ToolResultContentType.Text;
+        text: string;
+    } | {
+        type: ToolResultContentType.EmbeddedResource;
+        data: string;
+        contentType: string;
+    })[];
+    error?: {
+        message: string;
+    };
+};